alktunnels/tasks/tunnels/corrmiss-gate-tests.md

---
id: tunnels/corrmiss-gate-tests
name: "Tests: the forwarded gate — typed miss at the open, gate-pass flow, residual race, scope-gate ordering"
status: completed
depends_on: [tunnels/corrmiss-forwarded-gate]
scope: narrow
risk: low
impact: component
level: implementation
tags: [tests, establisher, forwarded-op, correlation-miss, review-003]
---

## Description

Land W1's test item (plan 003 §W1 "Tests:"): pin the four behaviors
the establisher variant introduces, mirroring the shapes the existing
suite uses (`tests/producer_forwarded.rs` — the serving-half e2e +
scope-gate + malformed-params + correlation-miss tests are the
precedents; the harness's `wire_with` + `Topology.consumer_registry`
shape needs no harness changes per the `forwarded-receipt` task's
notes).

The four pins:

1. **Miss at the gate → typed failure, no phantom.** A `listen` token
   with no waiting session → the open fails as a
   `channel:open_failed` reply with `details.reason ==
   "unknown_resource"`; the transiently allocated channel is torn
   down by the wrapper (ADR-049 §5 — the reply is the typed error,
   not a phantom channel); the pump handler NEVER runs. Probe by
   opening the forwarded op with a token the gate rejects.
2. **Gate pass → the existing serving flow is unchanged.** A token the
   gate accepts → the registration serves exactly like the base
   shape: the injected `ForwardedHandler` receives the parsed params +
   the `BiStream`, the byte round-trip works end to end (the
   `producer_forwarded.rs` round-trip shape, driven through the
   establisher-registered variant).
3. **The residual race shape still reaps cleanly.** Gate passes, route
   gone at handler time → the injected handler's error path drops the
   stream and returns → teardown-at-birth reaps the forwarded channel
   (the base shape's pinned semantics — re-pin them under the
   establisher variant; the narrow establisher-pass→handler-run window
   is the residual `correlation-miss` class).
4. **Scope gate precedes the establisher.** An identity WITHOUT
   `tunnel:forwarded` → FORBIDDEN and the gate closure is never
   invoked (a witness-style `Arc<AtomicBool>` or captured flag the
   gate sets on entry; assert unmoved) — the registry runs the ACL
   before the open op's establishment phase; pin the order.

If the establisher variant's parse-failure behavior (malformed params
→ typed `channel:open_failed` rather than birth-teardown, the design
decision 1 of the API task) is separately testable through the public
surface, pin it as a fifth test; if the existing malformed-params test
already covers the base shape, note the establisher-shape delta
explicitly (do not silently assume).

## Acceptance Criteria

- [ ] Gate-miss test: typed `channel:open_failed` /
      `unknown_resource` / no handler invocation / no phantom channel
- [ ] Gate-pass test: the full round-trip through the establisher
      variant (handler receives parsed params + stream, bytes
      round-trip)
- [ ] Residual-race test: gate passes → handler-time miss → the
      channel reaps (teardown-at-birth re-pinned)
- [ ] Ordering test: missing `tunnel:forwarded` scope → FORBIDDEN and
      the gate never invoked
- [ ] The establisher-variant malformed-params delta is pinned or
      explicitly noted
- [ ] Full verification green: `cargo test`,
      `cargo clippy --all-targets -- -D warnings` (native + wasm32),
      `cargo fmt --check`,
      `cargo check --target wasm32-unknown-unknown`,
      `cargo test --all-features`

## References

- docs/plans/003-correlation-miss-resolve.md §W1 (the Tests bullet;
  plan-level AC "W1 ... tests green")
- tests/producer_forwarded.rs (the shapes to mirror: the serving e2e,
  the FORBIDDEN gate, the malformed-params gates, the
  correlation-miss teardown)
- tasks/tunnels/corrmiss-forwarded-gate.md (the surface being tested;
  design decisions 1 + 3 — the parse-failure and error-mapping pins)
- docs/architecture/wire.md §The Open Ops (the
  `details.reason == "unknown_resource"` vocabulary — the assertion
  target)
- alkcall 0.10.0 `src/channels/operations.rs:761` (the wrapper's
  establisher failure → typed open_failed semantics; ADR-049 §5)

## Notes

- New test file `tests/producer_forwarded_gate.rs` — the
  establisher-variant probes live in their own file (the base shape's
  `tests/producer_forwarded.rs` stays untouched), reusing the
  harness's `wire_with` + `Topology.consumer_registry` shape with no
  harness changes, exactly as the `forwarded-receipt` task's notes
  predicted.
- The gate under test closes over a `std::sync::Mutex<HashSet<u32>>`
  of waiting tokens (the gate is a sync closure — no awaits) and sets
  an `Arc<AtomicBool>` witness on entry; the witness is what the
  miss/ordering pins assert against. Poisoned-lock handling follows
  convention 2 (`unwrap_or_else(|e| e.into_inner())`).
