db: add fail-safe document-change ingestion trigger

[BigSimmo]

Summary

• Add a fail-safe documents metadata trigger that enqueues the existing document-change ingestion webhook only when reindex_requested transitions to JSON boolean true.
• Read the webhook secret from Vault and require an operator-supplied base URL; there is no production default.
• Regenerate the schema drift manifest, add schema/ACL/trigger assertions, and document activation, at-most-once delivery, recovery, and data-preserving rollback.

RAG impact: no retrieval behaviour change — this database trigger only enqueues the existing ingestion path.

Verification

• npm run verify:pr-local — exit 0; 365 files, 3241 passed, 1 skipped; build correctly skipped by path selection.
• npm run verify:ui — not run; no UI, routing, styling, or browser behavior changed.
• npm run verify:release — not run; this is a focused database handoff, not a release-confidence run.
• npm run drift:manifest -- --container clinical-kb-drift-manifest-supabase-trigger-20260724-2340 --port 56673 — disposable PostgreSQL 17 replay passed and the scratch container was removed.
• npm run test -- tests/supabase-schema.test.ts tests/drift-detection.test.ts tests/webhooks-supabase-document-change-route.test.ts — 89/89 passed.
• npm run check:migration-role — passed.
• npm run check:function-grants — passed; all 30 security-definer functions conform.
• npm run check:owner-scope — passed; 40 API files and 25 owner-scoped tables checked.
• npm run check:production-readiness:ci — READY; the isolated worktree intentionally has no local provider secrets, so configuration warnings were expected.
• npm run eval:rag:offline — 21 suites / 307 tests passed.
• npm run verify:cheap — exit 0; 365 files, 3241 passed, 1 skipped.

Risk and rollout

• Risk: pg_net delivery is intentionally at-most-once. A dropped request is recovered by clearing and re-setting the reindex flag. The trigger is inert when the Vault secret or base URL is missing, and trigger failures never abort the document update.
• Rollback: drop documents_ingestion_webhook, then drop public.notify_document_change_ingestion_webhook(); no document rows are modified or deleted.
• Provider or production effects: None from this PR. Live Supabase migration and operator configuration are separate, approval-gated rollout steps.

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; no clinical decision-support behavior changes

Notes

• Hosted migration replay remains the merge gate.
• Live drift comparison is intentionally deferred until the migration is applied; running it before rollout would report the expected repository-ahead state.

---

Note

Medium Risk
Touches production database ingestion wiring and outbound HTTP from triggers; mitigated by fail-open writes, no prod URL default, and narrow payload, but live migration plus operator secret/GUC setup is required before it becomes active.

Overview
Adds a Supabase documents metadata trigger that POSTs to the existing /api/webhooks/supabase/document-change receiver when metadata.reindex_requested transitions to JSON boolean true (not string "true"). Delivery uses Vault (ingestion_webhook_secret) and a per-environment app.ingestion_webhook_base_url GUC—no production URL fallback—and sends only allowlisted id / owner_id / status / reindex_requested fields.

The trigger is AFTER UPDATE OF metadata only, runs as SECURITY DEFINER with execute revoked from public/anon/authenticated, and fails open (missing config or pg_net errors never block the row update). Docs cover at-most-once delivery recovery (clear/re-flip the flag) and data-preserving rollback; drift manifest and schema contract tests lock the migration in.

^{Reviewed by Cursor Bugbot for commit 67c96b8. Configure here.}

Summary by CodeRabbit

• New Features

  • Added automatic document-change webhook notifications when reindexing is requested.
  • Notifications include only essential document details and require configured delivery settings.
  • Failed webhook delivery does not interrupt document updates.

• Documentation

  • Updated webhook setup, migration, rollback, and implementation status documentation.
  • Refreshed database drift metadata and review records.

• Bug Fixes

  • Normalized webhook URLs to prevent trailing-slash issues.

[supabase]

Updates to Preview Branch (codex/supabase-document-change-trigger) ↗︎

