docs: resolve OQ-TN-14 — unix in via local, stdio out (alktty owns process stdio)

Split the last open substrate-placement question:

- Unix: ships with the local feature v1 (dial_unix — same halves
  shape as TCP; the wire enum already carried unix per ADR-001;
  the params task's schema list includes all three values)
- Stdio: OUT of scope — a spawned process's stdin/stdout/stderr IS
  alktty's pipe mode (LocalTtyBackend + tokio::process + Stdio::piped,
  alktty tty-local.md): three multiplexed logical streams + the
  exit-code control chunk (alktty ADR-004) + signal forwarding
  (REQ-TTY-02). A stdio bridge here would be alktty's runner mode
  with the terminal stripped out — a strictly worse duplicate that
  also drops the semantics that matter (a byte tunnel has neither
  exit codes nor signals). Remote command execution composes via
  alktty on the same channels substrate.

Updated: open-questions.md OQ-TN-14 (resolved), overview.md feature
gate + deps + OQ summary, producer.md OQ ref, OQ-TN-10 promotion
(#3 split), phase-0-findings + both POC summaries' resolution notes,
params task (schema enum includes unix), local-socket-halves task
(unix ships, stdio does NOT — with the composition rationale),
oq-tn-14-tracker task repurposed (boundary-maintenance: re-opens only
if a consumer needs stdio-without-process-semantics — which would
need its own ADR, or if the alktty/alktunnels boundary needs
sharpening).

Verified: taskgraph valid (12 tasks, no cycles)
This commit is contained in:
glm-5.3-flash committed 2026-09-07 19:44:03 +00:00
1 parent 69498b79cc
commit 3a447273a8
10 files changed
+90 -52

No files matched your search

+30 -22
View File
@@ -1,52 +1,60 @@
---
id: architecture/oq-tn-14-tracker
name: "[external-trigger, deferred-oq] OQ-TN-14 unix/stdio placement tracker"
name: "OQ-TN-14 follow-through: unix lands with local v1; stdio stays alktty's"
status: pending
depends_on: []
scope: single
risk: trivial
impact: isolated
level: research
tags: [architecture, deferred-oq, external-trigger, unix, stdio]
tags: [architecture, external-trigger, unix, stdio, alktty]
---
## Description
External-trigger tracker for OQ-TN-14 (`docs/architecture/open-questions.md`
— unix-socket and stdio substrate placement, currently `open` leaning
unix-yes-v1). This task is NOT actionable implementation work; it tracks
whether the unblocking condition has arrived. If the condition arrives, this
task flips the OQ (and the implementation task `tunnels/local-unix-halves`
below) from its deferred/open posture to actionable.
OQ-TN-14 is resolved (open-questions.md, 2026-09-07): unix ships with
the `local` feature v1 (`tunnels/local-socket-halves`); stdio is OUT of
scope — a spawned process's stdio is alktty's pipe mode (exit codes +
signals are tty semantics, not tunnel semantics); remote command
execution composes via alktty.
Unblocking conditions (any one):
This task stays open as the boundary-maintenance tracker (research
level — not implementation work). It re-opens the question only if a
concrete consumer demonstrates the resolved posture is wrong:
1. A consumer needs unix-socket tunneling through alktunnels (a hub exposing
a docker container's unix socket, or a local daemon bridge).
2. The `tunnels/crate-init` task lands and the `local` feature module needs
its v1 surface finalized (the decision point baked into that task).
1. A consumer needs stdio tunneling with NO process semantics (no exit
code, no signals) — e.g. piping an already-running long-lived
process's existing stdio. That is a different resource shape (the
pipe IS the resource, no dial); it would need its own ADR, not a
silent addition to `local`.
2. A consumer reports confusion about when to use alktunnels vs alktty
for a stdio-like flow — the composition boundary in OQ-TN-14 needs
sharpening in the docs, not code.
If neither arrives by the end of the v1 implementation phase, the OQ stays
open and `local` ships TCP+UDP only (the lean posture ADR-004 endorses).
If neither arrives, this task closes with the implementation phase.
## Work
- Re-read OQ-TN-14 + `docs/architecture/overview.md` §Feature Gates when
triaging; confirm whether the unix helper ships with `local` v1.
- Re-read OQ-TN-14 + alktty's `tty-local.md` §pipe mode at triage;
confirm the boundary held (no stdio-shaped resource got registered
as a tunnel resource).
## Verification
- [ ] Tracked (this file existing and being reviewed at triage time IS the
tracking mechanism — no code or doc change is expected until the
condition arrives)
- [ ] Tracked (this file existing and being reviewed at triage time IS
the tracking mechanism — no code or doc change is expected unless
a boundary condition above arrives)
## Out of scope
- Implementing the unix/stdio helpers (see `tunnels/local-unix-halves`)
- Implementing stdio bridging (would need its own ADR per the
conditions above)
## References
- docs/architecture/open-questions.md OQ-TN-14
- docs/architecture/open-questions.md OQ-TN-14 (the resolution)
- alktty `docs/architecture/tty-local.md` §pipe mode (the owner of
process stdio)
- docs/sdd_process.md §Deferred OQs and the blocker-task half
## Notes
+4
View File
@@ -47,6 +47,10 @@ pub struct UdpAssociateHalves { sock: Arc<UdpSocket> } // the POC's associate s
`poll_recv` into a too-small caller buffer must fail loud
(OQ-TN-13's resolved posture — ADR-003). The codec wraps at this
boundary; the pump never sees UDP specifics.
- **Unix**: `dial_unix` ships (OQ-TN-14 resolved — same halves shape
as TCP). **Stdio does NOT** — a spawned process's stdio is alktty's
pipe mode (exit codes + signals are tty semantics, not tunnel
semantics); remote command execution composes via alktty, not here.
- **Error mapping** to `TunnelEstablishError` variants (the POC's
`Into<EstablishmentError>` path).
- `TargetHandle` re-used from producer.rs (the halves type lives in
+8 -7
View File
@@ -34,12 +34,12 @@ pub enum Substrate { Tcp, Udp, Unix }
- `deny_unknown_fields` is the loud-rejection posture (ADR-001: unknown
fields fail schema validation, never silently ignored).
- `Substrate::Unix` is included in the type (the wire enum per ADR-001)
but NOT in the open-op schema's enum list v1 (`["tcp", "udp"]`) until
OQ-TN-14 resolves — an older producer rejecting a newer substrate is
the SSH "unknown channel type" posture; the schema list is the
authoritative gate. Document this asymmetry in the type docs (type
extensible, schema conservative).
- `Substrate::Unix` is included in the type AND in the open-op schema's
enum list v1 (`["tcp", "udp", "unix"]` — OQ-TN-14 resolved: unix has
an implementation path via the `local` feature). The schema list is
the authoritative gate for newer-substrate negotiation: an older
producer rejecting a newer substrate value is the SSH "unknown
channel type" posture (loud, not silent).
### The open-op spec (in producer.rs or params.rs — put it where
`tunnels/producer-open-op` can consume; the spec builder lives in
@@ -56,7 +56,8 @@ pub fn tunnel_open_spec() -> OperationSpec
- `OperationType::Sub`; `Visibility::External`; channel-open marker
`ChannelOpenSpec::new(TUNNEL_ALPN)`.
- `input_schema`: `{resource: string (required), substrate: string enum
["tcp","udp"] (required)}` — JSON Schema Draft shape as the POCs used.
["tcp","udp","unix"] (required)}` — JSON Schema Draft shape as the
POCs used (unix in the list per OQ-TN-14's resolution).
- `output_schema`: `{channel_id: integer > 0}`.
- `AccessControl.required_scopes: [TUNNEL_OPEN_SCOPE]` (ADR-006).
- `description`: a one-line human hint (round-trips through discovery;