fix(rag): restore the strict source_metadata presence pin on retrieval rows

[BigSimmo]

Summary

• Restores sourceMetadataSchema in src/lib/rag/rag-row-contracts.ts from .nullish() back to .nullable(). PR feat(ledger): record 15 delivered resolutions, harden operator runbooks, and relax source metadata schema #2107 loosened it inside a mixed-scope ledger/runbook PR; its own RAG-impact text conceded the effect: a retrieval row with the source_metadata key absent (RPC column drift) is now silently accepted instead of raising RetrievalRowShapeError. That reverses the tranche-1 decision recorded with the owner (PR harden(rag): validate retrieval RPC rows against a Zod shape contract #1946, "throw on mismatch") on the one field pinned stricter than the rest for exactly that reason, and it landed with no fixture proving the case.
• Present-and-null remains accepted (unchanged); absent is again rejected. Adds the discriminating test feat(ledger): record 15 delivered resolutions, harden operator runbooks, and relax source metadata schema #2107 lacked (rejects a row whose source_metadata key is absent). Comment on the schema explains the pin and points at Retrieval correctness: repair #325 golden regression, corpus-grounded finding #11 fix, RC9 confidence hardening #343 for the constraint-backing follow-up.
• Nothing else from feat(ledger): record 15 delivered resolutions, harden operator runbooks, and relax source metadata schema #2107 (15 ledger inbox requests, runbook/AGENTS.md edits) is touched.

RAG impact: no retrieval behaviour change — restores the exact row-contract the last green canary (run 32111839806 on 84aa667ad) measured; ranking, scoring and citation output unchanged; only the validation boundary is re-tightened to fail loudly on drift.

Verification

• npx vitest run tests/rag-retrieval-row-contract.test.ts — Tests 26 passed (26) (25 existing + the new absent-key rejection).
• npm run eval:rag:offline — Tests 623 passed (623); Offline RAG fixture and production-contract checks passed.
• npm run check:rag:fixtures — Offline RAG fixture and manifest validation passed (36 golden cases, 26 suites).
• npx tsc --noEmit clean; Prettier applied.
• Live: all 2851 live documents carry object metadata (measured 2026-08-14/17), so no live row is rejected by this pin today — the pin's value is catching future RPC drift.
• No canary needed: this returns the contract to the state measured by run 32111839806; feat(ledger): record 15 delivered resolutions, harden operator runbooks, and relax source metadata schema #2107 ran none for the loosening either.

Risk and rollout

• Risk: low. If a future RPC omits source_metadata, retrieval fails loudly (the intended behaviour) rather than degrading citations silently. Rollback: revert this commit. Provider or production effects: none.

Clinical Governance Preflight

Complete this section when the change touches ingestion, answer generation, search/ranking, source rendering, document access, privacy, production env, or clinical output.

• 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

• Follow-up (already ledgered as Retrieval correctness: repair #325 golden regression, corpus-grounded finding #11 fix, RC9 confidence hardening #343): make the pin structural with check (jsonb_typeof(metadata) = 'object') on documents, or decide to loosen it deliberately with a fixture and a canary — not silently.
• Ledger record for head c5effece6 under docs/branch-review-records/.

---

Opened by the RAG programme coordinator chat (Claude Code).

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

[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:37 minutes

Limit details: You’ve used all 1 included review currently available under your plan. You completed 101 included PR reviews in the past 7 days; at that activity level, included reviews refill at 1 review per hour.

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: 8c98986e-b911-4266-8bdd-aeb4d87b2d50

📥 Commits

Reviewing files that changed from the base of the PR and between 86cc82f and 332e2e8.

📒 Files selected for processing (3)

• docs/branch-review-records/0a18b8e9ba7fa494f75b85ffd05fd9b65fead2f59404ca47158efc100ed27dc6.record.md
• src/lib/rag/rag-row-contracts.ts
• tests/rag-retrieval-row-contract.test.ts

---

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

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