---
id: tunnels/end-to-end-suite
name: End-to-end suite — forward, reverse, listen, datagram, teardown matrix
status: pending
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.

## Summary

> Agent fills this on completion.