feat(examples): collect_gate — per-phase probe-attribution harness

[nh13]

Sibling PR 1 of 2 (the other adds a C usage example for prmi_collect_smems). Closes out the collect deliverable with its profiling tooling.

What

Adds examples/collect_gate: run LearnedIndex::collect_smems over a FASTQ against a built prmi sidecar, write the emitted SMEMs to a TSV (rid m n k s), and report total SA-probes/read with a per-phase breakdown — pass-1 left/right, reseed left/forward, and pass 3 — from the attrib buckets.

Now that pass 3 is live (#34), all five attrib buckets populate, so this gives a complete per-read probe attribution for a real read — useful for deciding whether any future optimization (e.g. eventually the deferred LCP-accel wiring, #36) would actually pay on a given workload, without an end-to-end consumer round-trip.

Shape

• Gated on the spectrum-probe-count feature (the probe counter + attrib are compiled out without it); a stub main on the default build prints the feature hint and exits 2.
• Paths from env — PRMI_PREFIX / PRMI_FQ / PRMI_PAC required, no machine-specific defaults (mirrors the ffi_overhead example; the perf-branch original had hardcoded local paths, dropped here). CollectOpts knobs default to the bwa-mem values; PRMI_OUT optional.
• stdout is just the probes/read number, for scripting.

Testing

cargo build --all-targets clean in both feature configs (stub-main default + real harness with spectrum-probe-count); fmt/clippy clean; the missing-env path exits 2 with a clear message. No production code touched — example only. Pre-PR /coderabbitai-review: 0 findings.

Summary by CodeRabbit

• Documentation
  • Added a new example demonstrating how to process FASTQ sequences with the index, collect results to TSV output, and generate performance benchmark metrics.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9f37c928-7e60-48ad-8f89-fb041eec9f35

📥 Commits

Reviewing files that changed from the base of the PR and between 7da93a5 and 11b5860.

📒 Files selected for processing (1)

• prmi/examples/collect_gate.rs

---

Walkthrough

Adds prmi/examples/collect_gate.rs, a feature-gated binary that runs LearnedIndex::collect_smems over a FASTQ file, streams SMEM fields to a TSV, and reports global probe counters and per-depth/attrib breakdowns. Requires the spectrum-probe-count feature; exits with code 2 otherwise.

Changes

collect_gate.rs benchmark example

Layer / File(s)	Summary
Feature-gate stub and main setup prmi/examples/collect_gate.rs	Stub main exits with code 2 when spectrum-probe-count is absent. Feature-enabled main parses CollectOpts, loads the PRMI index and packed PAC, opens FASTQ/output files, and resets probe/attrib counters.
FASTQ iteration and SMEM collection prmi/examples/collect_gate.rs	Reads FASTQ records, converts bases to numeric codes, calls collect_smems with on-demand buffer resizing on "need" errors, and writes rid m n k s rows to the TSV output.
Finalization and probe reporting prmi/examples/collect_gate.rs	Flushes output, guards against zero reads, computes total probes, prints per-depth bucket and per-attrib disjoint-bucket breakdowns to stderr, and emits probes/read to stdout.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fg-labs/prmi#32: Introduces LearnedIndex::collect_smems and the spectrum-probe-count-gated attrib probe counters that this example directly exercises.

🚥 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 and specifically describes the main change: a new example utility for per-phase probe attribution analysis.
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.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/v0.3-collect-gate

---

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.