docs: UDP tunnel POC summary — shape validated end-to-end

17 tests pass (7 codec + 10 integration). The producer/consumer
shape, ADR-049 establishment integration, codec decision, and typed
establishment errors all validated over alkcall 0.5.0 channels.

Key findings folded into the ledger:
- OQ-TN-05 resolved for stream substrates: no backend trait —
  pump_halves generic over boxed halves (TCP into_split, UDP
  UdpHalf adapter); remaining thread is only the hub re-produce
  composition question
- OQ-TN-06 convergence test satisfied: producer pump and consumer
  pump are the same shape modulo channel side; extraction decidable
  in Phase 1
- New finding for the alkcall ledger: OpenHandler JoinHandle
  semantics are load-bearing and undocumented — a handler that
  returns before the data plane starts tears the channel down at
  birth (the POC found this by hanging; the pump must be awaited
  inline). Plus: Establishment should carry the channel plan
  (the reserved extension point) to kill the establisher handoff
  side-channel
- UdpHalf truncation semantics flagged for the Phase 1 ADR
  (recommend fail-loud over silent truncation)

POC crate: /workspace/alktunnels-udp-poc (db224cc).
This commit is contained in:
2026-09-07 07:53:39 +00:00
parent 20672be48c
commit 6beabe9457
2 changed files with 351 additions and 8 deletions
+33 -8
View File
@@ -512,12 +512,15 @@ so the question:
surface as-is? If a helper is warranted, it may share shape with the
substrate dial/listen trait — which would argue for the trait.
**Status:** open — needs a survey of what backends would actually
implement (local TCP? docker exec? ssh -w?) before deciding trait vs
no-trait. Half-answer (hunch): a thin trait (or just a fn alias) for
"obtain a bidirectional substrate stream for a target," possibly no
trait at all if the only meaningful backends are local sockets — decide
after surveying candidate backends.
**Status: resolved for stream substrates, 2026-09-06 (POC).**
`pump_halves` is generic over `(AsyncRead, AsyncWrite)` halves — TCP
contributes `into_split()` halves, UDP contributes the `UdpHalf`
socket adapter, the pump never knows which. "Produce boxed halves for
a resource" is a function, not a trait; the `TunnelBackend` trait
question resolves to *no trait* for substrate access. The only
remaining thread is the hub re-produce composition question (above) —
a Phase 1 spec question, and now decidable against the validated
producer/consumer surface.
### OQ-TN-06: The two-pump helper — extract now?
@@ -539,6 +542,13 @@ consumer (POC tunnel was the first; SSH `direct-tcpip` would be a third).
not a blocker for the spec. Half-answer: the helper probably belongs
upstream (alkcall, near the channels-adapter handler-integration
conventions) but only if the two shapes genuinely converge.
**Convergence input 2026-09-06 (POC):** the producer pump
(`pump_halves`) and the consumer pump (`take_halves` + copy) are the
same shape modulo channel side — the ADR-078 convergence test is
satisfied; extraction is decidable in Phase 1. Also surfaced by the
POC: the `OpenHandler` JoinHandle semantics (see `poc-summary.md` §
Issues Surfaced #1) are where such a helper would pin the teardown
contract.
### OQ-TN-07: ALPN strategy
@@ -707,6 +717,10 @@ Phase 0 may need (in rough priority order, per the SDD process's
fit: chunk-size vs datagram-size interaction, MTU cap against the
channels bounded buffers, idle-expiry mapping, and the chosen
endpoint-addressing shape. Derisks OQ-TN-02 (and OQ-TN-07's option B).
**Done 2026-09-06** — see `poc-summary.md`. 17 tests pass; the
producer/consumer shape validated end-to-end over alkcall 0.5.0
(establisher + two-pump + codec + typed establishment errors).
2. **Reverse-flow POC**`-R`-style: the accept side listens, the far
side carries. Derisks OQ-TN-03's advertisement/lifecycle shape.
Template available: SSH's `tcpip-forward` global-request
@@ -807,7 +821,18 @@ Candidate reading for the research specialist (to be expanded):
OQ-TN-05 trait shape
- [ ] Decision input: backend trait vs no-trait (OQ-TN-05), now
including the hub re-produce composition question
- [ ] Targeted POC(s) run + summary (OQ-TN-10) — UDP first, reverse
flow second
- [ ] Targeted POC(s) run + summary (OQ-TN-10) — UDP POC DONE
(2026-09-06, `poc-summary.md`); reverse-flow POC remains
- [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
alknet ADR-078 convergence test is satisfied, extraction now
decidable in Phase 1
- [x] OQ-TN-05 executable input (backend trait vs no-trait) — POC
confirms stream substrates need no trait: `pump_halves` is
generic over boxed halves (TCP `into_split`, UDP `UdpHalf`
adapter); "produce halves for a resource" is a function. The
hub re-produce composition question is the only remaining
OQ-TN-05 thread
- [ ] Open questions promoted to Phase 1
`docs/architecture/open-questions.md` with statuses