test(bench): consumer-hotpath microbenchmarks, hinted-spectrum prototypes, thread-local SA-probe counter

[nh13]

PR #7 of the v0.2 stack (carries 29bb8de, with d1d8e88 folded in per the stack plan). Base is feat/v0.2-isa-hint (#19). Tracked in V0.2_PR_STACK.md row #7.

What this does

Benchmarking + profiling harness and the hinted-spectrum prototypes (no production-path behavior change):

• Benches — mem_search_bench, primitives_bench (consumer-hotpath microbenchmarks).
• probe_audit example + thread-local SA-probe counter (prmi_probe_count_* FFI, ffi_probe_count.rs) for measuring search probes per read. d1d8e88 (report the model max_error_bound in the probe-audit header) is folded in.
• Hinted-spectrum prototypes in spectrum.rs (forward/backward "from hint" paths), oracle-tested byte-identical to the cold path (forward_spectrum_from_hint_equals_cold, backward_spectrum_from_hint_equals_cold, backward_stale_hint_is_self_consistent_and_not_longer).

Cherry-picked cleanly onto #6 (additive — no conflicts with the carried guards).

Green-pass

• build ✅ · clippy -D warnings ✅ · cargo +nightly fmt --check ✅ · cargo test --workspace ✅ (162 lib + all integration/FFI; new probe-count + hint-equivalence tests; only Plan-3 deferrals ignored).

Summary by CodeRabbit

• New Features

  • Optional compile-time probe-counting support exposed via FFI for thread-local probe metrics
  • Hinted spectrum search variants to reduce probe work and improve search efficiency
  • K-mer table seeding to accelerate backward search operations

• Tests

  • End-to-end FFI probe-counter tests and hinted-vs-cold correctness checks

• Chores

  • New memory-search and primitives benchmark suites
  • Probe-count auditing example added

[coderabbitai]

Warning

Review limit reached

@nh13, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 54 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 39ec52e4-a2f7-496a-9068-f54abaa7d513

📥 Commits

Reviewing files that changed from the base of the PR and between 7df2f22 and 70224eb.

📒 Files selected for processing (8)

• prmi-sys/Cargo.toml
• prmi-sys/src/lib.rs
• prmi-sys/tests/ffi_probe_count.rs
• prmi/Cargo.toml
• prmi/benches/mem_search_bench.rs
• prmi/benches/primitives_bench.rs
• prmi/examples/probe_audit.rs
• prmi/src/index/spectrum.rs

📝 Walkthrough

Walkthrough

Adds a feature-gated C-ABI probe-count API, three hint/table-backed spectrum search implementations with property tests, Criterion benchmarks for mem-search and primitives, and a feature-gated probe-audit example that measures probe counts end-to-end.

Changes

Spectrum Search Optimization and Instrumentation

Layer / File(s)	Summary
Probe Counting C-ABI Interface prmi-sys/Cargo.toml, prmi-sys/src/lib.rs	spectrum-probe-count feature is declared and forwarded to prmi. Three feature-gated FFI functions (prmi_probe_count_enabled, prmi_probe_count_reset, prmi_probe_count_get) report/reset/read a thread-local probe counter; they no-op or return 0 when the feature is absent.
Probe Counting FFI Tests prmi-sys/tests/ffi_probe_count.rs	Adds an always-callable API test for the probe-counter FFI and a feature-gated integration test that builds an ISA-enabled sidecar, seeds probe counting, computes est_hint via prmi_isa_at, measures probes around backward searches, and includes a pack helper for 2-bit packing.
Spectrum Hint Algorithms and Correctness prmi/src/index/spectrum.rs	Adds kmer_lex_index; implements forward_spectrum_from_hint, backward_spectrum_tabled, and backward_spectrum_from_hint; and extends property tests to assert byte-identical traces vs cold paths and validate stale-hint safety and fail-closed behavior.
Memory Search Benchmarking Infrastructure prmi/Cargo.toml, prmi/benches/mem_search_bench.rs	Adds mem_search_bench bench target and an extensive Criterion suite that builds a synthetic reference with a tandem repeat, constructs forward/reverse corpora with ISA-derived hints (validating hinted equality during prep), and benchmarks model-launch and two hinted variants across UNIQUE and repeat regimes.
Primitives Benchmarking Suite prmi/benches/primitives_bench.rs	Adds primitives_bench bench target with deterministic synthetic inputs and throughput benchmarks for isa_at, sa_position_for, sa_positions, reverse-complement utilities, and 32-mer tokenization using a temp index fixture.
Comprehensive Probe Audit Example prmi/examples/probe_audit.rs	Feature-gated example that builds an index, defines a mean-probes-per-call helper around the FFI probe counter, prepares forward/reverse corpora (validating hinted equality), benchmarks probe counts for model-launch/tabled/hinted variants, and cleans up temporary files.

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly Related PRs

