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

Review 003 — The correlation-miss arrival class: alkssh consumer input on the forwarded-arrival event vocabulary

Status

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 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)