perf(spectrum): forward one-shot returns the insertion point, recovers the interval from it

[nh13]

v0.3 perf series (authored fresh on main; the perf branch diverged from the merged O(log) internals, so it is re-derived, not cherry-picked).

What

forward_maximal_len now returns (match_len, insertion_point). mem_search recovers the maximal match's SA interval by galloping its lower bound from that insertion point (which sits at the interval's edge) instead of re-looking-up the prefix's 32-mer key and re-searching the model window.

Why

find_boundary is seed-independent — the seed only sets the probe count, never the boundary returned. The full query's insertion point is right at the edge of the maximal match's interval, so galloping from it is ~0 probes for a unique deep match, versus ~log2(occ) when a high-occ 32-mer prefix's loose model window brackets the wide block. Net: fewer SA probes on the forward one-shot, byte-identical output.

Byte-identity

Verified by the existing mem_search_equals_maximal_forward_step oracle proptest (mem_search vs an independent brute-force forward_spectrum maximal step) — a wrong lower would change sa_start and fail it. All byte-identity oracles pass.

Notes

• mem_search_backward ignores the insertion point: its q is the reverse-complement, so ip is in RC-strand space while the forward p_slice recovery is forward-space (different SA regions) — it can't seed that recovery.
• The (match_len, ip) return also unblocks the upcoming min_intv-truncated reseed primitive (TRUNC_IV), which needs the insertion point.

Self-reviewed with /coderabbitai-review before opening (0 findings).

Summary by CodeRabbit

• Refactor
  • Optimized internal search indexing mechanisms to improve code efficiency and maintainability. No user-facing changes in this update.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c1b03e64-93a9-41d7-b21d-951ffd1f0ff2

📥 Commits

Reviewing files that changed from the base of the PR and between 185d4ed and ce8051f.

📒 Files selected for processing (1)

• prmi/src/index/spectrum.rs

---

📝 Walkthrough

Walkthrough

forward_maximal_len is refactored to return both the maximal forward match length and the SA insertion point. Documentation and empty-input handling are updated, the return statement includes the insertion point, and call sites in mem_search and mem_search_backward are adapted to destructure the tuple.

Changes

forward_maximal_len tuple return refactoring

Layer / File(s)	Summary
forward_maximal_len refactoring prmi/src/index/spectrum.rs	Documentation describes the new tuple return (match_len, insertion_point). Empty input returns (0, 0). Final return statement switches from returning only match length to returning the tuple with computed insertion point.
mem_search untabled path prmi/src/index/spectrum.rs	Destructures the new tuple into (match_len, ip), uses insertion point ip to directly seed find_boundary instead of computing window bounds from lookup(qm_key).
mem_search_backward call site prmi/src/index/spectrum.rs	Adapts to the tuple return by binding (match_len, _ip) and using only match_len for control flow while discarding the insertion point.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fg-labs/prmi#23: Both PRs modify forward_maximal_len and its use in mem_search/mem_search_backward, including interval recovery via find_boundary.
• fg-labs/prmi#17: Both PRs touch the spectrum engine's maximal forward/backward match computation in forward_maximal_len that the mem_search APIs expose.
• fg-labs/prmi#21: Both PRs modify find_boundary flow in spectrum.rs—this PR changes how interval recovery seeds it using forward_maximal_len's insertion point, while that PR adds SA prefetching in boundary-search paths.

Poem

🐰 A tuple takes flight where one value once gleamed,
Two travelers born from the match's sweet seam—
The length and the point where the suffix arrays meet,
Now mem_search dances with insertion-point feet!

🚥 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 describes the main change: forward_maximal_len now returns the insertion point and mem_search recovers the interval from it, which is the core optimization in this changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

---

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.