---
status: reviewed
last_updated: 2026-10-28
---

# Mapping — server direction: SSH channels × family seams (the spine)

## The door framing

The server direction is a door *for vanilla clients*: vanilla in,
family out. Vanilla `ssh`/`git` connect as they would to any sshd;
every accepted channel/request maps to **exactly one family protocol
seam** and **exactly one cargo feature** (ADR-003). Rows below are
POC-3-validated against published sibling crates with real vanilla
tooling (OpenSSH 9.6, git 2.43, curl 8.5 — `poc-3-mapping-bakeoff.md`).

## The seams

| Family crate | Serve-over-a-stream entry | Signature shape |
|---|---|---|
| alktty | `drive_session[_pre_negotiated]` | `(impl AsyncWrite, impl AsyncRead, backends, identity)` |
| alkgit | `serve_duplex_resolved` | `(repo_id, identity, service, duplex, limits, backend traits)` |
| alktunnels | — no serve entry (**absence note resolved**: route 1 never needed one, ADR-006) | consumer/open-op registrations |

russh channels convert to duplex via `into_stream`/`split` — the
bridge primitives every mapping uses (POC-1 §7).

## Channel-type rows

| SSH channel type | Vanilla use | Feature | Family seam | Contract notes |
|---|---|---|---|---|
| `session` → `pty_request` + `shell_request` | `ssh host` interactive shell | `session` | alktty: `NegotiateRequest` constructed locally → `drive_session_pre_negotiated` | `pty_request` args → `TerminalParamsWire` (term/cols/rows/pixels; SSH modes → the reserved modes JSON); shell argv = the assembly-supplied serve-config shell (no crate default; unset → `shell_request` declines — OQ-08 resolved); the data plane is a **translation bridge**, not a byte pump — alktty is chunk-framed both directions (stdin/stdout/stderr/CTRL chunks): SSH data→stdin chunks; stdout chunks→SSH data; stderr chunks→`extended_data(1)`; exit chunk→`exit-status`/`exit-signal` + close (POC-3 §D.1) |
| `session` → `exec_request` (non-git) | `ssh host "cmd"` | `session` | alktty pipe mode (`terminal: None`) — separate stderr | the wire's command string → the configured exec wrapper argv with the command appended as final element (`wrapper ++ [cmd]`, OQ-08 — never naively split); wrapper unset → clean decline; stderr rides `extended_data(1)` — only valid without PTY; PTY mode merges (kernel PTY, POC-3 §D.1 proven) |
| `session` → `exec_request` git | `git clone/push ssh://` | `git` | alkgit: parse command → `Service` + repo → `serve_duplex_resolved(repo_id, identity, service, duplex, …)` | **exec-only** (ADR-006 decision 2): the repo rides inside the exec command string (`git-upload-pack '/repo'`); vanilla git never speaks subsystem for git; process-mode dialect (server-speaks-first advertisement); exit-status proven both directions |
| `session` → `subsystem_request` | `sftp` clients; manual `ssh -s` | `sftp` (placeholder) / `git` rows | — | **`sftp` name**: declines until alkfs lands — the feature exists, the route doesn't (OQ-13 resolved: the tested decline placeholder is the shipped behavior until an alkfs-mapping ADR changes it). **git service names**: decline with reason — a subsystem request carries only a name, never a repo id (POC-3 §A.3); never half-serves |
| `direct-tcpip` | `ssh -L`; all `ssh -D` traffic | `tunnel` | alktunnels **route 1**: adapter-side bridge — `TunnelSession::open_direct` on a held `ChannelClient`, pump `take_halves()` vs the channel | target = `SubstrateAddr::HostPort`/`Path`; `Substrate` = Tcp/Unix; accept only **after** the fabric open succeeds — failure maps to an explicit `ConnectFailed` reject (POC-3 §C.2); vanilla `-D`'s dynamic targets dispatch here (POC-3 correction 2) |
| `forwarded-tcpip` | `ssh -R` data channels | `tunnel` | the `register_tunnel_forwarded_openable`'s `ForwardedHandler` shape — hand the channel duplex to the handler | listen flow = the global-request rows below; the data leg is untested in POC-3 beyond refusal (see the POC-3 note below) |
| `direct-streamlocal` | unix-socket forward | `tunnel` | `SubstrateAddr::Path` treatment | compiles wherever `tunnel` compiles; serving is **runtime-Unix-gated** — on Unix serves, on other platforms a clean open-decline (OQ-11 resolved: universal compile + runtime decline, no per-platform feature fork) |
| `x11` | X forwarding | — (never) | — | always declines; not feature-gated (ADR-003 §5) |
| `auth-agent` | agent forwarding | — (never) | — | always declines; the anti-pattern of the alkvault custody posture (ADR-003 §5) |
| `session` → SOCKS5-in-channel | (no vanilla use) | — (retired, ADR-003 §1a) | — | vanilla `-D` is client-side SOCKS + `direct-tcpip`; the family local door is alksocks composed at the assembly — see `client.md` |