- The five tests:
  1. `gate_miss_fails_typed_no_phantom_no_handler` — AC 1: open with
     an absent token → `Err(CallError)` with
     `code == "channel:open_failed"` and
     `details.reason == "unknown_resource"` (the existing
     `From<TunnelEstablishError>` table, 1:1); after a settle sleep
     the opener-side manager has no channels (the wrapper's transient
     allocation was torn down — ADR-049 §5, no phantom); the gate's
     witness IS set (the miss is at the gate, not before it) and the
     pump handler's witness is unmoved (the handler never ran).
  2. `gate_pass_serves_the_unchanged_serving_flow` — AC 2: token in
     the map + correlated halves → the open resolves with the
     wrapper's `channel_id`; the injected handler is witnessed with
     the parsed params verbatim; the full dispatcher-pump dance
     (adopt + driving echo) round-trips bytes end to end — the
     `producer_forwarded.rs` e2e shape driven through the
     establisher-registered variant.
  3. `residual_race_still_reaps_cleanly` — AC 3: the token is in the
     map (the gate passes, the open RESOLVES at the call plane) but
     the halves vec is empty at handler time → the handler's error
     path drops the stream and returns → teardown-at-birth reaps.
     Re-pins the base shape's `forwarded_correlation_miss_
     tears_channel_down` semantics under the establisher variant —
     the establisher-pass→handler-run window is the residual
     `correlation-miss` class.
  4. `scope_gate_precedes_the_establisher` — AC 4: an identity
     holding only `tunnel:open` → `FORBIDDEN` naming the missing
     scope, and the gate's witness stays unmoved even though the
     token WOULD have passed the gate (the tie-break is the order —
     schema → ACL → allocate → establisher → handler — pinning that
     the registry runs the ACL before the establishment phase).
  5. `malformed_params_fail_typed_at_the_establisher` — AC 5: the
     establisher-shape malformed-params delta IS separately
     testable through the public surface, so it is pinned: the
     schema gates (`listen: 0`, missing `peer`) fire first exactly
     as in the base shape (`INVALID_INPUT`, the test explicitly
     re-checks both), but an unknown top-level field — passes the
     schema's additive posture, fails the establisher's serde parse
     — becomes a TYPED `channel:open_failed` with
     `details.reason == "handler_error"` (vs the base shape's
     success-with-channel_id + silent birth-teardown: the improvement
     design decision 1 pins). The establisher's parse precedes the
     gate (the gate's witness stays unmoved), the wrapper tears the
     transient allocation down, and the handler never runs.
- Verification deviation, discovered and characterized, pre-existing:
  `cargo clippy --target wasm32-unknown-unknown --all-targets` cannot
  compile on this repo's baseline (the wasm clippy's `--all-targets`
  pulls the test/dev targets whose `mio`/`socket2` deps do not
  compile for wasm) — verified by removing the new test file and
  re-running: identical failure without the change. The repo's
  AGENTS.md verification list specifies wasm clippy WITHOUT
  `--all-targets`
  (`cargo clippy --target wasm32-unknown-unknown -- -D warnings`),
  which is green; the AC's "(native + wasm32)" is read through the
  AGENTS.md command list as `--all-targets` native + the no-targets
  wasm clippy (same posture the API task's summary pinned: clippy
  `--all-targets` native, wasm clippy clean).

## Summary

Landed W1's test item: five tests in the new
`tests/producer_forwarded_gate.rs` pinning the establisher variant's
behaviors — (1) gate miss → typed `channel:open_failed` /
`details.reason == "unknown_resource"` / no phantom channel / handler
never runs; (2) gate pass → the base serving flow unchanged (params
witnessed verbatim + full byte round-trip through the
establisher-registered variant); (3) the residual race (gate pass,
route gone at handler time) reaps cleanly via teardown-at-birth,
re-pinning the base shape's correlation-miss semantics under the
establisher variant; (4) scope-gate ordering — a scope-less identity
is FORBIDDEN and the gate closure is never invoked (witness unmoved);
(5) the establisher-variant malformed-params delta pinned explicitly:
schema gates unchanged (`INVALID_INPUT`) but an unknown top-level
field becomes a typed `channel:open_failed` with
`details.reason == "handler_error"` and the parse precedes the gate.
Verification green: `cargo test` (14 suites, 0 failures),
`cargo clippy --all-targets -- -D warnings` (native) clean,
wasm clippy `cargo clippy --target wasm32-unknown-unknown -- -D
warnings` clean (see Notes for the `--all-targets`-wasm deviation —
pre-existing, dev-deps do not target wasm),
`cargo fmt --check` clean,
`cargo check --target wasm32-unknown-unknown` clean (default crate
stays wasm-clean), `cargo test --all-features` green, `cargo doc
--no-deps` clean. Harness unchanged. Follow-ups: the sibling-repo
adoptions (`corrmiss-alkssh-adopt`, `corrmiss-alksocks-adopt`) — the
W1 wave's tests are green.