Handoff: Reconcile response contracts and finish rebasing the bounded reply buffering PR

Written: 2026-10-22 00:18 UTC.

RE-VERIFY: This is a write-time snapshot. Recheck https://github.com/CodexCoder21Organization/UrlProtocol/pull/765 with gh pr view 765 --repo CodexCoder21Organization/UrlProtocol --json state,headRefOid,baseRefName,mergeStateStatus,mergedAt and git ls-remote origin refs/heads/main refs/heads/fix/r104-windowed-reply-buffering before acting.

Design decisions in force

Owner direction carried by the 2026-10-22 brief: "I think we should do the things that the web server does." and "I think the shared buffer size should also have a cap per connection, and the shared buffer should have a maximum bounded size but also should shrink if it isn't being heavily utilized..."

The brief requires preserving main and bounded-buffering intent, forbids weakening/deleting/skipping tests or assertions, and says: "If a conflict is a genuine semantic contradiction you cannot resolve with confidence, stop and write it up instead of guessing."

No merge, enqueue, gh pr merge, --to-merged, publish, deployment, timeout increases, iteration cuts, CI check re-requests, reflection, or mocks. No full-suite run: another lane's full run was active when assigned. Before each allowed targeted run, inspect ps -eo pid,args -ww | grep 'scripts/test.bash'; run one targeted test at a time with scripts/test.bash --local --test <name> --log <xml-path>. Record first-attempt counts from XML. Push only after verification and confirming OPEN, using force-with-lease. Do not edit the existing description except the explicitly permitted rebase note.

Mission summary

Brief r137 asks to rebase the bounded reply buffering branch onto current main so it can be ready when BuildTest accepts builds again, around 02:00 UTC. The work belongs to the TinySite outage effort. The rebase encountered response-contract differences requiring a decision; it has not been completed or pushed.

What was found and done

Rebase conflict assessment — STOP

Observed text conflicts

1. tryReserveFailureSignal: main selects FAILURE versus LONG_POLL_FAILURE and reserves that separate accounting lane. The PR replaces the failure frame allocation with a lease from the shared physical reply pool. Both selection and leased ownership need to survive.
2. hasFailureCapacity: main selects connectionBytes/processBytes for normal versus long-poll failure capacity. The PR adds sharedReplyBufferPool.hasCapacity. Both the selected lane accounting and physical pool check need to survive.
3. JSONObject writeRpcResponseReturningOutcome: main delegates to a new pre-encoded ByteArray overload and extracts checkRpcAttachmentFrameLimits; the PR routes JSON/attachments into a demand-driven producer. Blind selection of either side drops behavior.

Observed semantic disagreement

• Main's tests/testDeclaredLongPollOversizedReplyKeepsSlotUntilDelivered.kts returns a string of 4 * 1024 * 1024 + 1024 characters on a deliberately unwritable root. It requires ADMITTED:FAILURE, an exact OUTBOX_FULL error, and retention of the 192nd long-poll permit until that fallback is delivered.
• The PR's docs/REPLY_BUFFERING.md says to change production from a complete wire buffer to a demand-driven framed source, and its final JSONObject writer always sends large valid frames through writeAwaitedReplyProducer. A >4 MiB result no longer necessarily needs the old size-based fallback. The existing main test and unconditional streamed-large-reply behavior therefore require a policy reconciliation, not deletion of an assertion.
• Main's encodeRpcResponseOrEncodingFailure uses RpcEncodingResources.guard, JSON serialization, checkJsonWireStructure, and attachment checks before writing. It sends a descriptive request-specific error when conversion fails. Its new ByteArray overload bypasses the PR's producer if retained unchanged, including aggregate ByteBuf creation. Replacing that path with the branch's direct producer loses complete-wire structural validation (including JSONString-provided text and receiver depth/string/element limits). A safe bounded preflight needs design and focused coverage; it is not just a marker removal.

Confidence and decision needed

These findings are from source/test inspection, not test executions. The two failure-capacity hunks have a clear combined resolution. I cannot confidently resolve the response-policy and preflight interactions within a mechanical rebase while promising preservation of both behaviors. Per the brief, stopped instead of guessing. Decide whether oversized declared long-poll responses keep the existing OUTBOX_FULL size policy as a special case, or gain streamed delivery with an explicitly authorized test/contract change; then design a bounded preflight that preserves main's conversion/receiver-limit errors.

