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:
1 parent
7b06dc7aac
commit
20834d297e
4 files changed
+110
-4
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user