@taopao/memoir 0.0.0-stage → 0.1.0

package/assets/migrations-pg/0116_unified_bank_documents.sql

@@ -0,0 +1,197 @@
+-- 统一银行卡/信用卡事实；原字段逐列复制，原键、金额、原始 JSON、批次和历史审计均保留。
+-- 本文件由迁移执行器包在 migration 会话和同一事务内，不创建任何备份。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+CREATE TEMP TABLE vault_bank_merge_map (
+  old_table text PRIMARY KEY, target_table text NOT NULL, source_kind text NOT NULL,
+  key_column text NOT NULL, columns_sql text
+) ON COMMIT DROP;
+INSERT INTO vault_bank_merge_map(old_table,target_table,source_kind,key_column) VALUES
+ ('psbc_bank_statements','bank_card_statements','psbc_debit_card','statement_key'),
+ ('tailong_bank_statements','bank_card_statements','tailong_debit_card','statement_key'),
+ ('ccb_bank_statements','bank_card_statements','ccb_debit_card','statement_key'),
+ ('icbc_bank_statements','bank_card_statements','icbc_debit_card','statement_key'),
+ ('boc_bank_statements','bank_card_statements','boc_debit_card','statement_key'),
+ ('jsb_bank_statements','bank_card_statements','jsb_debit_card','statement_key'),
+ ('cmbc_bank_statements','bank_card_statements','cmbc_debit_card','statement_key'),
+ ('hzbank_bank_statements','bank_card_statements','hzbank_debit_card','statement_key'),
+ ('psbc_bank_transactions','bank_card_transactions','psbc_debit_card','transaction_key'),
+ ('tailong_bank_transactions','bank_card_transactions','tailong_debit_card','transaction_key'),
+ ('ccb_bank_transactions','bank_card_transactions','ccb_debit_card','transaction_key'),
+ ('icbc_bank_transactions','bank_card_transactions','icbc_debit_card','transaction_key'),
+ ('boc_bank_transactions','bank_card_transactions','boc_debit_card','transaction_key'),
+ ('jsb_bank_transactions','bank_card_transactions','jsb_debit_card','transaction_key'),
+ ('cmbc_bank_transactions','bank_card_transactions','cmbc_debit_card','transaction_key'),
+ ('hzbank_bank_transactions','bank_card_transactions','hzbank_debit_card','transaction_key'),
+ ('ccb_credit_card_transactions','credit_card_transactions','ccb_credit_card','transaction_key'),
+ ('icbc_credit_card_transactions','credit_card_transactions','icbc_credit_card','transaction_key');
+
+-- 原共享借记卡表含仅适用于三个旧来源的 CHECK，改为统一来源范围。
+DO $$ DECLARE r record; BEGIN
+ FOR r IN SELECT conrelid::regclass AS tbl,conname FROM pg_constraint
+  WHERE conrelid IN ('bank_card_statements'::regclass,'bank_card_transactions'::regclass)
+   AND contype='c' AND pg_get_constraintdef(oid) LIKE '%source_kind%'
+ LOOP EXECUTE format('ALTER TABLE %s DROP CONSTRAINT %I',r.tbl,r.conname); END LOOP;
+END $$;
+ALTER TABLE bank_card_statements ALTER COLUMN page_count DROP NOT NULL;
+ALTER TABLE bank_card_statements ADD CONSTRAINT bank_statement_source_check CHECK(source_kind IN
+ ('citic_debit_card','cmb_debit_card','bocom_debit_card','psbc_debit_card','tailong_debit_card','ccb_debit_card','icbc_debit_card','boc_debit_card','jsb_debit_card','cmbc_debit_card','hzbank_debit_card'));
+ALTER TABLE bank_card_transactions ADD CONSTRAINT bank_transaction_source_check CHECK(source_kind IN
+ ('citic_debit_card','cmb_debit_card','bocom_debit_card','psbc_debit_card','tailong_debit_card','ccb_debit_card','icbc_debit_card','boc_debit_card','jsb_debit_card','cmbc_debit_card','hzbank_debit_card'));
+ALTER TABLE credit_card_transactions ALTER COLUMN statement_key DROP NOT NULL;
+ALTER TABLE credit_card_transactions ADD COLUMN source_kind text;
+ALTER TABLE credit_card_transactions ADD COLUMN card_key text;
+UPDATE credit_card_transactions t SET source_kind=s.source_kind,card_key=s.card_key
+ FROM credit_card_statements s WHERE s.statement_key=t.statement_key;
+ALTER TABLE credit_card_transactions ALTER COLUMN source_kind SET NOT NULL;
+ALTER TABLE credit_card_transactions ALTER COLUMN card_key SET NOT NULL;
+ALTER TABLE credit_card_transactions ADD CONSTRAINT credit_transaction_source_check
+ CHECK(source_kind IN ('citic_credit_card','cmb_credit_card','bocom_credit_card','ccb_credit_card','icbc_credit_card'));
+
+-- 根据旧表实际目录建立字段并集，不能凭手写字段名单漏掉银行特有列。
+DO $$ DECLARE m record; c record; cols text; different boolean; BEGIN
+ FOR m IN SELECT * FROM vault_bank_merge_map ORDER BY old_table LOOP
+  SELECT string_agg(quote_ident(attname),',' ORDER BY attnum) INTO cols
+   FROM pg_attribute WHERE attrelid=to_regclass(m.old_table) AND attnum>0 AND NOT attisdropped;
+  IF cols IS NULL THEN RAISE EXCEPTION '待合并事实表不存在: %',m.old_table; END IF;
+  UPDATE vault_bank_merge_map SET columns_sql=cols WHERE old_table=m.old_table;
+  FOR c IN SELECT attname,format_type(atttypid,atttypmod) AS typ FROM pg_attribute
+   WHERE attrelid=to_regclass(m.old_table) AND attnum>0 AND NOT attisdropped LOOP
+   IF NOT EXISTS(SELECT 1 FROM pg_attribute WHERE attrelid=to_regclass(m.target_table) AND attname=c.attname AND attnum>0 AND NOT attisdropped)
+   THEN EXECUTE format('ALTER TABLE %I ADD COLUMN %I %s',m.target_table,c.attname,c.typ); END IF;
+  END LOOP;
+ END LOOP;
+ -- 账单头先于交易复制，任何键冲突直接回滚，不使用忽略冲突丢弃数据。
+ FOR m IN SELECT * FROM vault_bank_merge_map ORDER BY (key_column='transaction_key'),old_table LOOP
+  EXECUTE format('INSERT INTO %I (%s) SELECT %s FROM %I',m.target_table,m.columns_sql,m.columns_sql,m.old_table);
+  -- 对每一列做双向集合比较，确认重命名或合并没有改变已存字段。
+  EXECUTE format('SELECT EXISTS((SELECT %s FROM %I EXCEPT SELECT %s FROM %I) UNION ALL (SELECT %s FROM %I WHERE %I IN (SELECT %I FROM %I) EXCEPT SELECT %s FROM %I))',
+   m.columns_sql,m.old_table,m.columns_sql,m.target_table,m.columns_sql,m.target_table,m.key_column,m.key_column,m.old_table,m.columns_sql,m.old_table) INTO different;
+  IF different THEN RAISE EXCEPTION '字段保留核对失败: %',m.old_table; END IF;
+ END LOOP;
+END $$;
+
+ALTER TABLE bank_card_statements ADD COLUMN bank_card_id text REFERENCES bank_cards(id);
+ALTER TABLE bank_card_transactions ADD COLUMN bank_card_id text REFERENCES bank_cards(id);
+ALTER TABLE credit_card_statements ADD COLUMN bank_card_id text REFERENCES bank_cards(id);
+ALTER TABLE credit_card_transactions ADD COLUMN bank_card_id text REFERENCES bank_cards(id);
+ALTER TABLE bank_card_transactions ADD CONSTRAINT bank_transaction_statement_fk FOREIGN KEY(statement_key) REFERENCES bank_card_statements(statement_key);
+
+-- 来源内账户标识仍是事实身份，卡片 ID 只是明确归属后的关联；不按尾号单独猜卡。
+CREATE FUNCTION vault_match_bank_card(src text, identity_key text, masked text, last_four text)
+RETURNS text LANGUAGE plpgsql STABLE AS $$
+DECLARE bank text; typ text; result text; n bigint; known text; fingerprint text;
+BEGIN
+ bank := CASE split_part(src,'_',1) WHEN 'citic' THEN '中信银行' WHEN 'cmb' THEN '招商银行'
+ WHEN 'bocom' THEN '交通银行' WHEN 'psbc' THEN '邮储银行' WHEN 'tailong' THEN '浙江泰隆商业银行'
+ WHEN 'ccb' THEN '建设银行' WHEN 'icbc' THEN '工商银行' WHEN 'boc' THEN '中国银行'
+ WHEN 'jsb' THEN '江苏银行' WHEN 'cmbc' THEN '民生银行' WHEN 'hzbank' THEN '杭州银行' END;
+ typ := CASE WHEN src LIKE '%_credit_card' THEN 'credit' ELSE 'debit' END;
+ known := regexp_replace(coalesce(masked,''),'[^0-9*]','','g');
+ fingerprint := substring(identity_key from ':([0-9a-f]{64})$');
+ SELECT count(*),min(id) INTO n,result FROM bank_cards c WHERE c.deleted_at IS NULL
+  AND c.card_type=typ AND c.bank_name LIKE bank||'%' AND right(c.card_number,4)=last_four
+  AND (known='' OR c.card_number ~ ('^'||replace(known,'*','[0-9]*')||'$'))
+  AND (src<>'citic_credit_card' OR left(c.card_number,6)=split_part(identity_key,':',1))
+  AND (fingerprint IS NULL OR fingerprint IN (
+   encode(sha256(convert_to(to_json(c.card_number)::text,'UTF8')),'hex'),
+   encode(sha256(convert_to(c.card_number,'UTF8')),'hex'),
+   encode(sha256(convert_to(to_json(known)::text,'UTF8')),'hex')));
+ RETURN CASE WHEN n=1 THEN result ELSE NULL END;
+END $$;
+
+CREATE FUNCTION vault_link_bank_card() RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE r jsonb; identity_key text; masked text; tail text;
+BEGIN
+ IF TG_TABLE_NAME='credit_card_transactions' AND NEW.statement_key IS NOT NULL THEN
+  SELECT s.source_kind,s.card_key,s.bank_card_id INTO NEW.source_kind,NEW.card_key,NEW.bank_card_id FROM credit_card_statements s WHERE s.statement_key=NEW.statement_key;
+ END IF;
+ r:=to_jsonb(NEW); identity_key:=coalesce(r->>'account_key',r->>'card_key');
+ masked:=r->>'account_masked'; tail:=coalesce(r->>'card_last_four',right(masked,4));
+ IF NEW.bank_card_id IS NULL THEN NEW.bank_card_id:=vault_match_bank_card(NEW.source_kind,identity_key,masked,tail); END IF;
+ RETURN NEW;
+END $$;
+DO $$ DECLARE tbl text; BEGIN
+ FOREACH tbl IN ARRAY ARRAY['bank_card_statements','bank_card_transactions','credit_card_statements','credit_card_transactions'] LOOP
+  EXECUTE format('CREATE TRIGGER trg_%s_card_link BEFORE INSERT OR UPDATE ON %I FOR EACH ROW EXECUTE FUNCTION vault_link_bank_card()',tbl,tbl);
+  EXECUTE format('UPDATE %I SET bank_card_id=bank_card_id',tbl);
+  EXECUTE format('CREATE INDEX ix_%s_card ON %I(bank_card_id)',tbl,tbl);
+ END LOOP;
+END $$;
+CREATE INDEX ix_bank_transaction_source_date ON bank_card_transactions(source_kind,occurred_at);
+CREATE INDEX ix_credit_transaction_source_date ON credit_card_transactions(source_kind,posting_date);
+CREATE INDEX ix_credit_transaction_card_date ON credit_card_transactions(card_key,posting_date);
+
+-- 原件关联是一对多/多对多关系，空账单和多卡文件也必须保留。
+CREATE TABLE bank_card_document_links (
+ link_id text PRIMARY KEY, batch_id text NOT NULL, file_sha256 text NOT NULL,
+ source_kind text NOT NULL, bank_card_id text REFERENCES bank_cards(id),
+ account_key text NOT NULL, bank_statement_key text REFERENCES bank_card_statements(statement_key),
+ credit_statement_key text REFERENCES credit_card_statements(statement_key),
+ period_from text,period_to text,link_basis text NOT NULL,
+ FOREIGN KEY(batch_id,file_sha256) REFERENCES import_files(batch_id,file_sha256),
+ CHECK(num_nonnulls(bank_statement_key,credit_statement_key)<=1)
+);
+CREATE TABLE bank_document_records (
+ record_id text PRIMARY KEY,batch_id text NOT NULL,file_sha256 text NOT NULL,source_kind text NOT NULL,
+ bank_card_id text REFERENCES bank_cards(id),record_kind text NOT NULL,locator_json text NOT NULL CHECK(vault_json_valid(locator_json)),
+ raw_json text NOT NULL CHECK(vault_json_valid(raw_json)),normalized_json text NOT NULL CHECK(vault_json_valid(normalized_json)),
+ parser_version text NOT NULL,coverage_status text NOT NULL CHECK(coverage_status IN ('mapped','raw_only','partial','conflict')),
+ bank_statement_key text REFERENCES bank_card_statements(statement_key),bank_transaction_key text REFERENCES bank_card_transactions(transaction_key),
+ credit_statement_key text REFERENCES credit_card_statements(statement_key),credit_transaction_key text REFERENCES credit_card_transactions(transaction_key),
+ FOREIGN KEY(batch_id,file_sha256) REFERENCES import_files(batch_id,file_sha256),
+ CHECK(num_nonnulls(bank_statement_key,bank_transaction_key,credit_statement_key,credit_transaction_key)<=1)
+);
+CREATE INDEX ix_bank_document_card_file ON bank_card_document_links(bank_card_id,batch_id,file_sha256);
+CREATE INDEX ix_bank_document_record_file ON bank_document_records(batch_id,file_sha256,record_kind);
+CREATE INDEX ix_bank_document_record_card ON bank_document_records(bank_card_id,record_kind);
+
+-- 新来源记录同样受事实写保护、逐行审计与 TRUNCATE 保护，不允许普通 SQL 悄悄改写。
+DO $$ DECLARE tbl text; key_col text; g record; BEGIN
+ FOREACH tbl IN ARRAY ARRAY['bank_card_document_links','bank_document_records'] LOOP
+  key_col:=CASE WHEN tbl='bank_card_document_links' THEN 'link_id' ELSE 'record_id' END;
+  EXECUTE format('CREATE TRIGGER trg_%s_guard BEFORE INSERT OR UPDATE OR DELETE ON %I FOR EACH ROW EXECUTE FUNCTION vault_guard(''fact'')',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_truncate BEFORE TRUNCATE ON %I FOR EACH STATEMENT EXECUTE FUNCTION vault_guard(''fact'')',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_version AFTER INSERT OR UPDATE OR DELETE ON %I FOR EACH STATEMENT EXECUTE FUNCTION vault_touch()',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_audit AFTER INSERT OR UPDATE OR DELETE ON %I FOR EACH ROW EXECUTE FUNCTION vault_audit(%L)',tbl,tbl,key_col);
+  FOR g IN SELECT grantee,privilege_type FROM information_schema.role_table_grants WHERE table_schema='public' AND table_name='bank_card_transactions' AND grantee<>current_user AND privilege_type IN ('SELECT','INSERT','UPDATE','DELETE') LOOP
+   EXECUTE format('GRANT %s ON %I TO %s',g.privilege_type,tbl,CASE WHEN g.grantee='PUBLIC' THEN 'PUBLIC' ELSE quote_ident(g.grantee) END);
+  END LOOP;
+ END LOOP;
+END $$;
+
+-- 在删除旧物理表前保存其全部已入库字段，后续从归档补入每份文件的原始页/单元格及解析记录。
+DO $$ DECLARE tbl text; target text; key_col text; ref_col text; src_sql text; m record; BEGIN
+ FOR m IN SELECT old_table AS tbl,target_table FROM vault_bank_merge_map
+  UNION ALL SELECT x,x FROM unnest(ARRAY['bank_card_statements','bank_card_transactions','credit_card_statements','credit_card_transactions']) x LOOP
+  tbl:=m.tbl; target:=m.target_table;
+  key_col:=CASE WHEN target LIKE '%statements' THEN 'statement_key' ELSE 'transaction_key' END;
+  ref_col:=CASE WHEN target LIKE 'bank_%' THEN 'bank_' ELSE 'credit_' END||key_col;
+  src_sql:=CASE WHEN target='credit_card_transactions' AND tbl='credit_card_transactions' THEN 't.source_kind' ELSE 't.source_kind' END;
+  EXECUTE format($sql$
+   INSERT INTO bank_document_records(record_id,batch_id,file_sha256,source_kind,bank_card_id,record_kind,locator_json,raw_json,normalized_json,parser_version,coverage_status,%I)
+   SELECT md5(%L||t.%I||f.batch_id||f.file_sha256),f.batch_id,f.file_sha256,%s,u.bank_card_id,%L,
+    json_build_object('legacy_table',%L,'key',t.%I)::text,t.raw_json,row_to_json(t)::text,b.importer_version,'mapped',t.%I
+   FROM %I t JOIN %I u ON u.%I=t.%I
+   JOIN LATERAL (SELECT ff.* FROM import_files ff WHERE ff.file_sha256=t.source_sha256 ORDER BY (ff.batch_id=t.first_batch_id) DESC,ff.batch_id LIMIT 1) f ON true
+   JOIN import_batches b ON b.id=f.batch_id
+   ON CONFLICT(record_id) DO NOTHING
+  $sql$,ref_col,tbl,key_col,src_sql,CASE WHEN key_col='statement_key' THEN 'statement' ELSE 'transaction' END,tbl,key_col,key_col,tbl,target,key_col,key_col);
+ END LOOP;
+END $$;
+
+-- 不保留第二份事实数据；旧名称成为严格只读视图，历史查询仍然按原列回查。
+CREATE FUNCTION vault_bank_legacy_readonly() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN RAISE EXCEPTION '旧银行表已统一，兼容视图仅供读取'; END $$;
+DO $$ DECLARE m record; g record; BEGIN
+ FOR m IN SELECT * FROM vault_bank_merge_map ORDER BY (key_column='statement_key'),old_table LOOP
+  EXECUTE format('DROP TABLE %I',m.old_table);
+ END LOOP;
+ FOR m IN SELECT * FROM vault_bank_merge_map LOOP
+  EXECUTE format('CREATE VIEW %I AS SELECT %s FROM %I WHERE source_kind=%L',m.old_table,m.columns_sql,m.target_table,m.source_kind);
+  EXECUTE format('CREATE TRIGGER trg_%s_readonly INSTEAD OF INSERT OR UPDATE OR DELETE ON %I FOR EACH ROW EXECUTE FUNCTION vault_bank_legacy_readonly()',m.old_table,m.old_table);
+  FOR g IN SELECT grantee FROM information_schema.role_table_grants WHERE table_schema='public' AND table_name=m.target_table AND privilege_type='SELECT' AND grantee<>current_user LOOP
+   EXECUTE format('GRANT SELECT ON %I TO %s',m.old_table,CASE WHEN g.grantee='PUBLIC' THEN 'PUBLIC' ELSE quote_ident(g.grantee) END);
+  END LOOP;
+ END LOOP;
+END $$;
+

package/assets/migrations-pg/0117_agent_submissions.sql

@@ -0,0 +1,50 @@
+-- Agent 提交与审计基础；只新增版本，不修改既有事实与历史，不生成备份。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+ALTER TABLE public.audit_log ADD COLUMN change_set text;
+ALTER TABLE public.audit_log ADD COLUMN object_schema text;
+ALTER TABLE public.audit_log ADD COLUMN primary_key_json text CHECK(primary_key_json IS NULL OR public.vault_json_valid(primary_key_json));
+CREATE INDEX ix_audit_change_set ON public.audit_log(change_set,id) WHERE change_set IS NOT NULL;
+CREATE OR REPLACE FUNCTION public.vault_audit() RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE item jsonb; row_key text; key_value jsonb; old_value text; new_value text;
+BEGIN
+ item:=CASE WHEN TG_OP='DELETE' THEN to_jsonb(OLD) ELSE to_jsonb(NEW) END;
+ SELECT string_agg(item ->> key, ':' ORDER BY ord),jsonb_object_agg(key,item -> key)
+ INTO row_key,key_value FROM unnest(TG_ARGV) WITH ORDINALITY AS keys(key,ord);
+ IF TG_OP<>'INSERT' THEN old_value:=to_jsonb(OLD)::text; END IF;
+ IF TG_OP<>'DELETE' THEN new_value:=to_jsonb(NEW)::text; END IF;
+ INSERT INTO public.audit_log(at,actor,reason,table_name,row_key,op,before_json,after_json,change_set,object_schema,primary_key_json)
+ VALUES(to_char(clock_timestamp() AT TIME ZONE 'Asia/Shanghai','YYYY-MM-DD HH24:MI:SS'),
+ current_setting('vault.actor'),nullif(current_setting('vault.reason',true),''),TG_TABLE_NAME,row_key,lower(TG_OP),old_value,new_value,
+ nullif(current_setting('vault.change_set',true),''),TG_TABLE_SCHEMA,key_value::text);
+ RETURN NULL;
+END $$;
+CREATE SCHEMA agent;
+CREATE TABLE agent.submissions (
+ id text PRIMARY KEY,actor text NOT NULL,idempotency_key text NOT NULL,fingerprint text NOT NULL,
+ source_id text NOT NULL REFERENCES public.journal_entries(id),
+ result_json text NOT NULL CHECK(public.vault_json_valid(result_json)),
+ created_at text NOT NULL,UNIQUE(actor,idempotency_key)
+);
+CREATE TABLE agent.candidates (
+ id text PRIMARY KEY,submission_id text NOT NULL REFERENCES agent.submissions(id),
+ operation_key text NOT NULL,reason text NOT NULL,payload_json text NOT NULL CHECK(public.vault_json_valid(payload_json)),
+ source_id text NOT NULL REFERENCES public.journal_entries(id),quote text,
+ state text NOT NULL DEFAULT 'pending' CHECK(state IN ('pending','resolved','dismissed')),
+ created_at text NOT NULL,created_by text NOT NULL,UNIQUE(submission_id,operation_key)
+);
+-- 管理记录同样需要写会话、审计和版本；核心写入从不依赖这些表存在。
+DO $$ DECLARE tbl text; g record; BEGIN
+ FOREACH tbl IN ARRAY ARRAY['submissions','candidates'] LOOP
+  EXECUTE format('CREATE TRIGGER trg_%s_guard BEFORE INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH ROW EXECUTE FUNCTION public.vault_guard(''session'')',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_truncate BEFORE TRUNCATE ON agent.%I FOR EACH STATEMENT EXECUTE FUNCTION public.vault_guard(''session'')',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_audit AFTER INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH ROW EXECUTE FUNCTION public.vault_audit(''id'')',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_version AFTER INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH STATEMENT EXECUTE FUNCTION public.vault_touch()',tbl,tbl);
+  -- 继承既有角色的最小权限，不猜测部署角色名，不授予删除或结构修改权限。
+  FOR g IN SELECT DISTINCT grantee,privilege_type FROM information_schema.role_table_grants
+   WHERE table_schema='public' AND table_name='persons' AND grantee<>'PUBLIC' AND privilege_type IN ('SELECT','INSERT','UPDATE')
+  LOOP
+   EXECUTE format('GRANT USAGE ON SCHEMA agent TO %I',g.grantee);
+   EXECUTE format('GRANT %s ON agent.%I TO %I',g.privilege_type,tbl,g.grantee);
+  END LOOP;
+ END LOOP;
+END $$;

package/assets/migrations-pg/0118_agent_reversions_analysis.sql

@@ -0,0 +1,34 @@
+-- 撤销映射和分析资料均持久保留；不回删原批次、原文、审计或版本，不创建备份。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+CREATE TABLE agent.reversions (
+ id text PRIMARY KEY,submission_id text NOT NULL UNIQUE REFERENCES agent.submissions(id),
+ actor text NOT NULL,reason text NOT NULL,result_json text NOT NULL CHECK(public.vault_json_valid(result_json)),created_at text NOT NULL
+);
+CREATE TABLE agent.analysis_reports (
+ id text PRIMARY KEY,actor text NOT NULL,idempotency_key text NOT NULL,fingerprint text NOT NULL,
+ title text NOT NULL,body text NOT NULL,metrics_json text NOT NULL CHECK(public.vault_json_valid(metrics_json)),
+ scope_note text NOT NULL,period_from text,period_to text,script_text text,
+ sensitivity text NOT NULL CHECK(sensitivity IN ('normal','private','intimate')),created_at text NOT NULL,
+ UNIQUE(actor,idempotency_key),CHECK(period_to IS NULL OR period_from IS NULL OR period_to>=period_from)
+);
+CREATE TABLE agent.analysis_sources (
+ id text PRIMARY KEY,report_id text NOT NULL REFERENCES agent.analysis_reports(id),
+ object_schema text NOT NULL,table_name text NOT NULL,primary_key_json text NOT NULL CHECK(public.vault_json_valid(primary_key_json)),
+ source_revision text NOT NULL,quote text NOT NULL
+);
+-- 撤销记录和报告是历史资料，默认只增；不提供修改旧报告的捷径。
+DO $$ DECLARE tbl text; g record; BEGIN
+ FOREACH tbl IN ARRAY ARRAY['reversions','analysis_reports','analysis_sources'] LOOP
+  EXECUTE format('CREATE TRIGGER trg_%s_guard BEFORE INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH ROW EXECUTE FUNCTION public.vault_guard(''append'')',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_truncate BEFORE TRUNCATE ON agent.%I FOR EACH STATEMENT EXECUTE FUNCTION public.vault_guard(''append'')',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_audit AFTER INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH ROW EXECUTE FUNCTION public.vault_audit(''id'')',tbl,tbl);
+  EXECUTE format('CREATE TRIGGER trg_%s_version AFTER INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH STATEMENT EXECUTE FUNCTION public.vault_touch()',tbl,tbl);
+  FOR g IN SELECT DISTINCT grantee,privilege_type FROM information_schema.role_table_grants
+   WHERE table_schema='public' AND table_name='persons' AND grantee<>'PUBLIC' AND privilege_type IN ('SELECT','INSERT')
+  LOOP
+   EXECUTE format('GRANT USAGE ON SCHEMA agent TO %I',g.grantee);
+   EXECUTE format('GRANT %s ON agent.%I TO %I',g.privilege_type,tbl,g.grantee);
+  END LOOP;
+ END LOOP;
+END $$;
+CREATE INDEX ix_agent_analysis_source ON agent.analysis_sources(object_schema,table_name);

package/assets/migrations-pg/0119_agent_extension_registry.sql

@@ -0,0 +1,72 @@
+-- 扩展注册与历史由结构服务写入；不改动已发布迁移，不创建业务扩展表或任何备份。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+CREATE SCHEMA agent_ext;
+CREATE SCHEMA agent_archive;
+CREATE TABLE agent.extension_domains (
+ key text PRIMARY KEY,description text NOT NULL,created_at text NOT NULL,created_by text NOT NULL
+);
+CREATE TABLE agent.extensions (
+ id text PRIMARY KEY,domain_key text NOT NULL REFERENCES agent.extension_domains(key),
+ schema_name text NOT NULL CHECK(schema_name IN ('agent_ext','agent_archive')),table_name text NOT NULL,
+ version integer NOT NULL CHECK(version>0),checksum text NOT NULL,fingerprint text NOT NULL UNIQUE,
+ purpose_key text NOT NULL,description text NOT NULL,semantics text NOT NULL CHECK(semantics IN ('recorded_fact','observation','analysis')),
+ sensitivity text NOT NULL CHECK(sensitivity IN ('normal','private','intimate')),
+ state text NOT NULL CHECK(state IN ('active','deprecated','retired')),
+ descriptor_json text NOT NULL CHECK(public.vault_json_valid(descriptor_json)),distinct_reason text,
+ catalog_json text NOT NULL CHECK(public.vault_json_valid(catalog_json)),
+ created_at text NOT NULL,created_by text NOT NULL,updated_at text NOT NULL,updated_by text NOT NULL,
+ UNIQUE(schema_name,table_name)
+);
+CREATE TABLE agent.extension_migrations (
+ extension_id text NOT NULL REFERENCES agent.extensions(id),version integer NOT NULL,checksum text NOT NULL,
+ descriptor_json text NOT NULL CHECK(public.vault_json_valid(descriptor_json)),ddl_sql text NOT NULL,
+ trial_json text NOT NULL CHECK(public.vault_json_valid(trial_json)),result_json text NOT NULL CHECK(public.vault_json_valid(result_json)),
+ applied_at text NOT NULL,actor text NOT NULL,PRIMARY KEY(extension_id,version)
+);
+CREATE TABLE agent.extension_reads (
+ extension_id text NOT NULL REFERENCES agent.extensions(id),actor text NOT NULL,version integer NOT NULL,seen_at text NOT NULL,
+ PRIMARY KEY(extension_id,actor)
+);
+-- 稳定数据库层持有保护函数。卸载执行包后仍读取保留的注册描述，不依赖在线 Agent。
+CREATE FUNCTION public.vault_extension_guard() RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE actor text:=nullif(current_setting('vault.actor',true),''); item record; col text;
+BEGIN
+ IF TG_OP IN ('DELETE','TRUNCATE') THEN RAISE EXCEPTION '扩展只允许软删除'; END IF;
+ IF actor IS NULL THEN RAISE EXCEPTION '未设置写入会话'; END IF;
+ SELECT schema_name,table_name,state INTO item FROM agent.extensions WHERE id=TG_ARGV[0];
+ IF NOT FOUND OR item.schema_name<>TG_TABLE_SCHEMA OR item.table_name<>TG_TABLE_NAME THEN RAISE EXCEPTION '扩展注册与物理对象不一致'; END IF;
+ IF actor='migration' THEN RETURN NEW; END IF;
+ IF item.state<>'active' THEN RAISE EXCEPTION '扩展已停止写入'; END IF;
+ IF nullif(current_setting('vault.change_set',true),'') IS NULL THEN RAISE EXCEPTION '扩展写入需要批次'; END IF;
+ IF NEW.updated_by<>actor OR (TG_OP='INSERT' AND NEW.created_by<>actor) THEN RAISE EXCEPTION '扩展审计身份不一致'; END IF;
+ IF TG_OP='UPDATE' THEN
+  IF NEW.created_at IS DISTINCT FROM OLD.created_at OR NEW.created_by IS DISTINCT FROM OLD.created_by THEN RAISE EXCEPTION '扩展创建信息不可修改'; END IF;
+  FOREACH col IN ARRAY TG_ARGV[1:array_length(TG_ARGV,1)] LOOP
+   IF (to_jsonb(NEW)->col) IS DISTINCT FROM (to_jsonb(OLD)->col) THEN RAISE EXCEPTION '扩展主键不可修改'; END IF;
+  END LOOP;
+ END IF;
+ RETURN NEW;
+END $$;
+DO $$ DECLARE tbl text; mode text; keys text; g record; BEGIN
+ FOREACH tbl IN ARRAY ARRAY['extension_domains','extensions','extension_migrations','extension_reads'] LOOP
+  mode:=CASE WHEN tbl IN ('extension_domains','extension_migrations') THEN 'append' ELSE 'session' END;
+  keys:=CASE WHEN tbl='extension_domains' THEN '''key''' WHEN tbl='extension_migrations' THEN '''extension_id'',''version''' WHEN tbl='extension_reads' THEN '''extension_id'',''actor''' ELSE '''id''' END;
+  EXECUTE format('CREATE TRIGGER trg_%s_guard BEFORE INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH ROW EXECUTE FUNCTION public.vault_guard(%L)',tbl,tbl,mode);
+  EXECUTE format('CREATE TRIGGER trg_%s_truncate BEFORE TRUNCATE ON agent.%I FOR EACH STATEMENT EXECUTE FUNCTION public.vault_guard(%L)',tbl,tbl,mode);
+  EXECUTE format('CREATE TRIGGER trg_%s_audit AFTER INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH ROW EXECUTE FUNCTION public.vault_audit(%s)',tbl,tbl,keys);
+  EXECUTE format('CREATE TRIGGER trg_%s_version AFTER INSERT OR UPDATE OR DELETE ON agent.%I FOR EACH STATEMENT EXECUTE FUNCTION public.vault_touch()',tbl,tbl);
+  -- 部署可能存在默认授权，不能因此让普通 app 改写结构注册与迁移历史。
+  EXECUTE format('REVOKE ALL ON agent.%I FROM PUBLIC',tbl);
+  FOR g IN SELECT DISTINCT r.rolname AS grantee FROM pg_class c CROSS JOIN LATERAL aclexplode(c.relacl) a JOIN pg_roles r ON r.oid=a.grantee WHERE c.oid=to_regclass('agent.'||tbl) AND a.grantee<>c.relowner LOOP
+   EXECUTE format('REVOKE ALL ON agent.%I FROM %I',tbl,g.grantee);
+  END LOOP;
+  FOR g IN SELECT DISTINCT grantee,privilege_type FROM information_schema.role_table_grants WHERE table_schema='public' AND table_name='persons' AND grantee<>'PUBLIC' AND privilege_type='SELECT' LOOP
+   EXECUTE format('GRANT USAGE ON SCHEMA agent_ext,agent_archive TO %I',g.grantee);
+   EXECUTE format('GRANT SELECT ON agent.%I TO %I',tbl,g.grantee);
+  END LOOP;
+ END LOOP;
+ -- 已读状态可由 app 写入，结构描述及迁移记录仅由 owner 结构服务维护。
+ FOR g IN SELECT DISTINCT grantee,privilege_type FROM information_schema.role_table_grants WHERE table_schema='public' AND table_name='persons' AND grantee<>'PUBLIC' AND privilege_type IN ('INSERT','UPDATE') LOOP
+  EXECUTE format('GRANT %s ON agent.extension_reads TO %I',g.privilege_type,g.grantee);
+ END LOOP;
+END $$;

package/assets/migrations-pg/0120_agent_record_sources.sql

@@ -0,0 +1,22 @@
+-- 扩展写入的结构化来源单独保留，不能把带复合键的引用伪装成普通网页手工证据。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+CREATE TABLE agent.record_sources (
+ id text PRIMARY KEY,submission_id text NOT NULL REFERENCES agent.submissions(id),
+ extension_id text NOT NULL REFERENCES agent.extensions(id),record_key_json text NOT NULL CHECK(public.vault_json_valid(record_key_json)),
+ source_schema text NOT NULL,source_table text NOT NULL,source_key_json text NOT NULL CHECK(public.vault_json_valid(source_key_json)),
+ source_revision text NOT NULL,quote text NOT NULL
+);
+CREATE INDEX ix_agent_record_source ON agent.record_sources(source_schema,source_table);
+CREATE TRIGGER trg_record_sources_guard BEFORE INSERT OR UPDATE OR DELETE ON agent.record_sources FOR EACH ROW EXECUTE FUNCTION public.vault_guard('append');
+CREATE TRIGGER trg_record_sources_truncate BEFORE TRUNCATE ON agent.record_sources FOR EACH STATEMENT EXECUTE FUNCTION public.vault_guard('append');
+CREATE TRIGGER trg_record_sources_audit AFTER INSERT OR UPDATE OR DELETE ON agent.record_sources FOR EACH ROW EXECUTE FUNCTION public.vault_audit('id');
+CREATE TRIGGER trg_record_sources_version AFTER INSERT OR UPDATE OR DELETE ON agent.record_sources FOR EACH STATEMENT EXECUTE FUNCTION public.vault_touch();
+DO $$ DECLARE g record; BEGIN
+ REVOKE ALL ON agent.record_sources FROM PUBLIC;
+ FOR g IN SELECT DISTINCT r.rolname AS grantee FROM pg_class c CROSS JOIN LATERAL aclexplode(c.relacl) a JOIN pg_roles r ON r.oid=a.grantee WHERE c.oid='agent.record_sources'::regclass AND a.grantee<>c.relowner LOOP
+  EXECUTE format('REVOKE ALL ON agent.record_sources FROM %I',g.grantee);
+ END LOOP;
+ FOR g IN SELECT DISTINCT grantee,privilege_type FROM information_schema.role_table_grants WHERE table_schema='public' AND table_name='persons' AND grantee<>'PUBLIC' AND privilege_type IN ('SELECT','INSERT') LOOP
+  EXECUTE format('GRANT %s ON agent.record_sources TO %I',g.privilege_type,g.grantee);
+ END LOOP;
+END $$;

package/assets/migrations-pg/0121_agent_extension_deprecation.sql

@@ -0,0 +1,30 @@
+-- 生命周期修订独立于字段结构版本；保留迁移、业务行和来源历史，不自动备份。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+ALTER TABLE agent.extensions ADD COLUMN lifecycle_revision integer NOT NULL DEFAULT 1 CHECK(lifecycle_revision>0);
+ALTER TABLE agent.extensions ADD COLUMN deprecation_reason text;
+ALTER TABLE agent.extensions ADD COLUMN superseded_by text REFERENCES agent.extensions(id);
+ALTER TABLE agent.extensions ADD CONSTRAINT ck_extension_superseded_by CHECK(superseded_by IS NULL OR superseded_by<>id);
+-- 旧已读标记对应初始生命周期修订 1，不因新增通知字段把所有已读结构重置。
+ALTER TABLE agent.extension_reads ADD COLUMN lifecycle_revision integer NOT NULL DEFAULT 1 CHECK(lifecycle_revision>0);
+CREATE TABLE agent.extension_lifecycle_events (
+ id text PRIMARY KEY,extension_id text NOT NULL REFERENCES agent.extensions(id),
+ actor text NOT NULL,idempotency_key text NOT NULL,fingerprint text NOT NULL,
+ from_state text NOT NULL CHECK(from_state IN ('active','deprecated','retired')),to_state text NOT NULL CHECK(to_state IN ('active','deprecated','retired')),reason text NOT NULL,
+ superseded_by text REFERENCES agent.extensions(id),lifecycle_revision integer NOT NULL CHECK(lifecycle_revision>1),
+ result_json text NOT NULL CHECK(public.vault_json_valid(result_json)),created_at text NOT NULL,
+ UNIQUE(actor,idempotency_key),UNIQUE(extension_id,lifecycle_revision)
+);
+CREATE TRIGGER trg_extension_lifecycle_events_guard BEFORE INSERT OR UPDATE OR DELETE ON agent.extension_lifecycle_events FOR EACH ROW EXECUTE FUNCTION public.vault_guard('append');
+CREATE TRIGGER trg_extension_lifecycle_events_truncate BEFORE TRUNCATE ON agent.extension_lifecycle_events FOR EACH STATEMENT EXECUTE FUNCTION public.vault_guard('append');
+CREATE TRIGGER trg_extension_lifecycle_events_audit AFTER INSERT OR UPDATE OR DELETE ON agent.extension_lifecycle_events FOR EACH ROW EXECUTE FUNCTION public.vault_audit('id');
+CREATE TRIGGER trg_extension_lifecycle_events_version AFTER INSERT OR UPDATE OR DELETE ON agent.extension_lifecycle_events FOR EACH STATEMENT EXECUTE FUNCTION public.vault_touch();
+DO $$ DECLARE g record; BEGIN
+ REVOKE ALL ON agent.extension_lifecycle_events FROM PUBLIC;
+ FOR g IN SELECT DISTINCT r.rolname AS grantee FROM pg_class c CROSS JOIN LATERAL aclexplode(c.relacl) a JOIN pg_roles r ON r.oid=a.grantee WHERE c.oid='agent.extension_lifecycle_events'::regclass AND a.grantee<>c.relowner LOOP
+  EXECUTE format('REVOKE ALL ON agent.extension_lifecycle_events FROM %I',g.grantee);
+ END LOOP;
+ -- 普通调用者只读生命周期历史；状态和事件由内部结构服务在同一事务写入。
+ FOR g IN SELECT DISTINCT grantee FROM information_schema.role_table_grants WHERE table_schema='public' AND table_name='persons' AND grantee<>'PUBLIC' AND privilege_type='SELECT' LOOP
+  EXECUTE format('GRANT SELECT ON agent.extension_lifecycle_events TO %I',g.grantee);
+ END LOOP;
+END $$;

package/assets/migrations-pg/0122_agent_extension_controlled_revert.sql

@@ -0,0 +1,107 @@
+-- 停止写入的扩展只允许限定的历史恢复，不恢复 app 写 ACL、不更改生命周期，不自动备份。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+
+CREATE OR REPLACE FUNCTION public.vault_extension_guard() RETURNS trigger
+LANGUAGE plpgsql SECURITY INVOKER SET search_path=pg_catalog,pg_temp AS $$
+DECLARE actor text:=nullif(current_setting('vault.actor',true),''); item record; col text; controlled boolean;
+BEGIN
+ IF TG_OP IN ('DELETE','TRUNCATE') THEN RAISE EXCEPTION '扩展只允许软删除'; END IF;
+ IF actor IS NULL THEN RAISE EXCEPTION '未设置写入会话'; END IF;
+ SELECT schema_name,table_name,state INTO item FROM agent.extensions WHERE id=TG_ARGV[0];
+ IF NOT FOUND OR item.schema_name<>TG_TABLE_SCHEMA OR item.table_name<>TG_TABLE_NAME THEN RAISE EXCEPTION '扩展注册与物理对象不一致'; END IF;
+ IF actor='migration' THEN RETURN NEW; END IF;
+ -- 标志本身不是权限：必须处于限定恢复函数的 owner 执行身份，app 即使自行 SET 也不能写。
+ SELECT TG_OP='UPDATE' AND nullif(current_setting('vault.extension_revert',true),'')=TG_ARGV[0]
+   AND c.relowner=r.oid INTO controlled FROM pg_class c JOIN pg_roles r ON r.rolname=current_user WHERE c.oid=TG_RELID;
+ IF item.state<>'active' AND NOT coalesce(controlled,false) THEN RAISE EXCEPTION '扩展已停止写入'; END IF;
+ IF nullif(current_setting('vault.change_set',true),'') IS NULL THEN RAISE EXCEPTION '扩展写入需要批次'; END IF;
+ IF NEW.updated_by<>actor OR (TG_OP='INSERT' AND NEW.created_by<>actor) THEN RAISE EXCEPTION '扩展审计身份不一致'; END IF;
+ IF TG_OP='UPDATE' THEN
+  IF NEW.created_at IS DISTINCT FROM OLD.created_at OR NEW.created_by IS DISTINCT FROM OLD.created_by THEN RAISE EXCEPTION '扩展创建信息不可修改'; END IF;
+  FOREACH col IN ARRAY TG_ARGV[1:array_length(TG_ARGV,1)] LOOP
+   IF (to_jsonb(NEW)->col) IS DISTINCT FROM (to_jsonb(OLD)->col) THEN RAISE EXCEPTION '扩展主键不可修改'; END IF;
+  END LOOP;
+ END IF;
+ RETURN NEW;
+END $$;
+
+-- 只在已认证的原提交与新撤销会话中锁注册扩展，解决 app 对只读表没有强表锁权限的问题。
+-- 锁随调用方事务持有，函数不创建独立事务，也不授予该表 UPDATE。
+CREATE FUNCTION public.vault_lock_extension_revert(p_extension_id text,p_submission_id text) RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path=pg_catalog,pg_temp AS $$
+DECLARE e record; role_oid oid; v_actor text:=nullif(current_setting('vault.actor',true),''); v_change_set text:=nullif(current_setting('vault.change_set',true),'');
+BEGIN
+ IF v_actor IS NULL OR v_change_set IS NULL OR v_change_set=p_submission_id OR nullif(current_setting('vault.reason',true),'') IS NULL THEN RAISE EXCEPTION 'Agent 撤销会话无效'; END IF;
+ PERFORM pg_advisory_xact_lock(hashtext('relation-vault:write'));
+ IF NOT EXISTS(SELECT 1 FROM agent.submissions s WHERE s.id=p_submission_id AND s.actor=v_actor) OR EXISTS(SELECT 1 FROM agent.reversions r WHERE r.submission_id=p_submission_id) THEN RAISE EXCEPTION 'Agent 原提交不存在、身份不匹配或已撤销'; END IF;
+ SELECT * INTO e FROM agent.extensions WHERE id=p_extension_id FOR SHARE;
+ IF NOT FOUND OR e.schema_name NOT IN ('agent_ext','agent_archive') OR e.state NOT IN ('active','deprecated','retired') THEN RAISE EXCEPTION 'Agent 撤销扩展未登记'; END IF;
+ SELECT oid INTO role_oid FROM pg_roles WHERE rolname=current_user;
+ IF NOT EXISTS(SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace WHERE n.nspname=e.schema_name AND c.relname=e.table_name AND c.relkind='r' AND c.relowner=role_oid) THEN RAISE EXCEPTION 'Agent 撤销函数与扩展属主不一致'; END IF;
+ EXECUTE format('LOCK TABLE %I.%I IN SHARE ROW EXCLUSIVE MODE',e.schema_name,e.table_name);
+END $$;
+
+-- 参数只能定位原审计行，不接受调用者提供待恢复字段、SQL 或操作者。
+-- 核心依赖/隐私校验仍由同一事务中的业务撤销入口编排，不能单独调用此内部函数绕过协议。
+CREATE FUNCTION public.vault_restore_extension_revert(p_extension_id text,p_submission_id text,p_key_json text,p_last_audit bigint) RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path=pg_catalog,pg_temp AS $$
+DECLARE e record; audit_row record; first_before jsonb; final_after jsonb; previous_after jsonb; key_value jsonb:=p_key_json::jsonb;
+ original_object text; current_object text; columns_now text[]; columns_audit text[]; pk_now text[]; pk_input text[];
+ chain_count integer:=0; last_id bigint; current_row jsonb; statement text; updates text; changed bigint; stamp text;
+ previous_marker text:=current_setting('vault.extension_revert',true); v_actor text:=nullif(current_setting('vault.actor',true),'');
+BEGIN
+ PERFORM public.vault_lock_extension_revert(p_extension_id,p_submission_id);
+ SELECT * INTO e FROM agent.extensions WHERE id=p_extension_id;
+ IF e.state NOT IN ('deprecated','retired') OR e.version<>1 THEN RAISE EXCEPTION 'Agent 限定恢复仅用于结构兼容的已废弃或归档扩展'; END IF;
+ original_object:='agent_ext.'||(e.descriptor_json::jsonb->'domain'->>'key')||'_'||(e.descriptor_json::jsonb->>'entity');
+ current_object:=e.schema_name||'.'||e.table_name;
+ IF (e.state='deprecated' AND current_object IS DISTINCT FROM original_object)
+   OR (e.state='retired' AND current_object IS DISTINCT FROM 'agent_archive.ext_'||replace(e.id,'-',''))
+   OR NOT EXISTS(SELECT 1 FROM agent.extension_migrations m WHERE m.extension_id=e.id AND m.version=e.version AND m.checksum=e.checksum AND m.descriptor_json::jsonb=e.descriptor_json::jsonb)
+ THEN RAISE EXCEPTION 'Agent 扩展结构或位置历史不一致'; END IF;
+ IF jsonb_typeof(key_value)<>'object' OR key_value='{}'::jsonb OR EXISTS(SELECT 1 FROM jsonb_each(key_value) kv WHERE jsonb_typeof(kv.value) NOT IN ('string','number')) THEN RAISE EXCEPTION 'Agent 撤销主键无效'; END IF;
+ -- 字段名使用固定字符序比较，不能让数据库地区排序规则影响结构兼容判断。
+ SELECT array_agg(x ORDER BY x COLLATE "C") INTO pk_input FROM jsonb_object_keys(key_value) x;
+ SELECT array_agg(a.attname::text ORDER BY k.ord) INTO pk_now FROM pg_index i CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY k(attnum,ord) JOIN pg_attribute a ON a.attrelid=i.indrelid AND a.attnum=k.attnum WHERE i.indrelid=to_regclass(format('%I.%I',e.schema_name,e.table_name)) AND i.indisprimary;
+ IF pk_now IS NULL OR to_jsonb(pk_now) IS DISTINCT FROM e.descriptor_json::jsonb->'primary_key'
+   OR (SELECT array_agg(x ORDER BY x COLLATE "C") FROM unnest(pk_now) x) IS DISTINCT FROM pk_input THEN RAISE EXCEPTION 'Agent 撤销主键结构已变化'; END IF;
+ -- 新旧物理位置共同定位同一稳定对象，保持原审计文本，不按冒号拆分复合键。
+ FOR audit_row IN SELECT l.* FROM public.audit_log l WHERE l.change_set=p_submission_id AND l.primary_key_json::jsonb=key_value AND coalesce(l.object_schema,'public')||'.'||l.table_name IN (original_object,current_object) ORDER BY l.id LIMIT 4001 LOOP
+  chain_count:=chain_count+1;
+  IF audit_row.after_json IS NULL OR audit_row.actor IS DISTINCT FROM v_actor OR (chain_count>1 AND previous_after IS DISTINCT FROM audit_row.before_json::jsonb) THEN RAISE EXCEPTION 'Agent 扩展审计链不完整'; END IF;
+  IF chain_count=1 THEN first_before:=audit_row.before_json::jsonb; END IF;
+  final_after:=audit_row.after_json::jsonb; previous_after:=final_after; last_id:=audit_row.id;
+  IF NOT (key_value<@final_after) OR (audit_row.before_json IS NOT NULL AND NOT (key_value<@audit_row.before_json::jsonb)) THEN RAISE EXCEPTION 'Agent 扩展审计主键不一致'; END IF;
+ END LOOP;
+ IF chain_count=0 OR chain_count>4000 OR last_id IS DISTINCT FROM p_last_audit THEN RAISE EXCEPTION 'Agent 扩展审计末端已变化'; END IF;
+ SELECT array_agg(attname::text ORDER BY attname::text COLLATE "C") INTO columns_now FROM pg_attribute WHERE attrelid=to_regclass(format('%I.%I',e.schema_name,e.table_name)) AND attnum>0 AND NOT attisdropped;
+ SELECT array_agg(x ORDER BY x COLLATE "C") INTO columns_audit FROM jsonb_object_keys(final_after) x;
+ IF columns_now IS DISTINCT FROM columns_audit OR NOT ('deleted_at'=ANY(columns_now)) OR (first_before IS NOT NULL AND (SELECT array_agg(x ORDER BY x COLLATE "C") FROM jsonb_object_keys(first_before) x) IS DISTINCT FROM columns_now) THEN RAISE EXCEPTION 'Agent 扩展审计字段与当前结构不兼容'; END IF;
+ EXECUTE format('SELECT to_jsonb(t) FROM %I.%I t WHERE $1 <@ to_jsonb(t) FOR UPDATE',e.schema_name,e.table_name) INTO current_row USING key_value;
+ IF current_row IS DISTINCT FROM final_after OR EXISTS(SELECT 1 FROM public.audit_log l WHERE l.id>last_id AND l.primary_key_json::jsonb=key_value AND coalesce(l.object_schema,'public')||'.'||l.table_name IN (original_object,current_object)) THEN RAISE EXCEPTION 'Agent 扩展行或后续审计已变化'; END IF;
+ stamp:=to_char(clock_timestamp() AT TIME ZONE 'Asia/Shanghai','YYYY-MM-DD HH24:MI:SS');
+ IF first_before IS NULL THEN updates:='deleted_at=$2';
+ ELSE
+  SELECT string_agg(format('%1$I=(jsonb_populate_record(NULL::%2$I.%3$I,$1)).%1$I',c,e.schema_name,e.table_name),',' ORDER BY c) INTO updates
+   FROM unnest(columns_now) c WHERE NOT (c=ANY(pk_now)) AND c NOT IN ('created_at','created_by','updated_at','updated_by');
+ END IF;
+ statement:=format('UPDATE %I.%I t SET %s,updated_at=$2,updated_by=$3 WHERE $4 <@ to_jsonb(t)',e.schema_name,e.table_name,updates);
+ PERFORM set_config('vault.extension_revert',e.id,true);
+ EXECUTE statement USING first_before,stamp,v_actor,key_value;
+ GET DIAGNOSTICS changed=ROW_COUNT;
+ PERFORM set_config('vault.extension_revert',coalesce(previous_marker,''),true);
+ IF changed<>1 THEN RAISE EXCEPTION 'Agent 扩展限定恢复未命中唯一记录'; END IF;
+END $$;
+
+-- 新函数默认 PUBLIC EXECUTE 必须收回，也清除部署默认 ACL；仅映射现有业务更新角色。
+DO $$ DECLARE f text; g record; BEGIN
+ FOREACH f IN ARRAY ARRAY['public.vault_lock_extension_revert(text,text)','public.vault_restore_extension_revert(text,text,text,bigint)'] LOOP
+  EXECUTE format('REVOKE ALL ON FUNCTION %s FROM PUBLIC',f);
+  FOR g IN SELECT DISTINCT r.rolname FROM pg_proc p CROSS JOIN LATERAL aclexplode(p.proacl) a JOIN pg_roles r ON r.oid=a.grantee WHERE p.oid=to_regprocedure(f) AND a.grantee<>p.proowner LOOP
+   EXECUTE format('REVOKE ALL ON FUNCTION %s FROM %I',f,g.rolname);
+  END LOOP;
+  FOR g IN SELECT DISTINCT r.rolname FROM pg_class c CROSS JOIN LATERAL aclexplode(coalesce(c.relacl,acldefault('r',c.relowner))) a JOIN pg_roles r ON r.oid=a.grantee WHERE c.oid='public.persons'::regclass AND a.privilege_type='UPDATE' LOOP
+   EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO %I',f,g.rolname);
+  END LOOP;
+ END LOOP;
+END $$;

package/assets/migrations-pg/0123_agent_extension_versions.sql

@@ -0,0 +1,54 @@
+-- 结构升级后的停止使用扩展仍可撤销同结构批次；不修改 0122 已发布文件，不回填旧业务值。
+-- CREATE OR REPLACE 保留原函数属主与 EXECUTE ACL，固定搜索路径、锁、原审计及完整列校验保持生效。
+-- 升级前审计缺少新增列时继续拒绝恢复，不能把未知字段补造为历史事实。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+
+CREATE OR REPLACE FUNCTION public.vault_restore_extension_revert(p_extension_id text,p_submission_id text,p_key_json text,p_last_audit bigint) RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path=pg_catalog,pg_temp AS $$
+DECLARE e record; audit_row record; first_before jsonb; final_after jsonb; previous_after jsonb; key_value jsonb:=p_key_json::jsonb;
+ original_object text; current_object text; columns_now text[]; columns_audit text[]; pk_now text[]; pk_input text[];
+ chain_count integer:=0; last_id bigint; current_row jsonb; statement text; updates text; changed bigint; stamp text;
+ previous_marker text:=current_setting('vault.extension_revert',true); v_actor text:=nullif(current_setting('vault.actor',true),'');
+BEGIN
+ PERFORM public.vault_lock_extension_revert(p_extension_id,p_submission_id);
+ SELECT * INTO e FROM agent.extensions WHERE id=p_extension_id;
+ IF e.state NOT IN ('deprecated','retired') OR (e.version<1 OR (e.descriptor_json::jsonb->>'version')::integer IS DISTINCT FROM e.version) THEN RAISE EXCEPTION 'Agent 限定恢复仅用于结构兼容的已废弃或归档扩展'; END IF;
+ original_object:='agent_ext.'||(e.descriptor_json::jsonb->'domain'->>'key')||'_'||(e.descriptor_json::jsonb->>'entity');
+ current_object:=e.schema_name||'.'||e.table_name;
+ IF (e.state='deprecated' AND current_object IS DISTINCT FROM original_object)
+   OR (e.state='retired' AND current_object IS DISTINCT FROM 'agent_archive.ext_'||replace(e.id,'-',''))
+   OR NOT EXISTS(SELECT 1 FROM agent.extension_migrations m WHERE m.extension_id=e.id AND m.version=e.version AND m.checksum=e.checksum AND m.descriptor_json::jsonb=e.descriptor_json::jsonb)
+ THEN RAISE EXCEPTION 'Agent 扩展结构或位置历史不一致'; END IF;
+ IF jsonb_typeof(key_value)<>'object' OR key_value='{}'::jsonb OR EXISTS(SELECT 1 FROM jsonb_each(key_value) kv WHERE jsonb_typeof(kv.value) NOT IN ('string','number')) THEN RAISE EXCEPTION 'Agent 撤销主键无效'; END IF;
+ -- 字段名使用固定字符序比较，不能让数据库地区排序规则影响结构兼容判断。
+ SELECT array_agg(x ORDER BY x COLLATE "C") INTO pk_input FROM jsonb_object_keys(key_value) x;
+ SELECT array_agg(a.attname::text ORDER BY k.ord) INTO pk_now FROM pg_index i CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY k(attnum,ord) JOIN pg_attribute a ON a.attrelid=i.indrelid AND a.attnum=k.attnum WHERE i.indrelid=to_regclass(format('%I.%I',e.schema_name,e.table_name)) AND i.indisprimary;
+ IF pk_now IS NULL OR to_jsonb(pk_now) IS DISTINCT FROM e.descriptor_json::jsonb->'primary_key'
+   OR (SELECT array_agg(x ORDER BY x COLLATE "C") FROM unnest(pk_now) x) IS DISTINCT FROM pk_input THEN RAISE EXCEPTION 'Agent 撤销主键结构已变化'; END IF;
+ -- 新旧物理位置共同定位同一稳定对象，保持原审计文本，不按冒号拆分复合键。
+ FOR audit_row IN SELECT l.* FROM public.audit_log l WHERE l.change_set=p_submission_id AND l.primary_key_json::jsonb=key_value AND coalesce(l.object_schema,'public')||'.'||l.table_name IN (original_object,current_object) ORDER BY l.id LIMIT 4001 LOOP
+  chain_count:=chain_count+1;
+  IF audit_row.after_json IS NULL OR audit_row.actor IS DISTINCT FROM v_actor OR (chain_count>1 AND previous_after IS DISTINCT FROM audit_row.before_json::jsonb) THEN RAISE EXCEPTION 'Agent 扩展审计链不完整'; END IF;
+  IF chain_count=1 THEN first_before:=audit_row.before_json::jsonb; END IF;
+  final_after:=audit_row.after_json::jsonb; previous_after:=final_after; last_id:=audit_row.id;
+  IF NOT (key_value<@final_after) OR (audit_row.before_json IS NOT NULL AND NOT (key_value<@audit_row.before_json::jsonb)) THEN RAISE EXCEPTION 'Agent 扩展审计主键不一致'; END IF;
+ END LOOP;
+ IF chain_count=0 OR chain_count>4000 OR last_id IS DISTINCT FROM p_last_audit THEN RAISE EXCEPTION 'Agent 扩展审计末端已变化'; END IF;
+ SELECT array_agg(attname::text ORDER BY attname::text COLLATE "C") INTO columns_now FROM pg_attribute WHERE attrelid=to_regclass(format('%I.%I',e.schema_name,e.table_name)) AND attnum>0 AND NOT attisdropped;
+ SELECT array_agg(x ORDER BY x COLLATE "C") INTO columns_audit FROM jsonb_object_keys(final_after) x;
+ IF columns_now IS DISTINCT FROM columns_audit OR NOT ('deleted_at'=ANY(columns_now)) OR (first_before IS NOT NULL AND (SELECT array_agg(x ORDER BY x COLLATE "C") FROM jsonb_object_keys(first_before) x) IS DISTINCT FROM columns_now) THEN RAISE EXCEPTION 'Agent 扩展审计字段与当前结构不兼容'; END IF;
+ EXECUTE format('SELECT to_jsonb(t) FROM %I.%I t WHERE $1 <@ to_jsonb(t) FOR UPDATE',e.schema_name,e.table_name) INTO current_row USING key_value;
+ IF current_row IS DISTINCT FROM final_after OR EXISTS(SELECT 1 FROM public.audit_log l WHERE l.id>last_id AND l.primary_key_json::jsonb=key_value AND coalesce(l.object_schema,'public')||'.'||l.table_name IN (original_object,current_object)) THEN RAISE EXCEPTION 'Agent 扩展行或后续审计已变化'; END IF;
+ stamp:=to_char(clock_timestamp() AT TIME ZONE 'Asia/Shanghai','YYYY-MM-DD HH24:MI:SS');
+ IF first_before IS NULL THEN updates:='deleted_at=$2';
+ ELSE
+  SELECT string_agg(format('%1$I=(jsonb_populate_record(NULL::%2$I.%3$I,$1)).%1$I',c,e.schema_name,e.table_name),',' ORDER BY c) INTO updates
+   FROM unnest(columns_now) c WHERE NOT (c=ANY(pk_now)) AND c NOT IN ('created_at','created_by','updated_at','updated_by');
+ END IF;
+ statement:=format('UPDATE %I.%I t SET %s,updated_at=$2,updated_by=$3 WHERE $4 <@ to_jsonb(t)',e.schema_name,e.table_name,updates);
+ PERFORM set_config('vault.extension_revert',e.id,true);
+ EXECUTE statement USING first_before,stamp,v_actor,key_value;
+ GET DIAGNOSTICS changed=ROW_COUNT;
+ PERFORM set_config('vault.extension_revert',coalesce(previous_marker,''),true);
+ IF changed<>1 THEN RAISE EXCEPTION 'Agent 扩展限定恢复未命中唯一记录'; END IF;
+END $$;