@happyvertical/smrt-core 0.46.0 → 0.47.1

package/dist/postgres-permissions.d.ts

@@ -7,6 +7,10 @@ export interface PostgresPermissionContract {
     migrationOwner: string;
     runtimeRole: string;
     managedTables: string[];
+    /** Existing operator-owned tables retained outside the runtime data surface. */
+    retainedTables?: string[];
+    /** Exact zero-argument trigger functions bound only to managed tables. */
+    managedTriggerFunctions?: string[];
     monitor?: {
         role: string;
         tables: Record<string, string[]>;
@@ -27,9 +31,13 @@ export interface PostgresPermissionPlan {
     fingerprint: string;
     limitations: string[];
 }
+type NormalizedPostgresPermissionContract = PostgresPermissionContract & {
+    managedTriggerFunctions: string[];
+    retainedTables: string[];
+};
 type Executor = Pick<DatabaseInterface, 'query'>;
 /** Validate configuration before opening a connection; unknown options fail closed. */
-export declare function validatePostgresPermissionContract(value: unknown): PostgresPermissionContract;
+export declare function validatePostgresPermissionContract(value: unknown): NormalizedPostgresPermissionContract;
 /** Read-only catalog inspection. No application records or credentials are read. */
 export declare function planPostgresPermissions(db: Executor, contract: PostgresPermissionContract): Promise<PostgresPermissionPlan>;
 /** Apply the reviewed contract atomically, rejecting stale catalog snapshots. */

package/dist/postgres-permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-permissions.d.ts","sourceRoot":"","sources":["../src/postgres-permissions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,0EAA0E;AAC1E,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,eAAe,EAAE,IAAI,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,WAAW,EAAE,4BAA4B,EAAE,CAAC;IAC5C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,KAAK,QAAQ,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;AA8DjD,uFAAuF;AACvF,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,GACb,0BAA0B,CA4E5B;AAssBD,oFAAoF;AACpF,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,0BAA0B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CAEjC;AAED,iFAAiF;AACjF,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,0BAA0B,EACpC,OAAO,EAAE;IAAE,mBAAmB,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,sBAAsB,CAAC,CA2CjC"}
+{"version":3,"file":"postgres-permissions.d.ts","sourceRoot":"","sources":["../src/postgres-permissions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAS5D,0EAA0E;AAC1E,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,eAAe,EAAE,IAAI,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,WAAW,EAAE,4BAA4B,EAAE,CAAC;IAC5C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,KAAK,oCAAoC,GAAG,0BAA0B,GAAG;IACvE,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,KAAK,QAAQ,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;AA2JjD,uFAAuF;AACvF,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,GACb,oCAAoC,CA2GtC;AA2+BD,oFAAoF;AACpF,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,0BAA0B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CAEjC;AAED,iFAAiF;AACjF,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,0BAA0B,EACpC,OAAO,EAAE;IAAE,mBAAmB,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,sBAAsB,CAAC,CA8CjC"}

package/dist/postgres-permissions.js

@@ -1,3 +1,4 @@
+import { CREATE_POSTGRES_CHANGE_FEED_APPEND_FUNCTION, CREATE_POSTGRES_CHANGE_FEED_DRAIN_FUNCTION, POSTGRES_CHANGE_FEED_APPEND_FUNCTION_IDENTITY, POSTGRES_CHANGE_FEED_DRAIN_BATCH, POSTGRES_CHANGE_FEED_DRAIN_FUNCTION_IDENTITY } from "./system/schema.js";
 import { createHash } from "node:crypto";
 //#region src/postgres-permissions.ts
 var bookkeeping = /* @__PURE__ */ new Set([
@@ -8,6 +9,31 @@ var bookkeeping = /* @__PURE__ */ new Set([
 var identifier = (value) => `"${value.replaceAll("\"", "\"\"")}"`;
 var literal = (value) => `E'${value.replaceAll("\\", "\\\\").replaceAll("'", "''")}'`;
 var qualified = (schema, name) => `${identifier(schema)}.${identifier(name)}`;
+var normalizeFunctionSource = (value) => value.replaceAll("\r\n", "\n").trim();
+var normalizeArgumentTypes = (value) => value.replaceAll(/\s*,\s*/g, ",");
+var normalizeFunctionResult = (value) => value.replaceAll(/\s+/g, " ").replaceAll(/\s*,\s*/g, ",").replaceAll(/\(\s*/g, "(").replaceAll(/\s*\)/g, ")").trim().toLowerCase();
+function sourceFromFunctionDdl(ddl) {
+	const match = ddl.match(/\bAS\s+\$([A-Za-z_][A-Za-z0-9_]*)\$\n([\s\S]*?)\n\$\1\$;/);
+	if (!match) throw new Error("Framework function DDL has no dollar-quoted body.");
+	return normalizeFunctionSource(match[2]);
+}
+function resultFromFunctionDdl(ddl) {
+	const match = ddl.match(/\bRETURNS\s+([\s\S]*?)\nLANGUAGE\s+/);
+	if (!match) throw new Error("Framework function DDL has no return result.");
+	return normalizeFunctionResult(match[1]);
+}
+function frameworkRoutine(identity, ddl) {
+	const match = identity.match(/^([^()]+)\((.*)\)$/);
+	if (!match) throw new Error(`Invalid framework function identity: ${identity}`);
+	return {
+		name: match[1],
+		argumentTypes: normalizeArgumentTypes(match[2]),
+		argumentDefaults: match[1] === "_smrt_drain_changes" ? String(POSTGRES_CHANGE_FEED_DRAIN_BATCH) : null,
+		result: resultFromFunctionDdl(ddl),
+		source: sourceFromFunctionDdl(ddl)
+	};
+}
+var frameworkRoutines = [frameworkRoutine(POSTGRES_CHANGE_FEED_APPEND_FUNCTION_IDENTITY, CREATE_POSTGRES_CHANGE_FEED_APPEND_FUNCTION), frameworkRoutine(POSTGRES_CHANGE_FEED_DRAIN_FUNCTION_IDENTITY, CREATE_POSTGRES_CHANGE_FEED_DRAIN_FUNCTION)];
 function object(value, keys, label) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
 	for (const key of Object.keys(value)) if (!keys.includes(key)) throw new Error(`Unknown ${label} property: ${key}.`);
@@ -25,6 +51,8 @@ function validatePostgresPermissionContract(value) {
 		"migrationOwner",
 		"runtimeRole",
 		"managedTables",
+		"retainedTables",
+		"managedTriggerFunctions",
 		"monitor"
 	], "postgresPermissions");
 	if (input.schemaExclusive !== true) throw new Error("postgresPermissions.schemaExclusive must explicitly be true.");
@@ -34,6 +62,12 @@ function validatePostgresPermissionContract(value) {
 	const runtimeRole = name(input.runtimeRole, "runtimeRole");
 	if (!Array.isArray(input.managedTables)) throw new Error("managedTables must be an array.");
 	const managedTables = [...new Set(input.managedTables.map((table) => name(table, "managedTables entry")))].sort();
+	if (input.retainedTables !== void 0 && !Array.isArray(input.retainedTables)) throw new Error("retainedTables must be an array.");
+	const retainedTables = [...new Set((input.retainedTables ?? []).map((table) => name(table, "retainedTables entry")))].sort();
+	const overlap = retainedTables.find((table) => managedTables.includes(table));
+	if (overlap) throw new Error(`Table ${overlap} cannot be both managed and retained.`);
+	if (input.managedTriggerFunctions !== void 0 && !Array.isArray(input.managedTriggerFunctions)) throw new Error("managedTriggerFunctions must be an array.");
+	const managedTriggerFunctions = [...new Set((input.managedTriggerFunctions ?? []).map((routine) => name(routine, "managedTriggerFunctions entry")))].sort();
 	let monitor;
 	if (input.monitor !== void 0) {
 		const entry = object(input.monitor, ["role", "tables"], "monitor");
@@ -62,6 +96,8 @@ function validatePostgresPermissionContract(value) {
 		migrationOwner,
 		runtimeRole,
 		managedTables,
+		retainedTables,
+		managedTriggerFunctions,
 		...monitor ? { monitor } : {}
 	};
 }
@@ -81,9 +117,13 @@ async function snapshot(db, contract) {
 		memberships: `SELECT pg_get_userbyid(member) AS member, pg_get_userbyid(roleid) AS parent FROM pg_auth_members WHERE member IN (SELECT oid FROM pg_roles WHERE rolname IN (${roleNames})) OR roleid IN (SELECT oid FROM pg_roles WHERE rolname IN (${roleNames})) ORDER BY member, roleid`,
 		database: `SELECT datname AS name, pg_get_userbyid(datdba) AS owner, ${acl("COALESCE(datacl, acldefault('d',datdba))")} AS acl FROM pg_database WHERE datname=current_database()`,
 		schemas: `SELECT nspname AS name, pg_get_userbyid(nspowner) AS owner, ${acl("COALESCE(nspacl, acldefault('n',nspowner))")} AS acl FROM pg_namespace WHERE left(nspname,3) <> 'pg_' AND nspname <> 'information_schema' ORDER BY nspname`,
-		relations: `SELECT c.oid::text, n.nspname AS schema, c.relname AS name, c.relkind AS kind, pg_get_userbyid(c.relowner) AS owner, c.relrowsecurity AS rls, ${acl("COALESCE(c.relacl, acldefault(CASE WHEN c.relkind='S' THEN 's'::\"char\" ELSE 'r'::\"char\" END,c.relowner))")} AS acl FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace WHERE left(n.nspname,3) <> 'pg_' AND n.nspname <> 'information_schema' AND c.relkind IN ('r','p','v','m','f','S') ORDER BY n.nspname,c.relname`,
+		relations: `SELECT c.oid::text, n.nspname AS schema, c.relname AS name, c.relkind AS kind, pg_get_userbyid(c.relowner) AS owner, c.relrowsecurity AS rls, (SELECT parent.relname FROM pg_depend d JOIN pg_class parent ON parent.oid=d.refobjid JOIN pg_namespace parent_schema ON parent_schema.oid=parent.relnamespace WHERE d.classid='pg_class'::regclass AND d.objid=c.oid AND d.refclassid='pg_class'::regclass AND d.deptype IN ('a','i') AND parent_schema.oid=n.oid LIMIT 1) AS parent_table, ${acl("COALESCE(c.relacl, acldefault(CASE WHEN c.relkind='S' THEN 's'::\"char\" ELSE 'r'::\"char\" END,c.relowner))")} AS acl FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace WHERE left(n.nspname,3) <> 'pg_' AND n.nspname <> 'information_schema' AND c.relkind IN ('r','p','v','m','f','S') ORDER BY n.nspname,c.relname`,
+		inherits: `SELECT child_schema.nspname AS child_schema, child.relname AS child_table, parent_schema.nspname AS parent_schema, parent.relname AS parent_table FROM pg_inherits i JOIN pg_class child ON child.oid=i.inhrelid JOIN pg_namespace child_schema ON child_schema.oid=child.relnamespace JOIN pg_class parent ON parent.oid=i.inhparent JOIN pg_namespace parent_schema ON parent_schema.oid=parent.relnamespace ORDER BY child_schema.nspname,child.relname,parent_schema.nspname,parent.relname`,
+		foreignKeys: `SELECT child_schema.nspname AS child_schema, child.relname AS child_table, parent_schema.nspname AS parent_schema, parent.relname AS parent_table, con.confdeltype::text AS delete_action, con.confupdtype::text AS update_action FROM pg_constraint con JOIN pg_class child ON child.oid=con.conrelid JOIN pg_namespace child_schema ON child_schema.oid=child.relnamespace JOIN pg_class parent ON parent.oid=con.confrelid JOIN pg_namespace parent_schema ON parent_schema.oid=parent.relnamespace WHERE con.contype='f' ORDER BY child_schema.nspname,child.relname,parent_schema.nspname,parent.relname,con.conname`,
+		rewriteRules: `WITH RECURSIVE rule_dependencies AS (SELECT r.oid AS rule_oid, r.ev_class AS source_oid, r.rulename AS rule_name, d.refobjid AS referenced_oid FROM pg_rewrite r JOIN pg_depend d ON d.classid='pg_rewrite'::regclass AND d.objid=r.oid AND d.refclassid='pg_class'::regclass WHERE r.rulename <> '_RETURN' UNION SELECT dependencies.rule_oid, dependencies.source_oid, dependencies.rule_name, d.refobjid FROM rule_dependencies dependencies JOIN pg_rewrite view_rule ON view_rule.ev_class=dependencies.referenced_oid AND view_rule.rulename='_RETURN' JOIN pg_depend d ON d.classid='pg_rewrite'::regclass AND d.objid=view_rule.oid AND d.refclassid='pg_class'::regclass) SELECT n.nspname AS schema, c.relname AS table_name, dependencies.rule_name, referenced_schema.nspname AS referenced_schema, referenced.relname AS referenced_table FROM rule_dependencies dependencies JOIN pg_class c ON c.oid=dependencies.source_oid JOIN pg_namespace n ON n.oid=c.relnamespace JOIN pg_class referenced ON referenced.oid=dependencies.referenced_oid JOIN pg_namespace referenced_schema ON referenced_schema.oid=referenced.relnamespace ORDER BY n.nspname,c.relname,dependencies.rule_name,referenced_schema.nspname,referenced.relname`,
 		columns: `SELECT c.oid::text AS relation, a.attname AS name, ${acl("a.attacl")} AS acl FROM pg_attribute a JOIN pg_class c ON c.oid=a.attrelid JOIN pg_namespace n ON n.oid=c.relnamespace WHERE left(n.nspname,3) <> 'pg_' AND n.nspname <> 'information_schema' AND c.relkind IN ('r','p','v','m','f') AND a.attnum>0 AND NOT a.attisdropped ORDER BY c.oid,a.attnum`,
-		routines: `SELECT n.nspname AS schema, p.oid::text, p.proname AS name, pg_get_userbyid(p.proowner) AS owner, ${acl("COALESCE(p.proacl, acldefault('f',p.proowner))")} AS acl FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace WHERE left(n.nspname,3) <> 'pg_' AND n.nspname <> 'information_schema' ORDER BY n.nspname,p.oid`,
+		routines: `SELECT n.nspname AS schema, p.oid::text, p.proname AS name, format('%I.%I(%s)', n.nspname, p.proname, oidvectortypes(p.proargtypes)) AS identity, oidvectortypes(p.proargtypes) AS argument_types, pg_get_expr(p.proargdefaults,0) AS argument_defaults, p.prokind AS kind, p.prorettype::regtype::text AS return_type, pg_get_function_result(p.oid) AS result, p.procost::text AS cost, p.prorows::text AS rows, p.prosupport::regproc::text AS support, p.pronargs::text AS argument_count, l.lanname AS language, p.prosecdef AS security_definer, p.provolatile::text AS volatility, p.proparallel::text AS parallel, p.proleakproof AS leakproof, p.proisstrict AS strict, COALESCE(to_json(p.proconfig),'[]'::json) AS config, p.prosrc AS source, CASE WHEN p.prokind='f' THEN pg_get_functiondef(p.oid) END AS definition, pg_get_userbyid(p.proowner) AS owner, ${acl("COALESCE(p.proacl, acldefault('f',p.proowner))")} AS acl FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace JOIN pg_language l ON l.oid=p.prolang WHERE left(n.nspname,3) <> 'pg_' AND n.nspname <> 'information_schema' ORDER BY n.nspname,p.oid`,
+		triggers: `SELECT t.oid::text, n.nspname AS schema, c.relname AS table_name, t.tgname AS name, t.tgfoid::text AS function_oid, t.tgenabled AS enabled, t.tgisinternal AS internal, t.tgtype::text AS type, encode(t.tgargs,'hex') AS arguments, pg_get_triggerdef(t.oid, true) AS definition FROM pg_trigger t JOIN pg_class c ON c.oid=t.tgrelid JOIN pg_namespace n ON n.oid=c.relnamespace WHERE left(n.nspname,3) <> 'pg_' AND n.nspname <> 'information_schema' ORDER BY n.nspname,c.oid,t.oid`,
 		types: `SELECT n.nspname AS schema, t.typname AS name, pg_get_userbyid(t.typowner) AS owner, ${acl("COALESCE(t.typacl, acldefault('T',t.typowner))")} AS acl FROM pg_type t JOIN pg_namespace n ON n.oid=t.typnamespace LEFT JOIN pg_class c ON c.oid=t.typrelid WHERE left(n.nspname,3) <> 'pg_' AND n.nspname <> 'information_schema' AND NOT EXISTS (SELECT 1 FROM pg_type element WHERE element.typarray=t.oid) AND (t.typrelid=0 OR c.relkind='c') ORDER BY n.nspname,t.typname`,
 		systemSchemas: `SELECT nspname AS name, pg_get_userbyid(nspowner) AS owner, ${acl("COALESCE(nspacl, acldefault('n',nspowner))")} AS acl FROM pg_namespace WHERE left(nspname,3)='pg_' OR nspname='information_schema' ORDER BY nspname`,
 		systemPrivileges: `WITH resources AS (
@@ -184,6 +224,26 @@ async function plan(db, input) {
 		statements.push(`REVOKE ALL PRIVILEGES${suffix} ON ${kind} ${resource} FROM ${identifier(role)}`);
 		if (desired.length) statements.push(`GRANT ${desired.join(", ")}${suffix} ON ${kind} ${resource} TO ${identifier(role)}`);
 	}
+	function reconcileRoutine(resource, entries, desiredByRole) {
+		const grantee = (role) => role === "PUBLIC" ? "PUBLIC" : identifier(role);
+		for (const entry of entries) if (roles.includes(entry.grantor ?? "") && entry.grantee !== entry.grantor) unsupported("dependent-routine-grant", resource, `Configured role granted ${entry.privilege} to ${entry.grantee}; grant chains require infrastructure review to preserve other roles.`, entry.grantor);
+		const managedGrantees = /* @__PURE__ */ new Set([
+			contract.migrationOwner,
+			...roles,
+			"PUBLIC"
+		]);
+		for (const entry of entries) if (!managedGrantees.has(entry.grantee)) unsupported("outside-routine-grant", resource, `${entry.grantee} has ${entry.privilege}; direct routine access outside the declared roles requires infrastructure review.`, entry.grantee);
+		for (const role of [...roles, "PUBLIC"]) {
+			const desired = desiredByRole.get(role) ?? [];
+			const excess = entries.filter((entry) => entry.grantee === role).filter((entry) => !desired.includes(entry.privilege) || entry.grantable);
+			const missing = desired.filter((privilege) => !entries.some((entry) => entry.grantee === role && entry.privilege === privilege));
+			for (const entry of excess) add("excessive", "excessive-routine-privilege", resource, `${entry.privilege}${entry.grantable ? " WITH GRANT OPTION" : ""} is not declared.`, role);
+			for (const privilege of missing) add("missing", "missing-routine-privilege", resource, `${privilege} is required.`, role);
+			if (!excess.length && !missing.length) continue;
+			statements.push(`REVOKE ALL PRIVILEGES ON FUNCTION ${resource} FROM ${grantee(role)}`);
+			if (desired.length) statements.push(`GRANT ${desired.join(", ")} ON FUNCTION ${resource} TO ${grantee(role)}`);
+		}
+	}
 	for (const role of roles) {
 		reconcile("DATABASE", identifier(database.name), database.acl, role, ["CONNECT"]);
 		for (const entry of state.schemas) {
@@ -222,11 +282,40 @@ async function plan(db, input) {
 	const tables = state.relations.filter((entry) => entry.schema === contract.schema && entry.kind !== "S");
 	for (const table of bookkeeping) if (!tables.some((entry) => entry.name === table)) unsupported("missing-bookkeeping-table", qualified(contract.schema, table), "Bootstrap all framework bookkeeping tables as the migration owner before permission setup. Stop runtime and monitoring access during migrations or restores, then reconcile before reactivation.");
 	const declared = new Set(contract.managedTables);
+	const retained = new Set(contract.retainedTables);
 	for (const table of tables) if (table.name.startsWith("_smrt_")) declared.add(table.name);
+	for (const table of retained) if (declared.has(table)) unsupported("retained-managed-table", qualified(contract.schema, table), "Retained tables must be outside the managed and framework table surfaces.");
 	for (const table of declared) if (!tables.some((entry) => entry.name === table)) unsupported("missing-table", qualified(contract.schema, table), "Run supported schema migrations before reconciling permissions.");
+	for (const table of retained) if (!tables.some((entry) => entry.name === table)) unsupported("missing-retained-table", qualified(contract.schema, table), "Retained tables must already exist before permission reconciliation.");
+	for (const relation of state.inherits) {
+		const managedParent = relation.parent_schema === contract.schema && declared.has(relation.parent_table ?? "");
+		const childRetained = relation.child_schema === contract.schema && retained.has(relation.child_table);
+		const parentRetained = relation.parent_schema === contract.schema && retained.has(relation.parent_table ?? "");
+		if (managedParent && relation.child_schema !== contract.schema) unsupported("managed-inheritance", qualified(relation.child_schema, relation.child_table), "Managed tables may not have external inheritance or partition children: parent table privileges can invoke external triggers outside the retained-table isolation boundary.");
+		else if (childRetained !== parentRetained) unsupported("retained-inheritance", qualified(relation.child_schema, relation.child_table), "Retained tables may inherit only from retained tables in the dedicated schema; an accessible parent can otherwise expose retained rows.");
+	}
+	for (const relation of state.foreignKeys) {
+		const managedParent = relation.parent_schema === contract.schema && declared.has(relation.parent_table ?? "");
+		const childRetained = relation.child_schema === contract.schema && retained.has(relation.child_table);
+		const parentRetained = relation.parent_schema === contract.schema && retained.has(relation.parent_table ?? "");
+		if (managedParent && relation.child_schema !== contract.schema) {
+			unsupported("managed-foreign-key", `${qualified(relation.child_schema, relation.child_table)} -> ${qualified(relation.parent_schema, relation.parent_table ?? "")}`, "Managed tables may not have external foreign-key children: referential actions can invoke external triggers outside the retained-table isolation boundary.");
+			continue;
+		}
+		if (childRetained === parentRetained) continue;
+		unsupported("retained-foreign-key", `${qualified(relation.child_schema, relation.child_table)} -> ${qualified(relation.parent_schema, relation.parent_table ?? "")}`, "Retained tables may reference only retained tables; referential actions from an accessible table can otherwise mutate retained rows.");
+	}
+	for (const rule of state.rewriteRules) {
+		const managedSource = rule.schema === contract.schema && declared.has(rule.table_name);
+		const retainedSource = rule.schema === contract.schema && retained.has(rule.table_name);
+		const managedTarget = rule.referenced_schema === contract.schema && declared.has(rule.referenced_table);
+		if (retainedSource && managedTarget) unsupported("user-rewrite-rule", `${qualified(rule.schema, rule.table_name)} (${rule.rule_name})`, "Retained tables may not reference managed tables through rewrite rules.");
+		else if (managedSource && rule.referenced_schema !== contract.schema) unsupported("user-rewrite-rule", `${qualified(rule.schema, rule.table_name)} (${rule.rule_name})`, "Managed rewrite rules may not reference external relations: rule-owner table privileges can invoke external triggers outside the retained-table isolation boundary.");
+		else if (rule.referenced_schema === contract.schema && retained.has(rule.referenced_table)) unsupported("user-rewrite-rule", `${qualified(rule.schema, rule.table_name)} (${rule.rule_name})`, "User-defined rewrite rules are unsupported because rule-owner privileges can write retained tables indirectly.");
+	}
 	for (const [table, columns] of Object.entries(contract.monitor?.tables ?? {})) {
 		const relation = tables.find((entry) => entry.name === table);
-		if (!declared.has(table) || !relation) unsupported("monitor-table", table, "Monitor tables must exist and belong to managedTables or framework tables.");
+		if (!declared.has(table) || retained.has(table) || !relation) unsupported("monitor-table", table, "Monitor tables must exist and belong to the managed or framework table surface, never retained tables.");
 		for (const column of columns) if (!relation || !state.columns.some((entry) => entry.relation === relation.oid && entry.name === column)) unsupported("monitor-column", `${table}.${column}`, "The declared monitoring column does not exist.");
 	}
 	for (const relation of state.relations) {
@@ -237,7 +326,8 @@ async function plan(db, input) {
 			continue;
 		}
 		if (relation.owner !== contract.migrationOwner) unsupported("resource-owner", resource, `Managed resources must be owned by ${contract.migrationOwner}; ownership is never changed.`);
-		if (relation.kind !== "S" && !declared.has(relation.name)) unsupported("undeclared-table", resource, "The dedicated schema contains an undeclared table; defaults cannot safely cover a mixed schema.");
+		if (relation.kind !== "S" && !declared.has(relation.name) && !retained.has(relation.name)) unsupported("undeclared-table", resource, "The dedicated schema contains an undeclared table; defaults cannot safely cover a mixed schema.");
+		if (relation.kind === "S" && (!relation.parent_table || !declared.has(relation.parent_table) && !retained.has(relation.parent_table))) unsupported("undeclared-sequence", resource, "Sequences must belong to a declared managed or retained table before permission reconciliation.");
 		if (![
 			"r",
 			"p",
@@ -246,7 +336,7 @@ async function plan(db, input) {
 		if (relation.rls) unsupported("row-level-security", resource, "RLS policies require a separate application authorization review; ACL verification cannot establish allowed row operations.");
 		for (const role of roles) {
 			const isRuntime = role === contract.runtimeRole;
-			const desired = isRuntime ? relation.kind === "S" ? ["USAGE"] : bookkeeping.has(relation.name) ? ["SELECT"] : [
+			const desired = isRuntime ? relation.kind === "S" ? retained.has(relation.parent_table ?? "") ? [] : ["USAGE"] : retained.has(relation.name) ? [] : bookkeeping.has(relation.name) ? ["SELECT"] : [
 				"SELECT",
 				"INSERT",
 				"UPDATE",
@@ -254,12 +344,35 @@ async function plan(db, input) {
 			] : [];
 			reconcile(relation.kind === "S" ? "SEQUENCE" : "TABLE", resource, relation.acl, role, desired);
 			for (const column of columns) {
-				const wanted = !isRuntime && (contract.monitor?.tables[relation.name] ?? []).includes(column.name) ? ["SELECT"] : [];
+				const wanted = !isRuntime && !retained.has(relation.name) && (contract.monitor?.tables[relation.name] ?? []).includes(column.name) ? ["SELECT"] : [];
 				reconcile("TABLE", resource, column.acl, role, wanted, ` (${identifier(column.name)})`);
 			}
 		}
 	}
-	for (const category of ["routines", "types"]) for (const resource of state[category]) for (const role of roles) if (resource.schema === contract.schema || resource.owner === role || relevant(resource.acl, role).length) unsupported(`unsupported-${category}`, qualified(resource.schema, resource.name), `User-defined ${category} are outside the supported table/sequence contract; review their effective privileges explicitly.`, role);
+	const triggerRoutineNames = new Set(contract.managedTriggerFunctions);
+	const acceptedTriggerRoutineNames = /* @__PURE__ */ new Set();
+	const acceptedTriggerRoutineOids = /* @__PURE__ */ new Set();
+	const routineConfigIsEmpty = (value) => Array.isArray(value) && value.length === 0 || value === "[]";
+	for (const resource of state.routines) {
+		const resourceName = qualified(resource.schema, resource.name);
+		const framework = frameworkRoutines.find((expected) => resource.schema === contract.schema && resource.name === expected.name && normalizeArgumentTypes(resource.argument_types) === expected.argumentTypes);
+		if (framework) {
+			if (!(resource.owner === contract.migrationOwner && resource.kind === "f" && resource.language === "plpgsql" && resource.security_definer === false && resource.argument_defaults === framework.argumentDefaults && normalizeFunctionResult(resource.result) === framework.result && resource.cost === "100" && resource.rows === "1000" && resource.support === "-" && resource.volatility === "v" && resource.parallel === "u" && resource.leakproof === false && resource.strict === false && routineConfigIsEmpty(resource.config) && normalizeFunctionSource(String(resource.source)) === framework.source)) unsupported("framework-routine-definition", resourceName, "Framework routine must retain its canonical identity, owner, invoker security, defaults, execution properties, settings and generated body.");
+			else reconcileRoutine(resource.identity, resource.acl, /* @__PURE__ */ new Map([[contract.runtimeRole, ["EXECUTE"]]]));
+			continue;
+		}
+		const bindings = state.triggers.filter((trigger) => trigger.function_oid === resource.oid);
+		if (resource.schema === contract.schema && triggerRoutineNames.has(resource.name) && resource.kind === "f" && resource.return_type === "trigger" && resource.argument_types === "" && resource.argument_count === "0" && resource.owner === contract.migrationOwner && resource.language === "plpgsql" && resource.security_definer === false && routineConfigIsEmpty(resource.config) && bindings.length > 0 && bindings.every((trigger) => trigger.schema === contract.schema && trigger.internal === false && (trigger.enabled === "O" || trigger.enabled === "A") && declared.has(trigger.table_name))) {
+			acceptedTriggerRoutineNames.add(resource.name);
+			acceptedTriggerRoutineOids.add(resource.oid);
+			reconcileRoutine(resource.identity, resource.acl, /* @__PURE__ */ new Map());
+			continue;
+		}
+		for (const role of roles) if (resource.schema === contract.schema || resource.owner === role || relevant(resource.acl, role).length) unsupported("unsupported-routines", resourceName, triggerRoutineNames.has(resource.name) ? "Declared trigger routines must be migration-owner invoker PL/pgSQL functions returning trigger with no declared arguments, no function settings, and enabled non-internal bindings only to declared managed tables." : "User-defined routines are outside the supported table/sequence and declared trigger contract; review their effective privileges explicitly.", role);
+	}
+	for (const name of triggerRoutineNames) if (!acceptedTriggerRoutineNames.has(name)) unsupported("missing-managed-trigger-function", qualified(contract.schema, name), "Run the migration that creates this exact managed trigger function and its enabled binding before reconciling permissions.");
+	for (const trigger of state.triggers) if (trigger.schema === contract.schema && declared.has(trigger.table_name) && trigger.internal === false && (trigger.enabled === "O" || trigger.enabled === "A") && !acceptedTriggerRoutineOids.has(trigger.function_oid)) unsupported("unsupported-managed-trigger", `${qualified(trigger.schema, trigger.table_name)} (${trigger.name})`, "Enabled managed-table triggers must use an exact declared invoker trigger routine; undeclared or SECURITY DEFINER trigger functions can bypass retained-table isolation.");
+	for (const resource of state.types) for (const role of roles) if (resource.schema === contract.schema || resource.owner === role || relevant(resource.acl, role).length) unsupported("unsupported-types", qualified(resource.schema, resource.name), "User-defined types are outside the supported table/sequence contract; review their effective privileges explicitly.", role);
 	for (const defaults of state.defaults) {
 		const resource = `DEFAULT ${defaults.kind} (${defaults.schema || "global"})`;
 		if (defaults.owner !== contract.migrationOwner && defaults.acl.some((entry) => roles.includes(entry.grantee))) unsupported("other-creator-access", resource, `Creator ${defaults.owner} grants configured roles future access outside this contract.`);
@@ -313,7 +426,8 @@ async function plan(db, input) {
 			"Only PostgreSQL table, column, sequence, schema and database ACLs are qualified; application authorization and RLS are separate. Large-object ownership/access is unsupported, and lo_compat_privileges must remain off for deployed roles.",
 			"Future user-defined routines and types are unsupported. PostgreSQL implicit global defaults grant PUBLIC EXECUTE/USAGE; rerun diagnostics after every migration before activating runtime roles.",
 			"Pause migrations and external ACL/role writers during planning and apply. The advisory lock coordinates SMRT permission writers only.",
-			"All framework bookkeeping tables must exist before setup. Stop runtime and monitor access throughout migrations, restores and repair: recreated bookkeeping tables temporarily receive creator CRUD defaults and require explicit reconciliation before either role is reactivated."
+			"All framework bookkeeping tables must exist before setup. Stop runtime and monitor access throughout migrations, restores and repair: recreated bookkeeping tables temporarily receive creator CRUD defaults and require explicit reconciliation before either role is reactivated.",
+			"Retained tables are operator-owned data outside the runtime and monitor surfaces. Creator defaults initially grant runtime access to every new table and sequence, so create or restore every retained table first, then apply its reviewed plan and verify access is revoked before reactivating restricted roles."
 		],
 		statements: [...new Set(statements)],
 		canApply: !diagnostics.some((entry) => entry.severity === "unsupported"),
@@ -329,20 +443,20 @@ async function planPostgresPermissions(db, contract) {
 }
 /** Apply the reviewed contract atomically, rejecting stale catalog snapshots. */
 async function applyPostgresPermissions(db, contract, options) {
-	validatePostgresPermissionContract(contract);
+	const normalizedContract = validatePostgresPermissionContract(contract);
 	if (!options || !/^[a-f0-9]{64}$/.test(options.expectedFingerprint)) throw new Error("An expectedFingerprint from a reviewed permission plan is required.");
 	if (!db.transaction) throw new Error("PostgreSQL permissions require a transaction-capable database.");
 	return db.transaction(async (tx) => {
 		await tx.query("SET LOCAL lock_timeout = '5s'");
 		await tx.query("SET LOCAL statement_timeout = '30s'");
-		await tx.query(`SELECT pg_advisory_xact_lock(hashtext(${literal(`smrt-permissions:${contract.schema}`)}))`);
-		const before = await plan(tx, contract);
+		await tx.query(`SELECT pg_advisory_xact_lock(hashtext(${literal(`smrt-permissions:${normalizedContract.schema}`)}))`);
+		const before = await plan(tx, normalizedContract);
 		if (before.fingerprint !== options.expectedFingerprint) throw new Error("Permission plan is stale; generate and review a new plan.");
 		if (!before.canApply) throw new Error("Permission plan has unsupported privilege sources or missing prerequisites; resolve its diagnostics first.");
 		const executor = (await tx.query("SELECT current_user AS name, rolsuper FROM pg_roles WHERE rolname=current_user")).rows[0];
-		if (!executor.rolsuper && executor.name !== contract.migrationOwner) throw new Error("Apply must execute as the migration owner or a PostgreSQL superuser.");
+		if (!executor.rolsuper && executor.name !== normalizedContract.migrationOwner) throw new Error("Apply must execute as the migration owner or a PostgreSQL superuser.");
 		for (const statement of before.statements) await tx.query(statement);
-		const after = await plan(tx, contract);
+		const after = await plan(tx, normalizedContract);
 		if (!after.canApply || after.diagnostics.length) throw new Error("Permission verification failed; all permission changes have been rolled back.");
 		return after;
 	});