From 66839c97353eea08928f88b0ab03bd8cd6050bc7 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sat, 10 Oct 2026 16:08:27 -0400 Subject: [PATCH 1/2] Record immutable context document version history context_documents only kept the current pointer, so every acceptance or withdrawal overwrote which result a revision pointed at and a superseded brief could not resolve the version it cited. Add context_document_versions, written once per revision by a trigger on context_documents so none of the existing writers change, with an immutability trigger, a backfill of the current revision of existing documents, a documented rollback that keeps customer data, and a workspace-scoped read_context_document_history RPC. Fixture-tested on local PostgreSQL 17 with legacy backfill, lifecycle, service-role and rollback cases; CI runs the suite on PostgreSQL 15 and 16. Refs recoupable/app#2121 Co-Authored-By: Claude Fable 5.1 --- .github/workflows/document-versions.yml | 32 ++++ ...261010212100_context_document_versions.sql | 142 ++++++++++++++++ supabase/tests/context_document_versions.sql | 151 ++++++++++++++++++ tests/README.md | 4 + tests/test_context_document_versions.py | 108 +++++++++++++ 5 files changed, 437 insertions(+) create mode 100644 .github/workflows/document-versions.yml create mode 100644 supabase/migrations/20261010212100_context_document_versions.sql create mode 100644 supabase/tests/context_document_versions.sql create mode 100644 tests/test_context_document_versions.py 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..447f721 --- /dev/null +++ b/supabase/migrations/20261010212100_context_document_versions.sql @@ -0,0 +1,142 @@ +-- 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. +-- Existing documents are backfilled from their current revision; a fresh document +-- (revision 0, no result) has no version yet and gets no row. +-- +-- Rollback keeps customer documents, results, sources and briefs untouched: +-- 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 unique(id, owner_id) constraint on context_documents may remain; re-running +-- this migration skips it when present and re-backfills history from current rows. +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_id_owner' and conrelid='public.context_documents'::regclass) then + alter table public.context_documents add constraint context_documents_id_owner unique(id, owner_id); + end if; +end $$; + +create table public.context_document_versions ( + id uuid primary key default gen_random_uuid(), + owner_id uuid 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) references public.context_documents(id, owner_id) on delete restrict, + foreign key(result_id, owner_id) references public.context_results(id, owner_id) 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, insert on public.context_document_versions to service_role; + +-- History rows are never rewritten, even by service-role writers. +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 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, document_id, revision, result_id, change) + values (new.owner_id, 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(); +revoke all on function public.reject_context_document_version_change(), public.record_context_document_version() + from public, anon, authenticated; +grant execute on function public.reject_context_document_version_change(), public.record_context_document_version() + to 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, document_id, revision, result_id, change, backfilled, recorded_at) +select d.owner_id, 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..451e47a --- /dev/null +++ b/supabase/tests/context_document_versions.sql @@ -0,0 +1,151 @@ +-- 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,document_id,revision,result_id,change) values(owner,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,document_id,revision,result_id,change) values(outsider,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; + 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','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; + raise notice 'PASS: accepted/cleared revisions recorded, current pointer kept, superseded brief resolvable, immutable history, scoped reads, service-role path'; +end $$; +rollback; diff --git a/tests/README.md b/tests/README.md index 7822447..1b1ffb7 100644 --- a/tests/README.md +++ b/tests/README.md @@ -41,3 +41,7 @@ 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 path and browser-role denial), and the documented rollback followed by re-application. CI runs it on PostgreSQL 15 and 16. Rollback drops only the history table, triggers and read function; customer documents, results, sources and briefs are untouched, and re-running the migration re-backfills. 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..292f621 --- /dev/null +++ b/tests/test_context_document_versions.py @@ -0,0 +1,108 @@ +"""Document version history on disposable PostgreSQL: legacy backfill, lifecycle, rollback.""" +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 rollback: history objects only; documents, results and sources stay. +ROLLBACK = """ +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_rollback_keeps_customer_data_and_reapply_backfills(self): + self.sql(ROLLBACK) + 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() From 9a1a95899ff7b5c3f66cd1820e7512faa2f6afc0 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sat, 10 Oct 2026 16:58:09 -0400 Subject: [PATCH 2/2] Make document history trigger-only and subject-scoped Review found the service role could insert history directly, so a row could cite a result of another subject or topic, and a stray future revision blocked the legitimate withdraw_context_source path. The recording trigger now runs as the migration owner and the service role keeps select only. Each version carries the document's subject and topic, with foreign keys to the document and result on (id, owner, subject, topic), so a citation cannot cross subject or topic even for the owner. Rollback now starts by disabling the recording trigger, which keeps every recorded version and the read, with a tested re-enable that records the current revision of documents that moved meanwhile. Dropping the table is reserved for deployments whose history was never relied on, because re-applying backfills only current revisions. The header states that production apply waits for CE01 (recoupable/app#2117). Refs recoupable/app#2121 Co-Authored-By: Claude Opus 5.5 --- ...261010212100_context_document_versions.sql | 59 +++++++++---- supabase/tests/context_document_versions.sql | 17 +++- tests/README.md | 4 +- tests/test_context_document_versions.py | 87 +++++++++++++++++-- 4 files changed, 141 insertions(+), 26 deletions(-) diff --git a/supabase/migrations/20261010212100_context_document_versions.sql b/supabase/migrations/20261010212100_context_document_versions.sql index 447f721..98b9a0d 100644 --- a/supabase/migrations/20261010212100_context_document_versions.sql +++ b/supabase/migrations/20261010212100_context_document_versions.sql @@ -4,32 +4,56 @@ -- 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. -- --- Rollback keeps customer documents, results, sources and briefs untouched: +-- 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 unique(id, owner_id) constraint on context_documents may remain; re-running --- this migration skips it when present and re-backfills history from current rows. +-- 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_id_owner' and conrelid='public.context_documents'::regclass) then - alter table public.context_documents add constraint context_documents_id_owner unique(id, owner_id); + 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, @@ -38,8 +62,10 @@ create table public.context_document_versions ( recorded_at timestamptz not null default now(), unique(document_id, revision), unique(id, owner_id), - foreign key(document_id, owner_id) references public.context_documents(id, owner_id) on delete restrict, - foreign key(result_id, owner_id) references public.context_results(id, owner_id) on delete restrict, + 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 @@ -48,9 +74,9 @@ 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, insert on public.context_document_versions to service_role; +grant select on public.context_document_versions to service_role; --- History rows are never rewritten, even by service-role writers. +-- 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 @@ -63,7 +89,7 @@ create trigger context_document_versions_immutable -- 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 set search_path='' as $$ +returns trigger language plpgsql security definer set search_path='' as $$ begin if tg_op = 'UPDATE' then if new.revision = old.revision then @@ -78,23 +104,22 @@ begin elsif new.revision = 0 and new.current_result_id is null then return null; end if; - insert into public.context_document_versions(owner_id, document_id, revision, result_id, change) - values (new.owner_id, new.id, new.revision, new.current_result_id, + 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; -grant execute on function public.reject_context_document_version_change(), public.record_context_document_version() - to service_role; + 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, document_id, revision, result_id, change, backfilled, recorded_at) -select d.owner_id, d.id, d.revision, d.current_result_id, +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; diff --git a/supabase/tests/context_document_versions.sql b/supabase/tests/context_document_versions.sql index 451e47a..18d1420 100644 --- a/supabase/tests/context_document_versions.sql +++ b/supabase/tests/context_document_versions.sql @@ -115,11 +115,13 @@ begin 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,document_id,revision,result_id,change) values(owner,doc,2,second_result,'accepted'); + 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,document_id,revision,result_id,change) values(outsider,doc,9,second_result,'accepted'); + 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; @@ -137,15 +139,24 @@ begin 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; - raise notice 'PASS: accepted/cleared revisions recorded, current pointer kept, superseded brief resolvable, immutable history, scoped reads, service-role path'; + 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 1b1ffb7..5984340 100644 --- a/tests/README.md +++ b/tests/README.md @@ -44,4 +44,6 @@ Rollout: apply the contact migration before deploying API readers of `contact_id ## 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 path and browser-role denial), and the documented rollback followed by re-application. CI runs it on PostgreSQL 15 and 16. Rollback drops only the history table, triggers and read function; customer documents, results, sources and briefs are untouched, and re-running the migration re-backfills. This is fixture verification, not a hosted migration or live lineage check. +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 index 292f621..879dffd 100644 --- a/tests/test_context_document_versions.py +++ b/tests/test_context_document_versions.py @@ -1,4 +1,4 @@ -"""Document version history on disposable PostgreSQL: legacy backfill, lifecycle, rollback.""" +"""Document version history on disposable PostgreSQL: legacy backfill, lifecycle, forgery, disable, removal.""" import test_release_cases as release_cases ROOT = release_cases.ROOT @@ -42,8 +42,19 @@ ('{CLEARED_DOC}','{OWNER}','{SUBJECT}','lyrics',3,null,'2026-09-22T10:00:00Z'); """ -# The documented rollback: history objects only; documents, results and sources stay. -ROLLBACK = """ +# 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(); @@ -94,8 +105,74 @@ def test_lifecycle_immutability_and_access(self): result = self.sql(FIXTURE.read_text()) self.assertIn('PASS:', result.stderr) - def test_rollback_keeps_customer_data_and_reapply_backfills(self): - self.sql(ROLLBACK) + 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')