diff --git a/docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md b/docs/reviews/003-correlation-miss-arrival-class-alkssh-input.md new file mode 100644 index 0000000..98f5252 --- /dev/null +++ b/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) \ No newline at end of file