Handoff: Finish required full-suite verification for UrlProtocol response-encoding notification

Written: 2026-10-22 16:41 UTC, lane s105.

RE-VERIFY every PR/head/check before acting. Use GitHub GraphQL or gh pr view https://github.com/CodexCoder21Organization/UrlProtocol/pull/841 --json state,isDraft,headRefOid,statusCheckRollup and git ls-remote. This record is a snapshot; live state wins.

Design decisions in force

2026-10-22 lane brief: "Finish 841: the notification fires exactly once for a response that fails to encode, on every host the protocol offers (libp2p, TCP, relay) and every negotiated encoding mode; never for a response that encoded; it runs off any lock and its own failure is attached (suppressed), never replacing the encoding error; the caller still gets the descriptive error reply and the connection keeps serving other requests. Keep existing APIs source/binary compatible." "Encoder error: the error reported for an unencodable value names the path of the failing field (e.g. result.v), with the original exception as the cause; calls the value's toString at most once." "Fail-first tests for both, public API only; then implementation. README section updated." "Do not merge, enqueue or publish." No production deployment authorized. No timeout increases, reduced workloads, weakened assertions, reflection, mocks, or delegation. Required checks are bld-build and bld-all-tests; the two kotlin.build App checks are informational. No check re-request or rerun has been made in this lane.

Mission summary

The user wants extreme-condition UrlResolver tests that fail first, followed by fixes. https://github.com/CodexCoder21Organization/UrlResolver/pull/1251 needs an upstream notification to release registrations when transport encoding rejects a computed result. https://github.com/CodexCoder21Organization/UrlProtocol/pull/697 moved leaf conversion before the JSON writer and lost field location. This lane finishes that upstream contract in https://github.com/CodexCoder21Organization/UrlProtocol/pull/841 . It stops at green required checks and ready status, without merging or publishing.

What was found and done

1. TCP's adapter discarded the optional response owner, while optimized libp2p bytecode paths bypassed ordinary encoding notification. Shared failure handling now preserves original request/response/effect context, runs once after refused transport resources close and outside accounting/write locks, remains cancellable only after cleanup opportunity, suppresses ordinary callback failures, and retains established transport diagnostics. Later delivery failures do not notify a successfully encoded response. Existing base interface and public constructors are unchanged.
2. Recursive typed response encoding records field/index paths at the point it evaluates a throwing leaf; the original failure is the JSONException cause. Raw JSON writer wrapper contexts supply paths without serializing again. Parsing already written text was rejected after a fail-first malformed-earlier-JSONString case. Message text alone was also insufficient: a leaf's own JSONException can look like a writer wrapper. The final implementation tracks actual raw value boundaries and stops unwrapping at the leaf, preserving its exact exception/cause. Numeric refusal text and successful bytes remain unchanged.
3. RelayService public handlers carry encoded String payload bytes, not RpcResponse/RpcRequestHandler objects. There is no separate RPC encoding host there. A real three-node relay plus TCP owner test proves owner cleanup before relay delivery and no repeated forwarding cleanup. A new relay-only callback API was unnecessary; that premise was refuted by public signatures/source.
4. Final implementation is 841ef50af4114634c2bf0b98ca180ac081668db1 on fix/response-encoding-callback-q23, rebased without conflicts on main 8ee64cd68b1d58065e6edee995026a310bbc22ac. README error-handling section documents the contract. Complete module build passed in 125.101s. All 21 targeted public bodies passed first attempt, no retries, against that single complete artifact. This includes ten new scenarios, four original callback scenarios, three updated existing tests, two unchanged forwarded diagnostic cases, and two unchanged encoding corpora (72 value types × five positions). No artifact was published; build coordinate inherited 0.0.1429 and was used only locally.
5. Standard source fail-first evidence: https://github.com/CodexCoder21Organization/UrlProtocol/actions/runs/39807076797 has ten expected failures on unchanged main transport/encoder plus API declaration, no duplicate records. Those files matched bb0f16ff checkpoint. Nine remain identical; the original-JSONException scenario was strengthened and is independently proven on prior bb0f16ff implementation by https://github.com/CodexCoder21Organization/UrlProtocol/actions/runs/39810755358 (one expected first failure, no duplicates). The strengthened file is byte-identical to final implementation. Disposable PRs https://github.com/CodexCoder21Organization/UrlProtocol/pull/850 and https://github.com/CodexCoder21Organization/UrlProtocol/pull/855 are closed.
6. Only three pre-existing tests changed: testRefusedResultCleanupSnapshotsResourcesBeforeCloseCallbacks expects the located JSONException and additionally original IllegalArgumentException cause/full message, retaining all close-count/suppressed assertions; testRpcEncodingFailureWithThrowingMessageGetsReply pins complete located diagnostic including guarded message getter; testRpcSenderRefusesFramesReceiversWouldRefuse changes only response-side throwing-leaf exact text, preserving request expectations. All three were reversed against published 0.0.1431 and failed on the strengthened expectations. No workload or time budget changed. Dedicated test and code review passes were performed by the lane itself; no subagents were allowed. Review findings were reproduced before fixing.
7. Consumer limitation is evidence, not a claimed pass: https://github.com/CodexCoder21Organization/UrlResolver/blob/cf9892ed73f3326f175b2dcd6206aba6baf5669e/tests/testProviderRpcResultThatFailsToSerializeFailsOnlyThatRequest.kts asserts the entire old writer-wrapper cause-chain text, not just field presence. The deliberate canonical result.v diagnostic differs. It must explicitly update its expected literal when adopting the API/artifact. No consumer code/pin/assertion was changed and no consumer integration pass is claimed.