Tests and push

• No build or targeted test started. First-attempt runner XML counts: not available (zero executions), not 0 passed/0 failed.
• No full-suite run started. No background test/monitor process started.
• No push attempted. Remote PR head remains 21a2088cde91fbde40a96af5ade7f26a9130e0c7. No PR description edit, base edit, CI request, merge, enqueue, publish, or deployment.
• No build caches created. Fresh clone is retained with the stopped rebase; out/rebase-conflict.diff records its conflict. All source commits are already recoverable from the original remote branch and main; there is no new implementation to push.
• Initial rebase stopped because git identity was unset. Set repository-local identity matching the authenticated account and existing branch commits, aborted that incomplete start, then restarted fetch/rebase. This changed no tracked file.

Relevant PRs / refs

The PR's GitHub base is fix/r83-outbox-minimum-progress-rate, although the brief explicitly asks to rebase onto origin/main. No PR base edit was authorized or performed.

No new implementation was written, and no unique source work needs a remote checkpoint: all staged changes are git's automatic replay of existing remote commits. No partial-source push was made because the brief requires tests before push. The complete diagnostic record is embedded here. The stopped rebase can be recreated entirely from the linked branch and destination SHA: clone, configure repository-local git identity if needed, checkout the branch, git rebase edc4c63729f3119a47ecf4494dde98da82f36ca0. It stops at https://github.com/CodexCoder21Organization/UrlProtocol/commit/02739f7f6f1948fbec030f31dfb4933229c5ef2f (22/27). No stash exists. One worktree only.

Local scratch clone is /tmp/claude-1000/-code/2f854167-89e3-433d-bb44-9afc59221d1d/scratchpad/r137/UrlProtocol; findings and automatic conflict diff are adjacent in out/. Clone is retained with unresolved conflicts. Its partial applied HEAD is 72131c7b203390c9f11f2fb4d619f0fe772bec8a; do not mistake that for a completed new PR head.

Deployed/published but unmerged: none created by this effort. No service-management or artifact publication command was issued. Production state was not probed because deployment is outside this rebase brief.

Next steps

1. Re-verify branch/main/PR state and determine whether another lane has already reconciled these contracts.
2. Decide how oversized declared long-poll replies interact with streaming. Preserving the existing long-poll-specific fallback policy may be possible, but no implementation or assertion change has been validated.
3. Design bounded preflight preserving main's encoding diagnostics and receiver-limit checks. Main's ByteArray overload cannot simply remain the active ordinary response path without bypassing producer buffering.
4. Resolve the file, continue all remaining rebase commits, and review automatically merged forwarding/close code as well: main introduced ForwardedOutputCloseFailures and awaitForwardedResponseWrite, whereas the later producer commit replaces the forwarding writer. Do not assume surviving unused helpers preserve behavior.
5. Re-derive the allowed targeted list from the PR diff and conflict-touched test files. Run only that list, sequentially with XML logs and no full suite. No test has been attempted yet.
6. Only after successful verification, confirm OPEN and force-push with lease. Append the permitted short rebase note for these non-trivial conflicts. Clean build caches created for the clone and end all started background processes.

Reusable / operational knowledge

README has about 3,000 lines and no repository AGENTS.md exists. scripts/test.bash pins kompile-cli 0.0.124 and stores caches at $HOME/.aibuildcaches/ plus the absolute clone path with slashes replaced by underscores; jars/ is ignored. No cache was created here. The original fresh clone needed repository-local git user.name/user.email; matching identity is codexcoder21 / 216437543+codexcoder21@users.noreply.github.com. The first identity-free attempt was aborted and restarted; no tracked file was changed by setup.

Documents inspected: README overview/build/flow-control/API/forwarding/discovery/error sections; full docs/REPLY_BUFFERING.md; full create-handoff skill and handoffs README. Central Testing Architecture and Engineering Philosophy were fetched but only initial portions inspected; before writing tests, read the required testing guidance in full. No new tests or implementation were written in r137.