feat(rag): figure-aware extractive selection for dose/monitoring answers (E-3c PR-C)

[BigSimmo]

Summary

E-3c PR-C — attacks the worst finding of the run-#58 targeting baseline: dose 1/5 and monitoring 1/5, with every miss the same defect — the answer omits the concrete figure or schedule the clinician asked for, while a cited chunk contains it (the extractive sorter prefers the shortest same-priority sentence, which is usually the figure-less one).

• Lead-slot figure guarantee: when no lead fact carries the asked-for figure but a later extracted fact does, promote it (dose swaps the last of its two lead slots; monitoring appends a second sentence). No-op when a lead already carries a figure — currently-passing answers are byte-identical (test-pinned).
• Nuke-proofing guard: a figure is promoted only when the citing chunk's claim-support corpus verbatim supports it — atom-for-atom for value-bearing figures (via the shared clinicalValueAtomKey now exported from rag-claim-support), and verbatim-substring for genuinely zero-atom figures like "annually" (the post-review P2 fix, proven both directions). Digit+unit intervals such as "every 6 weeks" turn out to yield quantity atoms, so atom identity refuses unit mismatches; the interval pattern's full-match alternation ordering (CodeRabbit critical, fixed in 02b5c78) hardens the verbatim fallback against any future regex/atom-coverage drift. A promoted figure therefore always survives both numeric verification and claim support; the guard was proven load-bearing by red-testing it disabled.
• Fallback preference: the dose/threshold generation-fallback now prefers the safe single-chunk candidate that carries the intent figure over the first safe one — the safety gate itself is unchanged and order-stable (filter semantics verified side-effect-free).
• Fallback helpers extracted to rag-extractive-answer.ts (cycle-check verified); rag.ts down to 4901/5030.

Both reviewer subagents pre-push, no P0/P1:

• clinical-governance-reviewer APPROVE-WITH-NITS — all six clinical concerns cleared end-to-end: a promoted figure can never lack verbatim chunk support; citation bindings preserved (promotion reorders prominence, never touches the citation set); conservative failure test-proven; unsafe fallback candidates impossible; wrong-drug risk controlled by the pre-existing entity/multi-drug-table guards; no PHI surface.
• rag-retrieval-reviewer APPROVE-WITH-NITS — no-op path verified byte-identical, atom-key identity verified, 2-sentence append gate-safe, intent double-gated, zero retrieval/ordering change with the imputation contract test green. Its P2 (zero-atom figures passing the guard trivially, safe-direction) is fixed in this PR with discriminating tests.
• CodeRabbit post-push findings all resolved in 02b5c78: interval-pattern alternation reorder (+ mismatched-unit and genuine zero-atom "annually" test coverage), non-discriminating guard test replaced, promotionAtomKey hand-mirror deleted in favour of the exported key.

Six original discriminating tests each verified failing on prior code. Full suite 3068 passed pre-P2-fix; subsequent fixes re-verified across the focused extractive/claim-support/fallback suites (135 tests) + typecheck + lint.

RAG impact: behaviour change — canary pair: baselines #57/#58/#59 (banked) -> E-4 dispatch immediately post-merge; extractive answer composition + fallback candidate preference only; retrieval, ranking, and selection ordering untouched (adversarially verified); regression = single-commit revert per the proven drill.

Verification

• Red-proofs: monitoring lead promotion, dose slot swap, fallback preference each fail on prior code; nuke-guard proven load-bearing (disabled ⇒ unsupported figure ships); zero-atom guard proven both directions
• Focused: extractive-formatting 34/34; fallback + eval-cases + offline + contract + extractive-first + imputation contract green (claim-support + extractive-first 50/50 re-run post-review)
• npm run test — 3068 passed / 1 known container-only pdf artifact (pre-P2-fix tree; later fixes re-verified focused)
• typecheck, eslint, prettier, maintainability budgets (rag.ts 4901/5030) — clean
• E-4 live pair vs #57/[WIP] Refactor monolithic front‑end and decouple domain logic #58/[WIP] Optimize search and ingestion performance #59 — post-merge, merge-then-validate per the user-set precedent, revert drill armed

Risk and rollout

• Risk: medium — deliberately increases how often concrete dose figures/schedules appear in clinician-visible answers, bounded by the double guard (promotion corpus check + the unchanged downstream claim-support/numeric gates, so worst-case is a conservative evidence-gap, never an unsupported figure). Blast-radius cases enumerated: currently-passing dose/monitoring quality-* cases are no-op-pinned; watch relevance/fail_closed in the pair.
• Rollback: single revert; no schema/env/cache-version changes.
• Provider or production effects: the E-4 pair dispatch (~$3–6, user-authorized envelope).

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use — promotion is strictly narrower than the unchanged claim-support + numeric gates (reviewer-traced)
• No patient-identifiable document workflow was introduced or expanded
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy) — no access changes
• 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: dose/monitoring answers gain verbatim-supported figures — the most clinically sensitive change of the wave, double-guarded, governance-reviewed, live-pair-validated

🤖 Generated with Claude Code

