hpc: docstring the randomized_signature tests, bench, and e2e pipeline tests

[AdaWorldAPI]

Summary

Closes the docstring-coverage gap CodeRabbit flagged on #294, then finishes the job. Comments only — no behavioural change, in two commits.

The check reported 61.76% against an 80% threshold, scoped to functions touched by that diff (34 functions across 3 files). Tracing it: the gap was entirely in test and bench code.

Bucket	Before
3 public API fns (randomized_signature_{step,sweep,sweep_with})	✅ already documented (/// + # Panics + example)
4 private SIMD/validation helpers (dot_simd, axpy_simd, step_into, check_shapes)	✅ already documented
scalar_reference, projections	✅ already documented
SplitMix64::{next_u64, uniform, normal}	❌
wiggly_path, assert_matches_reference	❌
10 of 11 #[test] bodies	❌
8 of 9 bench fns	❌
7 e2e_tests pipeline tests in hpc/mod.rs	❌ (out of the check's scope — see below)

All are documented now. The three files measure 100% (42/42 functions).

Because the check is diff-scoped, the crate's public surface was never the problem — CLAUDE.md's hard rule ("All public APIs need /// doc comments with examples") was already satisfied, and rustdoc's missing_docs lint never fired because every undocumented item is private or #[cfg(test)].

Commit 1 — randomized_signature.rs + the bench

Where a test already carried an explanatory inline // block — zero_increment_path_leaves_state_at_zero, sub_epsilon_increment_is_skipped_but_supra_epsilon_is_not, custom_activation_is_the_one_applied — the prose is promoted into the docstring rather than duplicated, so each rationale is stated once. (That is why a comments-only diff shows deletions.)

The docs record why each test discriminates, not just what it calls:

• parity_across_state_widths — the widths straddle the F64x8 lane boundary both ways (1, 7 under; 8, 16, 64 exact; 9, 33 one past); a kernel that only walked whole lanes would pass at k = 8 and fail at k = 9.
• zero_increment_path_leaves_state_at_zero — documented as weak on its own (drop the skip and it still passes, since dx = 0 scales the axpy to nothing); the guard is falsifiable only via its paired supra-epsilon half.
• custom_activation_is_the_one_applied — the second half asserts tanh gives a different answer on the same inputs, so it cannot pass by the two activations happening to agree.
• path (bench) — the wobble keeps every increment clear of the 1e-15 skip, so both implementations do the full O(T·d·k²) of work being compared. A timing-correctness property, not realism.

Commit 2 — the seven e2e_tests in hpc/mod.rs

These were outside the #294 check's scope: that diff only added a pub mod line to this file, so its tests counted as untouched. They were nonetheless the remaining undocumented functions in the hpc module surface, so they are covered here rather than left as a known gap.

• fingerprint_to_node_to_seal — the seal half is the discriminating one: Wisdom against its own root, Staunen after one further encounter.
• cascade_search — the query is database[0], so an exact self-hit at Hamming 0 is the falsifiable minimum.
• clam_knn — the one-hot layout makes every non-self XOR exactly two set bytes (16 bits, uniform), leaving the self-match as the single unambiguous winner; root().cardinality == n is the coverage check that !nodes.is_empty() would miss.
• causality_decomposition — three channels with mixed signs, so a decomposition applying one direction uniformly matches at most 2 of 3.
• bnn_inference — both poles pin the whole affine match-count→score map; either alone would admit a wrong scale or offset.
• blackboard_arena — asserts a present and an absent key, so contains cannot pass by always returning true.
• full_e2e — pins that the stages compose on one node pair, where the other six each pin a single stage.

Test plan

• cargo fmt -- --check — clean, whole repo
• cargo clippy --release --lib --tests --example randomized_signature_bench -- -D warnings — clean
• cargo test --release --lib — 2270 passed, 0 failed, 30 ignored
• cargo test --release --lib hpc::e2e_tests — 7 passed (confirmed these run under the default hpc-extras feature, rather than assumed)
• cargo test --release --doc randomized_signature — 3 passed
• Coverage recount across the three files — 100% (42/42)

Note for reviewers

This PR is a draft, and CodeRabbit does not auto-review drafts — so the coverage figure above is verified by a strict /// scan, not yet by the bot that raised it. CodeRabbit's heuristic counts something looser than a leading /// (it scored 21/34 where a strict scan finds 10), so the strict superset was fixed, which necessarily contains whatever it flagged. Marking ready for review, or a @coderabbitai review comment, would confirm it — at the cost of one review against an org allowance that was already at its spending cap.

🤖 Generated with Claude Code

https://claude.ai/code/session_016WkNBjHc2e3zuyz9i8qJEv

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_308a3853-c390-41ba-bacd-f479a4f43237)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.