alknet/docs/reviews/005-coverage-analysis.md

status, last_updated, reviewed_artifacts, tool, invocation, reviewer

status	last_updated	reviewed_artifacts	tool	invocation	reviewer
partially-resolved	2026-06-25	crates/alknet-vault/src/{lib,cache,derivation,encryption,ethereum,mnemonic,protocol,service}.rs crates/alknet-core/src/{lib,auth,config,endpoint,types}.rs crates/alknet-call/src/{lib,registry/*,protocol/*}.rs	cargo-llvm-cov 0.8.4	cargo llvm-cov --workspace --all-features	coverage pass (post-review-#004)

Coverage Analysis #005

Purpose

First dedicated code-coverage pass after the implementation round and the review-#004 fix round. Goal: locate the weakly-covered areas that should be tightened up while the surface is still small, and identify anything that needs research (ACME was flagged upfront as a likely hard spot).

Headline result: coverage is in good shape for a single implementation + single review pass. Workspace line coverage is 87.1% (5759/6615), all 224 tests pass, and the vault + registry layers are essentially fully covered. The remaining gaps concentrate in three files (endpoint.rs, types.rs, connection.rs) and almost all of them share a single root cause: tests build Connection/CallConnection over a MockConnection whose open_bi/accept_bi return Err(StreamClosed), so the real stream and accept-loop machinery is never exercised. That's a testing-infrastructure gap, not a logic gap.

Methodology

• cargo llvm-cov --workspace --all-features --lcov --output-path cov.lcov (matches the project convention of building/testing with --all-features; --all-features matters here because endpoint.rs has large #[cfg(feature = "acme")] and #[cfg(feature = "iroh")] blocks that are invisible under default features).
• Per-file line + region breakdown from the lcov export.
• Uncovered line ranges mapped back to source for the three weak files and the mid-tier files (adapter.rs, config.rs, protocol.rs).
• Each gap classified by testability: pure-function, needs-real-stream, or needs-network (ACME).

Summary Statistics

Severity	Count
Critical	0
Warning	0
Suggestion	8 (S1–S8)

No correctness findings — this is a coverage pass, not a logic review (that was #004). Everything below is a suggestion ordered by leverage, not severity.

---

Per-File Coverage

File	Lines	Covered	%
alknet-vault/src/derivation.rs	141	141	100.0%
alknet-vault/src/encryption.rs	123	123	100.0%
alknet-vault/src/ethereum.rs	126	126	100.0%
alknet-core/src/auth.rs	192	192	100.0%
alknet-call/src/protocol/abort.rs	250	250	100.0%
alknet-call/src/registry/registration.rs	543	538	99.1%
alknet-call/src/registry/env.rs	374	369	98.7%
alknet-call/src/registry/discovery.rs	418	412	98.6%
alknet-vault/src/cache.rs	289	286	99.0%
alknet-call/src/protocol/wire.rs	355	347	97.7%
alknet-call/src/protocol/pending.rs	409	398	97.3%
alknet-vault/src/service.rs	408	389	95.3%
alknet-call/src/registry/spec.rs	197	187	94.9%
alknet-call/src/registry/context.rs	89	86	96.6%
alknet-vault/src/mnemonic.rs	78	74	94.9%
alknet-core/src/config.rs	232	218	94.0%
alknet-call/src/protocol/adapter.rs	726	669	92.1%
alknet-vault/src/protocol.rs	90	78	86.7%
alknet-core/src/types.rs	374	212	56.7%
alknet-core/src/endpoint.rs	837	468	55.9%
alknet-call/src/protocol/connection.rs	364	196	53.8%
TOTAL	6615	5759	87.1%

Vault and registry layers: solid. Three weak files: the focus of this pass.

---

Suggestions

S1. dispatch_envelope and SubscriptionStream are untested pure logic (connection.rs)

File: crates/alknet-call/src/protocol/connection.rs:206–230, 299–345

Problem: dispatch_envelope is a pure function over &Arc<Mutex<PendingRequestMap>> + an EventEnvelope — it matches on EVENT_RESPONDED, EVENT_COMPLETED, EVENT_ABORTED, EVENT_ERROR, and _, calling handle_* on the pending map. None of these arms is exercised today (only register_imported* / overlay_env tests exist in this file). Likewise SubscriptionStream::{new, closed} and the three Stream::poll_next branches (Ok value, Err error, channel-closed) are pure async plumbing with zero coverage.

Fix: ~45 lines of unit tests. Drive dispatch_envelope with a freshly registered pending entry and each of the five event types; assert the pending map transitions. For SubscriptionStream, wire an mpsc::channel, push Ok/Err/None, poll, and assert the three envelopes/termination.

Lift: ~45 uncovered lines in connection.rs, no new infrastructure.

S2. map_*_connection_error and error Display/Debug/source for all variants (types.rs)

File: crates/alknet-core/src/types.rs:134–217, 491–513

Problem: map_quinn_connection_error and map_iroh_connection_error are pure mappings from ConnectionError variants to StreamError. None of their arms (TimedOut, ConnectionClosed, ApplicationClosed, Reset, other) is hit — the only tests use MockConnection. Separately, the HandlerError and StreamError Debug/Display/error::Error::source impls are only exercised for HandlerError::AuthRequired's Display; the other 11 arms are uncovered.

Fix: ~50 lines of unit tests. Construct each ConnectionError variant (quinn exposes them publicly; iroh's are iroh::endpoint::ConnectionError) and assert the StreamError mapping. Format each HandlerError/StreamError variant via format!("{:?}", e) / format!("{e}") and assert the strings; call .source() and assert Some/None per variant.

Lift: ~80 uncovered lines in types.rs, no new infrastructure. This is the single highest-leverage pure-function addition in the pass.

S3. Capabilities zeroize/default and Ed25519SecretKey from_bytes/sign/Debug (config.rs, types.rs)

File: crates/alknet-core/src/types.rs:62–67, 107–109; crates/alknet-core/src/config.rs:41–62

Problem: Capabilities::zeroize, Capabilities::default, and Ed25519SecretKey::{from_bytes, sign, Debug} are trivial but untested.

Fix: ~15 lines. Round-trip a key through from_bytes/as_bytes, sign a message and verify with ed25519-dalek's VerifyingKey, assert the Debug output is Ed25519SecretKey { .. }. Call Capabilities::default() and Capabilities::zeroize() on a populated instance, assert cleared.

Lift: ~15 lines across two files.

S4. Tier A of endpoint.rs: directly-callable TLS/rustls helpers

File: crates/alknet-core/src/endpoint.rs

A cluster of endpoint.rs functions are synchronous and directly callable but only reachable today via a live QUIC handshake. They can be unit-tested in isolation:

• build_rustls_server_config RawKey and SelfSigned arms (endpoint.rs:635–657) — only X509 is tested (via tls_setup_x509_returns_no_acme_state). Call the function directly with each TlsIdentity variant, assert the returned config has the supplied ALPNs and max_early_data_size == u32::MAX.
• build_quinn_server_config_from_rustls (endpoint.rs:603–612) — feed a rustls ServerConfig, assert Ok.
• load_private_key empty-file error path (endpoint.rs:713–717) — write an empty file with tempfile, assert Err(TlsConfig).
• has_iroh_identity (endpoint.rs:256–261) — pure bool over StaticConfig; assert both Some(RawKey) and None/X509 branches.
• HandlerRegistry::default and Debug for AlknetEndpoint (endpoint.rs:73–75, 112–117) — trivial.
• AcceptAnyCertVerifier trait methods (endpoint.rs:758–809) — offer_client_auth, client_auth_mandatory, root_hint_subjects, verify_client_cert, verify_tls12_signature, verify_tls13_signature, supported_verify_schemes are all pure/synchronous. Call each directly and assert (assertion() results, the scheme vector contents, etc.). These are currently lit only by a live TLS handshake that never runs in tests.
• RawKeyCertResolver::resolve (endpoint.rs:832–837) and Ed25519SigningKey::{choose_scheme (both branches), algorithm, public_key, sign} (endpoint.rs:880–908) — directly callable. only_raw_public_keys is already tested; the rest isn't. Assert choose_scheme returns Some when ED25519 is offered and None when it isn't; assert sign produces a 64-byte signature that verifies against the public key.

Fix: ~110 lines of unit tests, all #[cfg(feature = "quinn")]-gated where appropriate, no networking.

Lift: endpoint.rs from ~56% to roughly 80%. This is the bulk of the endpoint.rs gap and the largest single win in the pass.

S5. Tier B: one loopback quinn integration test (the real unlock)

Files: crates/alknet-core/src/endpoint.rs:135–252, 264–364, 376–457; crates/alknet-core/src/types.rs:254–360, 385–478; crates/alknet-call/src/protocol/connection.rs:75–204; crates/alknet-call/src/protocol/adapter.rs:205–290, 442–447

Problem: The accept loops (run_quinn_accept_loop, run_iroh_accept_loop), the dispatch functions (dispatch_quinn, dispatch_iroh), the fingerprint extractors, AlknetEndpoint::{new, run, shutdown} quinn/iroh paths, Connection::{accept_bi, open_bi, close} for quinn/iroh, SendStream/RecvStream AsyncRead/AsyncWrite for quinn/iroh, CallConnection::{call, subscribe, abort, write_request, write_envelope, read_stream_until_closed}, and CallAdapter::handle / handle_stream are all uncovered. They share one root cause: no test ever drives a real bi-directional stream.

Fix: One integration test module (e.g. crates/alknet-core/tests/ loopback_quinn.rs) that:

1. Builds a self-signed cert (reuse generate_self_signed_cert's approach, exposed via a test helper).
2. Binds a quinn server endpoint on 127.0.0.1:0 with a DummyHandler registered for b"alknet/test" that echoes the inbound frame.
3. Connects a quinn client, opens a bi-stream, writes a frame, reads the echo.
4. Shuts down via AlknetEndpoint::shutdown.

That single test lights up run_quinn_accept_loop, dispatch_quinn, extract_quinn_alpn, extract_quinn_client_fingerprint, build_auth_context on a live conn, the AcceptAnyCertVerifier callbacks during the handshake, Connection::{accept_bi, open_bi, close}, and the SendStream/RecvStream quinn arms. An iroh variant does the same for the iroh side.

The same loopback then carries a CallConnection::call round-trip and a CallAdapter::handle session for connection.rs and adapter.rs. One harness, four files benefit.

Lift: lights up ~300 lines across the four weak files. After S1–S4 + S5, workspace coverage should land around 93–94%.

S6. ACME event-loop extraction (the flagged research item)

File: crates/alknet-core/src/endpoint.rs:521–599

Problem: TlsSetup::new_acme and its spawned event loop (endpoint.rs:552–593) handle 11 EventOk/EventError arms. None is covered. The Acme arm dispatch in AlknetEndpoint::new (endpoint.rs:147–150) likewise never runs. ACME was flagged upfront as a likely hard spot — confirmed: the rustls_acme::AcmeConfig builder owns the network, so it can't be driven directly in a unit test.

Options, in increasing fidelity:

1. Extract the event handler (endpoint.rs:552–593) from the tokio::spawn closure into a named async fn run_acme_event_loop(state, domains: Vec<String>) that takes the AcmeState stream. Then unit-test it by feeding a synthetic futures::stream::iter([...]) of EventOk and EventError values and asserting it consumes them without panicking. Covers all 11 match arms and the loop termination. Pure refactor, no behavior change. Recommended primary path — also makes the event-loop logic inspectable and debuggable.
2. Pebble (Let's Encrypt's ACME test server) in a Docker dev-container, pointed at via AcmeDirectory::Custom(pebble_url). Highest fidelity (real issuance against a local ACME server), but adds a CI/dev dependency and is slower. Treat as a future CI-hardening step, not a unit test.
3. Mock AcmeConfig — not viable; the builder is not mockable.

Recommend option 1 now; option 2 as a follow-up CI task if/when ACME becomes load-bearing in production.

Lift: ~50 lines (the 11 match arms + the loop body), no network.

S7. adapter.rs non-request event arms and handle accept loop

File: crates/alknet-call/src/protocol/adapter.rs:205–290, 442–447

Problem: handle_stream's EVENT_ABORTED arm (which invokes AbortCascade::cascade_abort — the W1 fix from review #004) and the unknown-event arm are untested, as is CallAdapter::handle's accept loop and the fail_all-on-close path. identity_provider() accessor (76–78) is also untested.

Fix: The EVENT_ABORTED arm needs a crafted EventEnvelope fed into handle_stream with a mock SendStream/RecvStream pair (the loopback from S5 covers handle; the abort arm specifically wants a direct handle_stream test with a prefilled PendingRequestMap). The identity_provider() accessor is a one-line test.

Lift: ~25 lines; depends on S5's loopback for the handle path.

S8. DerivedKey redacted-payload deserialize rejection (vault protocol.rs)

File: crates/alknet-vault/src/protocol.rs:78–89

Problem: The deserialize guard that rejects private_key == "[REDACTED]" is untested. This is a security-adjacent path (prevents a redacted DerivedKey from being silently re-imported with a bogus key).

Fix: One test — serialize a DerivedKey, mangle the JSON to set private_key to "[REDACTED]", deserialize, assert the Err message contains "redacted". ~10 lines.

Lift: 12 uncovered lines; closes a security-adjacent gap.

---

Recommended Order

1. S1, S2, S3 — pure-function tests across connection.rs / types.rs / config.rs. Lowest effort, ~140 uncovered lines, no new infrastructure.
2. S4 — Tier A of endpoint.rs (TLS/rustls helpers, verifier callbacks, signing-key trait impls). ~110 lines of tests, lifts endpoint.rs to ~80%.
3. S5 — the loopback quinn integration test. One harness unlocks the accept/dispatch/stream paths across endpoint.rs, types.rs, connection.rs, and adapter.rs. After this, workspace coverage should be ~93–94%.
4. S6 — ACME event-loop extraction + synthetic-stream unit test. Covers the 11 match arms without network; sets up Pebble as a future CI step.
5. S7, S8 — the remaining small gaps; S7 partly rides on S5's loopback.

Notes

• All line numbers are against the tree at the time of this pass and use --all-features; coverage under default features understates endpoint.rs because the acme and iroh cfg blocks are invisible to the instrumenter.
• No critical or warning findings: this pass confirms that the gaps are testing-only. The underlying logic was reviewed in #004 and the fix round landed cleanly.
• The concentration of gaps in three files, all stemming from the same mock-connection limitation, is a good sign — one loopback harness (S5) closes most of them, rather than requiring per-path test scaffolding.

---

Resolution (2026-06-25)

The straightforward Tier-A suggestions (S1, S2, S3, S4, S8) were implemented in the same pass. 165 new tests added (224 → 389 passing). Workspace coverage rose from 87.1% → 91.2% (5759/6615 → 6505/7135). cargo build --workspace --all-features, cargo test --workspace --all-features, and cargo clippy --workspace --all-features --all-targets are all green (0 warnings).

Per-file deltas on the targeted files:

File	Before	After
alknet-call/src/protocol/connection.rs	53.8%	78.4%
alknet-core/src/endpoint.rs	55.9%	73.4%
alknet-core/src/types.rs	56.7%	77.9%
alknet-core/src/config.rs	94.0%	98.1%
alknet-vault/src/protocol.rs	86.7%	100.0%

What landed:

• S1 (connection.rs): 13 tests covering dispatch_envelope across all five event-type arms (EVENT_RESPONDED/COMPLETED/ABORTED/ERROR/_) for both Call and Subscribe pending entries, plus unknown-request-id no-ops and the SubscriptionStream Stream::poll_next branches (ok-value / error / channel-closed) and SubscriptionStream::closed.
• S2 (types.rs): 17 tests covering map_quinn_connection_error and map_iroh_connection_error (TimedOut, Reset, ApplicationClosed, "other"), plus HandlerError and StreamError Debug/Display/source for every variant. Previously only HandlerError::AuthRequired's Display was tested.
• S3 (config.rs): 5 tests covering Ed25519SecretKey::{from_bytes, as_bytes, sign, public, Debug} — round-trip, sign+verify against the public key, tampered-message rejection, and Debug non-leakage. (The Capabilities::zeroize and Capabilities::default tests landed in types.rs as part of S2.)
• S4 (endpoint.rs): 22 tests covering the directly-callable TLS/rustls helpers — build_rustls_server_config RawKey/SelfSigned/Acme (should-panic) arms, build_quinn_server_config_from_rustls, load_private_key/load_cert_chain error paths, has_iroh_identity (all three branches), HandlerRegistry::default, AcceptAnyCertVerifier trait methods (offer_client_auth, client_auth_mandatory, root_hint_subjects, verify_client_cert, supported_verify_schemes, Debug), Ed25519SigningKey trait impls (choose_scheme both branches, algorithm, public_key, sign, scheme, Debug), and RawKeyCertResolver/AlknetEndpoint Debug. Lifted endpoint.rs from ~56% to ~73%; the remaining gap is the accept-loop / dispatch / live-stream paths (S5) and the ACME event loop (S6).
• S8 (vault protocol.rs): 3 tests. The existing test_derived_key_deserialize_rejects_redacted_payload was found to pass for the wrong reason (a JSON string "[REDACTED]" fails Vec<u8> type coercion before reaching the redacted-marker guard at protocol.rs:78). Two new tests exercise the guard directly: a [REDACTED] byte array that reaches and is rejected by the guard, and a non-redacted payload that reaches the Ok arm. vault protocol.rs is now at 100%.

Remaining (deferred to follow-up):

• S5 (loopback quinn integration test) — the real unlock for the accept/dispatch/stream paths across endpoint.rs, types.rs, connection.rs, and adapter.rs handle. Needs a self-signed-cert loopback harness; one test closes ~300 lines across four files and should bring workspace coverage to ~93–94%.
• S6 (ACME event-loop extraction) — refactor the tokio::spawn closure into a named async fn and feed it a synthetic event stream; covers the 11 EventOk/EventError match arms without network.
• S7 (adapter.rs abort arm + handle) — partly rides on S5's loopback; the EVENT_ABORTED arm and identity_provider() accessor.