fix(db): guard hosted migration role usage

[BigSimmo]

Summary

• Add a scoped hosted migration-role guard to CI and the local cheap gate.
• Checksum-pin the one immutable applied migration that legitimately retains the legacy role reference.
• Discover the bare Docker image's storage schema owner at runtime for drift replay and disaster recovery.
• Document the hosted/local boundary without changing schema or the drift snapshot.

RAG impact: no retrieval behaviour change — CI/database replay guardrails only; no protected RAG surface changed.

Verification

• Exact origin/main red proof: the new guard rejected the current generator, scaffold, and runbook on six hard-coded role references.
• npm run check:migration-role
• npm run check:gate-manifest — 21/21 local cheap gates represented in CI.
• node scripts/run-vitest.mjs run tests/hosted-migration-role-guard.test.ts tests/drift-detection.test.ts --reporter=verbose — 15/15 passed.
• npm run drift:manifest -- --container clinical-kb-migration-role-reconcile --port 56642 — disposable PostgreSQL 17.6 replay passed in 17s; container removed; regenerated snapshot structurally identical.
• npm run verify:cheap — all 21 gates passed; 359 files, 3,182 tests passed, 1 skipped.
• npm run format:changed && npm run build && npm run check:rag:fixtures — formatting, production build, client-secret scan, 36 fixtures and 21 suites passed.

verify:pr-local -- --dry-run selected runtime, format, lint, typecheck, unit, build and offline RAG fixtures. Its unit/static work was already covered by verify:cheap; the remaining format/build/fixture commands were run individually to avoid repeating the full unit suite.

Verification not run: browser matrix because no UI/browser behavior changed. No live Supabase project check, migration apply, OpenAI, Railway, or live RAG evaluation was run because this changes local/CI guardrails only and does not alter hosted schema or retrieval behavior.

Risk and rollout

• Risk: low; the guard is scoped to hosted SQL/workflow/replay surfaces, with regression tests for the checksum exception, false-positive boundaries, and runtime owner discovery.
• Rollback: revert this commit; no live database state or schema was changed.
• Provider or production effects: None. Hosted CI ran read-only/build/replay validation only.

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 when clinical decision-support behavior changed

Notes

• The archived workflow hunk and archived drift manifest were not replayed. CI wiring was added against the current gate-manifest structure, and no drift-manifest change is retained.

[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 hosted migration-role guard to repository validation and CI, pins immutable historical migration content, and updates bare-image storage scaffolding to discover the local schema owner dynamically. Documentation records the hosted and local role-handling rules.

Changes

Migration role safety

Layer / File(s)	Summary
Hosted migration-role guard scripts/check-hosted-migration-role.mjs, package.json, .github/workflows/ci.yml, tests/hosted-migration-role-guard.test.ts	Adds reserved-role scanning, historical migration hash validation, a package command, CI enforcement, and Vitest coverage for guarded paths and role detection.
Runtime storage-schema ownership scripts/generate-drift-manifest.ts, scripts/sql/drift-replay-scaffold.sql, docs/disaster-recovery-runbook.md	Discovers the bare-image storage schema owner at runtime and uses it for local scaffold application.
Supabase safety guidance AGENTS.md, docs/process-hardening.md	Documents hosted postgres-role requirements, local owner discovery, and required guard execution.

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

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant MigrationRoleGuard
  participant Repository
  CI->>MigrationRoleGuard: Run check:migration-role
  MigrationRoleGuard->>Repository: Enumerate files and read contents
  Repository-->>MigrationRoleGuard: Paths and file contents
  MigrationRoleGuard-->>CI: Pass or failure exit status

Loading

Possibly related PRs

• BigSimmo/Database#914: Updates hosted default-ACL/default-privilege SQL and related tooling from supabase_admin to postgres, matching this guard’s role constraint.

Suggested labels: codex

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly summarizes the main change: guarding hosted migration-role usage.
Description check	✅ Passed	The description covers the required summary, verification, risk, rollback, governance, and notes sections.

✨ 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/reconcile-migration-role-guardrails

---

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