chore: consume alkcall 0.6.0; OQ-TN-06 resolved by ADR-050
alkcall 0.6.0 landed the review 007 remediation (filed from this crate's UDP POC pass): - R-01: Establishment carries the plan (ADR-049 amendment 2) — typed-opaque ChannelPlan, OpenHandler gains the plan param, the wrapper threads it; the POC's side-channel HandleHandoff and its same-resource race are dead (the establisher returns the dialed handle: Ok(Establishment::new(plan))) - R-02: OpenHandler JoinHandle lifetime contract documented (early return = teardown-at-birth) + yield-once acceptance flag and debug! birth-teardown hint - R-03: pump_bidi pinned upstream (ADR-050) — two pumps, shutdown-on-completion, (u64, u64) copy counts, errors EOF-shaped alktunnels updates: - Cargo.toml: alkcall 0.5.0 -> 0.6.0 (lockfile resolves 0.6.0) - AGENTS.md convention 8: use alkcall channels::pump_bidi, do not hand-roll; await it inline inside the OpenHandler's task - AGENTS.md convention 11: pin note updated; amendment 2 marked load-bearing (Establishment::new replaces side-channel handoff) - AGENTS.md convention 13: fixed ADR citation bug (was "alkcall ADR-024, ADR-050" — those are peer-graph-routing and pump-bidi; intended targets are alknet ADR-024/ADR-050 with their alkcall ports ADR-019/ADR-011) - AGENTS.md architecture context: ADR-050 + ADR-049 amendment 2 rows - phase-0-findings OQ-TN-06: RESOLVED — pump_bidi landed upstream; the POC is cited as convergence input alongside alktty and the assembly-layer copies; Phase 1 consumes the helper - phase-0-findings OQ-TN-09: implementation note updated — Establishment::new(plan) replaces the handoff sketch - poc-summary: resolutions addendum for both upstream findings (R-01/R-02/R-03 with the typed-opaque and (u64, u64) deviations recorded); references note 0.6.0 supersession Verification: cargo test (0 tests, ok), clippy --all-targets -D warnings, fmt --check, wasm32 check, doc --no-deps — all clean
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: complete
|
||||
last_updated: 2026-09-06
|
||||
last_updated: 2026-09-07
|
||||
---
|
||||
|
||||
# alktunnels: UDP Tunnel POC Research Summary
|
||||
@@ -10,8 +10,10 @@ end-to-end over alkcall 0.5.0 channels, including the ADR-049
|
||||
establishment phase and the codec decision (raw pass-through for TCP,
|
||||
`[len: u16 BE]` for UDP). 17 tests pass (7 codec + 10 integration);
|
||||
clippy `-D warnings` clean; fmt clean. The remaining unknowns are
|
||||
spec-scope (Phase 1 ADRs), not feasibility.
|
||||
**Date:** 2026-09-06
|
||||
spec-scope (Phase 1 ADRs), not feasibility. Both upstream findings
|
||||
below landed in alkcall 0.6.0 (review 007) — see §Resolutions
|
||||
2026-09-07.
|
||||
**Date:** 2026-09-06 (resolutions added 2026-09-07)
|
||||
**Scope:** Validates the OQ-TN-10 #1 POC (UDP tunnel) — plus the
|
||||
consumer-side of the establisher hand-off (ADR-049), the two-pump
|
||||
pump-handler contract's `JoinHandle` semantics (a real finding — see
|
||||
@@ -247,6 +249,34 @@ substrate access.
|
||||
shape modulo channel side. The convergence test alknet ADR-078
|
||||
asked for is satisfied.
|
||||
|
||||
## Resolutions 2026-09-07 (alkcall 0.6.0, review 007)
|
||||
|
||||
Both upstream findings above landed, with deviations recorded in the
|
||||
review and ADRs:
|
||||
|
||||
1. **JoinHandle semantics (→ R-02)** — documented on the `OpenHandler`
|
||||
type and both `register_openable*` methods: the returned
|
||||
`JoinHandle` must track the data-plane lifetime; the wrapper awaits
|
||||
it and its completion triggers channel teardown. Plus the POC's
|
||||
second ask: a yield-once acceptance flag in
|
||||
`ChannelBidiStreamSource` and a `debug!` birth-teardown hint in the
|
||||
teardown task, so the hang-this-POC-found shape is diagnosable at
|
||||
runtime, not just in docs.
|
||||
2. **`Establishment` carries the plan (→ R-01)** — filled as
|
||||
`Establishment { plan: Option<ChannelPlan> }` with
|
||||
`Establishment::new(plan)`; **typed-opaque** (`ChannelPlan =
|
||||
Arc<dyn Any + Send + Sync>`), not the `Option<Value>` sketch here —
|
||||
the payloads are live handles (dialed sockets, TTY handles) with no
|
||||
JSON representation. The `OpenHandler` gains a `plan` parameter and
|
||||
the wrapper threads it. The POC's `HandleHandoff` side-channel and
|
||||
its same-resource race are dead: the establisher returns the dialed
|
||||
handle directly (`Ok(Establishment::new(dialed))`).
|
||||
3. **Two-pump helper (→ R-03, bonus)** — `alkcall::channels::pump_bidi`
|
||||
pinned upstream (ADR-050), with `(u64, u64)` copy counts (no
|
||||
`io::Result` — errors are EOF-shaped per the ADR-078 contract). The
|
||||
POC's `pump_halves` shape converged and became the helper; Phase 1
|
||||
consumes it instead of hand-rolling.
|
||||
|
||||
## What the POC does NOT validate
|
||||
|
||||
1. **Real transports** — `tokio::io::duplex` stands in for
|
||||
@@ -303,7 +333,9 @@ test udp_and_tcp_concurrent ... ok
|
||||
`ChannelCore::register_openable_with_establisher`,
|
||||
`OpenEstablisher`/`Establishment`/`EstablishmentError`,
|
||||
`ChannelOpenError` (typed client error), `run_open_wrapper`
|
||||
(`src/channels/operations.rs`).
|
||||
(`src/channels/operations.rs`). **0.6.0 supersedes parts:** ADR-049
|
||||
amendment 2 (`Establishment.plan`), ADR-050 (`pump_bidi`), review
|
||||
007 (filed from this POC, all units landed).
|
||||
- alknet ADR-078 — the two-pump shutdown-on-completion contract;
|
||||
`pump_halves` is its direct implementation.
|
||||
- alktunnels `docs/research/phase-0-findings.md` — the OQ ledger this
|
||||
|
||||
Reference in New Issue
Block a user