docs: close out review 003's doc trail — status resolved-for-W1, plan 003 W1 AC ticked, stale-comment sweep

- 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.
2026-11-03 12:53:27 +00:00
1 parent c7e8c875fd
commit 92c3cc5123
@@ -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
@@ -201,10 +201,16 @@ Scope gate (opener side): `["tunnel:forwarded"]`

 - Success: `{ "channel_id": <u32> }` — 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

@@ -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).
@@ -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
@@ -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!(
@@ -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
+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.