alkssh/docs/architecture/decisions/006-mapping-bridge-and-dispatch.md

status, last_updated

status	last_updated
draft	2026-10-26

ADR-006: Mapping decisions — route-1 bridge, exec-only git, SOCKS dispatch

Status

Accepted — 2026-10-26. All three decisions are POC-3-validated against published sibling crates; amendments are new ADRs.

Context

mapping-table.md left three choices explicit for the architecture pass: which of alktunnels' two routes serves direct-tcpip; whether git over SSH has a subsystem path; and the session-channel dispatch shape when one channel type serves both parseable commands and SOCK5-in-channel traffic. POC-3 resolved all three by construction (real git 2.43, real curl 8.5, real OpenSSH through published alkgit/alksocks/alktunnels/alktty).

Decision

1. direct-tcpip rides the adapter-side bridge (alktunnels route 1). alkssh holds a ChannelClient into the family fabric and calls TunnelSession::open_direct(client, target, substrate), pumping take_halves() against the russh channel (channel_open_direct_tcpip → accept only after the fabric open succeeds → copy bidirectional). POC-3 stage C proved it end to end (8 MiB in ~333 ms; fabric-open failure maps to an explicit SSH ConnectFailed reject — accept happens only post-success, since accept() consumes the handle). Registry-side bridging (route 2: alkssh-shaped ChannelOperations in a serving endpoint's registry) is rejected: it inverts the door posture by putting adapter work upstream of the door. The alktunnels absence note (no serve-over-stream entry) is thereby resolved — route 1 never needed one.
2. Git over SSH is exec-only; every subsystem request declines. The vanilla git connection model is: git spawns its ssh transport, which opens one session channel and sends exec_request "git-{upload,receive}-pack '/repo'" — the repo path rides inside the command string, so a subsystem request (name only, no repo id) can never dispatch. POC-3 proved the parse grammar (quoted/unquoted paths, service-only → decline, non-git → parse-then-fail with no resource alloc) and clone/push/second-push through the published seam with zero fixups. Vanilla git behavior loses nothing — vanilla git never speaks subsystem for git; the decline only refuses a manual ssh -s-style invocation, with a reason.
3. Session-channel dispatch: request-driven parse wins; detect covers the request-less case. The two POC-3 modes compose thus:
   • a session channel that receives exec_request / pty_request / shell_request takes the parse path first (git parse under git; else pipe/shell under session);
   • a session channel that receives no request (the family-native SOCKS shape — a client speaking SOCKS5 in-band) runs the SOCKS-detect under dynamic-forward: spawn, first- byte sniff (0x05), bounded window — 500 ms default, assembly-configurable, silent or non-SOCKS → decline (logged);
   • the detect never runs when the channel got a request, and the parse never runs on a request-less channel. One channel, one route, decided by what actually arrives. This resolves OQ-02 (the composition was the unknown; the window bound and configurability are now records, not questions).
4. The spawn-and-return rule is a structural constraint, not an implementation detail. russh 0.64.1-era servers run handler callbacks inline inside the session's packet loop — a blocking handler deadlocks against the peer's follow-up bytes (POC-3 proved by construction: receive-pack pushes bytes immediately after the exec request). Every serving path is tokio::spawn + handler-returns-fast; exit reporting from the spawned task rides the cloned Session::handle() — exit-status(then close) before channel close, exit-signal for signal termination (signal-name fidelity: OQ-10).

Consequences

• Positive: every one-seam-per-mapping row now has its route recorded; the OQ list loses its highest-priority pending item; the alkforge assembly gets an exact wiring recipe (POC-3 §C.4's in-process fabric leg is the template, verbatim).
• Negative: the 500 ms detect window is a tunable that can be misconfigured (too low: false declines on slow clients; too high: slow-fail paths) — it is bounded and configurable by design, and the decline is logged.
• Neutral: route 2 remains documented in mapping-table.md as the rejected alternative, with its rationale — useful if the posture is ever revisited (that revisit is an ADR, not a code flip).

References

• docs/research/poc-3-mapping-bakeoff.md (stages A–C: all three decisions' evidence; §C.4 the fabric wiring recipe)
• mapping-table.md (the rows + the absence note this ADR resolves)
• ADR-003 (the feature gates these dispatch decisions sit behind)
• docs/research/reverse-runner.md (the client-direction mirror of leg 1 — the -L/-R legs the same route-1 bridge serves)
• OQ-02 (resolved by this ADR), OQ-10 (exit-signal fidelity, open)