Deployments	Status	Updated
Database	✅	Thu, 23 Jul 2026 23:53:51 UTC
Services	✅	Thu, 23 Jul 2026 23:53:51 UTC
APIs	✅	Thu, 23 Jul 2026 23:53:51 UTC

Tasks are run on every commit but only new migration files are pushed.
Close and reopen this PR if you want to apply changes from existing seed or migration files.

Tasks	Status	Updated
Configurations	✅	Thu, 23 Jul 2026 23:54:01 UTC
Migrations	✅	Thu, 23 Jul 2026 23:55:24 UTC
Seeding	✅	Thu, 23 Jul 2026 23:55:28 UTC
Edge Functions	✅	Thu, 23 Jul 2026 23:55:29 UTC

---

View logs for this Workflow Run ↗︎.
Learn more about Supabase for Git ↗︎.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a fail-safe Supabase trigger that posts an allowlisted webhook when documents.metadata.reindex_requested changes to true. The schema, drift manifest, tests, webhook documentation, rollback instructions, and review-status records are updated accordingly.

Changes

Document change webhook

Layer / File(s)	Summary
Webhook trigger contract supabase/migrations/..., supabase/schema.sql	Adds the security-definer trigger function, guarded configuration lookup, restricted payload, failure warnings, execute revocations, and AFTER UPDATE OF metadata trigger.
Schema synchronization and validation supabase/drift-manifest.json, tests/supabase-schema.test.ts	Registers the function and trigger in the manifest and validates transition logic, security settings, endpoint construction, error handling, trigger scope, and privileges.
Operational documentation and review records docs/webhooks.md, docs/outstanding-issues.md, docs/branch-review-ledger.md	Normalizes the webhook URL, documents metadata-only trigger creation and additive rollback, and records replay verification and remaining activation steps.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• BigSimmo/Database#696: Adds grants guards relevant to the new function’s execute revocations.
• BigSimmo/Database#1065: Documents wiring and activation of the same Supabase document-change webhook path.

Suggested reviewers: claude

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main database trigger change.
Description check	✅ Passed	The description follows the template well and includes summary, verification, risk, rollout, and governance details.
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.

✨ 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 codex/supabase-document-change-trigger

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🤖 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/outstanding-issues.md`:
- Line 59: Replace the future-dated verification record in
docs/outstanding-issues.md:59 with the actual replay/test date, or mark
verification as pending if it has not occurred; update the review date in
docs/branch-review-ledger.md:23 to the actual date as well. Keep the documented
evidence and status consistent with dates on or before 2026-07-23.

🪄 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: 8fe5b47f-c2fd-404e-ad8e-66eb9923d8ea

📥 Commits

Reviewing files that changed from the base of the PR and between 9c7d9ed and 67c96b8.

📒 Files selected for processing (7)

• docs/branch-review-ledger.md
• docs/outstanding-issues.md
• docs/webhooks.md
• supabase/drift-manifest.json
• supabase/migrations/20260723150000_document_change_ingestion_webhook.sql
• supabase/schema.sql
• tests/supabase-schema.test.ts

[coderabbitai]

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Use actual dates for completed verification records. Both entries claim evidence from 2026-07-24, which is future-dated relative to 2026-07-23.

• docs/outstanding-issues.md#L59-L59: replace the future completion date with the actual replay/test date, or keep the verification pending.
• docs/branch-review-ledger.md#L23-L23: replace the future review date with the actual review date.

📍 Affects 2 files

• docs/outstanding-issues.md#L59-L59 (this comment)
• docs/branch-review-ledger.md#L23-L23

🤖 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 `@docs/outstanding-issues.md` at line 59, Replace the future-dated verification
record in docs/outstanding-issues.md:59 with the actual replay/test date, or
mark verification as pending if it has not occurred; update the review date in
docs/branch-review-ledger.md:23 to the actual date as well. Keep the documented
evidence and status consistent with dates on or before 2026-07-23.