Notification API

Optional interface RpcResponseEncodingFailureHandler : RpcRequestHandler:

suspend fun onResponseEncodingFailure(
    request: Libp2pRpcProtocol.RpcRequest,
    response: Libp2pRpcProtocol.RpcResponse,
    effectHandler: EffectPropagator,
    failure: Throwable,
): String?

A returned String supplies bounded INTERNAL_ERROR text; null keeps transport diagnostics. Ordinary callback failure is suppressed on the encoding failure and included in diagnostic text; fatal JVM failures propagate after cleanup. Covers libp2p 1.0/1.1, streaming and forwarded headers, and TcpServer.withHandler. Callback can reenter and suspend under request cancellation; close can prevent reply but does not abandon cleanup.

Required checks (refresh before submission)

• Final build: https://github.com/CodexCoder21Organization/UrlProtocol/actions/runs/39811280632 SUCCESS.
• Final full suite: https://github.com/CodexCoder21Organization/UrlProtocol/actions/runs/39811280704 IN_PROGRESS at the last check.
• Superseded full suites https://github.com/CodexCoder21Organization/UrlProtocol/actions/runs/39803068395 and https://github.com/CodexCoder21Organization/UrlProtocol/actions/runs/39807073399 do not establish the final head's gate. If they complete before stopping, collect/attribute their attempt artifacts as supplemental records.

Relevant PRs / refs

No deployed/published-but-unmerged code: this lane invoked only builds/tests, git/PR/evidence writes, and read/status operations. It did not invoke deploy or publish commands. No merge/queue mutation occurred.

Next steps

