feat(store): replace FTS5 default ranking with weighted BM25

[daniel-baf]

Closes #241

PR Type

• type:bug — Bug fix
• type:feature — New feature
• type:docs — Documentation only
• type:refactor — Code refactoring (no behavior change)
• type:chore — Maintenance, dependencies, tooling
• type:breaking-change — Breaking change

Summary

• Replaced SQLite FTS5 default ranking (fts.rank) in Store.Search query with a weighted BM25 query: bm25(observations_fts, 5.0, 1.0, 0.0, 0.0, 0.0, 3.0).
• Prioritizes matches in title (5.0 weight) and topic_key (3.0 weight) over lower-relevance columns like tool_name or type.
• Added unit test coverage validating that title matches rank higher than content matches.

Changes

File	Change
internal/store/store.go	Replace fts.rank with bm25(...) query and update ORDER BY clause
internal/store/store_test.go	Add TestSearch_WeightedBM25Ranking unit test

Test Plan

• Unit tests pass locally: go test ./...
• E2E tests pass locally: go test -tags e2e ./internal/server/...
• Manually tested the affected functionality (verified via unit test)

Contributor Checklist

• I linked an approved issue above (Closes #241)
• I added exactly one type:* label to this PR
• I ran unit tests locally
• I ran e2e tests locally
• Docs updated (no behavior change needing doc changes)
• Commits follow conventional commits format
• No Co-Authored-By trailers in commits

Summary by CodeRabbit

• Bug Fixes
  • Improved search result ranking so results are ordered using a more accurate BM25-based score, better prioritizing matches based on which observation fields contain the query.
• Tests
  • Added coverage to verify weighted BM25 ranking behavior, ensuring title matches are ranked ahead of content matches.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0218f1aa-4d74-4f14-9979-b5a6e8364ad9

📥 Commits

Reviewing files that changed from the base of the PR and between dc1d2b5 and 237009e.

📒 Files selected for processing (2)

• internal/store/store.go
• internal/store/store_test.go

---

📝 Walkthrough

Walkthrough

Store.Search now computes weighted BM25 scores instead of using fts.rank, orders results by the projected rank, and includes a test verifying title matches rank ahead of content matches.

Changes

Weighted BM25 FTS5 Ranking

Layer / File(s)	Summary
BM25 ranking and regression coverage internal/store/store.go, internal/store/store_test.go	Store.Search uses weighted bm25() scoring and orders by the projected rank alias. TestSearch_WeightedBM25Ranking verifies title-match results precede content-match results.

Estimated code review effort: 2 (Simple) | ~8 minutes

Suggested reviewers: copilot, alan-thegentleman, gentleman-programming

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: replacing FTS5 default ranking with weighted BM25 in store search.
Linked Issues check	✅ Passed	The query change and ranking test match issue #241’s weighted BM25 search-ranking requirements.
Out of Scope Changes check	✅ Passed	The PR stays focused on search ranking and its regression test, with no unrelated changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[daniel-baf]

Heads up: I opened #537 for issue #140, which changes the same Store.Search FTS query path from default FTS ranking to trigram-aware search.

Merge-order note:

• If fix(store): support CJK search with trigram FTS #537 merges first, this PR should rebase and apply the weighted BM25 expression only in the FTS branch of Search. The short-token fallback branch should keep its synthetic 0.0 as rank, because bm25(observations_fts, ...) is only valid when querying observations_fts.
• If this PR merges first, fix(store): support CJK search with trigram FTS #537 should rebase and preserve the weighted BM25 expression when it introduces the trigram FTS branch.

The intended final FTS branch shape is roughly:

bm25(observations_fts, 5.0, 1.0, 0.0, 0.0, 0.0, 3.0) as rank
...
WHERE observations_fts MATCH ? AND o.deleted_at IS NULL
ORDER BY rank

The v2/short-token fallback path added by #537 should not use BM25.

[Copilot]

Pull request overview

This PR updates Engram’s SQLite FTS5-backed observation search ranking to use an explicit weighted BM25 score instead of the default fts.rank, so results prioritize matches in higher-signal columns (notably title and topic_key) within Store.Search.

Changes:

• Replaced fts.rank with bm25(observations_fts, 5.0, 1.0, 0.0, 0.0, 0.0, 3.0) AS rank in the Store.Search FTS query and updated the ORDER BY to use the new alias.
• Added a unit test ensuring a title match ranks ahead of a content-only match for the same query term.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
internal/store/store.go	Updates the observations FTS query to use weighted BM25 scoring and orders by the computed rank.
internal/store/store_test.go	Adds a regression test validating the intended ranking preference (title > content).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.