--- id: tunnels/review-impl name: Review alktunnels v1 implementation for spec conformance (pre-release gate) status: completed depends_on: [tunnels/end-to-end-suite, tunnels/review-core-crates] scope: moderate risk: low impact: project level: review tags: [review, phase-gate] --- ## Description Review the v1 implementation against the architecture spec before any publish consideration. This is the phase-gate review (the SDD process's review-injection point at the end of the critical path): the wire surface (ADR-001/002/003) is a one-way door, and the API surface (ADR-005/006) becomes ABI-stable once a consumer exists. ### Review checklist 1. **Wire conformance** (wire.md + ADR-001/002/003): - params shape exact (`{resource, substrate}`, `deny_unknown_fields`, schema enum without `unix` until OQ-TN-14) - op id `channels/tunnel/sub`, ALPN marker `alk/tunnel`, scope `tunnel:open` - codec: `[len: u16 BE]`, `len=0` = legal empty datagram, `Oversize` at frame time, no sentinel in the codec - typed errors: the five establishment reasons + `FORBIDDEN` + `channel:too_many_channels` surfaces 2. **Producer conformance** (producer.md): - establisher = the awaited bounded phase; plan flow (R-01) — no side-channel handoff anywhere (grep for `Mutex` + poll-loop take patterns — the POC's dead shape) - pump handler: `pump_bidi` inline, no substrate types, JoinHandle tracks the data plane (R-02) - registration: post-hoc supported (W2); `ChannelOperations:: register_on` guidance correct - listen variant: same op, no new wire surface, typed error mapping 3. **Consumer conformance** (consumer.md + ADR-005): - `TunnelSession`: open/adopt/stream_halves/take_halves/ send_datagram/recv_datagram/pump_against/close/join/Drop - teardown matrix sound (no leaks; pump-less join `(0, 0, reaped)`) - no `Clone` 4. **Conventions sweep** (AGENTS.md): - no comments in code (doc comments fine); no unwrap/expect outside tests; thiserror everywhere; poisoned-lock `unwrap_or_else(into_inner)` - substrate types confined to `src/local/` (grep-verify: no `tokio::net` outside the feature gate + tests) - wasm-clean default crate (the structural guard passed at every step, but re-verify) - `pump_bidi` consumed, never hand-rolled (grep for hand-rolled two-pump loops) 5. **Docs ↔ implementation sync**: lib.rs doc comments match overview.md's module map; public API = lib.rs re-exports (convention 16); ADR statuses updated from Draft → Accepted where the implementation confirms them (or findings filed back to the OQ tracker). ### Deliverables Findings as a review doc (`docs/reviews/001-implementation-review.md`, the alkhttp/alkcall house pattern) with severity levels + concrete remediation tasks. Criticals block the phase; majors get remediation tasks; minors get a follow-up batch. ## Acceptance Criteria - [x] Review doc filed with severity-graded findings - [x] Remediation tasks created for anything above trivial - [x] The 5 checklist sections each covered with a verdict ## References - docs/architecture/ (the full spec set) - House pattern: `/workspace/@alkdev/alkcall/docs/reviews/` (the review numbering + severity legend) ## Notes > Agent fills during implementation. ### Review executed 2026-09-08 (tree `2efac9b`) — deliverable: `docs/reviews/001-implementation-review.md` Method: full source read (`src/` + `tests/`) against the complete spec set; alkcall 0.7.0 API surfaces verified in source (wrapper, establisher types, client errors, manager adopt/teardown, `pump_bidi`); executable probes over real sockets for the `local` UDP path (temporary test file, deleted after the run — probe evidence quoted in the review); the full verification battery (see below). The mid-phase `tunnels/ review-core-crates` checklist is subsumed (consolidated in the review doc; that task's Notes carry its verdicts). ### The five checklist verdicts 1. **Wire conformance — PASS.** Params shape exact (`deny_unknown_ fields`, required both, enum `["tcp","udp","unix"]` — the OQ-TN-14 note in this checklist predates the OQ's resolution; `unix` SHIPS per OQ-TN-14's resolution, and the enum carries it correctly); op id/ALPN/scope pinned; codec correct including `len=0` and frame-time `Oversize`; all five typed establishment reasons reachable and proven (3 by test: `unknown_resource`/`dial_failed`/ `resource_shortage`; `handler_error` through the same `From` arm; `timeout` by the hanging-establisher probe) + `FORBIDDEN` + `channel:too_many_channels`. 2. **Producer conformance — PASS.** Awaited bounded establisher (10s default + per-registration override proven); pure R-01 plan flow (grep-verified — no side-channel handoff, no poll-loop take); pump handler structurally R-02 (`pump_bidi` inline; JoinHandle tracks the data plane, pinned by test); post-hoc registration (W2) supported; listen variant rides the same op with the typed-error table proven. 3. **Consumer conformance — PASS.** Full session surface per ADR-005; teardown matrix sound (close/join/Drop/pump-less/failed-adopt — all leak-asserted on both managers); no `Clone` (compile-fail doctest). One documented divergence: `adopt` takes the substrate (the task sketch omitted it — a datagram session cannot exist without it). 4. **Conventions sweep — PASS.** No unwrap/expect/panic outside `#[cfg(test)]` (grep-verified); thiserror everywhere; all locks are `tokio::sync::Mutex` (unpoisoned — the `into_inner` rule has no application point, N/A); substrate types confined to `src/local/` + feature gate; wasm clean (`check` + `clippy --target wasm32-unknown-unknown`, `-D warnings` both); `pump_bidi` consumed, never hand-rolled. Inline `//` comments are the safety-constraint class convention 1 allows. 5. **Docs ↔ implementation sync — PASS with drift fixed in-review.** Module map matches; ADRs all Accepted (implementation confirms); N-5 (stale doc forward-reference), N-7 (broken doc link), N-8 (missing root re-exports) fixed in-review. ### Findings (full detail in the review doc) - **U-1 [major]** — the `local` UDP adapter is NOT the framed adapter ADR-003 mandates: codec-framed bytes reach real targets; empty datagrams are EOF-shaped at the adapter (tunnel teardown); >8 KiB datagrams split; unframed target-initiated datagrams are dropped. Executable-pinned by probes. **NOT fixed — remediation task `tunnels/fix-udp-framed-adapter`** (blocks UDP-over-`local` consumers; wire surface unaffected). - **C-1 [major]** — `AcceptQueue::pop` lost wakeup in the check→register window (open op hangs to the establishment bound on a lost push). **Fixed in-review** (create-`Notified`-before-check per iteration, the tokio `notify_waiters` contract; regression test added). - **U-2/U-3 [minor]** — `connect_udp` v4-only bind posture; 65535-byte per-tunnel scratch. Riders on the U-1 task. - **N-4/N-5/N-7/N-8/N-9/N-10/N-11 [minor]** — fixed in-review (payload serialization, doc staleness, doc link, root re-exports, README + publish dry-run, harness comment, `pump_against` UDP framing doc note). - **N-2** — retracted during the review by executable falsification (the codec's buffering is bounded by construction; the u16 cap IS the bound). - **N-6** — non-finding with rationale (`TunnelEstablishError` has no `Timeout` variant, correctly). No criticals — the phase-gate passes. ### Verification battery (all green) - `cargo test`: 62 passed (default) / 69 passed (`--features local`), 3× repeat-run clean in both configs - `cargo clippy --all-targets -- -D warnings`: clean - `cargo clippy --target wasm32-unknown-unknown -- -D warnings`: clean - `cargo fmt --check`: clean - `cargo doc --no-deps`: clean after N-7's fix - `cargo check --target wasm32-unknown-unknown`: clean - `cargo publish --dry-run --allow-dirty`: passes after N-9's README ## Summary > Agent fills this on completion. Phase-gate review complete: the wire surface (the one-way door) is conformant; the API surface matches ADR-005/006; two majors found — U-1 (local UDP framing, remediation task created) and C-1 (queue lost wakeup, fixed with the review commit). The trivial batch + README + publish dry-run also landed with the review. Findings with severity grading and remediation ordering: `docs/reviews/001-implementation-review.md`.