docs(review): alkssh consumer input — the correlation-miss arrival class, event-vocabulary alignment at the forwarded-arrival boundary

docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md

@@ -0,0 +1,91 @@
+# Review 003 — The correlation-miss arrival class: alkssh consumer input on the forwarded-arrival event vocabulary
+
+## 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.
+
+Doc-only in code impact. No wire contract, no API shape, no ACL
+behavior rides it — the ask is observability vocabulary alignment at
+the arrival boundary, so a composed deployment's traces name the same
+failure the same way in both crates.
+
+## The situation
+
+The `-R` leg composes across this crate's fabric and the door's
+arrival handling. A `forwarded-tcpip` / `forwarded-streamlocal`
+arrival can outlive its correlation partner on either side, and each
+crate currently names the resulting class differently:
+
+- **alkssh's door side** (verified at `src/tunnel_map.rs`): the shared
+  per-fabric-leg `ListenRouter` removes a session's tokens at
+  teardown (the handler's `Drop`), so a fabric arrival for a token
+  that no longer routes — or an echo-shape mismatch against the held
+  route — is the **`correlation-miss`** class:
+  `observe::decline_arrival(row, "correlation-miss", listen)` +
+  teardown-at-birth, never a half-open SSH channel (also the
+  `cap-exceeded` sibling class on a routed-but-full arrival).
+- **alktunnels' fabric side** (`src/producer.rs`, the bind-first
+  accept loop): a forwarded open that fails against a stale/expired
+  token lands in the generic failure arm — warn
+  `"tunnel bind-first: forwarded open failed; dropping the accepted
+  connection"`, drop, keep serving. The comment records the class
+  distinctions ("scope-less opener → FORBIDDEN; old opener →
+  NOT_FOUND; correlation miss → handler_error-class") — i.e. the
+  distinction exists as a code comment and flows into the generic
+  `handler_error` typed class (the producer error-mapping tables use
+  `dial_failed` / `resource_shortage` / `unknown_resource` /
+  `handler_error`).
+
+The mismatch arms are the "unreachable" ones in a healthy run — a
+vanilla client never initiates `forwarded-tcpip` (an inbound open is
+the unvanilla class, declined), and a correlation miss requires a
+fabric arrival racing its session's teardown — which is exactly why
+the naming was left unsettled during implementation. But when it does
+happen (teardown races, retries, a hub relaying arrivals after a
+door restart), it is an operator-visible event and the one place a
+composed `-R` deployment's logs mix vocabularies: alkssh-side the
+trace says `correlation-miss`, fabric-side it says
+`handler_error` at warn level with the distinction recoverable only
+from prose in a comment.
+
+## What a resolution decides (framing, not prescription)
+
+1. The shared name and semantics for the stale-token arrival class —
+   alkssh's `correlation-miss` is a candidate already shipped in a
+   published consumer's events; adopting it (or ruling a different
+   canonical name) is this repo's call.
+2. Whether the class distinction rides the typed error vocabulary
+   (e.g. a `unknown_resource`-adjacent class for the stale-token
+   forwarded open, which the bind-first arm could surface without
+   behavior change) or stays a logging convention.
+3. Whether the bind-first failure arm's level/posture aligns with the
+   door's (alkssh logs these declines at `debug` under its decline
+   classes; alktunnels logs the generic arm at `warn`). Either answer
+   is fine; the value is that it becomes recorded posture rather than
+   two undocumented choices.
+
+## References
+
+- alkssh `src/tunnel_map.rs` — the `ListenRouter` doc (tokens removed
+  at session teardown; "a fabric arrival after the session is gone is
+  the correlation-miss class") and the `decline_arrival` sites
+  (`correlation-miss`, `cap-exceeded`)
+- alkssh `src/observe.rs` — the door's field/level vocabulary (rows,
+  `decline_class`, `reason`; declines at `debug`)
+- alkssh `docs/architecture/mapping.md` — the `forwarded-tcpip` row
+  ("correlation-miss → teardown-at-birth") and the request-level `signal`
+  row's fidelity notes (OQ-10 lineage)
+- alkssh `tasks/implementation/review-wave-3.md` item 5 and
+  `docs/plans/implementation.md` ("Still booked with their owners") —
+  the original booking
+- `src/producer.rs` — the bind-first accept-loop failure arm (the
+  in-comment class distinction) and the establisher error-mapping
+  tables (`docs/architecture/producer.md` shape 3, ADR-008)
+- ADR-008 (bind-first + forwarded op; the mint discipline whose
+  staleness races this class guards)