docs: review 002 recorder — N-3/N-4 durable trail + N-2 ADR-008 widening + the no-action dispositions

- N-3: parse-before-accept telemetry note on make_forwarded_op_handler
  (the accepted-flag reads false for a malformed-params open by design)
- N-4: ADR-007 Consequences lines — the untagged-leniency-is-
  schema-gated paragraph + the overlapping-variants caution
- N-2: ADR-008 §1 widened to name the any-byte idle-read posture
  (the Ok(0)-only reading hangs on a write-happy peer)
- N-5: mint_token's doc comment records the 256-channel cap analysis
- The N-1/N-6/N-7 + G-1/G-3 no-action dispositions recorded in the
  task file (the tracker the task asked for)

Verified: fmt, clippy (native + wasm32), test, cargo doc — all green
This commit is contained in:
glm-5.3-flash committed 2026-09-20 08:32:45 +00:00
1 parent 7b06dc7aac
commit 20834d297e
4 files changed
+110 -4

No files matched your search

+67 -2
View File
@@ -1,7 +1,7 @@
---
id: tunnels/review-002-recorder
name: "N-1..N-7 — record the review's no-action notes in the code/ADR trail (N-4's ADR line + N-3's telemetry note)"
status: pending
status: completed
depends_on: []
scope: narrow
risk: trivial
@@ -111,4 +111,69 @@ G-1's four duplicated closures into one `params_to_input` helper
## Notes
> Agent fills during implementation.
> Agent fills during implementation.
## Implementation Notes (2026-09-20) — the review's no-action dispositions, recorded
The two durable-trail items landed as specified; the no-action notes'
dispositions follow (this section is the tracker the task asked for).
### Landed
- **N-3**: the parse-before-accept telemetry sentence added to
`make_forwarded_op_handler`'s doc comment
(`src/producer.rs`) — "the accepted-flag telemetry reads false here
by design; a malformed-params open IS a birth-teardown shape; do
not flag the flag (review 002 N-3)".
- **N-4**: both ADR-007 Consequences lines added — (1) the
`SubstrateAddr` untagged-leniency-is-schema-gated paragraph (the
sibling-keyed `render_target` backstop; "cross-shape garbage is the
schema's absence, not a serde failure"; the schema-less-registry
ADR-line-if-ever requirement) and (2) the overlapping-variants
caution (untagged disambiguation starts ordering → switch to an
internally-tagged form, deliberately, never by accident).
- **N-2 (ADR-008 §1 widening — APPLIED, not declined)**: §1's
accept-dispatcher bullet now states the any-byte idle-read posture
(`Ok(0)` / error / any non-empty read all tear down; fail closed;
the write-happy-peer test pins it) and names the `Ok(0)`-only
hang-on-write-happy-peer trap the narrower reading would produce.
Note: the doc-sync task and this task both touched ADR files but
never ADR-008, so no coordination conflict materialized.
- **N-5 (optionally tighten — done)**: `mint_token`'s doc comment now
records the review's cap analysis (the token is
per-producer-connection; the 256-channels-per-connection cap makes
the live-collision window unreachable by a wide margin).
### No-action dispositions (unchanged from the review)
- **N-1**: no action. `parse_listen_reply`'s positive-`listen`
requirement matches the forwarded params' `minimum: 1`; JSON-null-
as-absent is the standard lenient reading; the `deny_unknown_fields`
warning in `TunnelListenReply`'s doc comment is doing real work —
kept as-is.
- **N-2's code**: no action (fail-closed any-byte watch is correct as
shipped; only the ADR sentence was widened, above).
- **N-6**: no action. Sleep-then-assert is the established house
pattern (3x-repeat stable historically); if CI ever flakes on the
forwarded-arrival tests, the fix is a bounded poll loop on
`channel_ids()` extended to the arrivals — recorded here, not
implemented.
- **N-7**: no action. `test_bind()`'s bare `Arc<u32>` listener is
fine; the downcast-miss probe
(`accept_pair_loop_downcast_miss_fails_loud`) covers the failure
mode.
- **G-1/G-3 (the unreachable-by-construction arms)**: left uncovered,
per the review's recommendations — `open`/`open_direct`/
`TunnelListener::open` (+ `open_reverse_channel`'s twin)
params-serialize closures (serde_json cannot fail on these types)
and `join`'s pump-`Err` arm (unreachable through the public API; the
only path in is a panicking pump, out of contract). This section is
the "unreachable error arm" record the coverage appendix asked for;
the optional `params_to_input` helper collapse was skipped
(cosmetic; the review says fine to skip).
### Verification
- `cargo fmt --check`; `cargo clippy --all-targets -D warnings`
(native + wasm32); `cargo test` (all suites + doc-tests);
`cargo doc --no-deps` — all green.