alktunnels/tasks/tunnels/end-to-end-suite.md

---
id: tunnels/end-to-end-suite
name: End-to-end suite — forward, reverse, listen, datagram, teardown matrix
status: completed
depends_on: [tunnels/consumer-session, tunnels/producer-listen, tunnels/local-socket-halves]
scope: broad
risk: medium
impact: phase
level: implementation
tags: [tests, integration, phase-gate]
---

## Description

Consolidate the integration coverage into `tests/` as the crate's
end-to-end suite: every validated POC behavior, re-expressed against the
crate's public API (not the POCs' internals). This is the quality gate
before the implementation review — the suite is the spec's executable
form.

### Suites

1. **Forward (`-L`)**: consumer `open` → producer establisher dials →
   `pump_bidi` → round-trip; 1 MiB backpressure; typed errors
   (unknown_resource / dial_failed / FORBIDDEN / timeout-adjacent);
   per-call opener identity witness (CF-006).
2. **Reverse (`-R`)**: hub initiator — `open_reverse_channel` +
   `adopt` + `pump_against`; odd-ID allocation asserted (ADR-047 §5);
   identity precedence chain (transport alone / `ServingConfig.
   identity` override / token override / identity-less fail-closed);
   half-close (W4); out-of-band `channel/close` + self-reaping (W3);
   concurrent same-resource opens (R-01, no handoff race).
3. **Listen producer**: the accept-queue flow end-to-end + its typed
   errors (from `tunnels/producer-listen`).
4. **Datagram (`udp`)**: forward + reverse datagram sessions via the
   codec — round-trip, empty datagram (the F-2 layering), chunk-split
   survival, TCP+UDP concurrent channels on one connection.
5. **Teardown matrix** (ADR-005): close / join (with + without pump) /
   Drop — `channel_ids()` asserts no leaks on either side after each.
6. **`local` feature suite**: real sockets end-to-end (from
   `tunnels/local-socket-halves` — runs after that task lands; the
   duplex-transport suites above do not need it).

Transport stand-in: `tokio::io::duplex` (both POCs' harness; the
alkcall layer owns real transports — unchanged scope). The suite may
share one harness module (`tests/common/`); the POC harnesses
(`/workspace/alktunnels-udp-poc/src/harness.rs`,
`/workspace/alktunnels-reverse-poc/src/harness.rs`) are the two
topologies to unify.

### The spec-conformance assertions to keep visible

- A failed open never returns a `channel_id` (no phantom channel —
  both sides' `channel_ids()` hold only 0 afterward).
- A failed adopt never leaks the session (Drop reaps).
- The pump handler's `JoinHandle` tracks the data plane (a test that
  simulates early-return would hang/EOF-instantly — the R-02 shape;
  assert the correct shape survives).

## Acceptance Criteria

- [ ] All 6 suites present; ≥20 integration tests total
- [ ] `cargo test` green; `cargo test --features local` green
- [ ] Repeat-run stable (3× clean — the POCs' flakiness bar)
- [ ] Clippy/fmt clean; wasm32 check passes

## References

- docs/architecture/wire.md + consumer.md + producer.md (the normative
  behaviors under test)
- POC test suites: `/workspace/alktunnels-udp-poc/tests/tunnel_poc.rs`
  (10), `/workspace/alktunnels-reverse-poc/tests/tunnel_poc.rs` (16)

## Notes

> Agent fills during implementation.

### Implementation notes (2026-09-08)

The pre-existing per-task suites (36 integration tests across
`producer_open_op`, `consumer_session`, `producer_listen`,
`local_halves`) already carried much of the per-suite coverage; this
task consolidated the remaining POC-validated behaviors they didn't
cover into `tests/end_to_end.rs` (18 tests, the suites as enumerated)
and extended `tests/harness.rs`:

- `RegistrationMode::Timeout(Duration)` — a hanging establisher with
  an explicit per-registration establishment timeout (the ADR-049 §2
  deadline-expiry probe; the wrapper maps expiry to reason `timeout`
  with no channel surviving).
- `wire_serving_identity` — the `ServingConfig.identity` override
  probe shape (CF-005 (a)).

Gaps the suite filled (behaviors the per-task suites did not cover):
1 MiB backpressure round-trip (both POCs' sizing probe); the
deadline→`timeout` wire mapping; odd-ID allocation asserts (ADR-047 §5)
plus distinctness; the FULL identity precedence chain — the
`ServingConfig.identity` override and the token-over-transport
precedence with a DISTINCT resolved id (the existing token test
resolved to the same id as the transport identity, so it proved
authorization but not precedence — the new `DistinctTokenProvider`
probe proves precedence); reverse datagram sessions via the codec
(pump-less `(0, 0, reaped)` join shape); 40-datagram bursts with
batching (the pending-queue cover, both directions); the 7-byte
chunk-split codec probe (100 datagrams); TCP+UDP interleaved on one
connection; teardown matrix arms: close-with-pump (abort + reap both
sides), join copy counts, Drop-with-pump (abort AND reap), and the
failed-adopt no-leak arm; R-02's JoinHandle-tracks-the-data-plane
assertion (alive-and-pumpable long after the open, completion only at
both-direction EOF).

### Test-side findings (not product bugs — recorded for the record)

- **Parked ≠ adopted.** `teardown_channel` on a reverse-open'd but
  never-adopted channel id is `UnknownChannel` — the manager parks
  early arrivals for unseen ids (the adoption-race cover, ADR-047 §5)
  but does not install a channel entry until adopt. Cleanup for such
  ids is adopt-then-close (what the tests do). Worth knowing when an
  assembly layer errors between `open_reverse_channel` and `adopt`.
- **`read(&mut Vec)` vs `read(buf)`** — an unpopulated `Vec` passed to
  `AsyncReadExt::read` has len 0 and reads nothing (instant EOF); the
  1 MiB loop needed a size-`expected` buffer with `&mut received[got..]`.
- The empty-queue-vs-error posture from `tunnels/producer-listen`
  carries over verbatim: the queue's pop waits; mapping empty-pop to
  `resource_shortage` is the assembly closure's posture (producer.md's
  table), asserted here with a fail-fast closure.

## Summary

> Agent fills this on completion.

### Summary

`tests/end_to_end.rs` (18 tests) consolidates the POC-validated
behaviors into the crate's end-to-end suite over the shared duplex
harness: forward (1 MiB backpressure, deadline→`timeout`, CF-006
witness on transport + token paths), reverse (odd-ID asserts +
distinctness, the full CF-005 precedence chain incl. the
ServingConfig override and a distinct-id token probe, R-01 same-
resource concurrency ×3), listen (FIFO always-before-take, the typed
error table), datagram (batching survival, 7-byte chunk-split codec
probe, reverse codec session, TCP+UDP concurrent), teardown matrix
(close-with-pump / join copy counts / Drop-with-pump / failed-adopt),
and the spec-conformance assertions (no phantom channel, no leaked
session, R-02's data-plane-tracking pump handle).

Harness grew `RegistrationMode::Timeout` + `wire_serving_identity`.
Existing suites untouched. Verification: `cargo test` green (68 tests
incl. unit + doc), `cargo test --features local` green (75), 3×
repeat-run clean (both feature configs), clippy `-D warnings` clean
(all-targets, `--features local`, wasm32), `cargo fmt --check` clean,
wasm32 check passes. No product-code changes were needed — the
failures during development were all test-harness bugs (zero-len read
buffer, teardown-on-parked-id), recorded above.