SIGN IN SIGN UP

refactor(reranker): extract query rerank pipeline into src/internal (#59) (#65)

Move the query reranker pipeline out of the 6000-line src/tools.ts into
two new leaf modules, behavior-preserving (no logic changes):

- src/internal/retrieval-shared.ts — cross-cutting low-level helpers used
  by both the reranker and other tools.ts handlers: time/staleness
  (isStale, getFreshnessScore, getDaysUntil, isEntryExpiringSoon,
  findUpcomingEventDate + thresholds + DATE_PATTERN), tag utilities
  (parseTags, canonicalizeTags, getLifecycleTags, LIFECYCLE_TAGS,
  TAG_ALIASES), isTrackedNamespace, RELAXED_QUERY_STOPWORDS. Pure leaf:
  imports only db.js + types.js.

- src/internal/reranker.ts — the ranking/injection/assessment pipeline:
  buildRelaxedLexicalQuery, shouldApplyDefaultQuerySuppression,
  getTrackedStatusAssessments, injectCanonicalQueryEntries,
  injectAttentionQueryEntries, rerankQueryResults,
  QUERY_RERANK_OVERFETCH_MULTIPLIER, DEFAULT_SEARCH_RECENCY_WEIGHT,
  TrackedStatusAssessment, plus their helpers. Imports retrieval-shared,
  db, types. No import back into tools.ts — no cycle.

Why two modules: getTrackedStatusAssessments transitively needs the tag
utilities, which ~10 unrelated tools.ts handlers also use. Putting them
in retrieval-shared.ts (rather than reranker.ts, where they don't belong,
or leaving them in tools.ts, which would force a circular import) keeps
both new files clean leaves.

- benchmark/runner.ts now imports the reranker surface from
  src/internal/reranker.js (was src/tools.js).
- tests/benchmark-import-boundary.test.ts updated: benchmark/ must NOT
  import reranker names from src/tools.ts, and may import only the curated
  surface from src/internal/reranker.ts. Red/green verified.
- tools.ts no longer re-exports the pipeline (the dedicated module is the
  explicit surface); it imports only the 12 names it uses internally.

Verified byte-identical: rerankQueryResults/assessTrackedStatus bodies
diff-clean vs main (modulo the added `export`); runner-parity.test.ts
proves production_ranker top-k still matches memory_query across 4 corpus
shapes; full suite green (the lone flake is the pre-existing
wizard-routes timing test, unrelated). Pure refactor — no CHANGELOG entry
per repo policy.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
M
Magnus Gille committed
cb18bf54f4979e96c8faaa95dadb2dccc93c39a3
Parent: c838fce
Committed by GitHub <noreply@github.com> on 5/29/2026, 9:09:17 PM