alktty/docs/architecture/decisions/003-local-backend-placement.md

ADR-003: Local TTY Backend Placement (Single Crate with local Feature)

Status

Accepted (ported from alknet ADR-054 2026-08-17, with the single-crate consolidation recorded as the alktty resolution. Cross-references renumbered to alktty's ADR range — ADR-052→001, ADR-053→002, ADR-054→003, ADR-055→004, ADR-056→005, ADR-057→006, ADR-077→007, ADR-093→008. Alknet ADRs referenced by alknet number (003, 009, 017) are not ported into alktty's ADR range because they are not tty-specific; the alknet originals at /workspace/@alkdev/alknet/docs/architecture/decisions/ remain authoritative.)

Context

The alknet-tty research (DP-1) posed the placement question for the local-process backend (std::process::Command with piped stdio, or portable_pty for a real PTY):

• (a) In alktty: the crate ships with the local backend built-in. Pro: zero-config runner, one crate gets a terminal/process-streaming endpoint. Con: alktty pulls in portable_pty even for deployments that only use docker/ssh backends.
• (b) In a sibling crate (alknet-tty-local): alktty defines the trait (ADR-002); the local backend is a separate crate. Pro: alktty stays dependency-light; consumers opt into the local backend explicitly. Con: one extra crate for the common case.