• fg-labs/prmi#16: Implements the underlying spectrum-probe-count probe-counting hooks that the new prmi-sys FFI functions rely on.
• fg-labs/prmi#11: Introduced the prmi-sys C-ABI shim layer that this PR extends with additional probe-count exports.
• fg-labs/prmi#19: Related to inverse-SA .isa hint plumbing and hinted execution paths used by the new spectrum-from-hint logic.

"I'm a rabbit in the sidecar, nibbling bits of code,
I count the probes that wander down the road,
Hints guide the hops across the suffix tree,
Benchmarks hum a steady melody,
Quiet tails and faster searches — hip hooray!"

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the three main additions: benchmarking suites (mem_search_bench, primitives_bench), hinted-spectrum prototypes (forward/backward from_hint), and thread-local SA-probe counter (prmi_probe_count_* FFI exports).
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

prmi/benches/primitives_bench.rs (1)

133-144: ⚡ Quick win

Consider guarding against very small reference lengths.

The block benchmark will panic if sa_num < block (i.e., if PRMI_BENCH_REFLEN is set to less than 256). With the default 2M reference this is never an issue, but adding a simple guard would make the benchmark more robust.

🛡️ Suggested guard

     for &block in &[16usize, 256usize] {
+        if sa_num < block as u64 {
+            continue; // skip if reference too small for this block size
+        }
         let start = sa_num.saturating_sub(block as u64) / 3; // arbitrary in-range start

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@prmi/benches/primitives_bench.rs` around lines 133 - 144, The benchmark can
panic when sa_num < block (small reference lengths); before computing start/use
of block in the loop over blocks (the for &block in &[16usize, 256usize] loop)
add a guard that skips or adjusts the iteration when sa_num is smaller than
block (e.g., if sa_num < block as u64 { continue } or choose a smaller block),
so that idx.sa_positions(black_box(start), black_box(&mut out)) is only called
with a valid start and out buffer.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@prmi/benches/mem_search_bench.rs`:
- Around line 177-201: The forward-repeat corpus generation in
build_forward_repeat produces high-occ forward queries but the bench
registration (the unique hinted variants logic around the block that handles
297-323) omits running hinted-repeat forward benches; add a mirrored
hinted-forward benchmark path so high-occ hinted behavior is measured: either
extend build_forward_repeat to emit FwdItem entries with the hint field set for
the repeat matches (using fx.idx.mem_search result m.sa_start) or add a new
builder (e.g., build_forward_repeat_hinted) that returns the same queries with
hint populated, and then register those items in the same way the unique hinted
variants are registered so the bench harness runs both unhinted and hinted
forward-repeat cases (referencing FwdItem, build_forward_repeat, mem_search,
m.sa_start, and CORPUS_SIZE to locate where to add/insert the new benchmark
entries).

In `@prmi/src/index/spectrum.rs`:
- Around line 1749-1761: The code unsafely narrows anchor_len to usize and
computes pivot + anchor_len without checking for overflow/out-of-bounds (see
anchor_len_usize, pivot, p_end and tokenize_32mer usage in this function);
mirror the safe behavior from mem_search_backward_from_hint: validate anchor_len
fits into usize (use checked conversion), ensure
pivot.checked_add(anchor_len_usize) and the resulting slice bounds are within
read.len() (return an error/None on failure) and avoid panicking; apply the same
guarded conversion/bounds checks to the other backward prototype around the
p_end computation at the 1822-1824 area.

---

Nitpick comments:
In `@prmi/benches/primitives_bench.rs`:
- Around line 133-144: The benchmark can panic when sa_num < block (small
reference lengths); before computing start/use of block in the loop over blocks
(the for &block in &[16usize, 256usize] loop) add a guard that skips or adjusts
the iteration when sa_num is smaller than block (e.g., if sa_num < block as u64
{ continue } or choose a smaller block), so that
idx.sa_positions(black_box(start), black_box(&mut out)) is only called with a
valid start and out buffer.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a172d913-40cb-4d5d-bf9c-dd34a3ad28f0

📥 Commits

Reviewing files that changed from the base of the PR and between 7df2f22 and 98c34e3.

📒 Files selected for processing (8)

• prmi-sys/Cargo.toml
• prmi-sys/src/lib.rs
• prmi-sys/tests/ffi_probe_count.rs
• prmi/Cargo.toml
• prmi/benches/mem_search_bench.rs
• prmi/benches/primitives_bench.rs
• prmi/examples/probe_audit.rs
• prmi/src/index/spectrum.rs

[nh13]

@coderabbitai review

[nh13]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.