## Session-channel dispatch (ADR-006, as amended)

**Parse-only.** A session channel that receives a request takes the
parse path: `exec_request` parses first (a git-parseable command
routes to `git`; anything else to `session`'s pipe path), and
`pty_request`/`shell_request` route to `session`. Request-less session
channels decline as unfeatured. Parsing happens before dispatch and
before any resource allocation — a leaked channel alloc is a
capability leak, so **decline first, alloc never** (POC-3 stage A's
decline matrix is the contract: unknown repo → collapsed generic
denial *before any protocol byte* — no existence oracle; non-git
command → parse-then-fail).

## Global-request rows (the `-R` listen flow)

`Handler::tcpip_forward(address, &mut port) -> bool` +
`Handler::streamlocal_forward` — gate on `tunnel` (decline both the
listen request and the data channels when absent). `streamlocal_forward`
additionally carries the same runtime-Unix gate as its channel row
(OQ-11): off-Unix it declines. The bound-port
out-param (`port = 0` → server picks) is a spec detail in
`client.md`'s lifecycle primitives; disposition follows `tunnel`.
*POC-3 note: only the refusal shape was exercised (egress-only build);
the served listen flow is implementation-phase contract-test territory.*

## Request-level rows on a `session` channel

| SSH request | Family mapping |
|---|---|
| `pty_request` | `NegotiateRequest.tty = TerminalParamsWire{…}` (POC-3 §D.1: live `stty size` honored) |
| `shell_request` | `NegotiateRequest.cmd` = the **assembly-supplied serve-config shell argv** (no crate default; unset → clean decline, never a fallback — OQ-08 resolved; never wire-supplied) |
| `exec_request` | parse → git dispatch (`git`) or alktty pipe `cmd` = exec wrapper argv with the command string appended (`wrapper ++ [cmd]`, OQ-08 — vanilla quoting semantics, never naively split; wrapper unset → clean decline); unknown → `channel_failure`, no resource alloc |
| `subsystem_request` | decline (per the rows table; honest, with reason) |
| `env_request` | **declined unconditionally** (OQ-09 resolved; no allowlist ships) — wire env is not family config |
| `window_change_request` | resize control (POC-3 §D.1: live resize proven) |
| `signal` | signal control (alktty names verbatim); PTY mode reaches the process group, pipe mode is pid-only (backend semantics — fidelity note, OQ-10) |
| data / `extended_data(1)` | the translation bridge (rows table) |
| `exit_status` | from the alktty exit chunk — sent **before** close, from the spawned task via `Session::handle()` (POC-3 §D: proven both legs). Derivation contract rules 1, 3–6 below |
| `exit_signal` | negative exit-chunk codes (the Unix pipe path's signal encoding) → `exit-signal(name)` — derivation contract rule 2; `−1` → `exit-status(255)`, never a signal claim (rule 3). PTY path: signal-terminated children arrive as a plain code 1 (portable-pty's exit surface) → `exit-status(1)` — the signal-identity loss is an upstream alktty/portable-pty constraint (rule 5) |

## Exit chunk → SSH exit reporting (the derivation contract)

The alktty exit chunk (`{"type":"exit","code":N}`, exit-chunk-is-last —
alktty ADR-004, alknet ADR-055 lineage) is the sole fidelity input; the
chunk is **not widened** (any widening needs its own alktty ADR — the
convention is consumed as-is; OQ-10 resolved). Rules, normative for the
`exit_status`/`exit_signal` rows above:

1. **`code ≥ 0`** → `exit-status(N)`.
2. **Negative `−N`, N ≥ 2 (the Unix pipe path's signal encoding)** →
   `exit-signal(name)` via a Unix signal-number→name table (server-side
   work; signal semantics belong to the serving platform, where the
   backend reaps). `core_dumped` is **never asserted** — alktty discards
   `ExitStatus::core_dumped()`, so nothing better is knowable from the
   chunk, and SSH's `exit-signal` bool stays false. (POC-3 §D.2 observed
   the full derivation live: signal TERM → `−15` → `exit-signal("TERM")`.)
3. **`−1` → `exit-status(255)`** (OpenSSH's conventional failure value).
   alktty's could-not-determine sentinel collides with the SIGHUP
   encoding on the Unix pipe path, and this rule accepts the fidelity
   cost symmetrically: neither a fabricated signal for a wait failure
   (a signal that never happened) nor a real one — a *genuine* SIGHUP
   death on the pipe path also reports 255, not `exit-signal("HUP")`.
   If the wait-failure vs SIGHUP distinction ever becomes load-bearing,
   alktty's additive `exit_error` control type is the extension seam
   (recorded in alktty's own ADR); alkssh derives from whatever that
   carries, with no contract change here.
4. **Non-Unix**: no signal termination exists; `−1` is the only
   negative that can appear → rule 3.
5. **The PTY path (fidelity limit, upstream)**: portable-pty 0.9 reaps
   a signal-terminated Unix child as a plain code 1 (the signal number
   is unrecoverable through its trait surface — verified against
   portable-pty 0.9.0's source) → PTY-row signal-terminated sessions
   arrive as `exit-status(1)`. Faithful `exit-signal` there is an
   alktty/portable-pty ask with tty/pty-grounded justification; alkssh's
   contract adapts automatically if the convention ever holds on that
   path. Pipe-mode pid-only vs PTY process-group *scope* (the `signal`
   row note) is backend semantics, not a mapping detail.
6. **Unmapped negatives → rule 3.** The convention's producers are
   `−1` and `−signum` only; a negative value with no entry in the
   signal-name table (defensive case — the mapping never invents a
   name) reports `exit-status(255)`.

## The structural constraint: spawn-and-return

russh (this pin: ADR-002) runs server handler callbacks **inline
inside the session's packet loop** — a blocking handler suspends all
packet routing for the connection (channel data is routed by that
same loop; an inline serve deadlocks against the peer's immediate
follow-up bytes — POC-3 proved by construction with receive-pack).
Therefore: **every serving path is spawned; handlers return fast**;
exit/status reporting from spawned tasks rides the cloned
`Session::handle()`. This is a load-bearing correctness constraint of
the whole spine, not an implementation choice.

## Data-plane / limits

- russh knobs (`window_size`, `maximum_packet_size`,
  `channel_buffer_size`, `Limits`, `inactivity_timeout`,
  `keepalive_*`) + in-crate max-concurrent-channels cap + per-length
  exec-parse limits — per the bounded-resources policy in
  `overview.md`.
- alkcall bridge leg (when the family half is remote): channels-layer
  reassembly cap 1 MiB/channel; ADR-034 grants `alk/ssh` stream_types
  `[0, 1]` because SSH multiplexes internally.
- Honest advertisement: `Config::methods` mirrors implemented auth
  (ADR-004); an unfeatured channel type declines at open, never
  half-opens; vanilla clients observe clean diagnostics (POC-1 §5:
  channel-scoped decline, auth intact, no hangs).

## Decline matrix (per feature build, contract-tested)

| Build | Serves | Declines |
|---|---|---|
| none (default) | — | everything |
| `git` | git-parseable exec | pty/shell, plain exec, all other channel types, all `session` requests |
| `session` | pty/shell/pipe-exec (requires the configured shell/exec wrapper — OQ-08; an unset field declines its row though the feature is on) | git-parseable exec (the `git` parse is its gate), other channel types |
| `tunnel` | direct/forwarded-tcpip, streamlocal (unix), `-R` listens | session channels (auto-reject), all others |
| any build + `sftp` slot | unchanged from the underlying build | `sftp` subsystems decline-with-reason until alkfs |

Every row is tested in *every* build it can appear in — the decline
paths are contract territory (AGENTS.md conventions 5–6), including
under `--all-features`.

## Open Questions

None open or deferred — see [open-questions.md](open-questions.md)
(all of OQ-01…13 resolved). Doc-local contract anchors: OQ-02 (session
dispatch, ADR-006 as amended — §above), OQ-08 (the shell argv / exec
wrapper serve config — `shell_request`/`exec_request` rows and the
`session→pty+shell` channel row), OQ-09 (the `env_request` row),
OQ-10 (§the derivation contract — formalized, upstream constraint
noted there), OQ-11 (`direct-streamlocal` row + the listen-flow gate),
OQ-13 (the `sftp` rows — the decline placeholder is the shipped
behavior).

## References

- ADR-003 (features), ADR-006 (route 1, exec-only git, dispatch),
  ADR-001 (the ALPN/edge context), ADR-004 (auth)
- `docs/research/mapping-table.md` (the validated research ancestor +
  annotations), `poc-3-mapping-bakeoff.md` (stages A–D),
  `poc-1-auth-bridge.md` §5/§7 (decline observability, plumbing)
- Family ADR-003; alkcall ADR-034 (`alk/ssh` stream_types)
- `client.md` (the same door, client-side)