https://claude.ai/code/session_01EXsJcLrbZUXwnBeG91cVo9

Summary by CodeRabbit

• New Features

  • Extractive answers now prioritize cited dose and monitoring figures relevant to the question.
  • Fallback answers more reliably include the requested numeric detail when generation is incomplete.
  • Citations and supporting sources are narrowed to evidence directly used in the answer.

• Bug Fixes

  • Improved handling of figure selection when source evidence lacks structured value details.
  • Prevented unsupported figures from adjacent context from appearing in answers.

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

[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

The RAG extractive pipeline now promotes evidence-supported dose and monitoring figures into lead answers and selects figure-bearing candidates during generation-failure recovery. Shared fallback helpers, tests, and review ledger records were added.

Changes

Extractive RAG recovery

Layer / File(s)	Summary
Figure-aware extractive synthesis src/lib/rag/rag-claim-support.ts, src/lib/rag/rag-extractive-answer.ts, tests/extractive-answer-formatting.test.ts	Exports claim-support utilities, detects dose and monitoring figures, promotes evidence-supported facts into lead slots, and tests adjacent-context and zero-atom cases.
Safe extractive fallback recovery src/lib/rag/rag-extractive-answer.ts, src/lib/rag/rag.ts, tests/rag-answer-fallback.test.ts, docs/branch-review-ledger.md	Adds shared fallback safety and citation-retention helpers, prefers candidates carrying the requested figure after generation failure, tests dose selection, and records review outcomes.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RAG
  participant ExtractiveAnswer
  participant ClaimSupport
  participant CitedEvidence
  RAG->>ExtractiveAnswer: build extractive answer
  ExtractiveAnswer->>ClaimSupport: validate figure-bearing facts
  ClaimSupport->>CitedEvidence: inspect cited source text
  CitedEvidence-->>ClaimSupport: supported figure evidence
  ClaimSupport-->>ExtractiveAnswer: eligible lead fact
  ExtractiveAnswer-->>RAG: figure-aware answer or fallback candidate

Loading

Possibly related PRs

• BigSimmo/Database#870: Appends related review-record entries to the same branch review ledger.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.22% 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
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 clearly summarizes the main change: figure-aware extractive selection for dose and monitoring answers.
Description check	✅ Passed	The description covers the required sections and includes summary, verification, risk, rollout, and clinical governance details.

✨ 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/clinical-kb-pwa-review-asi3wb

---

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/lib/rag/rag-extractive-answer.ts (1)

1094-1109: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Hand-mirrored atom key risks silent drift.

promotionAtomKey duplicates the field list/order of a private atomKey in rag-claim-support.ts purely by comment convention ("Mirrors the private atom identity..."). If ClinicalValueAtom gains/reorders a field and only one of the two key builders is updated, the promotion guard and claim-support corpus check would silently disagree, defeating the "keep the two in lockstep" intent documented at Lines 215-221 of rag-claim-support.ts.

Consider exporting the real atomKey (or a shared key-builder) from rag-claim-support.ts and importing it here instead of maintaining a parallel hard-coded field list.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/rag/rag-extractive-answer.ts` around lines 1094 - 1109, The
promotionAtomKey helper duplicates the private atom identity logic and can drift
from claim assessment. Export the existing atomKey or move it to a shared
key-builder in rag-claim-support.ts, then import and reuse that symbol in the
promotion guard here, removing the local hard-coded field list while preserving
identical key behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/rag/rag-extractive-answer.ts`:
- Around line 374-378: Update monitoringIntervalFigurePattern so the
unit-bearing “every N” alternative is evaluated before the bare “every N”
alternative, ensuring matches include the full interval such as “every 6 weeks.”
Apply the same ordering fix to the corresponding pattern near
monitoringUnitRangeFigurePattern, and add coverage for mismatched units sharing
the same number.

In `@tests/extractive-answer-formatting.test.ts`:
- Around line 461-473: The test case around “refuses a bare-number interval that
lives only in adjacent context” does not match its setup or assertion. Either
remove this duplicate, or update it to place the interval exclusively in the
chunk’s adjacent_context and assert the interval is not promoted; if retaining a
distinct content-vs-adjacent-context case, add assertions that directly verify
the interval’s presence or absence.

---

Nitpick comments:
In `@src/lib/rag/rag-extractive-answer.ts`:
- Around line 1094-1109: The promotionAtomKey helper duplicates the private atom
identity logic and can drift from claim assessment. Export the existing atomKey
or move it to a shared key-builder in rag-claim-support.ts, then import and
reuse that symbol in the promotion guard here, removing the local hard-coded
field list while preserving identical key behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9f5445cf-8d84-422c-9d93-5418461ab15e

📥 Commits

Reviewing files that changed from the base of the PR and between 7eb2176 and fc26437.

📒 Files selected for processing (6)

• docs/branch-review-ledger.md
• src/lib/rag/rag-claim-support.ts
• src/lib/rag/rag-extractive-answer.ts
• src/lib/rag/rag.ts
• tests/extractive-answer-formatting.test.ts
• tests/rag-answer-fallback.test.ts