alktunnels/tasks/tunnels/review-002-coverage-gaps.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
tunnels/review-002-coverage-gaps	G-4 + G-5 — close the remaining cheap coverage gaps (unix accept-loop test, unnamed unix fail-loud guards)	completed		narrow	low	component	implementation	tests local unix coverage review-002 review-remediation

Description

The two remaining cheap-to-close coverage gaps from review 002's coverage appendix (docs/reviews/ 002-graduation-implementation-review.md), batched — both are local-feature test additions (no protocol-layer changes).

G-4 — UnixListenerHalves::accept_loop never driven

src/local/mod.rs:591-609 has zero coverage: no test constructs it (the unix dial test hand-rolls its own echo listener; the bind-first unix test uses accept_pair). It is the unix parity twin of the covered TcpListenerHalves::accept_loop (hit at ~107-125) — 15 lines of the same shape, and the largest single uncovered block in the crate.

Test: mirror tests/producer_listen.rs's accept_loop_stops_feeding_after_close_and_maps_the_drop with bind_unix + a temp path — closes the entire 593-607 range and exercises UnixListenerHalves beyond the bind-first path. Low value (copy-shaped) but the largest single uncovered block.

G-5 — the unnamed-peer/unnamed-bind fail-loud arms (unix)

Two fail-loud guards the ADR pins (ADR-008 §3 — "a producer that cannot determine the peer does not serve a bind-first listener over that substrate") never fire:

• src/local/mod.rs:626-633 — the accept_pair unnamed-peer handler_error (an autobind client)
• src/local/mod.rs:578-583 — the local_addr unnamed-bind error

The existing unix bind-first test binds a named client socket deliberately (the parity case); no test binds an abstract/autobind unix listener.

Test: bind an abstract unix listener (Linux: a leading-\0 path via socket2 — already a local dependency, or UnixListener::bind on an unnamed autobind socket), call local_addr() expecting the "no filesystem path" handler_error, and drive one autobind-client accept through accept_pair expecting the unnamed-peer error. Cheap, deterministic, and it pins the two ADR sentences the doc comments promise.

Explicitly NOT in this task (review guidance)

• G-7 — kernel-dependent readiness arms; leave uncovered.
• G-6 — the UDP empty-resolve arm; only if the ResolveFn seam refactor is ever wanted (optional, separate decision — do not do it here).
• G-1/G-3 — unreachable-by-construction serde/JoinError arms; leave uncovered.

Acceptance Criteria

• The unix accept_loop test added (G-4 — the 591-609 range covered)
• The abstract-listener test added (G-5 — both fail-loud arms covered: local_addr unnamed-bind + accept_pair unnamed-peer)
• cargo test --features local green; clippy --all-targets -D warnings clean (native + wasm32); fmt clean; the default crate stays wasm-clean

References

• docs/reviews/002-graduation-implementation-review.md §G-4, §G-5 (the coverage appendix)
• src/local/mod.rs:591-609 (UnixListenerHalves::accept_loop), 578-583 (local_addr unnamed-bind), 626-633 (accept_pair unnamed-peer)
• tests/producer_listen.rs (the accept-loop test shape to mirror)
• docs/architecture/decisions/008-listen-metadata-forwarded-op.md §3 (the fail-loud sentences the tests pin)

Notes

Agent fills during implementation.

Implementation (2026-09-20)

G-4 — unix_accept_loop_stops_feeding_after_close_and_maps_the_drop in tests/producer_listen.rs (mirroring the TCP twin above it): bind_unix + a temp path under the test's own pid-scoped dir, the listener's accept_loop spawned against a pre-closed AcceptQueue, one unix client connect, and the loop's handler_error exit asserted within a 5s bound. Covers the full 591-609 range (the unix accept-first loop was previously never driven).

G-5 — unix_unnamed_bind_and_unnamed_peer_fail_loud in tests/local_bindfirst.rs (#[cfg(target_os = "linux")] — abstract addresses + autobind are Linux-shaped). Both fail-loud arms pinned via the crate's own public API (no private-constructor seam needed):

• Unnamed bind: bind_unix("") — tokio passes the empty path through to bind(2), which the kernel autobinds (addlen == offsetof(sun_path), an abstract name, no filesystem path) — local_addr maps it to the "no filesystem path" handler error (the 578-583 arm). Probed on this host: the bound addr reports as_pathname() == None.
• Unnamed peer: a socket2 client bound to the empty abstract sockaddr (the autobind shape — verified Ok on this kernel) connects to a NAMED bind_unix listener; accept_pair refuses with the unnamed-peer handler error (the 626-633 arm). A plain unbound client behaves identically: mio's UDS accept maps ANY abstract-namespace peer (sun_path[0] == 0, which includes the autobind assignment) to an unnamed addr, so the fail-loud guard catches both client shapes through tokio's accept.

bind_unix_first itself stays untested for the unnamed-bind arm at the establisher level (it composes bind_unix + local_addr — the arm is the same code path the test drives directly); the local_addr assertion covers the composition's error leg.

Verification (all green):

• cargo test (135) + cargo test --features local (162 passed, 0 failed)
• cargo clippy --all-targets -- -D warnings (default + local)
• cargo fmt --check
• cargo check + cargo clippy -D warnings --target wasm32-unknown-unknown (the default crate stays wasm-clean)