Files
MikrotikManager/backend/src/db/migration-schema-inventory.ts
T

475 lines
53 KiB
TypeScript

import { createHash } from "node:crypto"
/** Read-only evidence capture. No configured pool, schema mutation, enrollment
* decision, attestation/signing or dispatcher import exists in this module. */
export interface SchemaInventoryClient { query(sql: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }> }
export interface SchemaInventoryScope { applicationNamespaces: readonly string[]; excludedControlNamespaces?: readonly string[] }
export class MigrationSchemaInventoryError extends Error { readonly code = "MIGRATION_SCHEMA_REFUSED" }
type Json = null | boolean | number | string | Json[] | { [key: string]: Json }
function fail(message: string): never { throw new MigrationSchemaInventoryError(message) }
const digest = (value: string) => createHash("sha256").update(value).digest("hex")
const acl = (value: string) => `CASE WHEN ${value} IS NULL THEN NULL ELSE ARRAY(SELECT x::text FROM pg_catalog.unnest(${value}) x ORDER BY x::text) END`
const options = (value: string) => `CASE WHEN ${value} IS NULL THEN NULL ELSE ARRAY(SELECT x FROM pg_catalog.unnest(${value}) x ORDER BY x) END`
const application = "n.nspname=ANY($1::text[])"
const rowLimit = 20000
const metadata = `pg_catalog.pg_backend_pid()::text AS backend_pid,
pg_catalog.transaction_timestamp()::text AS transaction_started,
pg_catalog.current_setting('transaction_read_only') AS read_only,
pg_catalog.current_setting('transaction_isolation') AS isolation,
pg_catalog.current_setting('search_path') AS search_path,
pg_catalog.current_setting('TimeZone') AS timezone,
pg_catalog.current_setting('DateStyle') AS date_style,
pg_catalog.current_setting('standard_conforming_strings') AS standard_strings,
pg_catalog.current_setting('server_version_num') AS server_version,
pg_catalog.current_setting('statement_timeout') AS statement_timeout`
const envelope = (section: string, sql: string, limit = rowLimit) => `/* migration-schema:${section} */ WITH captured AS MATERIALIZED (${sql} LIMIT ${limit + 1}) SELECT ${metadata},
CASE WHEN (SELECT count(*)>${limit} OR COALESCE(max(pg_catalog.octet_length(pg_catalog.to_jsonb(captured)::text)),0)>1048576 OR COALESCE(sum(pg_catalog.octet_length(pg_catalog.to_jsonb(captured)::text)),0)>33554432 FROM captured)
THEN NULL ELSE COALESCE((SELECT pg_catalog.jsonb_agg(pg_catalog.to_jsonb(captured)) FROM captured),'[]'::jsonb) END AS objects`
const unsupportedEventTriggers = "UNION ALL SELECT 'event-trigger',e.evtname FROM pg_catalog.pg_event_trigger e"
const controlEventTriggersSql = envelope("control-event-triggers", `SELECT e.evtname AS name, e.evtevent AS event,
pg_catalog.pg_get_userbyid(e.evtowner) AS owner, e.evtenabled::text AS enabled,
${options("e.evttags")} AS tags, pg_catalog.obj_description(e.oid, 'pg_event_trigger') AS comment,
n.nspname AS function_namespace, p.proname AS function_name,
pg_catalog.pg_get_function_identity_arguments(p.oid) AS function_arguments
FROM pg_catalog.pg_event_trigger e
JOIN pg_catalog.pg_proc p ON p.oid=e.evtfoid
JOIN pg_catalog.pg_namespace n ON n.oid=p.pronamespace`, 1024)
/** Fixed catalog contract: only SELECTs, only namespace names as bound values.
* LIMIT+1 overflow refuses; nothing is silently truncated or normalized away.
* Caller configures one checked-out PG18 repeatable-read READ ONLY transaction
* with search_path=pg_catalog, TimeZone=UTC, DateStyle='ISO, YMD', bounded
* statement_timeout before capture. Capture never SETs/BEGINs/COMMITs for it. */
export const MIGRATION_SCHEMA_QUERIES = Object.freeze({
database: envelope("database", `SELECT pg_catalog.pg_encoding_to_char(d.encoding) AS encoding,d.datcollate AS collate,d.datctype AS ctype,
d.datlocprovider::text AS locale_provider,pg_catalog.to_jsonb(d)->>'datlocale' AS locale,pg_catalog.to_jsonb(d)->>'daticurules' AS locale_rules,d.datcollversion AS collation_version,
ts.spcname AS default_tablespace,pg_catalog.shobj_description(d.oid,'pg_database') AS comment,
pg_catalog.pg_get_userbyid(d.datdba) AS owner,${acl("d.datacl")} AS acl FROM pg_catalog.pg_database d JOIN pg_catalog.pg_tablespace ts ON ts.oid=d.dattablespace WHERE d.datname=pg_catalog.current_database()`),
namespaces: envelope("namespaces", `SELECT n.nspname AS namespace,pg_catalog.pg_get_userbyid(n.nspowner) AS owner,${acl("n.nspacl")} AS acl,pg_catalog.obj_description(n.oid,'pg_namespace') AS comment
FROM pg_catalog.pg_namespace n WHERE n.nspname !~ '^pg_' AND n.nspname<>'information_schema'`),
relations: envelope("relations", `SELECT n.nspname AS namespace,c.relname AS name,c.relkind::text AS kind,c.relpersistence::text AS persistence,
pg_catalog.pg_get_userbyid(c.relowner) AS owner,${acl("c.relacl")} AS acl,${options("c.reloptions")} AS options,pg_catalog.obj_description(c.oid,'pg_class') AS comment,
am.amname AS access_method,t.spcname AS tablespace,${options("toast.reloptions")} AS toast_options,
CASE WHEN c.reloftype=0 THEN NULL ELSE pg_catalog.format_type(c.reloftype,NULL) END AS of_type,
c.relrowsecurity AS row_security,c.relforcerowsecurity AS force_row_security,
c.relreplident::text AS replica_identity,c.relispartition AS is_partition,c.relispopulated AS populated,
CASE WHEN c.relkind='p' THEN pg_catalog.pg_get_partkeydef(c.oid) ELSE NULL END AS partition_key,
CASE WHEN c.relispartition THEN pg_catalog.pg_get_expr(c.relpartbound,c.oid,false) ELSE NULL END AS partition_bound
FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace
LEFT JOIN pg_catalog.pg_am am ON am.oid=c.relam LEFT JOIN pg_catalog.pg_tablespace t ON t.oid=c.reltablespace LEFT JOIN pg_catalog.pg_class toast ON toast.oid=c.reltoastrelid WHERE ${application}`),
columns: envelope("columns", `SELECT n.nspname AS namespace,c.relname AS relation,a.attnum::int AS position,a.attname AS name,a.attisdropped AS dropped,
CASE WHEN a.atttypid=0 THEN NULL ELSE pg_catalog.format_type(a.atttypid,a.atttypmod) END AS type,a.atttypmod AS type_modifier,
a.attndims::int AS dimensions,a.attnotnull AS not_null,a.attidentity::text AS identity,a.attgenerated::text AS generated,
a.attstorage::text AS storage,a.attcompression::text AS compression,a.attstattarget::int AS statistics_target,
a.atthasmissing AS has_missing,a.attmissingval::text AS missing_value,${acl("a.attacl")} AS acl,${options("a.attoptions")} AS options,pg_catalog.col_description(c.oid,a.attnum) AS comment,
CASE WHEN co.oid IS NULL THEN NULL ELSE cn.nspname||'.'||co.collname END AS collation,
pg_catalog.pg_get_expr(ad.adbin,ad.adrelid,false) AS default_expression,a.attislocal AS is_local,a.attinhcount::int AS inherited_count
FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid=a.attrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace
LEFT JOIN pg_catalog.pg_attrdef ad ON ad.adrelid=a.attrelid AND ad.adnum=a.attnum
LEFT JOIN pg_catalog.pg_collation co ON co.oid=a.attcollation LEFT JOIN pg_catalog.pg_namespace cn ON cn.oid=co.collnamespace
WHERE ${application} AND a.attnum>0`, 100000),
constraints: envelope("constraints", `SELECT n.nspname AS namespace,c.conname AS name,r.relname AS relation,t.typname AS domain,c.contype::text AS kind,
c.condeferrable AS deferrable,c.condeferred AS deferred,c.convalidated AS validated,c.conislocal AS is_local,c.coninhcount::int AS inherited_count,pg_catalog.obj_description(c.oid,'pg_constraint') AS comment,
c.connoinherit AS no_inherit,pg_catalog.to_jsonb(c)->'conenforced' AS enforced,pg_catalog.to_jsonb(c)->'conperiod' AS period,pg_catalog.pg_get_constraintdef(c.oid,false) AS definition,
CASE WHEN c.contype='c' THEN pg_catalog.pg_get_constraintdef(c.oid,true) ELSE NULL END AS restore_definition,
pn.nspname AS parent_namespace,pr.relname AS parent_relation,pc.conname AS parent_constraint,
fn.nspname AS foreign_namespace,fr.relname AS foreign_relation
FROM pg_catalog.pg_constraint c JOIN pg_catalog.pg_namespace n ON n.oid=c.connamespace
LEFT JOIN pg_catalog.pg_class r ON r.oid=c.conrelid LEFT JOIN pg_catalog.pg_type t ON t.oid=c.contypid
LEFT JOIN pg_catalog.pg_constraint pc ON pc.oid=c.conparentid LEFT JOIN pg_catalog.pg_class pr ON pr.oid=pc.conrelid LEFT JOIN pg_catalog.pg_namespace pn ON pn.oid=pr.relnamespace
LEFT JOIN pg_catalog.pg_class fr ON fr.oid=c.confrelid LEFT JOIN pg_catalog.pg_namespace fn ON fn.oid=fr.relnamespace WHERE ${application}`),
indexes: envelope("indexes", `SELECT n.nspname AS namespace,ic.relname AS name,tc.relname AS relation,
pg_catalog.pg_get_indexdef(i.indexrelid) AS definition,i.indisunique AS unique_index,i.indisprimary AS primary_index,
i.indisexclusion AS exclusion,i.indimmediate AS immediate,i.indisclustered AS clustered,i.indisvalid AS valid,i.indisready AS ready,i.indislive AS live,
i.indisreplident AS replica_identity,i.indcheckxmin AS check_xmin,i.indnullsnotdistinct AS nulls_not_distinct,i.indnatts::int AS attributes,i.indnkeyatts::int AS key_attributes,
ARRAY(SELECT onsp.nspname||'.'||op.opcname FROM pg_catalog.unnest(i.indclass) WITH ORDINALITY x(opid,pos) JOIN pg_catalog.pg_opclass op ON op.oid=x.opid JOIN pg_catalog.pg_namespace onsp ON onsp.oid=op.opcnamespace ORDER BY x.pos) AS operator_classes,
ARRAY(SELECT COALESCE(cn.nspname||'.'||co.collname,'<none>') FROM pg_catalog.unnest(i.indcollation) WITH ORDINALITY x(colid,pos) LEFT JOIN pg_catalog.pg_collation co ON co.oid=x.colid LEFT JOIN pg_catalog.pg_namespace cn ON cn.oid=co.collnamespace ORDER BY x.pos) AS collations,
i.indkey::text AS keys,i.indoption::text AS key_options,pg_catalog.pg_get_expr(i.indexprs,i.indrelid,false) AS expressions,pg_catalog.pg_get_expr(i.indpred,i.indrelid,false) AS predicate
FROM pg_catalog.pg_index i JOIN pg_catalog.pg_class ic ON ic.oid=i.indexrelid JOIN pg_catalog.pg_namespace n ON n.oid=ic.relnamespace
JOIN pg_catalog.pg_class tc ON tc.oid=i.indrelid WHERE ${application}`),
inheritance: envelope("inheritance", `SELECT n.nspname AS namespace,c.relname AS child,pn.nspname AS parent_namespace,p.relname AS parent,i.inhseqno::int AS position,i.inhdetachpending AS detach_pending
FROM pg_catalog.pg_inherits i JOIN pg_catalog.pg_class c ON c.oid=i.inhrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace
JOIN pg_catalog.pg_class p ON p.oid=i.inhparent JOIN pg_catalog.pg_namespace pn ON pn.oid=p.relnamespace WHERE ${application}`),
sequences: envelope("sequences", `SELECT n.nspname AS namespace,c.relname AS name,pg_catalog.format_type(s.seqtypid,NULL) AS type,
s.seqstart::text AS start,s.seqincrement::text AS increment,s.seqmax::text AS maximum,s.seqmin::text AS minimum,s.seqcache::text AS cache,s.seqcycle AS cycle,
own.namespace AS owner_namespace,own.relation AS owner_relation,own.column_name AS owner_column,own.dependency AS owner_dependency
FROM pg_catalog.pg_sequence s JOIN pg_catalog.pg_class c ON c.oid=s.seqrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace
LEFT JOIN LATERAL (SELECT rn.nspname AS namespace,r.relname AS relation,a.attname AS column_name,d.deptype::text AS dependency
FROM pg_catalog.pg_depend d JOIN pg_catalog.pg_class r ON r.oid=d.refobjid JOIN pg_catalog.pg_namespace rn ON rn.oid=r.relnamespace
JOIN pg_catalog.pg_attribute a ON a.attrelid=r.oid AND a.attnum=d.refobjsubid
WHERE d.classid='pg_catalog.pg_class'::regclass AND d.objid=c.oid AND d.refclassid='pg_catalog.pg_class'::regclass AND d.deptype IN ('a','i')) own ON true
WHERE ${application}`),
views: envelope("views", `SELECT n.nspname AS namespace,c.relname AS name,c.relkind::text AS kind,pg_catalog.pg_get_viewdef(c.oid,false) AS definition
FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE ${application} AND c.relkind IN ('v','m')`),
types: envelope("types", `SELECT n.nspname AS namespace,t.typname AS name,t.typtype::text AS kind,t.typcategory::text AS category,
pg_catalog.pg_get_userbyid(t.typowner) AS owner,${acl("t.typacl")} AS acl,pg_catalog.obj_description(t.oid,'pg_type') AS comment,t.typlen::int AS length,t.typbyval AS by_value,t.typalign::text AS alignment,t.typstorage::text AS storage,
t.typnotnull AS not_null,t.typispreferred AS preferred,t.typisdefined AS defined,t.typdelim::text AS delimiter,t.typndims::int AS dimensions,
t.typinput::regprocedure::text AS input_function,t.typoutput::regprocedure::text AS output_function,t.typreceive::regprocedure::text AS receive_function,t.typsend::regprocedure::text AS send_function,
t.typmodin::regprocedure::text AS modifier_input,t.typmodout::regprocedure::text AS modifier_output,t.typanalyze::regprocedure::text AS analyze_function,t.typsubscript::regprocedure::text AS subscript_function,
CASE WHEN t.typbasetype=0 THEN NULL ELSE pg_catalog.format_type(t.typbasetype,t.typtypmod) END AS base_type,
CASE WHEN t.typelem=0 THEN NULL ELSE pg_catalog.format_type(t.typelem,NULL) END AS element_type,
rn.nspname AS relation_namespace,r.relname AS relation,pg_catalog.pg_get_expr(t.typdefaultbin,0,false) AS default_expression,t.typdefault AS default_literal,
CASE WHEN co.oid IS NULL THEN NULL ELSE cn.nspname||'.'||co.collname END AS collation,
COALESCE((SELECT pg_catalog.jsonb_agg(e.enumlabel ORDER BY e.enumsortorder) FROM pg_catalog.pg_enum e WHERE e.enumtypid=t.oid),'[]'::jsonb) AS enum_labels,
CASE WHEN rg.rngtypid IS NULL THEN NULL ELSE pg_catalog.jsonb_build_object('subtype',pg_catalog.format_type(rg.rngsubtype,NULL),'multirange',pg_catalog.format_type(rg.rngmultitypid,NULL),'canonical',rg.rngcanonical::regprocedure::text,'subdiff',rg.rngsubdiff::regprocedure::text,'opclass',opn.nspname||'.'||op.opcname,'collation',rcn.nspname||'.'||rc.collname) END AS range_definition
FROM pg_catalog.pg_type t JOIN pg_catalog.pg_namespace n ON n.oid=t.typnamespace
LEFT JOIN pg_catalog.pg_class r ON r.oid=t.typrelid LEFT JOIN pg_catalog.pg_namespace rn ON rn.oid=r.relnamespace
LEFT JOIN pg_catalog.pg_collation co ON co.oid=t.typcollation LEFT JOIN pg_catalog.pg_namespace cn ON cn.oid=co.collnamespace
LEFT JOIN pg_catalog.pg_range rg ON rg.rngtypid=t.oid OR rg.rngmultitypid=t.oid LEFT JOIN pg_catalog.pg_opclass op ON op.oid=rg.rngsubopc LEFT JOIN pg_catalog.pg_namespace opn ON opn.oid=op.opcnamespace
LEFT JOIN pg_catalog.pg_collation rc ON rc.oid=rg.rngcollation LEFT JOIN pg_catalog.pg_namespace rcn ON rcn.oid=rc.collnamespace WHERE ${application}`),
functions: envelope("functions", `SELECT n.nspname AS namespace,p.proname AS name,pg_catalog.pg_get_function_identity_arguments(p.oid) AS arguments,p.prokind::text AS kind,
l.lanname AS language,pg_catalog.pg_get_userbyid(p.proowner) AS owner,${acl("p.proacl")} AS acl,pg_catalog.obj_description(p.oid,'pg_proc') AS comment,
CASE WHEN p.prokind='f' THEN pg_catalog.pg_get_functiondef(p.oid) ELSE NULL END AS definition,p.probin AS external_library,
p.prosecdef AS security_definer,p.proleakproof AS leakproof,p.proisstrict AS strict,p.provolatile::text AS volatility,p.proparallel::text AS parallel,
p.procost::text AS cost,p.prorows::text AS rows,p.prosupport::regprocedure::text AS support,${options("p.proconfig")} AS configuration
FROM pg_catalog.pg_proc p JOIN pg_catalog.pg_namespace n ON n.oid=p.pronamespace JOIN pg_catalog.pg_language l ON l.oid=p.prolang WHERE ${application}`),
triggers: envelope("triggers", `SELECT n.nspname AS namespace,c.relname AS relation,
CASE WHEN t.tgisinternal THEN 'constraint:'||COALESCE(tcon.conname,'')||':'||fn.nspname||'.'||p.proname||':'||t.tgtype::text ELSE t.tgname END AS name,
t.tgisinternal AS internal,t.tgenabled::text AS enabled,t.tgtype::int AS type,pg_catalog.obj_description(t.oid,'pg_trigger') AS comment,
CASE WHEN t.tgisinternal THEN pg_catalog.replace(pg_catalog.pg_get_triggerdef(t.oid,false),pg_catalog.format('CREATE CONSTRAINT TRIGGER %I',t.tgname),'CREATE CONSTRAINT TRIGGER <internal>') ELSE pg_catalog.pg_get_triggerdef(t.oid,false) END AS definition,
fn.nspname AS function_namespace,p.proname AS function_name,pg_catalog.pg_get_function_identity_arguments(p.oid) AS function_arguments,
pg_catalog.encode(t.tgargs,'hex') AS arguments,CASE WHEN t.tgqual IS NULL THEN NULL ELSE pg_catalog.pg_get_triggerdef(t.oid,false) END AS condition,
t.tgdeferrable AS deferrable,t.tginitdeferred AS initially_deferred,t.tgoldtable AS old_table,t.tgnewtable AS new_table,
pc.relname AS parent_relation,
CASE WHEN pt.tgisinternal THEN 'constraint:'||COALESCE(pcon.conname,'')||':'||pfn.nspname||'.'||pf.proname||':'||pt.tgtype::text ELSE pt.tgname END AS parent_trigger,
tcon.conname AS constraint_name
FROM pg_catalog.pg_trigger t JOIN pg_catalog.pg_class c ON c.oid=t.tgrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace
JOIN pg_catalog.pg_proc p ON p.oid=t.tgfoid JOIN pg_catalog.pg_namespace fn ON fn.oid=p.pronamespace
LEFT JOIN pg_catalog.pg_constraint tcon ON tcon.oid=t.tgconstraint
LEFT JOIN pg_catalog.pg_trigger pt ON pt.oid=t.tgparentid LEFT JOIN pg_catalog.pg_class pc ON pc.oid=pt.tgrelid
LEFT JOIN pg_catalog.pg_proc pf ON pf.oid=pt.tgfoid LEFT JOIN pg_catalog.pg_namespace pfn ON pfn.oid=pf.pronamespace LEFT JOIN pg_catalog.pg_constraint pcon ON pcon.oid=pt.tgconstraint WHERE ${application}`),
unsupported: envelope("unsupported", `SELECT 'extension' AS kind,e.extname AS identity FROM pg_catalog.pg_extension e WHERE e.extname<>'plpgsql'
UNION ALL SELECT 'unsafe-type-io',n.nspname||'.'||t.typname FROM pg_catalog.pg_type t JOIN pg_catalog.pg_namespace n ON n.oid=t.typnamespace
LEFT JOIN pg_catalog.pg_proc ip ON ip.oid=t.typinput LEFT JOIN pg_catalog.pg_namespace ins ON ins.oid=ip.pronamespace
LEFT JOIN pg_catalog.pg_proc op ON op.oid=t.typoutput LEFT JOIN pg_catalog.pg_namespace ons ON ons.oid=op.pronamespace
WHERE ${application} AND (t.typtype NOT IN ('c','d','e','r','m') AND NOT(t.typtype='b' AND t.typcategory='A' AND t.typelem<>0 AND ip.proname='array_in' AND op.proname='array_out') OR ins.nspname IS DISTINCT FROM 'pg_catalog' OR ons.nspname IS DISTINCT FROM 'pg_catalog')
UNION ALL SELECT 'unsupported-routine',n.nspname||'.'||p.proname FROM pg_catalog.pg_proc p JOIN pg_catalog.pg_namespace n ON n.oid=p.pronamespace JOIN pg_catalog.pg_language l ON l.oid=p.prolang WHERE ${application} AND (p.prokind<>'f' OR l.lanname NOT IN ('sql','plpgsql') OR p.probin IS NOT NULL)
UNION ALL SELECT 'unsupported-relation',n.nspname||'.'||c.relname FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace LEFT JOIN pg_catalog.pg_am am ON am.oid=c.relam WHERE ${application} AND (c.relkind NOT IN ('r','p','i','I','S','v','m','c') OR c.relpersistence NOT IN ('p','u') OR am.amname IS NOT NULL AND am.amname NOT IN ('heap','btree','hash','gist','gin','spgist','brin'))
${unsupportedEventTriggers}
UNION ALL SELECT 'publication',p.pubname FROM pg_catalog.pg_publication p
UNION ALL SELECT 'subscription',s.subname FROM pg_catalog.pg_subscription s
UNION ALL SELECT 'policy',n.nspname||'.'||c.relname||'.'||p.polname FROM pg_catalog.pg_policy p JOIN pg_catalog.pg_class c ON c.oid=p.polrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE ${application}
UNION ALL SELECT 'rewrite-rule',n.nspname||'.'||c.relname||'.'||r.rulename FROM pg_catalog.pg_rewrite r JOIN pg_catalog.pg_class c ON c.oid=r.ev_class JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE ${application} AND r.rulename<>'_RETURN'
UNION ALL SELECT 'foreign-table',n.nspname||'.'||c.relname FROM pg_catalog.pg_foreign_table f JOIN pg_catalog.pg_class c ON c.oid=f.ftrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE ${application}
UNION ALL SELECT 'extended-statistics',n.nspname||'.'||s.stxname FROM pg_catalog.pg_statistic_ext s JOIN pg_catalog.pg_namespace n ON n.oid=s.stxnamespace WHERE ${application}
UNION ALL SELECT 'collation',n.nspname||'.'||c.collname FROM pg_catalog.pg_collation c JOIN pg_catalog.pg_namespace n ON n.oid=c.collnamespace WHERE ${application}
UNION ALL SELECT 'conversion',n.nspname||'.'||c.conname FROM pg_catalog.pg_conversion c JOIN pg_catalog.pg_namespace n ON n.oid=c.connamespace WHERE ${application}
UNION ALL SELECT 'operator',n.nspname||'.'||o.oprname FROM pg_catalog.pg_operator o JOIN pg_catalog.pg_namespace n ON n.oid=o.oprnamespace WHERE ${application}
UNION ALL SELECT 'operator-class',n.nspname||'.'||o.opcname FROM pg_catalog.pg_opclass o JOIN pg_catalog.pg_namespace n ON n.oid=o.opcnamespace WHERE ${application}
UNION ALL SELECT 'operator-family',n.nspname||'.'||o.opfname FROM pg_catalog.pg_opfamily o JOIN pg_catalog.pg_namespace n ON n.oid=o.opfnamespace WHERE ${application}
UNION ALL SELECT 'text-search-configuration',n.nspname||'.'||o.cfgname FROM pg_catalog.pg_ts_config o JOIN pg_catalog.pg_namespace n ON n.oid=o.cfgnamespace WHERE ${application}
UNION ALL SELECT 'text-search-dictionary',n.nspname||'.'||o.dictname FROM pg_catalog.pg_ts_dict o JOIN pg_catalog.pg_namespace n ON n.oid=o.dictnamespace WHERE ${application}
UNION ALL SELECT 'text-search-parser',n.nspname||'.'||o.prsname FROM pg_catalog.pg_ts_parser o JOIN pg_catalog.pg_namespace n ON n.oid=o.prsnamespace WHERE ${application}
UNION ALL SELECT 'text-search-template',n.nspname||'.'||o.tmplname FROM pg_catalog.pg_ts_template o JOIN pg_catalog.pg_namespace n ON n.oid=o.tmplnamespace WHERE ${application}
UNION ALL SELECT 'default-acl',COALESCE(n.nspname,'global')||':'||a.defaclobjtype::text FROM pg_catalog.pg_default_acl a LEFT JOIN pg_catalog.pg_namespace n ON n.oid=a.defaclnamespace WHERE a.defaclnamespace=0 OR ${application}
UNION ALL SELECT 'security-label',s.provider||':'||s.classoid::regclass::text FROM pg_catalog.pg_seclabel s
UNION ALL SELECT 'shared-security-label',s.provider||':'||s.classoid::regclass::text FROM pg_catalog.pg_shseclabel s
UNION ALL SELECT 'transform',t.trftype::regtype::text FROM pg_catalog.pg_transform t
UNION ALL SELECT 'cast',s.typname||'->'||t.typname FROM pg_catalog.pg_cast c JOIN pg_catalog.pg_type s ON s.oid=c.castsource JOIN pg_catalog.pg_namespace sn ON sn.oid=s.typnamespace JOIN pg_catalog.pg_type t ON t.oid=c.casttarget JOIN pg_catalog.pg_namespace tn ON tn.oid=t.typnamespace WHERE sn.nspname=ANY($1::text[]) OR tn.nspname=ANY($1::text[])
UNION ALL SELECT 'foreign-wrapper',f.fdwname FROM pg_catalog.pg_foreign_data_wrapper f
UNION ALL SELECT 'foreign-server',s.srvname FROM pg_catalog.pg_foreign_server s
UNION ALL SELECT 'large-object',m.oid::text FROM pg_catalog.pg_largeobject_metadata m
UNION ALL SELECT 'external-schema-dependency',i.identity FROM pg_catalog.pg_depend d CROSS JOIN LATERAL pg_catalog.pg_identify_object(d.refclassid,d.refobjid,d.refobjsubid) i
WHERE i.schema IS NOT NULL AND i.schema !~ '^pg_' AND i.schema<>'information_schema' AND NOT(i.schema=ANY($1::text[])) AND (
d.classid='pg_catalog.pg_class'::regclass AND EXISTS(SELECT 1 FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE c.oid=d.objid AND ${application})
OR d.classid='pg_catalog.pg_proc'::regclass AND EXISTS(SELECT 1 FROM pg_catalog.pg_proc p JOIN pg_catalog.pg_namespace n ON n.oid=p.pronamespace WHERE p.oid=d.objid AND ${application})
OR d.classid='pg_catalog.pg_type'::regclass AND EXISTS(SELECT 1 FROM pg_catalog.pg_type t JOIN pg_catalog.pg_namespace n ON n.oid=t.typnamespace WHERE t.oid=d.objid AND ${application})
OR d.classid='pg_catalog.pg_rewrite'::regclass AND EXISTS(SELECT 1 FROM pg_catalog.pg_rewrite r JOIN pg_catalog.pg_class c ON c.oid=r.ev_class JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE r.oid=d.objid AND ${application})
OR d.classid='pg_catalog.pg_constraint'::regclass AND EXISTS(SELECT 1 FROM pg_catalog.pg_constraint c JOIN pg_catalog.pg_namespace n ON n.oid=c.connamespace WHERE c.oid=d.objid AND ${application})
OR d.classid='pg_catalog.pg_trigger'::regclass AND EXISTS(SELECT 1 FROM pg_catalog.pg_trigger t JOIN pg_catalog.pg_class c ON c.oid=t.tgrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE t.oid=d.objid AND ${application})
OR d.classid='pg_catalog.pg_attrdef'::regclass AND EXISTS(SELECT 1 FROM pg_catalog.pg_attrdef a JOIN pg_catalog.pg_class c ON c.oid=a.adrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE a.oid=d.objid AND ${application}))`),
})
export type SchemaSection = keyof typeof MIGRATION_SCHEMA_QUERIES
/** Bind contract belongs to each fixed query, including the two global census
* queries that intentionally have no namespace placeholder. */
export const MIGRATION_SCHEMA_PARAMETERS = Object.freeze({
database: "none", namespaces: "none",
relations: "application-namespaces", columns: "application-namespaces",
constraints: "application-namespaces", indexes: "application-namespaces",
inheritance: "application-namespaces", sequences: "application-namespaces",
views: "application-namespaces", types: "application-namespaces",
functions: "application-namespaces", triggers: "application-namespaces",
unsupported: "application-namespaces",
} satisfies Record<SchemaSection, "none" | "application-namespaces">)
// Preflight only names/catalog flags before any expression/default deparser:
// unknown custom type output routines must never be invoked just to inspect a
// constant. Caller must separately quiesce concurrent DDL for stable evidence.
const sections: SchemaSection[] = ["database", "namespaces", "unsupported", ...(Object.keys(MIGRATION_SCHEMA_QUERIES) as SchemaSection[]).filter(section => !["database", "namespaces", "unsupported"].includes(section))]
const keys: Record<SchemaSection, string> = {
database: "encoding collate ctype locale_provider locale locale_rules collation_version default_tablespace comment owner acl",
namespaces: "namespace owner acl comment",
relations: "namespace name kind persistence owner acl options comment access_method tablespace toast_options of_type row_security force_row_security replica_identity is_partition populated partition_key partition_bound",
columns: "namespace relation position name dropped type type_modifier dimensions not_null identity generated storage compression statistics_target has_missing missing_value acl options comment collation default_expression is_local inherited_count",
constraints: "namespace name relation domain kind deferrable deferred validated is_local inherited_count comment no_inherit enforced period definition restore_definition parent_namespace parent_relation parent_constraint foreign_namespace foreign_relation",
indexes: "namespace name relation definition unique_index primary_index exclusion immediate clustered valid ready live replica_identity check_xmin nulls_not_distinct attributes key_attributes keys key_options operator_classes collations expressions predicate",
inheritance: "namespace child parent_namespace parent position detach_pending",
sequences: "namespace name type start increment maximum minimum cache cycle owner_namespace owner_relation owner_column owner_dependency",
views: "namespace name kind definition",
types: "namespace name kind category owner acl comment length by_value alignment storage not_null preferred defined delimiter dimensions input_function output_function receive_function send_function modifier_input modifier_output analyze_function subscript_function base_type element_type relation_namespace relation default_expression default_literal collation enum_labels range_definition",
functions: "namespace name arguments kind language owner acl comment definition external_library security_definer leakproof strict volatility parallel cost rows support configuration",
triggers: "namespace relation name internal enabled type comment definition function_namespace function_name function_arguments arguments condition deferrable initially_deferred old_table new_table parent_relation parent_trigger constraint_name",
unsupported: "kind identity",
}
function canonical(value: unknown, depth = 0): Json {
if (depth > 12) fail("Catalog JSON depth exceeds bound")
if (value === null || typeof value === "boolean") return value
if (typeof value === "number") { if (!Number.isSafeInteger(value)) fail("Nonintegral/unsafe catalog number"); return value }
if (typeof value === "string") { if (Buffer.byteLength(value) > 1048576 || value.includes("\0")) fail("Catalog string exceeds bound"); return value }
if (Array.isArray(value)) { if (value.length > 100001) fail("Catalog array exceeds bound"); return value.map(item => canonical(item, depth + 1)) }
if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype || Object.keys(value).length > 100) fail("Invalid catalog JSON value")
return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(Reflect.get(value, key), depth + 1)]))
}
function scopeValue(scope: SchemaInventoryScope) {
if (!scope || !Array.isArray(scope.applicationNamespaces) || scope.excludedControlNamespaces !== undefined && !Array.isArray(scope.excludedControlNamespaces)) fail("Missing exact schema scope")
const app = [...scope.applicationNamespaces].sort(), control = [...scope.excludedControlNamespaces ?? []].sort()
if (!app.length || app.length + control.length > 16 || new Set([...app, ...control]).size !== app.length + control.length || [...app, ...control].some(name => !/^[A-Za-z_][A-Za-z_0-9]{0,62}$/.test(name) || /^pg_/i.test(name) || name === "information_schema")) fail("Invalid exact schema scope")
return { applicationNamespaces: app, excludedControlNamespaces: control }
}
function session(row: Record<string, unknown>) {
const expected = "backend_pid transaction_started read_only isolation search_path timezone date_style standard_strings server_version statement_timeout objects".split(" ").sort()
if (JSON.stringify(Object.keys(row).sort()) !== JSON.stringify(expected)) fail("Unexpected catalog envelope")
if (typeof row.backend_pid !== "string" || !/^\d+$/.test(row.backend_pid) || typeof row.transaction_started !== "string" || !Number.isFinite(Date.parse(row.transaction_started)) || row.read_only !== "on" || !["repeatable read", "serializable"].includes(String(row.isolation)) || row.search_path !== "pg_catalog" || row.timezone !== "UTC" || row.date_style !== "ISO, YMD" || row.standard_strings !== "on" || typeof row.server_version !== "string" || !/^18\d{4}$/.test(row.server_version)) fail("PG18 fixed-context checked-out readonly snapshot required")
const timeout = /^(\d+(?:\.\d+)?)(ms|s|min)?$/.exec(String(row.statement_timeout))
const millis = timeout ? Number(timeout[1]) * ({ ms: 1, s: 1000, min: 60000 }[timeout[2] ?? "ms"] ?? 0) : 0
if (millis < 1 || millis > 10000) fail("Bounded read-only statement timeout required")
return JSON.stringify(Object.fromEntries(expected.filter(key => key !== "objects").map(key => [key, row[key]])))
}
function rowsFor(section: SchemaSection, raw: unknown) {
if (!Array.isArray(raw) || raw.length > (section === "columns" ? 100000 : rowLimit)) fail("Catalog section overflow: " + section)
const expected = keys[section].split(" ").sort()
const rows = raw.map(value => {
if (!value || typeof value !== "object" || Array.isArray(value) || JSON.stringify(Object.keys(value).sort()) !== JSON.stringify(expected)) fail("Unknown catalog row shape: " + section)
const row = canonical(value) as Record<string, Json>
const booleans = new Set("row_security force_row_security is_partition populated dropped not_null has_missing is_local deferrable deferred validated no_inherit enforced period unique_index primary_index exclusion immediate clustered valid ready live check_xmin nulls_not_distinct detach_pending cycle by_value preferred defined security_definer leakproof strict internal initially_deferred".split(" "))
const numbers = new Set("position type_modifier dimensions statistics_target inherited_count attributes key_attributes length".split(" "))
for (const [field, item] of Object.entries(row)) {
if (booleans.has(field) || field === "replica_identity" && section === "indexes") { if (typeof item !== "boolean") fail("Invalid catalog boolean: " + section + "." + field) }
// PG18 pg_attribute.attstattarget is nullable int2: NULL means system
// default, while 0 disables statistics. Preserve that distinction.
else if (section === "columns" && field === "statistics_target") { if (item !== null && typeof item !== "number") fail("Invalid catalog integer: " + section + "." + field) }
else if (numbers.has(field) || field === "type" && section === "triggers") { if (typeof item !== "number") fail("Invalid catalog integer: " + section + "." + field) }
else if (["acl", "options", "toast_options", "configuration", "enum_labels", "operator_classes", "collations"].includes(field)) { if (item !== null && (!Array.isArray(item) || item.some(value => typeof value !== "string"))) fail("Invalid catalog string array") }
else if (field === "range_definition") { if (item !== null && (!item || Array.isArray(item) || typeof item !== "object" || JSON.stringify(Object.keys(item).sort()) !== JSON.stringify(["canonical", "collation", "multirange", "opclass", "subdiff", "subtype"]) || Object.values(item).some(value => value !== null && typeof value !== "string"))) fail("Invalid range definition") }
else if (item !== null && typeof item !== "string") fail("Invalid catalog scalar: " + section + "." + field)
}
for (const field of ["namespace", "name"]) if (field in row && (typeof row[field] !== "string" || !row[field])) fail("Missing catalog object identity")
for (const field of ["acl", "options", "toast_options", "configuration"]) if (Array.isArray(row[field])) {
const values = row[field] as string[]
if (new Set(values.map(value => field === "acl" ? value : value.split("=", 1)[0])).size !== values.length) fail("Duplicate unordered catalog option")
row[field] = [...values].sort()
}
return row
})
const serialized = rows.map(row => JSON.stringify(row)).sort()
if (new Set(serialized).size !== serialized.length) fail("Duplicate catalog row: " + section)
return serialized.map(value => JSON.parse(value) as Record<string, Json>)
}
function validateSemantics(data: Record<SchemaSection, Record<string, Json>[]>, scope: ReturnType<typeof scopeValue>) {
if (data.database.length !== 1 || data.unsupported.length) fail("Unsupported database/schema object class")
if (!["b", "c", "i"].includes(String(data.database[0].locale_provider))) fail("Unknown database locale provider")
const namespaces = data.namespaces.map(row => row.namespace).sort()
if (JSON.stringify(namespaces) !== JSON.stringify([...scope.applicationNamespaces, ...scope.excludedControlNamespaces].sort())) fail("Unexpected or missing application/control namespace")
for (const section of sections.filter(section => !["database", "namespaces", "unsupported"].includes(section))) for (const row of data[section]) if (!scope.applicationNamespaces.includes(String(row.namespace))) fail("Catalog row escaped exact namespace scope")
for (const row of data.relations) if (!["r", "p", "i", "I", "S", "v", "m", "c"].includes(String(row.kind)) || !["p", "u"].includes(String(row.persistence)) || !["d", "n", "f", "i"].includes(String(row.replica_identity)) || row.access_method !== null && !["heap", "btree", "hash", "gist", "gin", "spgist", "brin"].includes(String(row.access_method))) fail("Unsupported relation or access method")
for (const row of data.types) if (!["c", "d", "e", "r", "m"].includes(String(row.kind)) && !(row.kind === "b" && row.category === "A" && typeof row.element_type === "string")) fail("Unsupported user base/pseudo type semantics")
for (const row of data.types) if (row.defined !== true || row.kind === "d" && typeof row.base_type !== "string" || ["r", "m"].includes(String(row.kind)) && row.range_definition === null || row.kind === "c" && (row.relation_namespace !== row.namespace || typeof row.relation !== "string")) fail("Incomplete user type semantics")
for (const row of data.functions) if (row.kind !== "f" || !["sql", "plpgsql"].includes(String(row.language)) || !["i", "s", "v"].includes(String(row.volatility)) || !["u", "r", "s"].includes(String(row.parallel)) || typeof row.definition !== "string" || row.external_library !== null) fail("Unsupported procedure/aggregate/window/external function semantics")
for (const row of data.columns) if (!Number.isSafeInteger(row.position) || Number(row.position) < 1 || !["", "a", "d"].includes(String(row.identity)) || !["", "s", "v"].includes(String(row.generated))) fail("Unsupported column semantics")
for (const row of data.columns) if (row.has_missing ? typeof row.missing_value !== "string" : row.missing_value !== null) fail("Invalid fast-default physical metadata")
for (const row of data.inheritance) if (!scope.applicationNamespaces.includes(String(row.parent_namespace)) || row.detach_pending !== false) fail("Unsupported external or pending-detach inheritance")
for (const row of data.constraints) {
if (row.kind === "c" ? typeof row.restore_definition !== "string" || !row.restore_definition : row.restore_definition !== null) fail("Missing fixed PostgreSQL CHECK restore definition")
if (row.kind === "t") {
// User constraint triggers have a pg_constraint row as well as the full
// pg_trigger definition captured below. Join by portable identity rather
// than OIDs, which legitimately change after dump/restore.
const triggers = data.triggers.filter(trigger => trigger.namespace === row.namespace && trigger.relation === row.relation && trigger.name === row.name && trigger.constraint_name === row.name)
if (typeof row.relation !== "string" || row.domain !== null || row.foreign_namespace !== null || row.foreign_relation !== null || row.parent_namespace !== null || row.parent_relation !== null || row.parent_constraint !== null || triggers.length !== 1) fail("Unsupported user constraint trigger shape")
const trigger = triggers[0]
if (trigger.internal !== false || trigger.deferrable !== row.deferrable || trigger.initially_deferred !== row.deferred || trigger.parent_relation !== null || trigger.parent_trigger !== null || !scope.applicationNamespaces.includes(String(trigger.function_namespace))) fail("Inconsistent user constraint trigger semantics")
} else if (!["p", "u", "f", "c", "x", "n"].includes(String(row.kind)) || row.foreign_namespace !== null && !scope.applicationNamespaces.includes(String(row.foreign_namespace))) fail("Unsupported external constraint semantics")
}
for (const row of data.triggers) if (!["O", "D", "R", "A"].includes(String(row.enabled)) || row.internal && (typeof row.constraint_name !== "string" || row.function_namespace !== "pg_catalog" || !String(row.function_name).startsWith("RI_FKey_")) || !row.internal && !scope.applicationNamespaces.includes(String(row.function_namespace))) fail("Unsupported internal/external trigger semantics")
for (const row of data.sequences) if (row.owner_namespace !== null && !scope.applicationNamespaces.includes(String(row.owner_namespace))) fail("Unsupported external sequence ownership")
const relationNames = new Set(data.relations.map(row => row.namespace + "." + row.name))
for (const row of data.columns) if (!relationNames.has(row.namespace + "." + row.relation)) fail("Column without captured relation")
for (const row of data.relations.filter(row => row.kind === "S")) if (!data.sequences.some(sequence => sequence.namespace === row.namespace && sequence.name === row.name)) fail("Missing sequence definition")
for (const row of data.relations.filter(row => ["i", "I"].includes(String(row.kind)))) if (!data.indexes.some(index => index.namespace === row.namespace && index.name === row.name)) fail("Missing index definition")
for (const row of data.relations.filter(row => ["v", "m"].includes(String(row.kind)))) if (!data.views.some(view => view.namespace === row.namespace && view.name === row.name)) fail("Missing view definition")
}
export interface CapturedMigrationSchema {
format: "pg18-application-schema-v3" | "pg18-application-schema-v4"
scope: ReturnType<typeof scopeValue>
serverVersion: string
sections: Record<SchemaSection, Record<string, Json>[]>
eventTriggers?: Record<string, Json>[]
/** Exact observed fast-default history; independently content-checked, never
* used as proof of row/data-migration equivalence. */
observedPhysical: { columns: Record<string, Json>[]; canonical: string; sha256: string }
/** v3 binds ALL raw fields, including original CHECK rendering, tombstones,
* numeric index keys and the additive fixed PostgreSQL restore rendering. */
observedRaw: { format: "pg18-raw-catalog-v1"; sha256: string }
/** v3 restore-portable logical definitions. Raw sections and physical
* fingerprint stay exact; dropped slots/attnums are normalized only here. */
canonical: string
sha256: string
}
/** Fast-default cached values describe existing tuple history, not the current
* default expression. ALTER ADD DEFAULT now() (pinned migration0018) caches its
* execution time; a table rewrite clears the cache/flag. Neither proves data
* migration equivalence. Keep exact observations separately, never erase them. */
function canonicalControlEventTriggers(raw: unknown, functions: CapturedMigrationSchema["sections"]["functions"]) {
if (!Array.isArray(raw) || raw.length > 1024) return fail("Bounded control event trigger catalog required")
const names = new Set<string>()
return raw.map(value => {
const row = canonical(value) as Record<string, Json>
if (!row || Object.keys(row).join(" ") !== "comment enabled event function_arguments function_name function_namespace name owner tags" ||
typeof row.name !== "string" || !row.name || names.has(row.name) || typeof row.event !== "string" || !row.event ||
typeof row.owner !== "string" || !row.owner || !["O", "D", "R", "A"].includes(String(row.enabled)) ||
row.comment !== null && typeof row.comment !== "string" ||
row.tags !== null && (!Array.isArray(row.tags) || row.tags.some(tag => typeof tag !== "string") || new Set(row.tags).size !== row.tags.length) ||
row.function_namespace !== "mmapp_control" || row.function_arguments !== "" ||
!functions.some(fn => fn.namespace === row.function_namespace && fn.name === row.function_name && fn.arguments === row.function_arguments)) {
return fail("Unsupported event trigger or uncaptured control function")
}
names.add(row.name)
if (Array.isArray(row.tags)) row.tags = [...row.tags].sort()
return row
}).sort((left, right) => String(left.name) < String(right.name) ? -1 : 1)
}
function projections(data: CapturedMigrationSchema["sections"], eventTriggers?: Record<string, Json>[]) {
const sortRows = (rows: Record<string, Json>[]) => rows.map(row => JSON.stringify(canonical(row))).sort().map(row => JSON.parse(row) as Record<string, Json>)
const physicalColumns = sortRows(data.columns.map(row => Object.fromEntries(["namespace", "relation", "position", "name", "has_missing", "missing_value"].map(field => [field, row[field]]))))
const physicalCanonical = JSON.stringify(canonical({ columns: physicalColumns }))
const observedRaw = { format: "pg18-raw-catalog-v1" as const, sha256: digest(JSON.stringify(canonical({
format: "pg18-raw-catalog-v1", sections: data, ...(eventTriggers ? { eventTriggers } : {}),
}))) }
// Never mutate raw catalog rows. A pg_dump/restore legitimately omits dropped
// slots and compacts physical attnums. Visible order remains semantic.
const relationKey = (namespace: Json, relation: Json) => JSON.stringify([namespace, relation])
const groups = new Map<string, Record<string, Json>[]>()
for (const row of data.columns) {
const key = relationKey(row.namespace, row.relation), rows = groups.get(key) ?? []
rows.push(row); groups.set(key, rows)
}
const visibleByAttnum = new Map<string, Map<number, string>>()
const columns: Record<string, Json>[] = []
for (const [key, rows] of groups) {
const ordered = [...rows].sort((a, b) => Number(a.position) - Number(b.position))
const positions = new Set<number>(), names = new Set<string>(), visible = new Map<number, string>()
let ordinal = 0
for (const row of ordered) {
const attnum = Number(row.position)
if (!Number.isSafeInteger(attnum) || attnum < 1 || attnum > 32767 || positions.has(attnum)) fail("Ambiguous physical column position")
positions.add(attnum)
if (row.dropped === true) continue
if (typeof row.name !== "string" || names.has(row.name)) fail("Ambiguous visible column identity")
names.add(row.name); visible.set(attnum, row.name)
columns.push({ ...Object.fromEntries(Object.entries(row).filter(([field]) => field !== "has_missing" && field !== "missing_value")), position: ++ordinal })
}
visibleByAttnum.set(key, visible)
}
const indexes = data.indexes.map(row => {
// indkey covers key AND INCLUDE attributes. Positive attnums must resolve
// to the exact live column of THIS indexed relation; zero is an expression
// slot, never an absent/dropped column. Definitions/expressions/predicates,
// key order, options, opclasses and collations remain independently pinned.
if (typeof row.keys !== "string" || !/^(?:0|[1-9][0-9]*)(?: (?:0|[1-9][0-9]*))*$/.test(row.keys) ||
!Number.isSafeInteger(row.attributes) || Number(row.attributes) < 1 || Number(row.attributes) > 32767) fail("Unsupported index attribute vector")
const tokens = row.keys.split(" ")
if (tokens.length !== row.attributes) fail("Index attribute vector arity mismatch")
const visible = visibleByAttnum.get(relationKey(row.namespace, row.relation))
const keys = tokens.map(token => {
if (token === "0") {
if (typeof row.expressions !== "string" || !row.expressions) fail("Index expression slot without expression")
return ["expression"]
}
const name = visible?.get(Number(token))
if (name === undefined) return fail("Dangling or dropped index column reference")
return ["column", name]
})
return { ...row, keys: JSON.stringify(keys) }
})
// inheritance.position is inhseqno, not attnum: it and every other catalog
// field/definition stay exact. The v3 marker prevents legacy reinterpretation.
// PostgreSQL itself removes nonsemantic CHECK deparser grouping; no SQL
// regex/rewriting or discarded CHECK is involved. Original false-rendered
// text remains in raw sections and observedRaw, while all constraint flags,
// identity, validation/enforcement and non-CHECK definitions remain exact.
const constraints = data.constraints.map(row => ({ ...Object.fromEntries(Object.entries(row).filter(([field]) => field !== "restore_definition")), definition: row.kind === "c" ? row.restore_definition : row.definition }))
const logical = { ...data, columns: sortRows(columns), indexes: sortRows(indexes), constraints: sortRows(constraints) }
return { logical, observedPhysical: { columns: physicalColumns, canonical: physicalCanonical, sha256: digest(physicalCanonical) }, observedRaw }
}
/** Every query envelope must identify the SAME backend + transaction + deparse
* context. Mutable sequence last_value/statistics/table data are not schema.
* Excluded control namespaces must be explicit and present, never inferred
* from marker/table existence. Their objects are outside this evidence scope. */
export async function captureMigrationSchema(client: SchemaInventoryClient, options: {
scope?: SchemaInventoryScope; deadlineAt?: number; includeControlEventTriggers?: boolean
} = {}): Promise<CapturedMigrationSchema> {
const scope = scopeValue(options.scope ?? { applicationNamespaces: ["public"] }), deadline = options.deadlineAt ?? Date.now() + 60000
if (options.includeControlEventTriggers && !scope.applicationNamespaces.includes("mmapp_control")) fail("Control event triggers require the control schema in scope")
if (!Number.isSafeInteger(deadline) || deadline <= Date.now() || deadline - Date.now() > 120000) fail("Invalid schema inventory deadline")
const data = {} as Record<SchemaSection, Record<string, Json>[]>
let owner: string | undefined, serverVersion = "", size = 0
for (const section of sections) {
if (Date.now() >= deadline) fail("Schema capture deadline expired")
const parameters = MIGRATION_SCHEMA_PARAMETERS[section] === "none" ? [] : [[...scope.applicationNamespaces]]
let result: Awaited<ReturnType<SchemaInventoryClient["query"]>>
const sql = MIGRATION_SCHEMA_QUERIES[section]
try { result = await client.query(section === "unsupported" && options.includeControlEventTriggers ? sql.replace(unsupportedEventTriggers, "") : sql, parameters) }
catch (cause) { throw new MigrationSchemaInventoryError("Catalog query failed: " + section, { cause }) }
if (result.rows.length !== 1) fail("Catalog query envelope unavailable")
const row = result.rows[0], current = session(row)
if (owner !== undefined && owner !== current) fail("Catalog capture changed backend, transaction or deparse context")
owner = current; serverVersion = String(row.server_version)
data[section] = rowsFor(section, row.objects)
if (section === "unsupported" && data.unsupported.length) fail("Unsupported schema semantics refused before detailed deparsing")
if (section === "namespaces" && JSON.stringify(data.namespaces.map(row => row.namespace).sort()) !== JSON.stringify([...scope.applicationNamespaces, ...scope.excludedControlNamespaces].sort())) fail("Unexpected or missing application/control namespace")
size += Buffer.byteLength(JSON.stringify(data[section])); if (size > 33554432 || Date.now() >= deadline) fail("Schema capture byte/deadline bound exceeded")
}
validateSemantics(data, scope)
let eventTriggers: Record<string, Json>[] | undefined
if (options.includeControlEventTriggers) {
const { rows } = await client.query(controlEventTriggersSql)
if (rows.length !== 1 || session(rows[0]) !== owner || Date.now() >= deadline) fail("Control event triggers escaped the catalog snapshot")
const captured = canonicalControlEventTriggers(rows[0].objects, data.functions)
if (size + Buffer.byteLength(JSON.stringify(captured)) > 33554432) fail("Control event trigger byte bound exceeded")
if (captured.length) eventTriggers = captured
}
const format = eventTriggers ? "pg18-application-schema-v4" : "pg18-application-schema-v3"
const value = { format, scope, serverVersion, sections: data, ...(eventTriggers ? { eventTriggers } : {}) } as const
const { logical, observedPhysical, observedRaw } = projections(data, eventTriggers)
const serialized = JSON.stringify(canonical({ ...value, sections: logical }))
return { ...value, observedPhysical, observedRaw, canonical: serialized, sha256: digest(serialized) }
}
/** Recompute and compare captured CONTENT, never trust a supplied boolean/hash.
* Evidence-only equality is not proof that a caller's reference is authorized.
* Equality covers logical schema, not cached tuple history or data migration.
* Reference generation from all36 pinned files belongs to the owner harness. */
export function compareMigrationSchemas(expected: CapturedMigrationSchema, observed: CapturedMigrationSchema) {
const checked = (snapshot: CapturedMigrationSchema) => {
if (!snapshot || !["pg18-application-schema-v3", "pg18-application-schema-v4"].includes(snapshot.format) || !/^18\d{4}$/.test(snapshot.serverVersion)) fail("Unsupported captured schema format/version")
const eventFormat = snapshot.format === "pg18-application-schema-v4"
const keys = ["canonical", "format", "observedPhysical", "observedRaw", "scope", "sections", "serverVersion", "sha256"]
if (eventFormat) keys.push("eventTriggers")
if (JSON.stringify(Object.keys(snapshot).sort()) !== JSON.stringify(keys.sort())) fail("Unexpected captured schema envelope")
const scope = scopeValue(snapshot.scope)
if (JSON.stringify(Object.keys(snapshot.sections).sort()) !== JSON.stringify([...sections].sort())) fail("Captured schema section set changed")
const data = Object.fromEntries(sections.map(section => [section, rowsFor(section, snapshot.sections[section])])) as Record<SchemaSection, Record<string, Json>[]>
validateSemantics(data, scope)
const eventTriggers = eventFormat ? canonicalControlEventTriggers(snapshot.eventTriggers, data.functions) : undefined
if (eventFormat && (!eventTriggers?.length || !scope.applicationNamespaces.includes("mmapp_control"))) fail("Unexpected event trigger scope")
const { logical, observedPhysical, observedRaw } = projections(data, eventTriggers)
if (JSON.stringify(canonical(snapshot.observedPhysical)) !== JSON.stringify(canonical(observedPhysical))) fail("Captured physical metadata/content digest was altered")
if (JSON.stringify(canonical(snapshot.observedRaw)) !== JSON.stringify(canonical(observedRaw))) fail("Captured raw catalog/content digest was altered")
const text = JSON.stringify(canonical({ format: snapshot.format, scope, serverVersion: snapshot.serverVersion, sections: logical, ...(eventTriggers ? { eventTriggers } : {}) }))
if (text !== snapshot.canonical || digest(text) !== snapshot.sha256) fail("Captured schema content/digest was altered")
return text
}
const reference = checked(expected), actual = checked(observed)
if (reference !== actual) fail("Observed schema differs from the exact captured reference")
return Object.freeze({ equal: true as const, evidenceOnly: true as const, enrollmentAuthorized: false as const, sha256: digest(actual) })
}