feat(mem-search): one-shot maximal exact forward and backward match (prmi_mem_search[_backward])

[nh13]

PR #4 of the v0.2 stack (carries commit 8d17f5b). Base is feat/v0.2-boundary-kmt (#16) — stacked on #3; merge after it. Tracked in V0.2_PR_STACK.md row #4.

What this does

Adds the one-shot maximal-exact-match primitive on top of the spectrum engine, so a consumer can get the maximal forward (or backward) match in a single FFI call instead of walking the full breakpoint trace:

• LearnedIndex::mem_search / mem_search_backward (spectrum.rs) — return the maximal (deepest) step of forward_spectrum_auto / backward_spectrum. Byte-identical by construction (they are the last breakpoint), reusing the .kmt table + occ-1 fast path unchanged. est_hint is accepted but reserved (the ISA/no-search launch lands later); ignoring a launch hint is byte-identical.
• prmi_mem_search / prmi_mem_search_backward FFI (prmi-sys/src/lib.rs) — with the PRMI_MEM_WANT_INTERVAL flag the SA interval is also written.
• Oracle + FFI tests proving mem_search ≡ maximal forward_spectrum step and mem_search_backward ≡ maximal backward step.

Cherry-picked cleanly onto #3 (no conflicts — purely additive).

Carry-forward consistency

The two new FFI entry points were authored before the #15 FFI-guard review fix, so I applied the same u64→usize pac_num_bases guard (via the existing packed_pac_bytes helper, returning -2) to prmi_mem_search and prmi_mem_search_backward, and updated their -2 doc enumerations — matching every other spectrum FFI entry point. The Rust mem_search/_backward need no extra packed-pac guard: they delegate to the already-guarded forward_spectrum_auto / backward_spectrum.

Green-pass

• cargo build --workspace ✅
• cargo clippy --workspace --all-targets --all-features -- -D warnings ✅
• cargo +nightly fmt --all -- --check ✅
• cargo test --workspace ✅ — 143 lib tests + all integration/FFI (incl. mem_search_equals_maximal_forward_step, mem_search_ffi_matches_forward_spectrum_maximal, mem_search_ffi_error_paths); only Plan-3 deferral tests remain ignored.

Summary by CodeRabbit

• New Features

  • Introduced forward and backward memory search capabilities enabling one-shot maximal exact match queries with optional interval output control via configuration flags.

• Tests

  • Expanded test coverage with end-to-end FFI tests and property-based validation of memory search operations against independent reference implementations and edge cases.

[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: 1064a058-7479-47c1-a358-d60caae204db

📥 Commits

Reviewing files that changed from the base of the PR and between 77bdf41 and 43bb1a3.

📒 Files selected for processing (3)

• prmi-sys/src/lib.rs
• prmi-sys/tests/spectrum_ffi.rs
• prmi/src/index/spectrum.rs

---

📝 Walkthrough

Walkthrough

This PR introduces a one-shot maximal exact match query API spanning both the Rust library layer and its C-FFI interface. A new MemMatch struct represents match results, and corresponding library methods compute maximal forward and backward matches. These are exposed via C-FFI with optional interval output control and comprehensive error handling.

Changes

One-shot maximal exact match queries

Layer / File(s)	Summary
Data model and core search methods prmi/src/index/spectrum.rs	Introduces MemMatch struct with match_len, sa_start, and occ fields. Implements LearnedIndex::mem_search as the maximal step from forward_spectrum_auto, and LearnedIndex::mem_search_backward as either the last backward step or anchor interval when no left extension exists.
Library property tests prmi/src/index/spectrum.rs	Validates mem_search against independent brute-force forward oracle and against both spectrum paths. Validates mem_search_backward against backward oracle with edge cases for zero occurrences and zero pivot.
FFI API contract and flag constant prmi-sys/src/lib.rs	Adds PRMI_MEM_WANT_INTERVAL flag to request conditional interval outputs. Implements prmi_mem_search and prmi_mem_search_backward FFI entry points with pointer validation, PAC byte-length conversion, conditional interval-pointer checks, and panic-to-error-code mapping.
FFI integration tests prmi-sys/tests/spectrum_ffi.rs	Tests both FFI functions validating interval outputs match library computation when requested, and outputs remain untouched when flag is absent. Includes negative-path tests for null pointers, invalid arguments, and flag-pointer consistency.

Sequence Diagram

sequenceDiagram
  participant Test
  participant FFI as C FFI Layer
  participant Lib as LearnedIndex
  participant Oracle as Reference Oracle
  Test->>FFI: prmi_mem_search(query, flags)
  FFI->>Lib: mem_search(query)
  Lib->>Lib: forward_spectrum_auto()
  Lib-->>FFI: MemMatch {match_len, sa_start, occ}
  FFI->>FFI: Conditionally write outputs based on flags
  FFI-->>Test: return code + outputs
  Test->>Test: Validate against Oracle reference
  Test->>FFI: prmi_mem_search_backward(read, pivot, flags)
  FFI->>Lib: mem_search_backward(anchor, read)
  Lib->>Lib: backward_spectrum() or anchor fallback
  Lib-->>FFI: MemMatch {match_len, sa_start, occ}
  FFI-->>Test: return code + outputs
  Test->>Test: Validate against Oracle reference

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fg-labs/prmi#11: Introduces the handle-validation and thread-local error-message patterns used by the new FFI entry points.

Poem

🐰 A hopping leap from forward to back,
Match length queries on the spectral track,
Intervals optional, errors in hand,
One-shot searches across the land! 🌾

🚥 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 pull request title accurately and specifically summarizes the main change: adding one-shot maximal exact forward and backward match functions (prmi_mem_search and prmi_mem_search_backward) to the spectrum engine.
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.