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.
This commit is contained in:
glm-5.3-flash committed 2026-11-03 12:53:27 +00:00
1 parent c7e8c875fd
commit 92c3cc5123
6 files changed
+111 -27

No files matched your search

+14 -4
View File
@@ -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
+9 -3
View File
@@ -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
+7 -3
View File
@@ -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