review: phase-gate review 001 — spec conformance of the v1 implementation

Findings + review doc: docs/reviews/001-implementation-review.md (the
alkcall house pattern). Closes tunnels/review-core-crates and
tunnels/review-impl.

Findings:
- U-1 [major, NOT fixed] — 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 real-socket probes (temporary test,
  deleted after the run). Remediation task: tunnels/fix-udp-framed-adapter.
- C-1 [major, fixed] — AcceptQueue::pop lost wakeup in the
  check→register window (open op hangs to the establishment bound);
  fixed via the tokio notify_waiters contract (Notified created before
  the check each iteration) + multi-thread regression test.
- N-4/N-5/N-7/N-8/N-9/N-10/N-11 [minor, fixed] — serialize TunnelParams
  in open_reverse_channel; stale doc ref; broken doc link; root
  re-exports (TunnelParams/Substrate/tunnel_open_spec/OP_TUNNEL_OPEN);
  README (publish dry-run was failing on the missing readme); harness
  comment; pump_against UDP framing doc note.
- N-2 retracted by executable falsification (codec buffering is
  bounded by construction); N-6 non-finding with rationale.

Verified: 63 tests default / 70 with --features local, 3x repeat-run
clean both configs; clippy -D warnings (all-targets + wasm32); fmt;
doc warning-free; wasm32 check; cargo publish --dry-run passes.

tasks/tunnels/review-impl.md

@@ -1,7 +1,7 @@
 ---
 id: tunnels/review-impl
 name: Review alktunnels v1 implementation for spec conformance (pre-release gate)
-status: pending
+status: completed
 depends_on: [tunnels/end-to-end-suite, tunnels/review-core-crates]
 scope: moderate
 risk: low
@@ -67,9 +67,9 @@ tasks; minors get a follow-up batch.
 
 ## Acceptance Criteria
 
-- [ ] Review doc filed with severity-graded findings
-- [ ] Remediation tasks created for anything above trivial
-- [ ] The 5 checklist sections each covered with a verdict
+- [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
 
@@ -81,6 +81,101 @@ tasks; minors get a follow-up batch.
 
 > 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.
+> 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`.