refactor(rag): extract per-request hydration

[BigSimmo]

Summary

Pure structural extraction (X3 / #101, the next unit after #86's coverage gate): move the per-request hydration cluster out of src/lib/rag/rag.ts into a new src/lib/rag/rag-hydration.ts.

• What moved, byte-for-byte: DocumentRankingMetadataCache, createDocumentRankingMetadataCache, attachDocumentRankingMetadata, withCachedIndexQuality, attachIndexQualityMetadata, attachPageVisualEvidence — one contiguous block at rag.ts:1478-1716 on d76b0f73. The only edit to any body is the export keyword added to the type and to createDocumentRankingMetadataCache, which now cross the module boundary. withCachedIndexQuality and attachIndexQualityMetadata stay module-private: nothing outside the cluster calls them.
• Why the responsibility is cohesive: all six exist to hydrate already-retrieved SearchResult[] with data fetched per request — document labels/summaries, index quality, and page visual evidence — behind one bounded DocumentRankingMetadataCache that exists to stop the same document being fetched twice within a request. They share that cache and nothing else does; withCachedIndexQuality and attachIndexQualityMetadata are pure internals of that flow.
• Cycle-free, verified not assumed: I diffed every free identifier in the cluster against rag.ts's own top-level declarations and the intersection was empty — the cluster referenced no rag.ts-local symbol at all. The new module's 11 dependencies all resolve to stable siblings (@/lib/types, @/lib/supabase/admin, @/lib/document-enrichment, @/lib/image-filtering, @/lib/reindex-pipeline, @/lib/rag/rag-answer-text, @/lib/rag/rag-source-block). No back-edge to rag.ts.
• Public export strategy: rag.ts re-exports attachDocumentRankingMetadata and attachPageVisualEvidence (export { … } from "@/lib/rag/rag-hydration"), chosen deliberately to preserve the public @/lib/rag/rag API and avoid consumer churn — tests/rag-query-concurrency.test.ts dynamically imports both from @/lib/rag/rag and is unchanged. check:knip is clean with the re-export in place. rag.ts additionally imports createDocumentRankingMetadataCache and the DocumentRankingMetadataCache type, which it still uses in prepareCoverageGateResults and searchChunksWithTelemetry.
• Seven import bindings orphaned by the move were pruned from rag.ts (ChunkImage, ClinicalImageUseClass, compactContextText, fetchRelatedDocumentMetadata, isCommittedGenerationMetadata, metadataText, normalizeImageBbox), each verified to have no remaining reference.
• Budget ratcheted 4780 → 4543, preserving the existing "keep the reclaimed budget" intent.

This does NOT unblock prepareCoverageGateResults — and that was predicted

PR #1454 left prepareCoverageGateResults in rag.ts because it needs five rag.ts-only runtime symbols. The Codex review on PR #1461 correctly pointed out that hydration covers only two of those five, and shipping it confirms exactly that. The remaining three are a separate ranking/timing seam and are untouched here:

Symbol	Location	Why it is not hydration
selectRankedRetrievalResults	rag.ts:1825 (pre-move)	retrieval selection
applySecondStageRerankIfNeeded	rag.ts:679	second-stage ranking
measureSearchPhase	rag.ts:1975 (pre-move)	shared pipeline timing wrapper — 21 references, only 2 are hydration phases

#086 and the X3 work order are updated to record this rather than repeat the earlier over-claim.

Files changed

File	Change
src/lib/rag/rag-hydration.ts	New module, six declarations (+252)
src/lib/rag/rag.ts	Cluster removed, imports pruned, re-export added (+10 / −247)
scripts/check-maintainability-budgets.mjs	rag.ts budget 4780 → 4543
docs/codebase-index.md	RAG module-map row for rag-hydration.ts
docs/maturity-backlog-workorders.md	X3 progress entry for #101
docs/outstanding-issues.md	#086 updated: hydration shipped; ranking/timing seam still open

Line counts and movement evidence

• src/lib/rag/rag.ts: 4780 → 4543 (−237), measured with sourceLineCount from scripts/check-maintainability-budgets.mjs.
• Configured budget: 4780 → 4543. The gate reported 4780/4780 before and reports 4543/4543 now.
• git diff --stat: 6 files changed, 289 insertions(+), 262 deletions(-).
• git diff --color-moved=zebra: 239 of 262 added lines classified as moved; the 23 plain additions are imports, the header comment, and the two export keywords. The 8 plain removals are the pruned import bindings plus those same two declarations.
• Total src/lib/rag/** LOC: 18141 → 18156 (+15) — ordinary import/export overhead. Each moved symbol is defined exactly once repo-wide; no pipeline body was duplicated.
• Byte-identity verified by extracting rag.ts:1478-1716 from origin/main and diffing against the new module: identical modulo the two added export keywords.

Verification

• npm run verify:pr-local

During development, use npm run verify:cheap as the faster iteration gate before the final PR-local preflight.

• npm run verify:ui when UI, routing, styling, browser behavior, reduced-motion, or forced-colors behavior changed
• npm run verify:release before release or handoff confidence claims

For retrieval, ranking, selection, chunking, source/citation rendering, or answer-contract changes, verify:pr-local runs eval:rag:offline automatically. Run the offline command directly during iteration before spending a live eval.

• npm run eval:retrieval:quality (must stay 36/36) when retrieval, ranking, selection, chunking, or scoring behavior changed — CI cannot run it (needs live keys), so run it locally and paste the summary. A metadata/governance-weighting change once buried correct docs (recall 1.0→0.76) and only this eval caught it.
• npm run eval:rag -- --limit 15 + npm run eval:quality -- --rag-only when answer generation, the synthesis prompt, or answer post-processing changed (grounded-supported must not drop; citation-failure 0)
• npm run check:production-readiness when clinical workflow, privacy, environment, Supabase, source governance, or deployment behavior changed
• npm run check:deployment-readiness when deployment startup, hosting, or rollout behavior changed

UI verification not run: no UI, routing, styling, browser, reduced-motion, or forced-colors surface is touched — the diff is two src/lib/rag modules, a budget script, and three docs.

Verification not run (provider-backed, deliberately withheld): eval:retrieval:quality, eval:rag, eval:quality --rag-only, check:production-readiness, check:deployment-readiness all call live OpenAI/Supabase and none was run. No live evaluation and no RAG canary was run, because this is a zero-behaviour-change structural extraction: the moved bodies are byte-identical, no comparator, threshold, default, fallback, ordering rule, or await changed, and the byte-range diff against origin/main is the evidence. A reviewer who disputes that classification can refute it cheaply by re-running that byte-range comparison; if it is disputed, require a live canary pair before merge.

Gates run

Command	Exit	Decisive output
npm run typecheck	0	tsc --noEmit completed with no diagnostics
npm run lint	0	eslint --max-warnings 0 completed with no output
npm run check:knip	0	no unused/unlisted/unresolved/duplicate findings (one pre-existing .css hint)
npm run check:maintainability-budgets	0	[maintainability] src/lib/rag/rag.ts: 4543/4543 lines
npm run test -- tests/rag-query-concurrency.test.ts tests/retrieval-query-variants.test.ts tests/rag-tail-latency.test.ts tests/rag-shared-cache.test.ts tests/rag-variant-early-exit.test.ts	0	Test Files 5 passed (5) / Tests 83 passed (83)
npm run eval:rag:offline	0	Test Files 22 passed (22) / Tests 572 passed (572) / Offline RAG fixture and production-contract checks passed.
npm run check:outstanding-issues	0	144 rows (71 open, 73 archived), unique ids, next-id=147 above the highest
npm run format:check	0	All matched files use Prettier code style!
npm run verify:cheap	0	Test Files 436 passed (436) / Tests 4574 passed | 4 skipped (4578)
npm run verify:pr-local	0	✓ Compiled successfully in 48s, Client bundle secret surface check passed., Offline RAG fixture and manifest validation passed (36 golden cases, 22 suites)
git diff --check	0	no whitespace errors

Risk and rollout

• Risk: LOW for behaviour, MEDIUM for surface sensitivity — a protected RAG surface (src/lib/rag/**), so the surface is high-consequence even though the diff is a mechanical move. The residual risk is a mis-transcribed body, refuted directly by the byte-range comparison against origin/main and by 4574 green unit tests including the 36-case offline golden fixture set.
• Rollback: a single-commit git revert restores rag.ts and the 4780 budget exactly. No data migration, no cache-format change, no persisted state.
• Provider or production effects: None. No OpenAI, Supabase, Railway, live database, ingestion, answer-generation, deployment, or release operation occurred. GitHub was used only to fetch main, push this branch, and open this PR.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

RAG impact: no retrieval behaviour change — pure module extraction

Notes

• Zero intentional behaviour change: no owner or document scope enforcement, admission-before-scope ordering, retrieval ordering, released-result ordering, ranking comparator or comparator-key order, evidence selection, coverage threshold or default, cache semantics, abort semantics, conservative fallback, citation verification, numeric-grounding verification, source governance rule, telemetry name, timing boundary, error propagation, rollback behaviour, clinical behaviour, or provider behaviour was intentionally changed. The per-request cache's identity and lifetime are unchanged — rag.ts still constructs it and threads it through exactly as before.
• Remaining coupling: rag.ts still owns prepareCoverageGateResults and the ranking/timing seam above. rag-hydration.ts has no back-edge to rag.ts.
• Handoff: chore(deps-dev): bump prettier from 3.9.0 to 3.9.1 #98, perf: pre-compute query phrases once per rankAnswerEvidence call #99 and docs: record phase 6 re-audit #100 remain separate follow-up tasks and are untouched.

---

Generated by Claude Code

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 36 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d1ddf4a4-ec37-4e52-9c36-0e7d138724ca

📥 Commits

Reviewing files that changed from the base of the PR and between ee34b4d and 0e70a6a.

📒 Files selected for processing (5)

• docs/codebase-index.md
• docs/maturity-backlog-workorders.md
• scripts/check-maintainability-budgets.mjs
• src/lib/rag/rag-hydration.ts
• src/lib/rag/rag.ts

---

_{Comment @coderabbitai help to get the list of available commands.}