diff --git a/.github/workflows/document-versions.yml b/.github/workflows/document-versions.yml new file mode 100644 index 0000000..bfbad0b --- /dev/null +++ b/.github/workflows/document-versions.yml @@ -0,0 +1,32 @@ +name: Context document version history transactions + +on: + pull_request: + branches: [main] + push: + branches: [main] + +permissions: + contents: read + +jobs: + document-versions: + runs-on: ubuntu-24.04 + timeout-minutes: 10 + strategy: + fail-fast: false + matrix: + postgres: [15, 16] + steps: + - uses: actions/checkout@v4 + - name: Install PostgreSQL + run: | + sudo apt-get update + sudo apt-get install -y postgresql-common + sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y + sudo apt-get update + sudo apt-get install -y postgresql-${{ matrix.postgres }} + - name: Test document version history + run: | + export PATH="/usr/lib/postgresql/${{ matrix.postgres }}/bin:$PATH" + python3 -m unittest discover -s tests -p 'test_context_document_versions.py' diff --git a/supabase/migrations/20261010212100_context_document_versions.sql b/supabase/migrations/20261010212100_context_document_versions.sql new file mode 100644 index 0000000..98b9a0d --- /dev/null +++ b/supabase/migrations/20261010212100_context_document_versions.sql @@ -0,0 +1,167 @@ +-- Immutable accepted-document-version history behind the existing current pointer. +-- context_documents keeps the current pointer and revision; every revision change +-- (a newly accepted result or a pointer cleared by source withdrawal) is recorded +-- once in context_document_versions by a trigger. accept_context_result, +-- withdraw_context_source, save_context_metadata, enrichment completion and the +-- entry functions therefore record history without any change to their bodies. +-- The trigger is the only writer: it runs as the migration owner, and the service +-- role can read history but cannot insert, update or delete it. Each version +-- carries the document's subject and topic, so it can cite only a result of the +-- same workspace, subject and topic. +-- Existing documents are backfilled from their current revision; a fresh document +-- (revision 0, no result) has no version yet and gets no row. +-- +-- Merge gate: production apply waits for the CE01 deployed-schema verification +-- (recoupable/app#2117); the added context_documents key and the revision guard +-- assume every deployed writer matches these migrations. +-- +-- Disable (first-line rollback; keeps every recorded version and the read): +-- alter table public.context_documents disable trigger context_documents_record_version; +-- Writers keep working unchanged; revisions made while disabled are not recorded. +-- Re-enable, then record the current revision of documents that moved meanwhile +-- (the skipped intermediate revisions stay visibly absent): +-- alter table public.context_documents enable trigger context_documents_record_version; +-- insert into public.context_document_versions(owner_id, subject_id, topic, document_id, revision, result_id, change, backfilled, recorded_at) +-- select d.owner_id, d.subject_id, d.topic, d.id, d.revision, d.current_result_id, +-- case when d.current_result_id is null then 'cleared' else 'accepted' end, true, d.updated_at +-- from public.context_documents d where d.current_result_id is not null or d.revision > 0 +-- on conflict (document_id, revision) do nothing; +-- Full removal drops recorded history that cannot be rebuilt (re-applying this +-- migration backfills only current revisions). Use it only for a deployment whose +-- history was never relied on; customer documents, results, sources and briefs +-- stay untouched either way: +-- drop trigger context_documents_record_version on public.context_documents; +-- drop trigger context_document_versions_immutable on public.context_document_versions; +-- drop function public.record_context_document_version(); +-- drop function public.reject_context_document_version_change(); +-- drop function public.read_context_document_history(uuid,uuid,bigint,integer); +-- drop table public.context_document_versions; +-- The context_documents_lineage_key constraint may remain; re-running this +-- migration skips it when present. +begin; +set local lock_timeout='5s'; +set local statement_timeout='60s'; + +do $$ begin + if not exists(select 1 from pg_catalog.pg_constraint + where conname='context_documents_lineage_key' and conrelid='public.context_documents'::regclass) then + alter table public.context_documents add constraint context_documents_lineage_key unique(id, owner_id, subject_id, topic); + end if; +end $$; + +create table public.context_document_versions ( + id uuid primary key default gen_random_uuid(), + owner_id uuid not null, + subject_id uuid not null, + topic text not null, + document_id uuid not null, + revision bigint not null check (revision >= 0), + result_id uuid, + change text not null check (change in ('accepted','cleared')), + backfilled boolean not null default false, + recorded_at timestamptz not null default now(), + unique(document_id, revision), + unique(id, owner_id), + foreign key(document_id, owner_id, subject_id, topic) + references public.context_documents(id, owner_id, subject_id, topic) on delete restrict, + foreign key(result_id, owner_id, subject_id, topic) + references public.context_results(id, owner_id, subject_id, topic) on delete restrict, + check ((change = 'cleared') = (result_id is null)) +); +create index context_document_versions_document_idx + on public.context_document_versions(owner_id, document_id, revision desc); +create index context_document_versions_result_idx + on public.context_document_versions(result_id, owner_id); +alter table public.context_document_versions enable row level security; +revoke all on public.context_document_versions from public, anon, authenticated, service_role; +grant select on public.context_document_versions to service_role; + +-- History rows are never rewritten, even by the table owner. +create function public.reject_context_document_version_change() +returns trigger language plpgsql set search_path='' as $$ +begin + raise exception 'Context document history is immutable'; +end $$; +create trigger context_document_versions_immutable + before update or delete on public.context_document_versions + for each row execute function public.reject_context_document_version_change(); + +-- One history row per document revision. A pointer that moves without a new +-- revision is a lineage bug and is rejected rather than silently overwritten. +create function public.record_context_document_version() +returns trigger language plpgsql security definer set search_path='' as $$ +begin + if tg_op = 'UPDATE' then + if new.revision = old.revision then + if new.current_result_id is distinct from old.current_result_id then + raise exception 'Context document pointer changed without a new revision'; + end if; + return null; + end if; + if new.revision < old.revision then + raise exception 'Context document revision cannot move backwards'; + end if; + elsif new.revision = 0 and new.current_result_id is null then + return null; + end if; + insert into public.context_document_versions(owner_id, subject_id, topic, document_id, revision, result_id, change) + values (new.owner_id, new.subject_id, new.topic, new.id, new.revision, new.current_result_id, + case when new.current_result_id is null then 'cleared' else 'accepted' end); + return null; +end $$; +create trigger context_documents_record_version + after insert or update of current_result_id, revision on public.context_documents + for each row execute function public.record_context_document_version(); +-- Trigger functions are never called directly; firing them needs no grant. +revoke all on function public.reject_context_document_version_change(), public.record_context_document_version() + from public, anon, authenticated, service_role; + +-- Existing data compatibility: the current revision of every existing document +-- becomes its first recorded version, dated by the document's last update. +insert into public.context_document_versions(owner_id, subject_id, topic, document_id, revision, result_id, change, backfilled, recorded_at) +select d.owner_id, d.subject_id, d.topic, d.id, d.revision, d.current_result_id, + case when d.current_result_id is null then 'cleared' else 'accepted' end, true, d.updated_at +from public.context_documents d +where d.current_result_id is not null or d.revision > 0; + +-- Scoped lineage read: newest revision first, bounded, with the cited result's +-- current status and source state so a superseded brief can be resolved. +-- Returns null when the document is not in the caller's authorized workspace. +create function public.read_context_document_history(p_owner uuid, p_document uuid, p_before bigint default null, p_limit integer default 50) +returns jsonb language plpgsql set search_path='' as $$ +declare doc public.context_documents; bound integer; items jsonb; more boolean; +begin + if p_owner is null or p_document is null then return null; end if; + select * into doc from public.context_documents where id=p_document and owner_id=p_owner; + if doc.id is null then return null; end if; + bound:=least(greatest(coalesce(p_limit,50),1),100); + select coalesce(jsonb_agg(jsonb_build_object( + 'revision',v.revision,'result_id',v.result_id,'change',v.change,'backfilled',v.backfilled,'recorded_at',v.recorded_at, + 'result_status',r.status,'evidence_kind',r.evidence_kind, + 'source_version_ids',coalesce((select jsonb_agg(rs.source_version_id order by rs.source_version_id) + from public.context_result_sources rs where rs.result_id=r.id and rs.owner_id=p_owner),'[]'::jsonb), + 'source_state',case when r.id is null then null + when exists(select 1 from public.context_result_sources rs + join public.context_source_versions sv on sv.id=rs.source_version_id and sv.owner_id=rs.owner_id + join public.context_sources s on s.id=sv.source_id and s.owner_id=sv.owner_id + where rs.result_id=r.id and rs.owner_id=p_owner and s.withdrawn_at is not null) then 'withdrawn' + when exists(select 1 from public.context_result_sources rs + join public.context_source_versions sv on sv.id=rs.source_version_id and sv.owner_id=rs.owner_id + where rs.result_id=r.id and rs.owner_id=p_owner and sv.removed_at is not null) then 'removed' + else 'live' end) order by v.revision desc),'[]'::jsonb) + into items + from (select * from public.context_document_versions + where owner_id=p_owner and document_id=doc.id and (p_before is null or revisionbound; + if more then items:=items-bound; end if; + return jsonb_build_object( + 'document',jsonb_build_object('id',doc.id,'subject_id',doc.subject_id,'topic',doc.topic, + 'current_revision',doc.revision,'current_result_id',doc.current_result_id,'updated_at',doc.updated_at), + 'versions',items,'has_more',more, + 'next_before',case when more then (items->(bound-1)->>'revision')::bigint end); +end $$; +revoke all on function public.read_context_document_history(uuid,uuid,bigint,integer) from public, anon, authenticated; +grant execute on function public.read_context_document_history(uuid,uuid,bigint,integer) to service_role; +commit; diff --git a/supabase/tests/context_document_versions.sql b/supabase/tests/context_document_versions.sql new file mode 100644 index 0000000..18d1420 --- /dev/null +++ b/supabase/tests/context_document_versions.sql @@ -0,0 +1,162 @@ +-- Disposable database only. The fixture rolls back; no external providers. +-- Requires the Context foundation, Spotify pipeline, brief snapshot and +-- document version migrations. +begin; +do $$ +declare owner uuid:=gen_random_uuid(); outsider uuid:=gen_random_uuid(); resource uuid; subject uuid; req uuid; + url text:='https://open.spotify.com/album/'||repeat('D',22); doc uuid; first_result uuid; second_result uuid; src uuid; + history jsonb; docs jsonb; manifest jsonb; brief jsonb; saved jsonb; readback jsonb; page jsonb; +begin + insert into public.accounts(id,name) values(owner,'Document history owner'),(outsider,'Other workspace'); + insert into public.context_resources(provider,resource_kind,provider_id,canonical_url) + values('spotify','release',repeat('D',22),url) returning id into resource; + insert into public.context_subjects(kind,resource_id) values('release',resource) returning id into subject; + insert into public.context_requests(owner_id,created_by,resource_id,idempotency_key,input_fingerprint,input,status,output) + values(owner,owner,resource,'history-fixture',repeat('a',64),'{}','completed',jsonb_build_object('subjectIds',jsonb_build_array(subject))) + returning id into req; + + -- First accepted observation becomes revision 1 through the unchanged writer. + doc:=public.save_context_metadata(owner,req,subject,'release_metadata',url,'{"title":"Fixture release","take":1}'); + select current_result_id into first_result from public.context_documents where id=doc; + if first_result is null or (select revision from public.context_documents where id=doc)<>1 then raise exception 'First acceptance did not set the current pointer'; end if; + history:=public.read_context_document_history(owner,doc); + if jsonb_array_length(history->'versions')<>1 or history->'versions'->0->>'revision'<>'1' + or history->'versions'->0->>'result_id'<>first_result::text or history->'versions'->0->>'change'<>'accepted' + or history->'versions'->0->>'backfilled'<>'false' or history->'versions'->0->>'source_state'<>'live' + or history->'versions'->0->>'result_status'<>'accepted' or jsonb_array_length(history->'versions'->0->'source_version_ids')<>1 + or history->>'has_more'<>'false' or history->'next_before'<>'null'::jsonb + then raise exception 'First version was not recorded: %',history; end if; + + -- Freeze a brief that cites revision 1 before the document changes. + docs:=public.read_context_documents(owner,req); + select coalesce(jsonb_agg(jsonb_build_object('documentId',value->'id','resultId',value->'resultId','subjectId',value->'subjectId', + 'topic',value->'topic','version',value->'version','sourceVersionIds',value->'sourceVersionIds') order by ordinal),'[]'::jsonb) + into manifest from jsonb_array_elements(docs) with ordinality d(value,ordinal); + brief:=jsonb_build_object('request_id',req,'request_ids',jsonb_build_array(req),'purpose','playlist_pitch', + 'text','Document history fixture','documents',docs,'input_manifest',jsonb_build_object('compilerVersion','context-brief-v1', + 'method','saved_evidence_selection','requestIds',jsonb_build_array(req),'documents',manifest)); + saved:=public.save_context_brief(owner,'history-brief',brief); + if saved->>'superseded'<>'false' or saved->>'state'<>'saved' then raise exception 'Fresh brief misreported: %',saved; end if; + + -- Identical content is reused without a new revision; changed content becomes revision 2. + if public.save_context_metadata(owner,req,subject,'release_metadata',url,'{"title":"Fixture release","take":1}')<>doc + or (select revision from public.context_documents where id=doc)<>1 then raise exception 'Identical content created a new revision'; end if; + perform public.save_context_metadata(owner,req,subject,'release_metadata',url,'{"title":"Fixture release (corrected)","take":2}'); + select current_result_id into second_result from public.context_documents where id=doc; + if second_result is null or second_result=first_result or (select revision from public.context_documents where id=doc)<>2 + then raise exception 'Second acceptance did not advance the pointer'; end if; + history:=public.read_context_document_history(owner,doc); + if jsonb_array_length(history->'versions')<>2 + or history->'versions'->0->>'revision'<>'2' or history->'versions'->0->>'result_id'<>second_result::text + or history->'versions'->1->>'revision'<>'1' or history->'versions'->1->>'result_id'<>first_result::text + or history->'document'->>'current_revision'<>'2' or history->'document'->>'current_result_id'<>second_result::text + or history->'document'->>'subject_id'<>subject::text or history->'document'->>'topic'<>'release_metadata' + then raise exception 'Two-version history mismatch: %',history; end if; + if public.read_context_documents(owner,req)->0->>'resultId'<>second_result::text then raise exception 'Current read changed'; end if; + + -- The superseded brief still cites revision 1, and history resolves that citation. + readback:=public.read_context_brief(owner,(saved->>'id')::uuid); + if readback->>'superseded'<>'true' or readback->>'state'<>'saved' or readback->'brief'<>brief then raise exception 'Superseded brief changed: %',readback; end if; + if (select result_id from public.context_document_versions where document_id=doc + and revision=(readback->'brief'->'input_manifest'->'documents'->0->>'version')::bigint) + <>(readback->'brief'->'input_manifest'->'documents'->0->>'resultId')::uuid + then raise exception 'Cited version does not resolve to the cited result'; end if; + + -- A late acceptance with a stale revision records nothing. + if public.accept_context_result(owner,doc,first_result,1) then raise exception 'Stale revision accepted'; end if; + if (select count(*) from public.context_document_versions where document_id=doc)<>2 then raise exception 'Rejected acceptance wrote history'; end if; + + -- Moving the pointer without a revision is a lineage bug, not a silent overwrite. + begin + update public.context_documents set current_result_id=first_result where id=doc; + raise exception 'TEST_FAILURE: pointer moved without a revision'; + exception when others then if SQLERRM like 'TEST_FAILURE:%' then raise; end if; end; + begin + update public.context_documents set revision=revision-1 where id=doc; + raise exception 'TEST_FAILURE: revision moved backwards'; + exception when others then if SQLERRM like 'TEST_FAILURE:%' then raise; end if; end; + + -- Withdrawal clears the pointer as revision 3; earlier versions report withdrawn sources. + select s.id into strict src from public.context_sources s where s.owner_id=owner and s.kind='provider_metadata' and s.withdrawn_at is null; + if not public.withdraw_context_source(owner,src) then raise exception 'Withdrawal failed'; end if; + history:=public.read_context_document_history(owner,doc); + if (select current_result_id from public.context_documents where id=doc) is not null + or jsonb_array_length(history->'versions')<>3 + or history->'versions'->0->>'revision'<>'3' or history->'versions'->0->>'change'<>'cleared' + or history->'versions'->0->'result_id'<>'null'::jsonb or history->'versions'->0->'source_state'<>'null'::jsonb + or history->'versions'->0->'source_version_ids'<>'[]'::jsonb + or history->'versions'->1->>'source_state'<>'withdrawn' or history->'versions'->1->>'result_status'<>'withdrawn' + or history->'versions'->2->>'source_state'<>'withdrawn' + or history->'document'->'current_result_id'<>'null'::jsonb + then raise exception 'Withdrawal history mismatch: %',history; end if; + if public.read_context_documents(owner,req)<>'[]'::jsonb then raise exception 'Withdrawn document still readable as current'; end if; + if public.read_context_brief(owner,(saved->>'id')::uuid)->>'state'<>'unavailable' then raise exception 'Withdrawn evidence leaked through the brief'; end if; + + -- Pagination walks newest first with an exclusive revision cursor; limits are clamped. + page:=public.read_context_document_history(owner,doc,null,2); + if jsonb_array_length(page->'versions')<>2 or page->>'has_more'<>'true' or page->>'next_before'<>'2' + or page->'versions'->0->>'revision'<>'3' or page->'versions'->1->>'revision'<>'2' + then raise exception 'First page mismatch: %',page; end if; + page:=public.read_context_document_history(owner,doc,(page->>'next_before')::bigint,2); + if jsonb_array_length(page->'versions')<>1 or page->>'has_more'<>'false' or page->'next_before'<>'null'::jsonb + or page->'versions'->0->>'revision'<>'1' + then raise exception 'Second page mismatch: %',page; end if; + if jsonb_array_length(public.read_context_document_history(owner,doc,null,0)->'versions')<>1 + or jsonb_array_length(public.read_context_document_history(owner,doc,null,1000)->'versions')<>3 + then raise exception 'Limit was not clamped'; end if; + + -- History is immutable and one revision is recorded once. + begin + update public.context_document_versions set result_id=null,change='cleared' where document_id=doc and revision=1; + raise exception 'TEST_FAILURE: history row updated'; + exception when others then if SQLERRM like 'TEST_FAILURE:%' then raise; end if; end; + begin + delete from public.context_document_versions where document_id=doc; + raise exception 'TEST_FAILURE: history row deleted'; + exception when others then if SQLERRM like 'TEST_FAILURE:%' then raise; end if; end; + begin + insert into public.context_document_versions(owner_id,subject_id,topic,document_id,revision,result_id,change) + values(owner,subject,'release_metadata',doc,2,second_result,'accepted'); + raise exception 'TEST_FAILURE: duplicate revision inserted'; + exception when unique_violation then null; end; + begin + insert into public.context_document_versions(owner_id,subject_id,topic,document_id,revision,result_id,change) + values(outsider,subject,'release_metadata',doc,9,second_result,'accepted'); + raise exception 'TEST_FAILURE: history cited another workspace'; + exception when foreign_key_violation then null; end; + if (select count(*) from public.context_document_versions where document_id=doc)<>3 then raise exception 'Rejected writes changed history'; end if; + + -- Another workspace or an unknown document reads nothing, not even existence. + if public.read_context_document_history(outsider,doc) is not null then raise exception 'Cross-workspace history read'; end if; + if public.read_context_document_history(owner,gen_random_uuid()) is not null then raise exception 'Unknown document returned history'; end if; + + -- The production service role records and reads history through the unchanged writers. + set local role service_role; + perform public.save_context_metadata(owner,req,subject,'release_metadata',url,'{"title":"Fixture release","take":3}'); + history:=public.read_context_document_history(owner,doc); + if jsonb_array_length(history->'versions')<>4 or history->'versions'->0->>'revision'<>'4' + or history->'versions'->0->>'change'<>'accepted' or history->'versions'->0->>'source_state'<>'live' + or history->'document'->>'current_result_id'<>history->'versions'->0->>'result_id' + then raise exception 'Service role lineage mismatch: %',history; end if; + if public.read_context_document_history(outsider,doc) is not null then raise exception 'Service role leaked another workspace'; end if; + begin + insert into public.context_document_versions(owner_id,subject_id,topic,document_id,revision,result_id,change) + values(owner,subject,'release_metadata',doc,5,null,'cleared'); + raise exception 'TEST_FAILURE: service role wrote history directly'; + exception when insufficient_privilege then null; end; + reset role; + + if pg_catalog.has_function_privilege('authenticated','public.read_context_document_history(uuid,uuid,bigint,integer)','EXECUTE') + or pg_catalog.has_function_privilege('anon','public.read_context_document_history(uuid,uuid,bigint,integer)','EXECUTE') + or pg_catalog.has_table_privilege('service_role','public.context_document_versions','INSERT') + or pg_catalog.has_table_privilege('service_role','public.context_document_versions','UPDATE') + or pg_catalog.has_table_privilege('service_role','public.context_document_versions','DELETE') + or pg_catalog.has_table_privilege('authenticated','public.context_document_versions','SELECT') + or pg_catalog.has_table_privilege('anon','public.context_document_versions','SELECT') + then raise exception 'Document history privileges are too broad'; end if; + if not (select prosecdef from pg_catalog.pg_proc where oid='public.record_context_document_version()'::regprocedure) + or (select prosecdef from pg_catalog.pg_proc where oid='public.read_context_document_history(uuid,uuid,bigint,integer)'::regprocedure) + then raise exception 'Only the recording trigger may write history as its owner'; end if; + raise notice 'PASS: accepted/cleared revisions recorded, current pointer kept, superseded brief resolvable, immutable history, scoped reads, service-role read-only path'; +end $$; +rollback; diff --git a/tests/README.md b/tests/README.md index 7822447..5984340 100644 --- a/tests/README.md +++ b/tests/README.md @@ -41,3 +41,9 @@ real transaction suite, preserved evidence, explicit enrollment and deployment l Run `python3 -m unittest discover -s tests -p 'test_player_org_fans.py'` on disposable local PostgreSQL. The suite applies the actual `20261010100000_player_organization_contacts.sql` migration to legacy synthetic fan data and exercises backfill, stable relationship/session IDs, latest non-null contact profiles, parallel sign-ins, separate provider identities despite identical emails, cross-workspace isolation, browser-role denial and existing playback/reporting behavior. CI runs both player suites on PostgreSQL 15 and 16. Rollout: apply the contact migration before deploying API readers of `contact_id` / `player_fan_contacts`. Existing `connect_player_fan` callers continue working through the new trigger. Artist relationships keep their original IDs; sessions and events are not reassigned. Workspace contacts never merge by email/name or across owners. The migration locks player_fans while backfilling and installing its composite identity FK; new connections can wait briefly during deployment. On API rollback, retain the additive contact schema and trigger so previously deployed capture still maintains contacts. Do not drop the new contacts or remove relationship/session history as a rollback shortcut. Live post-deployment verification is still required. + +## Context document version history + +Run `python3 -m unittest discover -s tests -p 'test_context_document_versions.py'` on disposable local PostgreSQL. The suite writes synthetic legacy Context documents before applying `20261010212100_context_document_versions.sql`, then checks the backfill (current revision recorded once, dated by the document's last update, fresh empty documents skipped), the unchanged `read_context_documents` reader, the `supabase/tests/context_document_versions.sql` lifecycle fixture (accepted and cleared revisions recorded by trigger through the unchanged writers, stale-revision acceptance recording nothing, a superseded brief resolving its cited result through history, immutable rows, duplicate-revision and cross-workspace rejection, clamped pagination, the production service role reading but not writing history, and browser-role denial), forgery resistance (the service role cannot insert history; a version cannot cite a result of another subject or topic; source withdrawal still records its cleared revision), the documented disable/re-enable path, and the documented full removal followed by re-application. CI runs it on PostgreSQL 15 and 16. + +Rollback: first disable the recording trigger. Writers keep working, every recorded version and the read function stay, and re-enabling records the current revision of documents that moved meanwhile. Full removal drops history that cannot be rebuilt (re-applying backfills only current revisions), so reserve it for a deployment whose history was never relied on. Customer documents, results, sources and briefs are untouched either way. Production apply waits for the CE01 deployed-schema verification (recoupable/app#2117). This is fixture verification, not a hosted migration or live lineage check. diff --git a/tests/test_context_document_versions.py b/tests/test_context_document_versions.py new file mode 100644 index 0000000..879dffd --- /dev/null +++ b/tests/test_context_document_versions.py @@ -0,0 +1,185 @@ +"""Document version history on disposable PostgreSQL: legacy backfill, lifecycle, forgery, disable, removal.""" +import test_release_cases as release_cases + +ROOT = release_cases.ROOT +MIGRATION = ROOT / 'supabase/migrations/20261010212100_context_document_versions.sql' +FIXTURE = ROOT / 'supabase/tests/context_document_versions.sql' + +# Synthetic identifiers only; the legacy rows are written before the history migration exists. +OWNER = '0d0c0b0a-0000-4000-8000-000000000001' +RESOURCE = '0d0c0b0a-0000-4000-8000-000000000002' +SUBJECT = '0d0c0b0a-0000-4000-8000-000000000003' +REQUEST = '0d0c0b0a-0000-4000-8000-000000000004' +SOURCE = '0d0c0b0a-0000-4000-8000-000000000005' +VERSION = '0d0c0b0a-0000-4000-8000-000000000006' +ATTEMPT = '0d0c0b0a-0000-4000-8000-000000000007' +RESULT = '0d0c0b0a-0000-4000-8000-000000000008' +ACCEPTED_DOC = '0d0c0b0a-0000-4000-8000-000000000009' +EMPTY_DOC = '0d0c0b0a-0000-4000-8000-00000000000a' +CLEARED_DOC = '0d0c0b0a-0000-4000-8000-00000000000b' +URL = 'https://open.spotify.com/album/' + 'L' * 22 + +LEGACY = f""" +insert into public.accounts(id,name) values('{OWNER}','Legacy history owner'); +insert into public.context_resources(id,provider,resource_kind,provider_id,canonical_url) + values('{RESOURCE}','spotify','release','{'L' * 22}','{URL}'); +insert into public.context_subjects(id,kind,resource_id) values('{SUBJECT}','release','{RESOURCE}'); +insert into public.context_requests(id,owner_id,created_by,resource_id,idempotency_key,input_fingerprint,input,status,output) + values('{REQUEST}','{OWNER}','{OWNER}','{RESOURCE}','legacy-history',repeat('a',64),'{{}}','completed', + jsonb_build_object('subjectIds',jsonb_build_array('{SUBJECT}'::uuid))); +insert into public.context_sources(id,owner_id,source_url,kind) values('{SOURCE}','{OWNER}','{URL}','provider_metadata'); +insert into public.context_source_versions(id,owner_id,source_id,fingerprint,content) + values('{VERSION}','{OWNER}','{SOURCE}',repeat('b',64),'{{}}'); +insert into public.context_attempts(id,owner_id,request_id,module,attempt,status,recipe_version,schema_version) + values('{ATTEMPT}','{OWNER}','{REQUEST}','release_metadata',1,'succeeded','1','1'); +insert into public.context_results(id,owner_id,attempt_id,subject_id,topic,reuse_key,status,evidence_kind,normalized_response,coverage) + values('{RESULT}','{OWNER}','{ATTEMPT}','{SUBJECT}','release_metadata',repeat('c',64),'accepted','observation', + '{{"title":"Legacy release"}}','{{"extent":"partial"}}'); +insert into public.context_result_sources values('{OWNER}','{RESULT}','{VERSION}'); +insert into public.context_documents(id,owner_id,subject_id,topic,revision,current_result_id,updated_at) values + ('{ACCEPTED_DOC}','{OWNER}','{SUBJECT}','release_metadata',2,'{RESULT}','2026-09-21T10:00:00Z'), + ('{EMPTY_DOC}','{OWNER}','{SUBJECT}','artist_research',0,null,'2026-09-21T10:00:00Z'), + ('{CLEARED_DOC}','{OWNER}','{SUBJECT}','lyrics',3,null,'2026-09-22T10:00:00Z'); +""" + +# The documented first-line rollback: stop recording, keep every recorded version. +DISABLE = "alter table public.context_documents disable trigger context_documents_record_version;" +ENABLE = """ +alter table public.context_documents enable trigger context_documents_record_version; +insert into public.context_document_versions(owner_id, subject_id, topic, document_id, revision, result_id, change, backfilled, recorded_at) +select d.owner_id, d.subject_id, d.topic, d.id, d.revision, d.current_result_id, + case when d.current_result_id is null then 'cleared' else 'accepted' end, true, d.updated_at +from public.context_documents d where d.current_result_id is not null or d.revision > 0 +on conflict (document_id, revision) do nothing; +""" + +# The documented full removal: history objects only; documents, results and sources stay. +REMOVE = """ +drop trigger context_documents_record_version on public.context_documents; +drop trigger context_document_versions_immutable on public.context_document_versions; +drop function public.record_context_document_version(); +drop function public.reject_context_document_version_change(); +drop function public.read_context_document_history(uuid,uuid,bigint,integer); +drop table public.context_document_versions; +""" + + +class ContextDocumentVersions(release_cases.ReleaseCases): + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.sql((ROOT / 'supabase/migrations/20260926170000_context_brief_snapshots.sql').read_text()) + cls.sql(LEGACY) + if MIGRATION.exists(): + cls.sql(MIGRATION.read_text()) + + def rows(self, document): + return self.sql( + "select revision||':'||change||':'||backfilled||':'||coalesce(result_id::text,'none')" + f" from public.context_document_versions where document_id='{document}' order by revision" + ).stdout.split() + + def assert_backfilled(self): + self.assertEqual(self.rows(ACCEPTED_DOC), [f'2:accepted:true:{RESULT}']) + self.assertEqual(self.rows(EMPTY_DOC), []) + self.assertEqual(self.rows(CLEARED_DOC), ['3:cleared:true:none']) + self.assertEqual(self.sql( + "select count(*) from public.context_document_versions v join public.context_documents d on d.id=v.document_id" + f" where d.owner_id='{OWNER}' and v.recorded_at<>d.updated_at").stdout.strip(), '0') + + def test_legacy_documents_backfill_without_rewriting_readers(self): + self.assert_backfilled() + current = self.sql( + f"select jsonb_array_length(d), d->0->>'id', d->0->>'version', d->0->>'resultId'" + f" from public.read_context_documents('{OWNER}','{REQUEST}') d").stdout.split('|') + self.assertEqual([x.strip() for x in current], ['1', ACCEPTED_DOC, '2', RESULT]) + history = self.sql( + f"select h->'versions'->0->>'backfilled', h->'versions'->0->>'result_status', h->'versions'->0->>'source_state'," + f" h->'document'->>'current_revision' from public.read_context_document_history('{OWNER}','{ACCEPTED_DOC}') h" + ).stdout.split('|') + self.assertEqual([x.strip() for x in history], ['true', 'accepted', 'live', '2']) + self.assertEqual(self.sql( + f"select public.read_context_document_history('{RESULT}','{ACCEPTED_DOC}') is null").stdout.strip(), 't') + + def test_lifecycle_immutability_and_access(self): + result = self.sql(FIXTURE.read_text()) + self.assertIn('PASS:', result.stderr) + + def test_disable_keeps_history_and_reenable_records_current_revision(self): + migration = MIGRATION.read_text() + self.assertIn(DISABLE, migration) + for line in ENABLE.strip().splitlines(): + self.assertIn(line, migration) + out = self.sql(f""" +begin; +{DISABLE} +select 'withdrawn:'||public.withdraw_context_source('{OWNER}','{SOURCE}'); +select 'disabled:'||string_agg(revision||'/'||change,',' order by revision) + from public.context_document_versions where document_id='{ACCEPTED_DOC}'; +select 'read:'||(h->'document'->>'current_revision')||'/'||jsonb_array_length(h->'versions') + from public.read_context_document_history('{OWNER}','{ACCEPTED_DOC}') h; +{ENABLE} +select 'enabled:'||string_agg(revision||'/'||change||'/'||backfilled,',' order by revision) + from public.context_document_versions where document_id='{ACCEPTED_DOC}'; +select 'cleared:'||count(*) from public.context_document_versions where document_id='{CLEARED_DOC}'; +select 'trigger:'||tgenabled::text from pg_catalog.pg_trigger where tgname='context_documents_record_version'; +rollback; +""").stdout.split() + marks = [line for line in out if ':' in line] + self.assertEqual(marks, ['withdrawn:true', 'disabled:2/accepted', 'read:3/1', + 'enabled:2/accepted/true,3/cleared/true', 'cleared:1', 'trigger:O']) + self.assert_backfilled() + + def test_history_cannot_be_forged_or_cross_topic_and_withdrawal_still_works(self): + result = self.sql(f""" +begin; +do $$ begin + set local role service_role; + begin + insert into public.context_document_versions(owner_id,subject_id,topic,document_id,revision,result_id,change) + values('{OWNER}','{SUBJECT}','release_metadata','{ACCEPTED_DOC}',3,null,'cleared'); + raise exception 'TEST_FAILURE: service role forged a future revision'; + exception when insufficient_privilege then null; end; + begin + insert into public.context_document_versions(owner_id,subject_id,topic,document_id,revision,result_id,change) + values('{OWNER}','{SUBJECT}','artist_research','{EMPTY_DOC}',1,'{RESULT}','accepted'); + raise exception 'TEST_FAILURE: service role wrote history'; + exception when insufficient_privilege then null; end; + reset role; + begin + insert into public.context_document_versions(owner_id,subject_id,topic,document_id,revision,result_id,change) + values('{OWNER}','{SUBJECT}','artist_research','{EMPTY_DOC}',1,'{RESULT}','accepted'); + raise exception 'TEST_FAILURE: history cited a result of another topic'; + exception when foreign_key_violation then null; end; + begin + insert into public.context_document_versions(owner_id,subject_id,topic,document_id,revision,result_id,change) + values('{OWNER}','{SUBJECT}','release_metadata','{EMPTY_DOC}',1,'{RESULT}','accepted'); + raise exception 'TEST_FAILURE: history relabelled a document topic'; + exception when foreign_key_violation then null; end; + set local role service_role; + if not public.withdraw_context_source('{OWNER}','{SOURCE}') then raise exception 'TEST_FAILURE: withdrawal failed'; end if; + reset role; + raise notice 'PASS: no forged history; withdrawal recorded'; +end $$; +select 'history:'||string_agg(revision||'/'||change||'/'||backfilled,',' order by revision) + from public.context_document_versions where document_id='{ACCEPTED_DOC}'; +select 'empty:'||count(*) from public.context_document_versions where document_id='{EMPTY_DOC}'; +rollback; +""") + self.assertIn('PASS:', result.stderr) + marks = [line for line in result.stdout.split() if line.startswith(('history:', 'empty:'))] + self.assertEqual(marks, ['history:2/accepted/true,3/cleared/false', 'empty:0']) + self.assert_backfilled() + + def test_remove_keeps_customer_data_and_reapply_backfills(self): + self.sql(REMOVE) + self.assertEqual(self.sql("select to_regclass('public.context_document_versions') is null").stdout.strip(), 't') + self.assertEqual(self.sql( + f"select count(*) from public.context_documents where owner_id='{OWNER}'").stdout.strip(), '3') + self.assertEqual(self.sql( + f"select current_result_id::text||':'||revision from public.context_documents where id='{ACCEPTED_DOC}'" + ).stdout.strip(), f'{RESULT}:2') + self.assertEqual(self.sql( + f"select count(*) from public.context_result_sources where result_id='{RESULT}'").stdout.strip(), '1') + self.sql(MIGRATION.read_text()) + self.assert_backfilled()