1. Re-verify current PR head, ready status and required checks. Clone fresh under workspace/ and read README; current checkout/cache is deliberately removed before the lane's final message.
2. Watch plain (never --to-merged): coursier launch buildwatchman:build-watchman:0.0.21 -r https://kotlin.directory -- --repo CodexCoder21Organization/UrlProtocol --pr 841 --idle-timeout-minutes 120 . Keep a hard deadline and a tracked process. Poll PR statuses no more than once per 60 seconds. The lane's watcher is stopped at handoff; do not assume it remains alive.
3. When final full suite completes, download test-attempt-history via gh run download 39811280704 -R CodexCoder21Organization/UrlProtocol --name test-attempt-history --dir <dir>. Parse every test element, including failed first attempts and duplicate names/retries. Attribute every failure rather than relying on final green. No manual CI retry has been used. If a new failure occurs, reproduce/diagnose under TESTING.md before fixing; never loosen assertions or timeouts. If unrelated, show it on main before saying so.
4. If both required checks are green and all first failures attributed, update PR description/findings with counts and final links, confirm ready, report complete and stop. Do not merge/enqueue/publish. If source changes are necessary, rebase before building/pushing and keep fail-first evidence.
5. Consumer adoption/release is separate authorization: the upstream lane cannot make its old exact literal pass merely by supplying a path, and publishing is expressly forbidden here.

Reusable / operational knowledge

• Full standard runner jobs race local-on-runner with remote. The remote buildtest health service currently responds STARTING: recovering local state; local runner compilation succeeds. Do not add retries or change CI selection on the real PR. The full-suite recent median reported by watchman is about 80 minutes.
• gh pr edit can fail on deprecated Projects classic projectCards; narrow GraphQL updatePullRequest mutation works. Cached IDs are PR_kwDOQugs888AAAABJ_kXRw (implementation), PR_kwDOQugs888AAAABKCy6Yg (first evidence), PR_kwDOQugs888AAAABKEH69w (follow-up evidence; re-query if needed).
• Long-lived watcher token hit REST403 while fresh gh calls had quota. Restarting a fresh bounded watcher fixed monitoring; no CI run was re-requested. GraphQL stayed available. Keep status-read cadence and obtain needed node IDs in one query.
• Ad-hoc partial JAR overlays were rejected as verification evidence after internal JVM helper/module-name mismatch. Final 21 passes use one whole artifact. Native harness source strips only build annotations/imports, keeps executable statements/assertions, splits on literal LF (Python splitlines corrupts a literal U+2028 golden), and puts harness jar before production MainKt. Never count wrong-main exit-zero runs as tests. Full traces/records/native source bodies are on the evidence branch; no JARs/caches are committed.
• The shared older handoff url://handoff/handoffs/hf-2026-10-14-land-the-urlresolver-extreme-condition-bug-fixes-fix-the-two-merge-queue-flakes-then-merge-the-reviewed-prs-and-finish-the-rest was archived 2026-10-21. A report to it was rejected; it was not reopened. This focused lane record does not replace or reopen that archived broader effort.
• Read documents: TESTING.md, PHILOSOPHY.md, repository README and relevant source contracts, PR 697/841 descriptions, exact consumer test, common lane instructions, Handoff spec. External CI procedure page timed out; commands confirmed in actual workflows. Full incremental observations, exact existing-test edits, rejected harness results and infrastructure traces are preserved in the evidence branch findings.md. report-challenge auto-merge flow was not invoked because no-merge/no-queue is explicit.

Time-box exit snapshot, 2026-10-22 16:41 UTC

Final live head remains 841ef50af4114634c2bf0b98ca180ac081668db1; PR OPEN/ready. Required build SUCCESS, final suite IN_PROGRESS. Superseded d6/bb full suites also remain IN_PROGRESS. The owned bounded watcher has exited without cancelling/re-requesting CI. No full-suite pass/count/first-attempt attribution is claimed before the artifact exists. The remaining work is exactly the required full-suite result and all-attempt review. Final source and all useful evidence are pushed; local checkouts/cache are removed at exit. This focused handoff is left unassigned when the lane stops.

Cleanup verified 2026-10-22 16:42 UTC: both local checkouts and their exact .aibuildcaches directories are absent; no owned watchman remains. Source/evidence pushes were verified by git ls-remote before deletion, and no local-only branch commits or stashes remained. Evidence branch final remote is f94f3a25679feabef1fe7cb629207db6118660a5.