docs(drift): forward-codify runbook for live-ahead retrieval RPCs

[BigSimmo]

Summary

Stages the non-live-gated half of drift backlog item 0 — forward-codifying the 7 retrieval RPCs whose live bodies are ahead of the repo (docs/database-drift-detection.md#reconciliation-backlog) — without touching the live project or hand-authoring the bodies.

Those bodies have diverged in both directions (e.g. match_document_chunks_hybrid in schema.sql carries the fail-closed retrieval_owner_matches predicate while live is ahead on the left-joined quality_score) and are actively churning under concurrent editing, so a hand-written body is exactly what got migration 20260705210000 neutralized. Only a verbatim pg_get_functiondef capture from a quiescent live DB is correct.

What's in this PR (all offline / inert)

• docs/forward-codify-retrieval-rpcs-workorder.md — operator runbook: read-only capture → fill-in-the-blanks migration skeleton → schema.sql reconcile → byte-faithful drift:manifest (Docker) + check:drift validation → allowlist cleanup → rollback.
• scripts/sql/capture-live-retrieval-rpcs.sql — READ-ONLY pg_get_functiondef capture for the target set (search_path=''), reusing the exact expressions schema_drift_snapshot() already runs in production.
• tests/forward-codify-retrieval-targets.test.ts — offline guard: the capture query's targets must equal the allowlist entries tagged LIVE IS AHEAD, so the artifact can't rot as siblings get reconciled.
• docs/database-drift-detection.md — link the runbook from backlog item 0.

Scope / risk

No runtime, schema.sql, or migration changes. The capture query is not wired into the app; the test is offline. Clinical governance preflight: N/A — this PR does not change ingestion, answer generation, search/ranking behavior, source rendering, document access, privacy, or production config. The live capture + apply remain an operator step gated on a quiescent DB + explicit approval.

Verification

• tests/forward-codify-retrieval-targets.test.ts + tests/drift-detection.test.ts green (13/13).
• Prettier clean; eslint --max-warnings 0 clean on the new test.

🤖 Generated with 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]

📝 Walkthrough

Walkthrough

Adds a staged runbook for forward-codifying seven live-ahead retrieval RPCs, a deterministic SQL capture script, and Vitest coverage ensuring the capture targets remain synchronized with the drift allowlist.

Changes

Retrieval RPC forward-codification

Layer / File(s)	Summary
Forward-codification runbook docs/forward-codify-retrieval-rpcs-workorder.md, docs/database-drift-detection.md	Documents the seven-function target set, capture and migration workflow, validation gates, operational prerequisites, and safety guidance.
Live RPC definition capture scripts/sql/capture-live-retrieval-rpcs.sql	Adds a read-only query that retrieves deterministic, verbatim definitions for the seven target RPC signatures.
Target consistency guard tests/forward-codify-retrieval-targets.test.ts	Checks that allowlisted live-ahead retrieval signatures match the capture query exactly and contain no duplicates.

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

Possibly related PRs

• BigSimmo/Database#433: Changes retrieval RPCs referenced by the new forward-codification workflow and guard test.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Verification Claims	❌ Error	The PR description claims tests were “green” and Prettier/ESLint were “clean” without exact commands/results, which this check forbids.	Rewrite verification notes as exact run lines, e.g. Ran npm run test -- ...: passed, Ran npm run prettier --check ...: passed, Ran npm run eslint --max-warnings 0 ...: passed.

✅ Passed checks (10 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: a drift-detection runbook for live-ahead retrieval RPCs.
Description check	✅ Passed	The description covers the summary, scope, and verification, but omits the repository's Notes section and checkbox template formatting.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Generated And Sensitive Files	✅ Passed	PASS: the PR only adds docs, a read-only SQL capture script, and an offline test; no secrets, local config, logs, caches, or build artifacts are present.
Risky Git Or Deployment Actions	✅ Passed	No force-push/reset/cleanup/branch-deletion guidance; live apply is explicitly gated by operator approval and a quiescent DB.
Supabase Project And Schema Safety	✅ Passed	Changed files are read-only docs/test; the only project ref matches the repo’s Clinical KB Database ref, and the runbook includes migration, rollback, and verification notes.
Runtime And Package Manager Integrity	✅ Passed	HEAD changes only docs, one SQL script, and one test; package.json/.npmrc/lockfile/runtime metadata are untouched, so Node 24/npm 11 integrity stays intact.
Api Route Failure Handling	✅ Passed	No API route, server action, RAG, search, ingestion, or provider integration code changed; the PR only adds docs, a read-only SQL capture, and an offline sync test.

✨ Finishing Touches

📝 Generate docstrings

• ✅ Generated successfully - (🔄 Check to regenerate)
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/forward-codify-retrieval-rpcs-05a3dc

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/forward-codify-retrieval-rpcs-05a3dc

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:414a4cc837

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 4

🤖 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 `@docs/forward-codify-retrieval-rpcs-workorder.md`:
- Line 164: Add language identifiers to the fenced code blocks in the
documentation: use sql for the block at line 164 and shell for the blocks at
lines 197, 207, 217, and 223, preserving their existing contents.
- Around line 249-257: Update the “Rollback / safety” guidance to require
preserving pre-apply function definitions as a known-good capture and generating
an explicit rollback migration from them. Do not recommend re-capturing live
after an incorrect apply as the rollback mechanism; retain the existing
migration-only and drift-check guidance.
- Around line 86-98: Update the diagnostic query’s unnest expression to assign
an explicit name to its output column, then reference that column in both the
SELECT projection and the to_regprocedure predicate. Keep the existing
function-signature array and missing-signature behavior unchanged.
In `@scripts/sql/capture-live-retrieval-rpcs.sql`:
- Around line 39-51: The capture query should tolerate missing functions instead
of failing on the cast to regprocedure. In the values subquery used by the
query, resolve each signature with to_regprocedure, filter out null results, and
pass the resolved OID to pg_get_functiondef while preserving the existing
signature output and fewer-than-seven-rows 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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 60a2cfe5-4962-4868-9269-da581bda391b

📥 Commits

Reviewing files that changed from the base of the PR and between a4ed305 and 414a4cc.

📒 Files selected for processing (4)

• docs/database-drift-detection.md
• docs/forward-codify-retrieval-rpcs-workorder.md
• scripts/sql/capture-live-retrieval-rpcs.sql
• tests/forward-codify-retrieval-targets.test.ts

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:333498f76e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Ok

[coderabbitai]

Caution

Docstrings generation - FAILED

No docstrings were generated.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:e8ee696dd6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Capture every live-only RPC before codifying

Fresh evidence beyond the prior capture-target comment: this newly added section now directs operators to take run_visual_eval_case, run_all_visual_eval_cases, and repair_enrichment_quality_batch from the fingerprint table, but that table only contains get_visual_evidence_cards among the live-only RPCs. When Step 2 asks them to codify and then remove allowlist entries for all four live-only functions, following this path leaves three functions without current definitions or ACL evidence, so the migration cannot be byte-faithful and drift can remain red or be miscodified; either add those signatures to a live capture artifact/table or stop listing them in this work-order.

Useful? React with 👍 / 👎.