The local backend is the simplest backend and the one that enables the runner pattern (a process whose stdin/stdout/stderr/exit-code stream over a framed bidi connection — the same shape as GitHub/Gitea Actions runners, just over alk's transport instead of HTTP polling). It has no heavy dependencies in the pipe case — just std — but the PTY case pulls in portable_pty (a non-trivial native dependency that builds on Unix openpty/ioctl and Windows ConPTY).

The relevant constraint from ADR-002: alktty itself depends only on alkcall and the wire-format codec (ADR-001). The portable_pty dependency does not belong in the core tty crate — a docker-only deployment or an SSH-PTY-only deployment should not pull in PTY allocation code. This is the same inversion as OperationAdapter (alknet ADR-017): the trait lives where the types live; the implementations live where their transport dependencies live.

The alknet mono-repo decision (sibling crate + feature re-export)

In the alknet mono-repo, the research recommended (b) sibling crate behind a feature flag on alknet-tty for the common case (features = ["local"] → re-export from alknet-tty-local). This keeps alknet-tty's default dependency surface minimal while making the local backend a one-feature opt-in. The portable_pty dependency lives in alknet-tty-local; alknet-tty itself never depends on portable_pty.

The sibling-crate placement was motivated by a cyclic-dependency workaround: alknet-tty-local depends on alknet-tty for the trait, and alknet ADR-054 wanted alknet-tty to re-export LocalTtyBackend behind a local feature — which cargo rejects (a crate cannot re-export from a sibling crate it depends on via an optional dep AND have that sibling depend back on it). The assembly-layer workaround (consumer depends on both crates directly) worked but was awkward.

The alktty consolidation (single crate, local feature)

alktty is a standalone single crate (not a mono-repo). The cyclic-dep workaround that motivated the alknet sibling-crate decision does not apply: the local backend can live in the same crate as the trait, gated behind a local cargo feature. The feature gate still keeps portable_pty out of the default dependency tree (a docker-only or ssh-only deployment enables neither feature and never pulls in portable_pty); the only thing that changes is the crate boundary.

This ADR records both decisions: the original alknet sibling-crate decision (preserved as the historical context for why the local backend is a separable concern), and the alktty consolidation (the operative decision — the local backend is folded into alktty behind a local feature).

Decision

1. The local backend is folded into alktty behind a local feature

LocalTtyBackend lives in src/local/ (a feature-gated module), implements TtyBackend (ADR-002), and is re-exported as alktty::local::LocalTtyBackend. The local cargo feature pulls in the heavy deps:

# alktty Cargo.toml
[features]
default = []
local = ["dep:portable-pty", "dep:tokio-util", "tokio/process", "tokio/rt-multi-thread"]

[dependencies]
portable-pty = { version = "0.9", optional = true }
tokio-util = { version = "0.7", features = ["io"], optional = true }

A consumer that wants the local backend enables features = ["local"] on alktty and gets alktty::local::LocalTtyBackend. A consumer that only wants docker/ssh backends uses the default features and depends on alknet-docker / alknet-ssh (or their own backend crate) directly — no portable_pty in the dependency tree.

This is the same feature-re-export pattern the Rust ecosystem uses for optional heavy dependencies (e.g., tokio's full feature pulling in tokio-util, h2, etc.). The seam is the TtyBackend trait; the feature gate is the only thing keeping portable_pty out of the default crate. Folding the local backend in is cheaper than the alknet sibling-crate pattern (no cross-crate coordination, no cyclic-dep workaround) and the local backend is small (~1.4k lines) and tightly coupled to the trait.

2. The local backend's dependency tree

alktty (local feature enabled)
├── alktty (default)   (TtyBackend trait, TtyHandle, TtyControl, wire types)
├── alkcall::core      (via alktty's re-export; not direct)
├── portable_pty       (PTY allocation — the heavy dep, here not in alktty default)
├── libc               (signal forwarding — REQ-TTY-02, Unix only)
└── tokio              (process, rt-multi-thread, mpsc, oneshot, AsyncRead/AsyncWrite)

The local feature is inherently non-wasm (portable-pty + tokio::process need a real OS); enabling local on wasm32-unknown-unknown is a build error by design. The default crate (no features) stays wasm-clean — this is what makes the downstream TS/Python adapter story work (a wasm-compiled alktty is the protocol layer for a sandboxed adapter; the local-process backend runs on a real OS, never in a sandbox).

3. PTY vs pipe is a per-session choice, not a per-deployment choice

TtyParams.terminal: Option<TerminalParams> (ADR-002) selects the mode:

• terminal: Some(TerminalParams { ... }) — allocate a real PTY via portable_pty. Terminal semantics: resize (via ioctl(TIOCSWINSZ)), signal delivery to the foreground process group (via libc::kill(-pgid, sig), REQ-TTY-02), escape-sequence handling (the kernel PTY's line discipline). stdout and stderr are merged (kernel PTY property — one output stream from the slave), so TtyHandle.stderr is None.
• terminal: None — pipe mode, no PTY. tokio::process::Command with Stdio::piped() for stdin/stdout/stderr. No resize, no escape-sequence handling, but kill(pid, sig) still works for signal forwarding. stdout and stderr are separate streams, so TtyHandle.stderr is Some. This is the runner case — a command-streaming endpoint with no terminal semantics.

The same LocalTtyBackend serves both; the allocate() call branches on params.terminal. A deployment that only does terminals always sends Some; a deployment that only does runners always sends None; a deployment that does both (a hub that runs agents in PTYs and runs cargo test as a runner) sends the appropriate one per session.

4. The runner pattern is preserved, not specialized

The pipe mode (terminal: None) is the "runner" generalization the research identified: a process whose stdin/stdout/stderr/exit-code stream over a framed bidi connection. This is functionally identical to GitHub/Gitea Actions runners, just over alk's transport instead of HTTP polling:

• A coordinator sends a negotiation frame with { "backend": "local", "tty": null, "cmd": ["cargo", "test"] }.
• The endpoint runs cargo test with piped stdio, streams stdout/stderr chunks back, sends {"type":"exit","code":N} when it finishes (ADR-004).
• The coordinator gets reliable completion notification (the exit control chunk + stream close) — no polling.

The runner-specific API surface (job management, log persistence, task graph integration) is out of scope for alktty. alktty provides the mechanism (a framed byte stream for a process); the runner policy is a downstream crate's job. This ADR commits to preserving the option (terminal: None → pipe mode) and not building runner policy into alktty. See OQ-46.

Consequences

Positive:

• alktty's default dependency surface is minimal (alkcall + the wire-format codec). A docker-only or ssh-only deployment never pulls in portable_pty.
• The local backend is a one-feature opt-in (features = ["local"]) for the common case — a consumer that wants a terminal/runner endpoint with no docker or SSH gets it with one feature flag, not a separate dependency.
• PTY vs pipe is per-session, so one LocalTtyBackend serves terminals and runners. A hub that does both doesn't need two backends.
• The runner pattern is preserved without baking runner policy into alktty. The mechanism is the framed byte stream; the policy is downstream.
• The single-crate placement composes with alknet ADR-003's no-handler-depends-on-another-handler rule: the local backend is in the same crate as the trait, so there is no cross-crate dependency edge to worry about. The docker and SSH backends remain separate crates (real external deps — bollard, russh — and their own resource models).
• The alktty consolidation resolves the alknet cyclic-dep workaround that motivated the original sibling-crate decision. No assembly-layer "depend on both crates directly" pattern; no cargo-rejected feature-re-export-from-an-optional-dep dance.

Negative:

• A consumer that wants the local backend must enable a feature flag (features = ["local"]). Forgetting the flag results in the alktty::local module not existing — a compile error, not a silent miss. This is the standard Rust feature-flag trade and is self-documenting.
• The local feature is non-wasm by design. A consumer that targets wasm32-unknown-unknown must not enable local — the build error is intentional (the local-process backend cannot run in a sandbox). The default crate stays wasm-clean so the downstream TS/Python adapter story works.
• The runner-specific API surface (job management, log persistence) is not in alktty. A downstream crate that wants a full runner builds on the pipe mode + the wire format. This is the right layering (mechanism vs policy) but means a "runner crate" is a separate future deliverable, not part of alktty. See OQ-46.

Door type

Two-way. The single-crate-with-feature-gate placement is reversible: if the local backend ever grows large enough to warrant splitting out (e.g., a future docker or SSH backend shares enough portable-pty bridge code to motivate a shared "blocking-backend bridge" crate), extracting src/local/ into a sibling crate behind the same local feature is mechanical — the trait is the seam, and the feature gate already exists. The cost of reversal is low (the module becomes a crate; the feature gate switches from dep:portable-pty to dep:alktty-local), and no downstream consumer breaks (the alktty::local::LocalTtyBackend path stays valid if the sibling crate re-exports it).

This is a two-way door that is decided (single crate + local feature), not deferred. The decision is made now; the reversal is cheap if a future split warrants it. See alknet ADR-009 §"What this framework is NOT" — door type classifies reversal cost, not urgency.

References

• alknet ADR-003 + Amendments 1 & 2 — crate decomposition rule (the single-crate placement preserves it; the local backend is in the same crate as the trait, not a separate crate that depends back)
• alknet ADR-009 — door-type-as-deferral anti-pattern (this ADR's two-way-door classification is reversal cost, not a deferral)
• alknet ADR-017 — the adapter-location-map pattern (trait where types live, implementation where deps live) this ADR follows (the local feature is where the deps live)
• ADR-002 — the TtyBackend trait this module implements
• ADR-001 — the wire format the adapter pumps to/from this backend
• ADR-004 — the exit-chunk ordering the local backend's waiter thread feeds
• ADR-005 — the cancel- cleanup contract the local backend's exit_code future's Drop implements
• OQ-46 — runner API surface (deferred(scope): mechanism in alktty, policy is a downstream crate)
• Spec: tty-local.md
• Port origin: alknet ADR-054 at /workspace/@alkdev/alknet/docs/architecture/decisions/054-local-tty-backend-sibling-crate.md