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.

README.md

@@ -0,0 +1,60 @@
+# alktunnels
+
+Arbitrary bidirectional tunnels over [alkcall](https://crates.io/crates/alkcall)
+channels: TCP, UDP, unix sockets, and other stream or datagram
+substrates — in the `ssh -L` / `ssh -D` / `ssh -R` sense, without SSH.
+
+A producer/consumer protocol crate riding alkcall channels the same
+way [alktty](https://crates.io/crates/alktty) does (`alk/tty` is the
+sibling precedent): the producer half registers the `alk/tunnel` open
+op and pumps bytes between the channel and the substrate; the consumer
+half is the typed session (`TunnelSession`) that opens tunnel channels
+and owns teardown.
+
+## A tunnel is a resource, not an address
+
+Open-op params identify a produced resource + substrate:
+
+```json
+{ "resource": "postgres-primary", "substrate": "tcp" }
+```
+
+The producer owns the backing — the consumer never learns an address.
+Rich addressing (SOCKS5 ATYP, per-datagram remotes) enters only
+through the `-D`/dynamic composition path, inside the tunnel payload,
+never in the wire (ADR-001).
+
+- Wire format: `docs/architecture/wire.md` (+ the BAST document at
+  `docs/architecture/bast.md`)
+- Open-op params: ADR-001; codec: ADR-003; ALPN: ADR-002
+- Producer shapes: ADR-004; consumer session: ADR-005; ACL: ADR-006
+- The full spec set: `docs/architecture/` (overview, wire, producer,
+  consumer, six ADRs, OQ tracker)
+
+## Status
+
+v0.1.0 — the v1 protocol implementation, Phase-2 complete (spec:
+`docs/architecture/`; reviews: `docs/reviews/`). The wire surface
+(params, ALPN, codec) is one-way-door stable from this point; the
+API surface becomes ABI-stable at the first external consumer.
+
+## Features
+
+| Feature | Contents | wasm |
+|---------|----------|------|
+| *(default)* | params, wire codec, open-op spec, establisher shapes, `TunnelSession` — protocol only | yes |
+| `local` | TCP/UDP/unix dial + listen helpers (real sockets) | no |
+
+## Verification
+
+```bash
+cargo test                                    # default crate (wasm-clean)
+cargo test --features local                   # + real-socket suites
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+cargo check --target wasm32-unknown-unknown   # the wasm-clean guard
+```
+
+## License
+
+MIT OR Apache-2.0