From 92c3cc51232db6b796e9cafc336c04bd62faaf89 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Tue, 3 Nov 2026 12:53:27 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20close=20out=20review=20003's=20doc=20tr?= =?UTF-8?q?ail=20=E2=80=94=20status=20resolved-for-W1,=20plan=20003=20W1?= =?UTF-8?q?=20AC=20ticked,=20stale-comment=20sweep?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/reviews/003-…alkssh-input.md: Status block now resolved — W1 absorbed (plan 003 §Decisions 1–4 + ADR-008 Amendment 2); W2/W3 pointed at the plan's §W2/§W3, open until those repos land - docs/plans/003-…: status header planned → W1 landed (W2/W3 open); the W1 plan-level AC box ticked; W2/W3 + family-coherence boxes left unticked (sibling-repo sessions) - Stale-comment sweep (src/ + docs/architecture/) aligned three stragglers still riding the pre-amendment miss vocabulary: - src/producer.rs: the accept-loop arm's "correlation miss → handler_error-class" comment → the typed unknown_resource open_failed under the establisher variant (Amendment 2) - wire.md §The Forwarded Op reply/errors: the miss is the typed unknown_resource open_failed (establisher variant); base shape's in-session miss = the assembly-side post-open decline, correlation-miss at debug - producer.md §The Forwarded Op: "no establisher" → the two-shape posture (Amendment 2 pointer); last_updated bumped Verification: cargo test (14 suites, 0 failures), clippy --all-targets -D warnings clean, cargo fmt --check clean, cargo doc --no-deps clean. --- docs/architecture/producer.md | 18 ++++-- docs/architecture/wire.md | 12 +++- docs/plans/003-correlation-miss-resolve.md | 10 +++- ...elation-miss-arrival-class-alkssh-input.md | 31 +++++++--- src/producer.rs | 11 +++- tasks/tunnels/corrmiss-doc-sync.md | 56 ++++++++++++++++--- 6 files changed, 111 insertions(+), 27 deletions(-) diff --git a/docs/architecture/producer.md b/docs/architecture/producer.md index 627765c..3c61ac5 100644 --- a/docs/architecture/producer.md +++ b/docs/architecture/producer.md @@ -1,6 +1,7 @@ --- status: draft -last_updated: 2026-09-18 (the direct op, the bind-first establisher, the forwarded op — ADR-007/008 as amended: the correlation token) +last_updated: 2026-11-03 (the forwarded op's serving-side establishment + phase + the correlation-miss vocabulary — ADR-008 Amendment 2) --- # alktunnels — Producer Half @@ -232,12 +233,16 @@ JoinHandle<()>`): whether the halves came from TCP, UDP, a unix socket, or an in-process pipe, and must not (AGENTS.md convention 7). -## The Forwarded Op (opener side, ADR-008 §3) +## The Forwarded Op (opener side, ADR-008 §3 as amended by Amendment 2) Accept-as-open: when the bind-first listener accepts, the PRODUCER opens a channel back toward the listen opener. The opener SERVES the op (`channels/tunnel/forwarded`, scope `tunnel:forwarded` — ingress; -no establisher, the data plane starts immediately): +Amendment 2's two serving shapes: the recommended correlation-gate +establisher variant — a stale/missing token fails the open as a +typed `channel:open_failed`/`unknown_resource` before the channel +is born — or the base establisher-less shape, the data plane starts +immediately and the assembly's post-open decline owns the miss): 1. The producer's per-accept open carries `{listen, substrate, peer}` — the correlation token from the plan (the value the establisher @@ -253,7 +258,12 @@ no establisher, the data plane starts immediately): 3. The opener-side handler correlates the open (via `listen`) to the waiting session (assembly-side bookkeeping — the protocol provides the op and params, not the wait state machine), accepts the - `BiStream`, and pumps against the local session's halves. + `BiStream`, and pumps against the local session's halves. Under + the establisher variant (Amendment 2) that correlation lookup + rides the gate at establisher time instead — the handler-side + correlation remains only for the narrow residual race (a token + vanishing between gate pass and handler run; the miss class is + named `correlation-miss` at `debug`, assembly-side). 4. Identity: the forwarded op's opener-side gate sees the PRODUCER's per-call identity (CF-005 precedence — the producer may carry an `auth_token` when it is itself forwarding); the peer address in diff --git a/docs/architecture/wire.md b/docs/architecture/wire.md index 6da18c4..3155827 100644 --- a/docs/architecture/wire.md +++ b/docs/architecture/wire.md @@ -201,10 +201,16 @@ Scope gate (opener side): `["tunnel:forwarded"]` - Success: `{ "channel_id": }` — the opener-allocated ID the producer adopts, then pumps the accepted halves against. -- Failure: a producer-side accept correlation miss is the typed - `channel:open_failed`/`handler_error`-class error; an opener without +- Failure: a stale/missing correlation token is the typed + `channel:open_failed` with `details.reason = "unknown_resource"` + (the establisher variant, ADR-008 Amendment 2 — the recommended + serving shape; the miss never births a channel). An opener without the scope is `FORBIDDEN`; an old opener that does not serve the op - rejects loudly (`NOT_FOUND` — the SSH posture). + rejects loudly (`NOT_FOUND` — the SSH posture). Other open failures + ride the existing typed vocabulary. Under the base (establisher- + less) serving shape an in-session miss produces no call error — it + is the assembly-side post-open decline (the channel reaps at + birth, `correlation-miss` at `debug`). ## The Data Plane diff --git a/docs/plans/003-correlation-miss-resolve.md b/docs/plans/003-correlation-miss-resolve.md index cbeca7c..b4bffb5 100644 --- a/docs/plans/003-correlation-miss-resolve.md +++ b/docs/plans/003-correlation-miss-resolve.md @@ -1,7 +1,11 @@ # Plan — resolve review 003: the correlation-miss arrival class -Status: planned (2026-11-03). Resolution of -`docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md`, +Status: W1 landed (2026-11-03) — ADR-008 Amendment 2, the +`…_with_establisher` surface, the gate tests, and the review/checkpoint ++ doc sync done. W2 (alkssh) / W3 (alksocks) are open: sibling-repo +sessions, unticked until those repos land. Resolution of +`docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md` +(also kept: it records the tri-vocabulary decision's ground), including the verification caveats found in this session (see §Verified findings — they extend the review, do not contradict it). @@ -109,7 +113,7 @@ and is otherwise out of scope here. ## Acceptance criteria (plan level) -- [ ] W1: ADR landed; `…_with_establisher` surface landed; tests green +- [x] W1: ADR landed; `…_with_establisher` surface landed; tests green (`cargo test`, clippy `--all-targets -D warnings`, fmt, wasm check; `--all-features` as far as features exist today); review 003 status updated to resolved (W1 absorbed; W2/W3 pointed). diff --git a/docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md b/docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md index 98f5252..089c99e 100644 --- a/docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md +++ b/docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md @@ -2,13 +2,30 @@ ## Status -Open — filed 2026-10-31. Consumer input from alkssh 0.1.0 (published -2026-10-31), under the family's upstream posture (file asks, never -absorb silently). Booked alkssh-side at its wave-3 review gate (item 5) -as "mapping.md's recorded event-vocabulary nuance for the unreachable -mismatch arms (`correlation-miss` naming)" and carried unabsorbed -through the alkssh 0.1.0 release (`docs/plans/implementation.md`, -"Still booked with their owners"); this is that filing. +**Resolved — W1 absorbed in alktunnels (2026-11-03); W2/W3 pointed at +the sibling repos.** The ask rode +`docs/plans/003-correlation-miss-resolve.md` §Decisions 1–4 and ADR-008 +Amendment 2 (`docs/architecture/decisions/008-listen-metadata-forwarded-op.md`): + +- The forwarded op's serving side gained a correlation-gate establisher + variant (`register_tunnel_forwarded_openable_with_establisher`): a + stale/missing token fails the open as a typed + `channel:open_failed` with `details.reason = "unknown_resource"` + before the channel is born — framing question 2 answered (the class + rides the existing typed vocabulary; `unknown_resource` reused, no + wire extension). +- Framing question 1 answered: `correlation-miss` (alkssh's shipped + name — published wins) is the canonical event name for the residual + post-open decline class; framing question 3's posture is recorded: + declines at `debug`, assembly-side; the producer-side generic arm + stays `warn`, now carrying the typed reason. +- The base (establisher-less) serving shape stays byte-for-byte for + compatibility + as the residual-race fallback. + +**W2 (alkssh) and W3 (alksocks) are the sibling repos' adoption waves +and remain open** — pointed at +`docs/plans/003-correlation-miss-resolve.md` §W2/§W3; the plan's +plan-level AC records them unticked until those repos land. Doc-only in code impact. No wire contract, no API shape, no ACL behavior rides it — the ask is observability vocabulary alignment at diff --git a/src/producer.rs b/src/producer.rs index ce93e29..103fb26 100644 --- a/src/producer.rs +++ b/src/producer.rs @@ -839,9 +839,14 @@ pub fn make_bindfirst_accept_handler( // Per-accept isolation: the // forwarded open failed (scope- // less opener → FORBIDDEN; old - // opener → NOT_FOUND; correlation - // miss → handler_error-class) — - // drop this accepted connection, + // opener → NOT_FOUND; a stale/ + // missing token → the typed + // `unknown_resource` open_failed + // under the serving side's + // establisher variant, ADR-008 + // Amendment 2; other establisher + // failures → handler_error-class) + // — drop this accepted connection, // keep serving. v1: no retry/ // backoff (documented posture). tracing::warn!( diff --git a/tasks/tunnels/corrmiss-doc-sync.md b/tasks/tunnels/corrmiss-doc-sync.md index 472442e..aec0d1b 100644 --- a/tasks/tunnels/corrmiss-doc-sync.md +++ b/tasks/tunnels/corrmiss-doc-sync.md @@ -1,7 +1,7 @@ --- id: tunnels/corrmiss-doc-sync name: "Doc sync: review 003 status + plan 003 checkboxes + plan-level AC close-out (W1)" -status: pending +status: completed depends_on: [tunnels/corrmiss-review] scope: narrow risk: trivial @@ -37,13 +37,13 @@ checkpoint are landed. ## Acceptance Criteria -- [ ] Review 003's Status block reads resolved-for-W1 with the W2/W3 +- [x] Review 003's Status block reads resolved-for-W1 with the W2/W3 pointer -- [ ] Plan 003's W1 acceptance clauses ticked; W2/W3 left visibly +- [x] Plan 003's W1 acceptance clauses ticked; W2/W3 left visibly open -- [ ] A stale-comment sweep across `src/` + `docs/architecture/` ran +- [x] A stale-comment sweep across `src/` + `docs/architecture/` ran clean (or the stragglers aligned) -- [ ] `cargo doc --no-deps` clean (doc edits touch lib.rs-adjacent +- [x] `cargo doc --no-deps` clean (doc edits touch lib.rs-adjacent comments only if the sweep found any) ## References @@ -57,8 +57,50 @@ checkpoint are landed. ## Notes -> To be filled by implementation agent +The sweep grep (`correlation miss` / `correlation-miss` / +`handler_error`-class across `src/` + `docs/architecture/`) found the +two-shape posture docs already synced by the earlier trio (the +`make_forwarded_op_handler` doc, both registration docs, the gate +establisher doc, wire.md §The Forwarded Op's registration paragraph, +the ADR amendment itself). Three STALE spots found and aligned: + +- `src/producer.rs:838-854` (the bind-first accept loop's failed-open + arm): the in-comment class-distinction still read + "correlation miss → handler_error-class" — the exact prose review + 003 flagged. Reworded: a stale/missing token is now the typed + `unknown_resource` open_failed under the serving side's establisher + variant (ADR-008 Amendment 2); other establisher failures ride + handler_error-class. (Deliberately a comment-update, not removal — + the class distinctions are the arm's working notes; convention 1's + removal rule is for pointers at superseded designs, and this one + now points at the current one.) +- `wire.md` §The Forwarded Op "Reply / errors": "a producer-side + accept correlation miss is the typed + `channel:open_failed`/`handler_error`-class error" — pre-amendment + attribution. Now records the amendment posture: the miss is the + typed `unknown_resource` open_failed (establisher variant, + recommended); under the base shape an in-session miss produces no + call error — the assembly-side post-open decline, + `correlation-miss` at `debug`. +- `producer.md` §The Forwarded Op: "(ADR-008 §3) … no establisher, + the data plane starts immediately" — now the two-shape posture with + the Amendment 2 pointer; the correlate step notes the gate rides + the establisher with the handler-side correlation as the residual + fallback. `last_updated` header bumped. ## Summary -> To be filled on completion \ No newline at end of file +Review 003's Status block now reads resolved-for-W1: the ask absorbed +via plan 003 §Decisions 1–4 + ADR-008 Amendment 2 (typed +`unknown_resource` open_failed at the gate; `correlation-miss` at +`debug` for the residual decline; `unknown_resource` reused, wire +vocabulary unextended), with W2 (alkssh) / W3 (alksocks) pointed at +the plan's §W2/§W3 and recorded as open. Plan 003's status header is +"W1 landed; W2/W3 open (sibling repos)" and only the W1 plan-level AC +box is ticked — W2/W3 and the family-coherence box stay untouched +until those repos land. The stale-comment sweep aligned three +stragglers (the accept-loop arm's comment, wire.md's failure line, +producer.md's forwarded-op section); everything else already carried +the two-shape posture. Verification: `cargo test` (14 suites, 0 +failures), clippy `--all-targets -- -D warnings` clean, +`cargo fmt --check` clean, `cargo doc --no-deps` clean. \ No newline at end of file