Invalidate RAG cache scope revision on table-fact and image edits (stacked on #3640)

Merged
BI
25d ago
+377-6

Summary

This PR extends rag_cache_scope_revision_v1 so that edits to document_table_facts and document_images change the cache scope revision and invalidate cached answers and searches. Before this, editing a fact threshold or action, or an image caption, relevance or searchability flag, could leave a stale cached answer in place.

Stacked on #3640. It must merge only after #3640, inside the owner-chosen production DB window. The base is #3640's branch because this migration replaces the function that #3640's 20261018082910_audit_durable_recovery_pairing_and_cache_fences.sql defines. Once #3640 merges, GitHub retargets this PR to main.

The owner approved this migration at 17:55 AWST on 18 Oct 2026, relayed by Grok Bot. Draft migration: supabase/migrations/20261018095804_rag_cache_scope_evidence_revision.sql, timestamped after main's newest and after #3640's.

Design and cost (gitar's concern)

  • The new table public.document_evidence_revisions holds one bigint counter per document. Statement-level triggers with transition tables, on insert, update and delete for both tables, bump it inside the writing transaction.
  • An UPDATE bumps the counter only when the row actually changes; created_at and search_tsv are excluded. A no-op rewrite does not invalidate the cache.
  • rag_cache_scope_revision_v1 keeps the same signature, digest shape and grants. Each document's row hash now also carries coalesce(r.revision, 0) through a keyed left join. The revision stays one pass over documents plus a PK join, with no per-request scan or hash of the fact or image tables.
  • RAG impact: deploying this changes every row hash once, so all cached answers and searches are invalidated once. After that, only documents whose evidence changes are invalidated.

Tests

  • tests/sql/rag-cache-scope-evidence-revision.sql runs in CI Migration replay on the replayed chain. It shows the revision changes on fact insert, threshold edit, fact delete, image insert, caption edit and relevance/searchable edit. It also shows that a no-op update does not change it, that another document's scoped revision is unaffected, and that deleting the document still cascades and removes the counter.
  • tests/rag-cache-governance-revocation.test.ts shows that an evidence-revision bump changes cacheIndexingVersion and rejects local and shared cached answers and searches.

Housekeeping

  • The migration is sealed with the append-only npm run migrations:seal. schema.sql has the projection appended. The drift manifest's schema_sha256 is synced; Docker isn't available on the box, so the full manifest snapshot will come from CI's regenerated drift-manifest-<run_id> artifact.
  • Auto-merge is deliberately off. AGENTS.md requires an owner-approved window for merging migration PRs, and this PR is stacked on #3640.

Not sealed or decided here (owner / clinical)

  • The cache revision now decides whether clinical evidence (table-fact thresholds and actions, image captions and relevance) can be served from cache. The owner should review this as a hazard control. No hazard control is sealed and no clinical sign-off is recorded.
  • The one-time global cache invalidation on deploy needs to fall in the production window.
  • #3640's TGA SaMD item and its other sign-offs are untouched.

Possible later follow-up

  • Duplicate-job close-out on retry.

Summary by cubic

Stops cached RAG answers and searches from going stale when a document's table facts or images are edited. Previously the cache scope revision only changed when the document row itself changed, so a fact threshold, image caption, relevance, or searchability edit could leave an outdated cached answer in place. Now those edits bump a per-document evidence counter that feeds into the cache scope revision, invalidating affected cached entries.

  • Adds document_evidence_revisions (one bigint counter per document) and statement-level triggers on document_table_facts and document_images that bump it in the writing transaction; created_at and search_tsv changes and no-op updates don't bump it.
  • rag_cache_scope_revision_v1 keeps its signature, digest shape, and grants; each document's row hash now includes the evidence counter via a keyed join (no per-request scan of the fact or image tables).
  • After deploy, every cached answer and search is invalidated once; afterwards only documents whose evidence changed are invalidated.

Migration

  • Merges only after #3640 inside an owner-approved production DB window; the migration must be sealed and no clinical or hazard sign-off is recorded in it.