refactor(rag): extract evidence-gate predicates into rag-evidence-gates (maturity X3)

[BigSimmo]

Summary

Phase 5 / maturity X3: the first real decomposition of the rag.ts monolith, enabled by X2's src/lib/rag/ directory (#994, now merged).

• Extracted 14 pure query/evidence gate predicates from rag.ts into a new src/lib/rag/rag-evidence-gates.ts: the document-alias / admission title-support checks (hasDocumentAliasWithoutTopTitleSupport, hasAdmissionCommunityLookupIntent, hasAdmissionCommunityTitleSupport, directTitleOrAliasSupport, and the internal normalizeDocumentAliasText) and the evidence-sufficiency gates (topEvidenceText, hasAnyTerm, isRiskFlowchartNextStepQuery, hasRiskFlowchartActionEvidence, hasDoseAmountEvidenceForGate, hasRouteEvidenceForGate, hasFrequencyEvidenceForGate, hasDirectSourceImageEvidence, sourceImageRequiredForQuery).
• Behaviour-preserving: the function bodies are byte-identical to their previous rag.ts definitions. rag.ts imports the 13 it still calls (normalizeDocumentAliasText stays module-internal — used only by the alias helpers) and drops the four sibling imports those predicates alone consumed.
• Ratchets the rag.ts maintainability budget 5238 → 5030 to lock in the reduction (now 5018 lines), directly addressing the audit's "budget caps but never reduces" note.
• shouldReturnBeforeMemory deliberately stayed in rag.ts (it depends on the later-defined shouldUseMemoryBeforeFastPath), keeping the extraction a clean closure with no forward references.

Diff: 3 files — +rag-evidence-gates.ts (154), rag.ts (−146/+15), budget (±1). Rebased onto main after #994 landed (the interim stacked base is gone); the diff is now purely the X3 extraction.

Verification

Full local gate on the rebased branch (on top of current main), all green:

• npm run typecheck — pass.
• npm run test — 3017 pass; the only failure is the pre-existing container-only pdf-extraction-budget flake (a Python child-tree kill-timing assertion, no rag dependency), which refactor(rag): extract the rag cluster into src/lib/rag/ (maturity X2) #994 already proved fails identically on clean origin/main — X3's diff touches only rag + the budget script, so it cannot affect it.
• npm run lint — pass (0 warnings; removed the now-unused imports).
• npm run check:maintainability-budgets — pass (src/lib/rag/rag.ts 5018/5030); npm run check:github-actions — pass.
• npm run docs:check-index — pass; npm run docs:check-links — pass (989 refs); npm run format:check — pass.
• UI verification not run: no UI/component change — pure library-layer extraction.
• Retrieval/answer evals not run: no retrieval, ranking, selection, chunking, or answer-contract logic changed — the predicates are byte-identical and only relocated, so offline/live evals are unaffected. No dependency change.

Risk and rollout

• Risk: low — a behaviour-preserving move of self-contained pure predicates (verified: every dependency is an already-imported sibling symbol; no cycle; content match at the git level). Proven by the full type + test gate.
• Rollback: revert the PR (single squash commit; no data or schema effect).
• Provider or production effects: None.

Clinical Governance Preflight

Behaviour-preserving relocation of pure predicate helpers; no clinical behaviour, data flow, or configuration changed. Each item holds by construction:

• 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

Notes

Next X3 increments (separate PRs) can peel further cohesive clusters off rag.ts (e.g. the answer-JSON schema + section-sanitization group, or the classifier-verdict memo cluster). A separate docs pass is also queued to re-verify the now-stale file:line citations in clinical-hazard-analysis.md / rag-injection-threat-model.md, which reference a bygone ~7,000-line rag.ts.

---

Generated by Claude Code

Summary by CodeRabbit

• Improvements
  • Improved answer quality by applying more consistent evidence checks to clinical searches.
  • Better recognizes requests involving admissions, community care, flowcharts, risk matrices, doses, routes, and frequencies.
  • More reliably identifies relevant document titles, aliases, labels, tables, charts, figures, and source images.
  • Strengthened handling of visual-source requests so responses are supported by appropriate image or table evidence.

[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]

📝 Walkthrough

Walkthrough

RAG evidence-gating predicates were extracted from rag.ts into a dedicated module, imports were updated, and the maintainability line budget for rag.ts was reduced from 5238 to 5030.

Changes

RAG evidence gate refactor

Layer / File(s)	Summary
Extract evidence gate predicates src/lib/rag/rag-evidence-gates.ts, src/lib/rag/rag.ts	Query-intent, title-support, risk-flowchart, medication-evidence, and source-image predicates now live in the dedicated gate module, while rag.ts imports them and removes the former local helpers and unused imports.
Tighten maintainability budget scripts/check-maintainability-budgets.mjs	The maximum permitted line count for src/lib/rag/rag.ts changes from 5238 to 5030.

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

Possibly related PRs

• BigSimmo/Database#443: Adds overlapping admission/community intent and title-support gating logic.
• BigSimmo/Database#446: Modifies related RAG evidence-coverage gating logic.
• BigSimmo/Database#571: Changes medication dose, route, and frequency evidence-gate behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.
Title check	✅ Passed	The title is concise and accurately describes the main change: extracting rag evidence-gate predicates.
Description check	✅ Passed	The PR description matches the template with summary, verification, risk/rollout, clinical preflight, and notes sections filled in.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/maturity-phase-5-rag-decomposition

---

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

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.