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

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
tunnels/corrmiss-gate-tests	Tests: the forwarded gate: typed miss at the open, gate-pass flow, residual race, scope-gate ordering	completed	tunnels/corrmiss-forwarded-gate	narrow	low	component	implementation	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, whose serving-half e2e, scope-gate, malformed-params, and 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 with 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, with 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, i.e. 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, where 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), which pins 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 while failing the establisher's serde parse, so it 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 pre-existing --all-targets-wasm deviation: 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 adoption waves (plan 003 §W2/§W3; executed in the alkssh and alksocks repos). The W1 wave's tests are green.