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:
@@ -150,9 +150,10 @@ OQ-TN numbering. Format per `docs/sdd_process.md`.
|
||||
- **Priority**: low
|
||||
- **Status**: resolved — UDP POC DONE (2026-09-06, 17 tests),
|
||||
reverse-flow POC DONE (2026-09-07, 14 tests; re-validated over
|
||||
alkcall 0.7.0, 16 tests). #3 (unix/stdio) folds into the real
|
||||
crate's test suite (pump agnosticism confirmed twice); #4 (helper
|
||||
spike) resolved by alkcall ADR-050. Findings F-1 (plan payloads
|
||||
alkcall 0.7.0, 16 tests). #3 split (OQ-TN-14): unix ships with the
|
||||
`local` feature; stdio is OUT — alktty's pipe mode owns process
|
||||
stdio (exit codes + signals are tty semantics). #4 (helper spike)
|
||||
resolved by alkcall ADR-050. Findings F-1 (plan payloads
|
||||
`Send + Sync` — documented upstream) and F-2 (UDP codec mandatory)
|
||||
recorded; W1 filed upstream and RESOLVED (CF-005/CF-006).
|
||||
- **Cross-references**: ADR-003, OQ-TN-05, OQ-TN-06
|
||||
@@ -215,13 +216,27 @@ OQ-TN numbering. Format per `docs/sdd_process.md`.
|
||||
### OQ-TN-14: Unix-socket and stdio substrate placement
|
||||
|
||||
- **Origin**: OQ-TN-10 #3 (the cheap un-POC'd item)
|
||||
- **Status**: open
|
||||
- **Priority**: low
|
||||
- **Impacts**: the `local` feature's module surface (whether unix
|
||||
dial/listen helpers ship in v1); not a wire/ADR question (the wire
|
||||
enum already carries `unix` per ADR-001).
|
||||
- **Resolution**: pending — both POCs confirm pump agnosticism; unix
|
||||
is cheap (same halves shape as TCP); stdio bridging is a different
|
||||
lifecycle (no dial — the pipe IS the resource). Fold into the
|
||||
backend module task; unix leans yes for v1, stdio leans deferred.
|
||||
- **Cross-references**: ADR-003, ADR-004, overview.md
|
||||
- **Status**: **resolved 2026-09-07 (split by substrate):**
|
||||
- **Unix: in scope for the `local` feature v1** — same halves shape
|
||||
as TCP (`dial_unix`), cheap, wire enum already carries `unix`
|
||||
(ADR-001). Implemented by `tunnels/local-socket-halves`.
|
||||
- **Stdio: OUT of scope — alktty owns it.** A spawned process's
|
||||
stdin/stdout/stderr IS a terminal session in alktty's model:
|
||||
`LocalTtyBackend`'s pipe mode (`tokio::process::Command` +
|
||||
`Stdio::piped()`, alktty `tty-local.md`) is exactly the stdio
|
||||
case — 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 (exit code, signals — a byte
|
||||
tunnel has neither). Consumers needing to run commands remotely
|
||||
compose: alkcall dial → alktty session (pipe mode) — the two
|
||||
crates are siblings on the same channels substrate, not
|
||||
competitors. (The OQ-TN-10 #3 "cheap item" was scoped before the
|
||||
sibling relationship was this clear.)
|
||||
- **Impacts**: `tunnels/local-socket-halves` (unix yes, stdio no);
|
||||
the wire enum's `unix` value now has a v1 implementation path.
|
||||
- **Cross-references**: ADR-003, ADR-004, overview.md; alktty
|
||||
`tty-local.md` §pipe mode, alktty ADR-004 (exit code on a control
|
||||
chunk)
|
||||
@@ -101,7 +101,7 @@ alktunnels (default — wasm-clean)
|
||||
└── (no backend deps — sockets/process live in feature-gated modules)
|
||||
|
||||
alktunnels (local feature) — non-wasm by design
|
||||
└── adds: tokio/net (TCP dial, UDP bind/connect, unix sockets — unix pending OQ-TN-14)
|
||||
└── adds: tokio/net (TCP dial, UDP connect, unix sockets — unix per OQ-TN-14)
|
||||
```
|
||||
|
||||
Same posture as alktty: the default crate is protocol-only and
|
||||
@@ -115,7 +115,7 @@ trivial here, since the codec is a 2-byte length prefix).
|
||||
| Feature | Contents | Wasm |
|
||||
|---------|----------|------|
|
||||
| *(default)* | params, wire codec, open-op spec, establisher shapes, `TunnelSession` — protocol only | yes |
|
||||
| `local` | TCP/UDP/unix dial + listen helpers — halves-producing dial/listen functions (ADR-004; unix pending OQ-TN-14) | no |
|
||||
| `local` | TCP/UDP/unix dial + listen helpers — halves-producing dial/listen functions (ADR-004). Unix ships (OQ-TN-14); stdio does NOT — a spawned process's stdio is alktty's pipe mode (exit codes, signals), not a tunnel | no |
|
||||
|
||||
## Module Map
|
||||
|
||||
@@ -157,7 +157,8 @@ Key questions affecting this document:
|
||||
- **OQ-TN-11**: resource naming collision domain + lifecycle (partially resolved)
|
||||
- **OQ-TN-12**: hub re-produce composition helper (deferred(scope))
|
||||
- **OQ-TN-13**: UDP truncation semantics (resolved — fail-loud, ADR-003)
|
||||
- **OQ-TN-14**: unix/stdio substrate placement (open)
|
||||
- **OQ-TN-14**: unix/stdio placement (resolved — unix in via
|
||||
`local`, stdio out: alktty's pipe mode owns process stdio)
|
||||
|
||||
## References
|
||||
|
||||
|
||||
@@ -177,8 +177,8 @@ Tunnels reach local networks — the open gate is the security boundary
|
||||
- **OQ-TN-11**: resource naming collision domain + lifecycle
|
||||
(partially resolved — the per-producer registry is the leading
|
||||
candidate)
|
||||
- **OQ-TN-14**: unix/stdio substrate placement (open — backend module
|
||||
task, not a wire question)
|
||||
- **OQ-TN-14**: resolved (split: unix in, stdio out — alktty's pipe
|
||||
mode owns process stdio; see open-questions.md)
|
||||
|
||||
## References
|
||||
|
||||
|
||||
@@ -35,6 +35,10 @@ this document is the normative WHAT.
|
||||
(NOT an address; the producer's registry maps it to its backing).
|
||||
- `substrate`: string, required, enum `["tcp", "udp", "unix"]` — the
|
||||
extensible discriminator (ADR-001); selects the data-plane framing.
|
||||
The schema ships with all three values in v1 (unix has an
|
||||
implementation path — OQ-TN-14). An older producer rejecting a
|
||||
newer substrate value is the SSH "unknown channel type" posture —
|
||||
loud, not silent.
|
||||
- `input_schema` pins both as required strings; unknown substrate
|
||||
values fail schema validation (typed error — loud, not silent).
|
||||
- Extensibility: a new substrate is a new enum value, not a format
|
||||
|
||||
@@ -886,10 +886,11 @@ Candidate reading for the research specialist (to be expanded):
|
||||
(2026-09-07, `reverse-poc-summary.md` — the `-R` shape validated
|
||||
end-to-end over alkcall 0.6.0, re-validated over 0.7.0 with the
|
||||
CF-005/CF-006 identity remediation; findings F-1/F-2; W1 filed
|
||||
upstream and RESOLVED). Remaining items (#3 unix/stdio, #4
|
||||
helper spike) are spec-scope: #3 folds into the real crate's
|
||||
tests (pump agnosticism confirmed twice), #4 resolved by
|
||||
alkcall 0.6.0 (ADR-050)
|
||||
upstream and RESOLVED). Remaining items resolved in Phase 1:
|
||||
#3 split — unix ships with the `local` feature (OQ-TN-14);
|
||||
stdio is OUT (alktty's pipe mode owns process stdio — exit
|
||||
codes + signals are tty semantics); #4 resolved by alkcall
|
||||
0.6.0 (ADR-050)
|
||||
- [x] Two-pump helper convergence input gathered (OQ-TN-06) — the POC
|
||||
gives both shapes (producer `pump_halves`, consumer
|
||||
`take_halves` + copy): same shape modulo channel side; the
|
||||
|
||||
@@ -293,7 +293,9 @@ review and ADRs:
|
||||
2. **Unix-socket and stdio substrates** — the OQ-TN-10 #3 "cheap"
|
||||
item. The pump is substrate-agnostic by construction (finding #5);
|
||||
these are wiring, not mechanics. Fold into the real crate's test
|
||||
suite rather than a separate POC.
|
||||
suite rather than a separate POC. (Phase 1 resolution: unix in via
|
||||
the `local` feature; stdio OUT — alktty's pipe mode owns process
|
||||
stdio. OQ-TN-14.)
|
||||
3. **The reverse-flow (`-R`) advertisement** — OQ-TN-10 #2 remains
|
||||
open; the SSH `tcpip-forward` template in the survey is the
|
||||
lifecycle shape to validate there.
|
||||
|
||||
@@ -223,7 +223,9 @@ alktunnels-reverse-poc/
|
||||
listen establisher over the same open op — spec-shaped, not POC-
|
||||
shaped.
|
||||
3. **Unix socket + stdio substrates** — OQ-TN-10 #3 (cheap; the pump
|
||||
is substrate-agnostic and both POCs now confirm it).
|
||||
is substrate-agnostic and both POCs now confirm it). Phase 1
|
||||
resolution: unix in via the `local` feature; stdio OUT — alktty's
|
||||
pipe mode owns process stdio (OQ-TN-14).
|
||||
4. ~~**W1 remediation**~~ — **resolved 2026-09-07 (alkcall 0.7.0)**:
|
||||
the remediation IS now exercised from this POC's topology
|
||||
(transport identity, `ServingConfig.identity` override, precedence,
|
||||
|
||||
Reference in New Issue
Block a user