@everystack/cli 0.4.100 → 0.4.103

package/src/cli/lifecycle-pull.ts

@@ -0,0 +1,252 @@
+/**
+ * db:pull's lifecycle fold — reads a lifecycle table back as `lifecycle: true`.
+ *
+ * `lifecycle: true` generates, per table: four columns, the reserved role's grants and policies,
+ * a `deleted_at IS NULL` guard on every other role's SELECT policy, and two functions, a restore
+ * function and two triggers. A pull that transcribed them would render the reserved role as an
+ * authored ability and the columns as authored fields (defineModel refuses both), and the five
+ * objects as derived descriptors (they would be generated twice).
+ *
+ * So the fold removes all of it from the pull's inputs, and the renderer writes `lifecycle: true`.
+ * It folds a table only when the catalog holds EXACTLY what the compiler writes: the four columns
+ * as generated, the reserved role's grants and policies equal to a compiled lifecycle model's, the
+ * role in no other policy, and the guard at the head of every other SELECT policy. Anything else is left as is, so the pull renders what is there and the model's own
+ * refusal names it. The generated objects are removed by name; a hand-edited body still shows,
+ * because the derived plan compares definitions.
+ *
+ * Pure: inputs in, folded copies out.
+ */
+
+import { defineModel, field, LIFECYCLE_OWNER_ROLE, type ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot, TableSchema } from './schema-introspect';
+import type { AuthzContract, PolicyContract, TableContract } from './authz-contract';
+import type { DerivedCatalog } from './derived-introspect';
+import { compileTableContract } from './authz-compile';
+import { lifecycleFkIndexName } from './schema-compile';
+
+/** The generated columns as the catalog reports them (`format_type`), nullable, no default. */
+const GENERATED_COLUMNS: Record<string, string> = {
+  deleted_at: 'timestamp with time zone',
+  deleted_by: 'text',
+  deleted_batch: 'uuid',
+  deleted_xid: 'bigint',
+};
+
+const GUARD = '(deleted_at IS NULL)';
+const DELETED_ONLY = '(deleted_at IS NOT NULL)';
+
+/** The commands the measured effective matrix reports (`effectivePrivileges`). */
+const EFFECTIVE_COMMANDS = new Set(['SELECT', 'INSERT', 'UPDATE', 'DELETE']);
+
+export interface LifecycleFold {
+  snapshot: SchemaSnapshot;
+  contract: AuthzContract;
+  catalog: DerivedCatalog;
+  /** Schema-qualified tables folded to `lifecycle: true`. */
+  tables: Set<string>;
+  /** lifecycle: { deleteWhen }'s predicate per folded table, read from its delete_when function's manifest. */
+  deleteWhen: Map<string, string>;
+}
+
+const split = (qualified: string): { schema: string; name: string } => {
+  const dot = qualified.indexOf('.');
+  return dot < 0 ? { schema: 'public', name: qualified } : { schema: qualified.slice(0, dot), name: qualified.slice(dot + 1) };
+};
+
+const sorted = (xs: readonly string[] | undefined): string => JSON.stringify([...(xs ?? [])].sort());
+
+const policyKey = (p: PolicyContract): string =>
+  JSON.stringify([p.name, p.command, [...p.roles].sort(), p.permissive, p.using, p.check]);
+
+/** The reserved role's part of a compiled lifecycle model — what an exact table must hold live. */
+function reservedRoleContract(qualified: string): TableContract {
+  const { schema, name } = split(qualified);
+  const model: ModelDescriptor = defineModel(name, { schema, lifecycle: true, fields: { id: field.integer().primaryKey() } });
+  return compileTableContract(model);
+}
+
+/**
+ * The SELECT policy's text with the guard removed (null: nothing else), or undefined when it does
+ * not carry the guard as compiled. The compiler puts the guard first in a top-level AND, and
+ * PostgreSQL deparses an AND as `((a) AND (b) …)`, so the guard is exactly this prefix.
+ */
+function unguarded(using: string | null): string | null | undefined {
+  if (using === GUARD) return null;
+  if (using?.startsWith(`(${GUARD} AND `) && using.endsWith(')')) return using.slice(GUARD.length + 6, -1);
+  return undefined;
+}
+
+function columnsAreGenerated(table: TableSchema): boolean {
+  return Object.entries(GENERATED_COLUMNS).every(([name, type]) => {
+    const c = table.columns.find((col) => col.name === name);
+    return c !== undefined && c.type === type && !c.notNull && c.default === null;
+  });
+}
+
+/** The lifecycle columns a deleted reader is never granted (compileColumnGrants). */
+const DELETED_READ_HIDDEN = new Set(['deleted_by', 'deleted_batch', 'deleted_xid']);
+
+/**
+ * can('read', { role, deleted }) with no columns compiles to a column SELECT of every column but
+ * deleted_by, deleted_batch and deleted_xid. Fold exactly that grant back to the table SELECT the
+ * renderer reads as a plain role read, so the pull renders `deleted` without a columns list; the
+ * compile turns it back into the same column grant. Any other column set stays as it is.
+ */
+function foldDeletedReadGrants(folded: TableContract, table: TableSchema): void {
+  const every = sorted(table.columns.map((c) => c.name).filter((name) => !DELETED_READ_HIDDEN.has(name)));
+  for (const p of folded.policies) {
+    if (p.deleted === undefined || p.roles.length !== 1) continue;
+    const role = p.roles[0];
+    const cols = folded.columnGrants?.[role];
+    if (!cols || folded.grants[role]?.includes('SELECT') || sorted(cols.SELECT) !== every) continue;
+    folded.grants = { ...folded.grants, [role]: [...(folded.grants[role] ?? []), 'SELECT'].sort() };
+    const { SELECT: _select, ...rest } = cols;
+    const { [role]: _role, ...others } = folded.columnGrants!;
+    folded.columnGrants = Object.keys(rest).length ? { ...others, [role]: rest } : others;
+  }
+}
+
+/** The folded contract for one table, or undefined when the table is not exactly lifecycle. */
+function foldContract(live: TableContract, table: TableSchema): TableContract | undefined {
+  const role = LIFECYCLE_OWNER_ROLE;
+  const expected = reservedRoleContract(live.table);
+  if (sorted(live.grants[role]) !== sorted(expected.grants[role])) return undefined;
+  const liveCols = live.columnGrants?.[role] ?? {};
+  const expectedCols = expected.columnGrants?.[role] ?? {};
+  if (sorted(Object.keys(liveCols)) !== sorted(Object.keys(expectedCols))) return undefined;
+  if (Object.keys(expectedCols).some((priv) => sorted(liveCols[priv]) !== sorted(expectedCols[priv]))) return undefined;
+  // The direct ACL matching is not enough: the role can hold more through membership or PUBLIC.
+  // When the live read measured it, the role must hold exactly the commands its compiled grants
+  // imply (a column grant counts as its command). Absent = not measured: the direct check stands.
+  // A grant to PUBLIC on the table widens the measured set too, so such a table stays unfolded:
+  // the check errs toward not folding, never toward a false fold.
+  if (live.effectivePrivileges) {
+    const implied = new Set([...(expected.grants[role] ?? []), ...Object.keys(expectedCols)].filter((p) => EFFECTIVE_COMMANDS.has(p)));
+    if (sorted(live.effectivePrivileges[role]) !== sorted([...implied])) return undefined;
+  }
+
+  const naming = (p: PolicyContract) => p.roles.includes(role);
+  const livePolicies = live.policies.filter(naming);
+  const expectedPolicies = expected.policies.filter(naming);
+  if (sorted(livePolicies.map(policyKey)) !== sorted(expectedPolicies.map(policyKey))) return undefined;
+
+  const policies: PolicyContract[] = [];
+  for (const p of live.policies) {
+    if (naming(p)) continue;
+    if (p.command !== 'SELECT') {
+      policies.push(p);
+      continue;
+    }
+    const rest = unguarded(p.using);
+    if (rest !== undefined) {
+      policies.push({ ...p, using: rest ?? 'true' });
+      continue;
+    }
+    // can('read', { role, deleted }): a role's own read policy compiled without the guard
+    // ('include') or with (deleted_at IS NOT NULL) in its place ('only'). Any other SELECT policy
+    // without the guard leaves the table unfolded, as before.
+    const own = p.roles.length === 1 && !['anon', 'authenticated', 'public'].includes(p.roles[0])
+      && p.name === `${split(live.table).name}_select_${p.roles[0]}`;
+    if (!own) return undefined;
+    if (p.using === DELETED_ONLY) policies.push({ ...p, using: 'true', deleted: 'only' });
+    else if (p.using?.startsWith(`(${DELETED_ONLY} AND `) && p.using.endsWith(')')) {
+      policies.push({ ...p, using: p.using.slice(DELETED_ONLY.length + 6, -1), deleted: 'only' });
+    } else policies.push({ ...p, deleted: 'include' });
+  }
+
+  const { [role]: _grant, ...grants } = live.grants;
+  const folded: TableContract = { ...live, grants, policies };
+  if (live.columnGrants) {
+    const { [role]: _cols, ...columnGrants } = live.columnGrants;
+    folded.columnGrants = columnGrants;
+  }
+  if (live.effectivePrivileges) {
+    const { [role]: _eff, ...effectivePrivileges } = live.effectivePrivileges;
+    folded.effectivePrivileges = effectivePrivileges;
+  }
+  foldDeletedReadGrants(folded, table);
+  return folded;
+}
+
+/**
+ * The five generated objects of one lifecycle table, exactly as the derived catalog keys them. The
+ * restore takes the primary key, and a function signature carries no type modifier
+ * (`character varying(255)` is `character varying` there). An author's own overload stays.
+ */
+function generatedIdentities(table: TableSchema): string[] {
+  const { schema, name } = split(table.table);
+  const pk = table.columns.find((c) => c.name === table.primaryKey[0]);
+  const arg = (pk?.type ?? '').replace(/\(\d+(,\s*\d+)?\)/g, '');
+  return [
+    `${schema}.${name}_lifecycle_transition()`,
+    `${schema}.${name}_lifecycle_guard()`,
+    `${schema}.${name}_restore(${arg})`,
+    `${table.table}.${name}_lifecycle_transition`,
+    `${table.table}.${name}_lifecycle_guard`,
+    `${schema}.${name}_lifecycle_delete_when()`,
+    `${table.table}.${name}_lifecycle_delete_when`,
+  ];
+}
+
+/**
+ * The generator's lifecycle FK index (lifecycleDependentIndexes): plain btree, exactly the columns of
+ * a foreign key into a folded lifecycle table, under exactly the generated name. Folded like the
+ * lifecycle columns, so the pull never renders it as an author index. Anything else stays.
+ */
+function withoutGeneratedFkIndexes(t: TableSchema, lifecycleTables: ReadonlySet<string>): TableSchema {
+  const name = t.table.slice(t.table.indexOf('.') + 1);
+  const indexes = t.indexes.filter((ix) => !(
+    !ix.unique && !ix.where && !ix.using && !ix.include?.length
+    && ix.name === lifecycleFkIndexName(name, ix.columns)
+    && t.foreignKeys.some((fk) => lifecycleTables.has(fk.refTable.includes('.') ? fk.refTable : `public.${fk.refTable}`)
+      && JSON.stringify(fk.columns) === JSON.stringify(ix.columns))));
+  return indexes.length === t.indexes.length ? t : { ...t, indexes };
+}
+
+export function foldLifecycle(snapshot: SchemaSnapshot, contract: AuthzContract, catalog: DerivedCatalog): LifecycleFold {
+  const tables = new Set<string>();
+  const foldedContracts = new Map<string, TableContract>();
+  for (const table of snapshot.tables) {
+    if (table.primaryKey.length !== 1 || !columnsAreGenerated(table)) continue;
+    const live = contract.tables.find((t) => t.table === table.table);
+    const folded = live && live.rls.enabled ? foldContract(live, table) : undefined;
+    if (!folded) continue;
+    tables.add(table.table);
+    foldedContracts.set(table.table, folded);
+  }
+  if (tables.size === 0) return { snapshot, contract, catalog, tables, deleteWhen: new Map() };
+
+  // A guarded table's predicate is the delete_when function's manifest input. The pull must render
+  // exactly that text, or the next plan would rebuild the guard; without it, refuse rather than drop
+  // the guard or render it as an author function.
+  const deleteWhen = new Map<string, string>();
+  for (const table of tables) {
+    const { schema, name } = split(table);
+    const fn = catalog.objects.find((o) => o.kind === 'function' && o.identity === `${schema}.${name}_lifecycle_delete_when()`);
+    if (!fn) continue;
+    let manifest: { role?: unknown; model?: unknown; deleteWhen?: unknown } | undefined;
+    try { manifest = typeof fn.comment === 'string' ? JSON.parse(fn.comment) : undefined; } catch { manifest = undefined; }
+    if (!manifest || manifest.role !== 'delete_when' || manifest.model !== table || typeof manifest.deleteWhen !== 'string' || manifest.deleteWhen.trim() === '') {
+      throw new Error(`db:pull: ${fn.identity} carries no readable deleteWhen in its lifecycle manifest, so ${table}'s lifecycle: { deleteWhen } `
+        + `cannot be rendered exactly. Run db:apply from the checkout that declared it (it rewrites the manifest), then pull again.`);
+    }
+    deleteWhen.set(table, manifest.deleteWhen);
+  }
+
+  const generated = new Set(snapshot.tables.filter((t) => tables.has(t.table)).flatMap(generatedIdentities));
+  return {
+    snapshot: {
+      ...snapshot,
+      tables: snapshot.tables.map((t) => withoutGeneratedFkIndexes(
+        tables.has(t.table) ? { ...t, columns: t.columns.filter((c) => !Object.hasOwn(GENERATED_COLUMNS, c.name)) } : t, tables)),
+    },
+    contract: { ...contract, tables: contract.tables.map((t) => foldedContracts.get(t.table) ?? t) },
+    catalog: {
+      objects: catalog.objects.filter((o) => !generated.has(o.identity)),
+      edges: catalog.edges.filter((e) => !generated.has(e.dependent) && !generated.has(e.referenced)),
+      provenance: catalog.provenance.filter((p) => !generated.has(p.identity)),
+    },
+    tables,
+    deleteWhen,
+  };
+}

package/src/cli/lifecycle-verify.ts

@@ -0,0 +1,238 @@
+/** Fail-closed verification of generated lifecycle definitions before db:pull writes. */
+import { LIFECYCLE_OWNER_ROLE, parseQualified, type FunctionDescriptor } from '@everystack/model';
+import { canonHash, canonOfFunction, type FunctionCanon } from './lifecycle-canon';
+import { regenerateLifecycle, lifecycleRole, MANIFEST_VERSION, LIFECYCLE_ROLES, type LifecycleDeclaration, type LifecycleManifest, type LifecycleTrigger } from './lifecycle-derived';
+import { normalizeArgType } from './pg-argtypes';
+import { parseTriggerType } from './derived-introspect';
+import { normalizeDeparsedExpr } from './deparse-normal';
+import { INTROSPECTION_SESSION, type SessionRunner } from './session';
+
+const FUNCTIONS = `SELECT n.nspname AS schema, p.proname AS name,
+ n.nspname || '.' || p.proname || '(' || coalesce((SELECT string_agg(format_type(t, NULL), ', ' ORDER BY o) FROM unnest(p.proargtypes::oid[]) WITH ORDINALITY x(t,o)), '') || ')' AS identity,
+ ARRAY(SELECT format_type(t,NULL) FROM unnest(p.proargtypes::oid[]) WITH ORDINALITY x(t,o) ORDER BY o) AS arg_types,
+ pg_get_function_arguments(p.oid) AS args, pg_get_function_result(p.oid) AS returns,
+ l.lanname AS language,p.prosecdef AS secdef,p.provolatile::text AS volatility,p.proisstrict AS strict,p.proleakproof AS leakproof,
+ coalesce(p.proconfig,'{}'::text[]) AS config,pg_get_userbyid(p.proowner) AS owner,p.prosrc AS body,obj_description(p.oid,'pg_proc') AS comment,
+ coalesce((SELECT array_agg(DISTINCT coalesce(g.rolname,'PUBLIC') ORDER BY coalesce(g.rolname,'PUBLIC'))
+  FROM aclexplode(coalesce(p.proacl,acldefault('f',p.proowner))) a LEFT JOIN pg_roles g ON g.oid=a.grantee
+  WHERE a.grantee<>p.proowner AND a.privilege_type='EXECUTE'),'{}'::name[])::text[] AS execute
+ FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace JOIN pg_language l ON l.oid=p.prolang
+ WHERE p.prokind IN ('f','p') AND n.nspname NOT IN ('pg_catalog','information_schema') AND n.nspname NOT LIKE 'pg_%'
+ AND NOT EXISTS(SELECT 1 FROM pg_depend d WHERE d.objid=p.oid AND d.deptype='e')`;
+const TRIGGERS = `SELECT n.nspname||'.'||c.relname AS "table",t.tgname AS name,t.tgtype::int AS type,t.tgenabled::text AS enabled,
+ t.tgconstraint<>0 AS is_constraint,t.tgdeferrable AS deferrable,t.tginitdeferred AS initially_deferred,
+ fn.nspname||'.'||p.proname AS fn,substring(pg_get_triggerdef(t.oid) from ' WHEN [(](.*)[)] EXECUTE ') AS when_expr,
+ coalesce((SELECT array_agg(a.attname::text ORDER BY x.ord) FROM unnest(t.tgattr::int2[]) WITH ORDINALITY x(attnum,ord)
+ JOIN pg_attribute a ON a.attrelid=t.tgrelid AND a.attnum=x.attnum),'{}'::text[]) AS update_of,encode(t.tgargs,'hex') AS args
+ FROM pg_trigger t JOIN pg_class c ON c.oid=t.tgrelid JOIN pg_namespace n ON n.oid=c.relnamespace
+ JOIN pg_proc p ON p.oid=t.tgfoid JOIN pg_namespace fn ON fn.oid=p.pronamespace
+ WHERE NOT t.tgisinternal AND n.nspname NOT IN ('pg_catalog','information_schema') AND n.nspname NOT LIKE 'pg_%'`;
+const TABLES = `SELECT n.nspname||'.'||c.relname AS identity,
+ coalesce((SELECT jsonb_agg(jsonb_build_object('role',coalesce(r.rolname,'PUBLIC'),
+ 'predicate',coalesce(pg_get_expr(p.polqual,p.polrelid),'true'),'permissive',p.polpermissive) ORDER BY p.polname,r.rolname)
+ FROM pg_policy p CROSS JOIN LATERAL unnest(p.polroles) role(oid) LEFT JOIN pg_roles r ON r.oid=role.oid
+ WHERE p.polrelid=c.oid AND p.polcmd IN ('d','*') AND r.rolname IS DISTINCT FROM 'everystack_lifecycle'),'[]'::jsonb) AS delete_policies,
+ ARRAY(SELECT a.attname::text FROM unnest(k.conkey) WITH ORDINALITY x(num,ord) JOIN pg_attribute a ON a.attrelid=c.oid AND a.attnum=x.num ORDER BY x.ord) AS pk_columns,
+ ARRAY(SELECT format_type(a.atttypid,a.atttypmod) FROM unnest(k.conkey) WITH ORDINALITY x(num,ord) JOIN pg_attribute a ON a.attrelid=c.oid AND a.attnum=x.num ORDER BY x.ord) AS pk_types,
+ EXISTS(SELECT 1 FROM pg_index i WHERE i.indrelid=c.oid AND i.indisunique AND NOT i.indisprimary) AS unique,
+ ((SELECT count(*)=4 FROM pg_attribute a WHERE a.attrelid=c.oid AND NOT a.attisdropped AND a.attname IN ('deleted_at','deleted_by','deleted_batch','deleted_xid'))
+ AND EXISTS(SELECT 1 FROM aclexplode(coalesce(c.relacl,acldefault('r',c.relowner))) a JOIN pg_roles r ON r.oid=a.grantee
+ WHERE r.rolname='everystack_lifecycle' AND a.privilege_type='DELETE')) AS lifecycle
+ FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace LEFT JOIN pg_constraint k ON k.conrelid=c.oid AND k.contype='p'
+ WHERE c.relkind IN ('r','p') AND n.nspname NOT IN ('pg_catalog','information_schema') AND n.nspname NOT LIKE 'pg_%'`;
+const EDGES = `SELECT pn.nspname||'.'||p.relname AS parent,cn.nspname||'.'||c.relname AS child,
+ ARRAY(SELECT a.attname::text FROM unnest(f.conkey) WITH ORDINALITY x(num,ord) JOIN pg_attribute a ON a.attrelid=c.oid AND a.attnum=x.num ORDER BY x.ord) AS columns,
+ ARRAY(SELECT a.attname::text FROM unnest(f.confkey) WITH ORDINALITY x(num,ord) JOIN pg_attribute a ON a.attrelid=p.oid AND a.attnum=x.num ORDER BY x.ord) AS references,
+ f.confdeltype::text AS action FROM pg_constraint f JOIN pg_class c ON c.oid=f.conrelid JOIN pg_namespace cn ON cn.oid=c.relnamespace
+ JOIN pg_class p ON p.oid=f.confrelid JOIN pg_namespace pn ON pn.oid=p.relnamespace WHERE f.contype='f'`;
+
+type Row = Record<string, unknown>;
+const record = (value: unknown): value is Row => value !== null && typeof value === 'object' && !Array.isArray(value);
+const strings = (value: unknown): string[] => Array.isArray(value) ? value.map(String) : [];
+const same = (a: unknown, b: unknown): boolean => canonHash(a) === canonHash(b);
+const hint = 'missing lifecycle manifest; db:apply for a managed install; db:reconcile --baseline for a brownfield object with no provenance (use --apply to persist)';
+
+interface TriggerCanon { kind: 'trigger'; identity: string; table: string; timing: string; events: string[]; forEach: string; fn: string; when: string | null; updateOf: string[]; args: string; enabled: string; constraint: boolean; deferrable: boolean; initiallyDeferred: boolean; }
+interface LiveFunction { name: string; argTypes: string[]; canon: FunctionCanon; comment: unknown; }
+export interface LifecycleVerdict { failures: string[]; notes: string[]; }
+export class LifecycleDriftError extends Error {
+  constructor(readonly lines: string[]) { super('lifecycle verification failed'); }
+}
+
+/** Only the two fixed generated WHEN expressions need catalog spelling normalization. */
+/** A trigger WHEN, normalised so the generated text and PostgreSQL's deparse compare equal. Exported for tests. */
+export function whenExpression(value: string | null): string | null {
+  if (value === null) return null;
+  const text = value.replace(new RegExp(`'${LIFECYCLE_OWNER_ROLE}'::name`, 'g'), `'${LIFECYCLE_OWNER_ROLE}'`);
+  const tokens = text.match(/'(?:[^']|'')*'|"(?:[^"]|"")*"|[^'"]+/g) ?? [];
+  return tokens.map(token => {
+    if (token.startsWith("'")) return token;
+    if (token.startsWith('"')) return token === '"deleted_at"' ? 'deleted_at' : token;
+    // PostgreSQL deparses a pg_catalog function unqualified; the generator writes it qualified.
+    // Drop only a WHOLE `pg_catalog.` qualifier, on the raw token (before spaces go, or `OR pg_catalog.`
+    // would fuse into `orpg_catalog.`): not after a name character, a dot or a quote, so
+    // `ppg_catalog.g_trigger_depth` and `x.pg_catalog.f` keep their text and show as drift.
+    return token.replace(/(?<![A-Za-z0-9_$."])pg_catalog\./gi, '').replace(/[()\s]/g, '').toLowerCase();
+  }).join('');
+}
+function canonOfTrigger(trigger: LifecycleTrigger): TriggerCanon {
+  return { kind: 'trigger', identity: `${trigger.on.schema}.${trigger.on.table}.${trigger.name}`, table: `${trigger.on.schema}.${trigger.on.table}`, timing: trigger.timing,
+    events: trigger.events, forEach: trigger.forEach, fn: trigger.execute.name, when: whenExpression(trigger.condition ?? null),
+    updateOf: trigger.of ?? [], args: '', enabled: 'O', constraint: false, deferrable: false, initiallyDeferred: false };
+}
+function typeIdentity(type: string): string {
+  return normalizeArgType(type) + '|' + (type.match(/\([^)]*\)/g) ?? []).join('').replace(/\s+/g, '');
+}
+function declaration(value: unknown): value is LifecycleDeclaration {
+  if (!record(value) || !record(value.tables) || !Array.isArray(value.edges)) return false;
+  for (const [id, table] of Object.entries(value.tables)) {
+    if (!record(table) || typeof table.schema !== 'string' || typeof table.table !== 'string' || id !== `${table.schema}.${table.table}`
+      || !record(table.pk) || typeof table.pk.column !== 'string' || typeof table.pk.type !== 'string'
+      || typeof table.unique !== 'boolean' || !record(table.auth) || Object.values(table.auth).some(p => typeof p !== 'string')) return false;
+  }
+  return value.edges.every(edge => record(edge) && typeof edge.parent === 'string' && typeof edge.child === 'string'
+    && typeof edge.column === 'string' && (edge.dependent === 'cascade' || edge.dependent === 'restrict'));
+}
+
+/** Fold catalog policies by role exactly as the compiler records DELETE/ALL rules. */
+function sameDeleteRules(auth: Record<string, string>, policies: unknown): boolean {
+  if (!Array.isArray(policies)) return false;
+  const byRole = new Map<string, string[]>();
+  for (const policy of policies) {
+    if (!record(policy) || typeof policy.role !== 'string' || typeof policy.predicate !== 'string' || policy.permissive !== true) return false;
+    const predicates = byRole.get(policy.role) ?? [];
+    predicates.push(normalizeDeparsedExpr(policy.predicate));
+    byRole.set(policy.role, predicates);
+  }
+  const live = Object.fromEntries([...byRole].map(([role, predicates]) => [role,
+    predicates.length === 1 ? predicates[0] : predicates.map(p => `(${p})`).join(' OR ')]));
+  const declared = Object.fromEntries(Object.entries(auth).map(([role, predicate]) => [role, normalizeDeparsedExpr(predicate)]));
+  return same(declared, live);
+}
+
+/**
+ * An older CLI generated a per-row `<t>_lifecycle_restrict` function (manifest role 'restrict') and
+ * BEFORE DELETE trigger; the restrict check now lives in the transition. That pair is stale output,
+ * not a malformed manifest or an author trigger: say so, and name the remedy.
+ */
+const OLD_RESTRICT = 'stale, generated by an older CLI: run db:apply to remove the old restrict function and trigger';
+const oldRestrictName = (table: string): string => `${table}_lifecycle_restrict`;
+
+/** Four catalog reads share one read-only snapshot. No function bodies or generated SQL execute. */
+export async function verifyLifecycle(session: SessionRunner, governedRoles: readonly string[] = ['anon', 'authenticated', 'admin', LIFECYCLE_OWNER_ROLE]): Promise<LifecycleVerdict> {
+  const results = await session([FUNCTIONS, TRIGGERS, TABLES, EDGES], INTROSPECTION_SESSION);
+  if (results.length !== 4 || results.some(rows => !Array.isArray(rows))) throw new Error('lifecycle catalog could not be read completely');
+  const [functions, triggers, tables, edges] = results as Row[][];
+  const problems = new Map<string, string>();
+  const add = (id: string, reason: string): void => { if (!problems.has(id)) problems.set(id, `drift: ${id}: ${reason}`); };
+  const notes = new Set<string>();
+  const tableById = new Map(tables.map(t => [String(t.identity), t]));
+  const lifecycleTables = new Set(tables.filter(t => t.lifecycle === true).map(t => String(t.identity)));
+  const liveFunctions = new Map<string, LiveFunction>();
+  for (const row of functions) {
+    const canon: FunctionCanon = { kind: 'function', identity: String(row.identity), args: String(row.args), returns: String(row.returns),
+      language: String(row.language), secdef: row.secdef === true, volatility: String(row.volatility), strict: row.strict === true, leakproof: row.leakproof === true,
+      config: strings(row.config), owner: String(row.owner), execute: strings(row.execute).sort(), body: String(row.body) };
+    liveFunctions.set(canon.identity, { name: `${row.schema}.${row.name}`, canon, argTypes: strings(row.arg_types), comment: row.comment });
+  }
+  const liveTriggers = new Map<string, TriggerCanon>();
+  const triggerTypes = new Map<string, number>();
+  for (const row of triggers) {
+    const shape = parseTriggerType(Number(row.type));
+    const canon: TriggerCanon = { kind: 'trigger', identity: `${row.table}.${row.name}`, table: String(row.table), timing: shape.timing, events: shape.events, forEach: shape.forEach,
+      fn: String(row.fn), when: whenExpression(row.when_expr == null ? null : String(row.when_expr)), updateOf: strings(row.update_of), args: String(row.args), enabled: String(row.enabled),
+      constraint: row.is_constraint === true, deferrable: row.deferrable === true, initiallyDeferred: row.initially_deferred === true };
+    liveTriggers.set(canon.identity, canon);
+    triggerTypes.set(canon.identity, Number(row.type));
+  }
+  const familyByName = (live: LiveFunction): boolean => [...lifecycleTables].some(model => {
+    if (live.name.startsWith(`${model}_lifecycle_`)) return true;
+    const pkTypes = strings(tableById.get(model)?.pk_types);
+    return live.name === `${model}_restore` && live.argTypes.length === 1 && pkTypes.length === 1
+      && normalizeArgType(live.argTypes[0]) === normalizeArgType(pkTypes[0]);
+  });
+  const manifests = new Map<string, LifecycleManifest>();
+  /** lifecycle: { deleteWhen }'s predicate per model, from its delete_when function's own manifest. */
+  const deleteWhenOf = new Map<string, string>();
+  const groups = new Map<string, { decl: LifecycleDeclaration; from: string }>();
+  for (const [id, live] of liveFunctions) {
+    let raw: unknown;
+    try { raw = typeof live.comment === 'string' ? JSON.parse(live.comment) : undefined; } catch {
+      if (live.canon.owner === LIFECYCLE_OWNER_ROLE || familyByName(live)) add(id, 'malformed lifecycle manifest');
+      continue;
+    }
+    const family = live.canon.owner === LIFECYCLE_OWNER_ROLE || (record(raw) && raw.everystack === 'lifecycle')
+      || familyByName(live);
+    if (!family) continue;
+    if (!record(raw) || raw.everystack !== 'lifecycle') { add(id, hint); continue; }
+    if (raw.v !== MANIFEST_VERSION) { add(id, `unsupported lifecycle manifest v${String(raw.v)}; this CLI emits v${MANIFEST_VERSION}; re-apply`); continue; }
+    if (raw.role === 'restrict' && typeof raw.model === 'string' && lifecycleTables.has(raw.model) && live.name === oldRestrictName(raw.model)) { add(id, OLD_RESTRICT); continue; }
+    if (typeof raw.model !== 'string' || !declaration(raw.decl) || typeof raw.role !== 'string' || !(LIFECYCLE_ROLES as readonly string[]).includes(raw.role)
+      || typeof raw.defHash !== 'string' || !/^[a-f0-9]{64}$/.test(raw.defHash) || !raw.decl.tables[raw.model]) { add(id, 'malformed lifecycle manifest'); continue; }
+    if (lifecycleRole(live.name, raw.model) !== raw.role) { add(id, 'manifest role does not match function name'); continue; }
+    const manifest = raw as unknown as LifecycleManifest;
+    if (manifest.role === 'delete_when') {
+      if (typeof manifest.deleteWhen !== 'string' || manifest.deleteWhen.trim() === '') { add(id, 'malformed lifecycle manifest'); continue; }
+      deleteWhenOf.set(manifest.model, manifest.deleteWhen);
+    }
+    manifests.set(id, manifest);
+    const prev = groups.get(manifest.model);
+    if (prev && JSON.stringify(prev.decl) !== JSON.stringify(manifest.decl)) add(id, `conflicting declarations for ${manifest.model}`);
+    else if (!prev) groups.set(manifest.model, { decl: manifest.decl, from: id });
+  }
+  for (const table of lifecycleTables) if (!groups.has(table)) add(table, hint);
+
+  const expectedFunctions = new Map<string, FunctionDescriptor>();
+  const expectedTriggers = new Map<string, TriggerCanon>();
+  for (const [model, { decl, from }] of groups) {
+    // The catalog is an independent input: a self-consistent comment and body cannot erase a unique index.
+    for (const [id, input] of Object.entries(decl.tables)) {
+      const actual = tableById.get(id);
+      if (!actual) { add(id, 'declared table missing from catalog'); continue; }
+      if (!same(strings(actual.pk_columns), [input.pk.column]) || !same(strings(actual.pk_types).map(typeIdentity), [typeIdentity(input.pk.type)])) add(id, 'primary key differs from catalog');
+      if (actual.unique !== input.unique) add(id, 'unique flag differs from catalog');
+      if (!sameDeleteRules(input.auth, actual.delete_policies)) add(id, 'delete rule in the manifest does not match the live policies');
+      for (const role of Object.keys(input.auth)) if (!governedRoles.includes(role)) notes.add(`ungoverned role ${role} in lifecycle manifest ${model}`);
+    }
+    for (const edge of decl.edges) {
+      const parent = tableById.get(edge.parent);
+      const child = decl.tables[edge.child] ?? (() => { const { schema, name: table } = parseQualified(edge.child); return { schema, table }; })();
+      if (!edges.some(actual => actual.parent === edge.parent && actual.child === `${child.schema}.${child.table}` && same(strings(actual.columns), [edge.column])
+        && same(strings(actual.references), strings(parent?.pk_columns)) && actual.action === 'r')) add(`${edge.child}.${edge.column}`, 'foreign key differs from catalog');
+    }
+    let objects;
+    try { objects = regenerateLifecycle(model, decl, deleteWhenOf.get(model)); } catch { add(from, 'malformed declaration cannot regenerate'); continue; }
+    for (const object of objects) {
+      if (object.kind === 'function') expectedFunctions.set(canonOfFunction(object).identity, object);
+      else { const canon = canonOfTrigger(object); expectedTriggers.set(canon.identity, canon); }
+    }
+  }
+  for (const [id, expected] of expectedFunctions) {
+    const actual = liveFunctions.get(id);
+    if (!actual) { add(id, 'missing generated function'); continue; }
+    const manifest = manifests.get(id);
+    if (!manifest) { add(id, hint); continue; }
+    const liveHash = canonHash(actual.canon);
+    if (manifest.defHash !== liveHash) { add(id, 'drifted, live definition differs from its recorded hash'); continue; }
+    if (canonHash(canonOfFunction(expected)) !== liveHash) add(id, 'stale, re-apply');
+  }
+  for (const [id] of manifests) if (!expectedFunctions.has(id)) add(id, 'unlisted function in lifecycle family');
+  for (const [id, expected] of expectedTriggers) {
+    const actual = liveTriggers.get(id);
+    if (!actual) add(id, 'missing generated trigger');
+    else if (!same(expected, actual)) add(id, 'generated trigger differs from regeneration (a hand edit, or an older CLI): run db:apply to re-create it');
+  }
+  const functionNames = new Set([...expectedFunctions.values()].map(fn => fn.name));
+  for (const [id, actual] of liveTriggers) {
+    if (expectedTriggers.has(id)) continue;
+    const bare = actual.table.slice(actual.table.lastIndexOf('.') + 1);
+    if (lifecycleTables.has(actual.table) && id === `${actual.table}.${bare}_lifecycle_restrict` && actual.fn === oldRestrictName(actual.table)) { add(id, OLD_RESTRICT); continue; }
+    if (functionNames.has(actual.fn)) add(id, 'unmanaged lifecycle trigger binding');
+    else if (lifecycleTables.has(actual.table)) {
+      const type = triggerTypes.get(id)!;
+      if ((type & 32) !== 0) add(id, 'author TRUNCATE trigger refused: bypasses lifecycle row removal');
+      else if ((type & (2 | 8)) === (2 | 8)) add(id, 'author BEFORE DELETE trigger refused: can suppress purge DELETE');
+    }
+  }
+  return { failures: [...problems.values()].sort(), notes: [...notes].sort() };
+}

package/src/cli/migration-compile.ts

@@ -19,13 +19,14 @@
  * lands with whole-DB introspection. The emission is identical either way.
  */
 
-import type { ModelDescriptor, Module, SequenceDescriptor } from '@everystack/model';
+import { lifecycleDependentIndexes, relationDeleteActions, type ModelDescriptor, type Module, type SequenceDescriptor } from '@everystack/model';
 import type { AuthzContract, TableContract } from './authz-contract';
-import { compileCreateTable, compileEnums, compileSequences, sequenceCreateSql, foreignKeySql, modelConstraintSpecs, qualifiedTable, toSnakeCase, type CompileTableOptions } from './schema-compile';
+import { compileCreateTable, compileEnums, compileSequences, sequenceCreateSql, foreignKeySql, modelConstraintSpecs, dependentIndexSpecs, qualifiedTable, toSnakeCase, type CompileTableOptions } from './schema-compile';
 import { compileTableContract } from './authz-compile';
 import { emitReconcileSql } from './authz-reconcile';
 import { emitSchemaSql, nextvalSequence, type SchemaChange } from './schema-diff';
 import { compileDerived } from './derived-compile';
+import { lifecycleDerived } from './lifecycle-derived';
 import { renderEnsureObjectSchemas } from './derived-apply';
 
 /** The empty (not-yet-created) authz state for a table — the greenfield baseline. */
@@ -44,6 +45,10 @@ export function compileMigration(
 ): string[] {
   const sql: string[] = [];
   const schemaOf = (m: ModelDescriptor): string => m.schema ?? 'public';
+  // A parent's hasMany `dependent` sets a child FK's ON DELETE; resolved over the whole set
+  // from THIS set, before any FK is compiled.
+  const dependents = relationDeleteActions(models);
+  const dependentIndexes = lifecycleDependentIndexes(models);
 
   // 0. Extensions — the BOOTSTRAP, before any table that might use one of their types.
   //    compileModuleMigration has always emitted these; compileMigration had no way to,
@@ -103,13 +108,13 @@ export function compileMigration(
   }
 
   // 2. Foreign keys — after every table exists.
-  for (const model of models) sql.push(...foreignKeySql(model));
+  for (const model of models) sql.push(...foreignKeySql(model, dependents));
 
   // 2b. Standalone indexes — after the columns they cover exist. The ON clause is the
   //     schema-qualified table, so a non-public index targets the right table.
   const indexCreates: SchemaChange[] = [];
   for (const model of models) {
-    for (const ix of modelConstraintSpecs(model).indexes) {
+    for (const ix of [...modelConstraintSpecs(model).indexes, ...dependentIndexSpecs(model, dependentIndexes)]) {
       indexCreates.push({
         kind: 'createIndex', table: qualifiedTable(model), name: ix.name, columns: ix.columns, unique: ix.unique,
         ...(ix.where ? { where: ix.where } : {}),
@@ -169,7 +174,8 @@ export function compileModuleMigration(modules: Module[], opts: CompileTableOpti
   //    objects — compiled in topological order, after every table. Greenfield = one
   //    complete script: state + compute; from then on the layer deploys via db:reconcile.
   const models = modules.flatMap((m) => m.models);
-  const derivedObjects = compileDerived(models, modules.flatMap((m) => m.derived));
+  // The lifecycle triggers are generated from the models, exactly as composeDeclaredDerived does.
+  const derivedObjects = compileDerived(models, [...modules.flatMap((m) => m.derived), ...lifecycleDerived(models)]);
 
   // 4a. A schema that ONLY derived objects live in has no model to create it, so phase 2
   //     never does — and the first CREATE VIEW in it fails with `schema … does not exist`.

package/src/cli/migration-generate.ts

@@ -16,6 +16,7 @@
  */
 
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
+import { assertExternalTargets, lifecycleDependentIndexes, relationDeleteActions } from '@everystack/model';
 import type { SchemaSnapshot, ColumnSchema } from './schema-introspect';
 import type { AuthzContract, SequenceGrantContract } from './authz-contract';
 import { compileTableSchema, compileRenames, compileTableRenames, compileTableMoves, compileCreateTable, compileEnums, compileSequences } from './schema-compile';
@@ -80,7 +81,8 @@ function isRemoval(change: SchemaChange, replacedConstraints: Set<string>): bool
   // DROP IDENTITY destroys the backing sequence and its counter — a removal, not a change.
   // ADD/SET GENERATED are not: they create or retune the auto-value and lose nothing.
   if (change.kind === 'setIdentity' && change.identity == null) return true;
-  if (change.kind === 'dropConstraint') return !replacedConstraints.has(`${change.table}::${change.name}`);
+  // A replaced primary key's drop is paired with the declared key's add in the same edge.
+  if (change.kind === 'dropConstraint') return !change.replacesPrimaryKey && !replacedConstraints.has(`${change.table}::${change.name}`);
   return false;
 }
 
@@ -124,12 +126,31 @@ export function unmodeledTables(models: ModelDescriptor[], current: SchemaSnapsh
  * the database (auth, jobs, observability) is left to its own migrations.
  */
 export function generateMigrationSql(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
+  return generateMigration(models, current, opts).statements;
+}
+
+/**
+ * {@link generateMigrationSql}, with the structural change set the data phase was emitted from.
+ * For a caller that must decide on what a statement IS (db:plan refusing a change it can only
+ * hold as a notice) rather than read it back out of the SQL text.
+ */
+export function generateMigration(
+  models: ModelDescriptor[],
+  current: SchemaSnapshot,
+  opts: GenerateOptions = {},
+): { statements: string[]; changes: SchemaChange[] } {
+  // An external FK target that this set models is an authoring error (use the model). linkModels
+  // checks it at load; checked again here because a caller can hand a set in without linking.
+  assertExternalTargets(models);
+  // hasMany `dependent` → the child FK's ON DELETE, derived from THIS set (and checked, for the same reason).
+  const dependents = relationDeleteActions(models);
+  const dependentIndexes = lifecycleDependentIndexes(models);
   const schema = opts.schema ?? 'public';
   // A table's schema comes from the model first (package tables live in dist/ops/auth),
   // then the call default — so one run spans schemas.
   const schemaOf = (m: ModelDescriptor): string => m.schema ?? schema;
   const desiredEnums = compileEnums(models);
-  const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema })), enums: desiredEnums, ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}) };
+  const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema, dependents, dependentIndexes })), enums: desiredEnums, ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}) };
   const declaredTables = new Set(desired.tables.map((t) => t.table));
   const declaredEnums = new Set(desiredEnums.map((e) => e.name));
   // Scope both tables and enums to what the Models declare — an undeclared table OR enum
@@ -305,7 +326,7 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
         })
     : [];
 
-  return [...extensionPhase, ...schemaPhase, ...usagePhase, ...dataPhase, ...authzPhase];
+  return { statements: [...extensionPhase, ...schemaPhase, ...usagePhase, ...dataPhase, ...authzPhase], changes };
 }
 
 /**

package/src/cli/model-api.ts

@@ -23,6 +23,15 @@ export * from './model-render';
 export * from './migration-compile';
 export * from './migration-generate';
 
+// --- the DECLARED state of a model set, as introspection would see it -------
+// `compileDeclaredState(models, { schema })` → `{ snapshot, contract }`: the same compilation
+// db:plan, db:check and the fingerprint use. Diff `.snapshot` against `introspectSchema(...)`
+// to verify a database built from the Models. Prefer it to mapping `compileTableSchema` over
+// the set yourself: the set derives table parts no single Model carries (the hasMany ON DELETE,
+// the generated `<table>_<column>_lifecycle_fk_idx` indexes), and a hand-rolled loop that misses
+// one reads the live object as a drop.
+export { compileDeclaredState, type DeclaredState } from './declared-diff';
+
 // --- authz layer: contract compile/introspect/diff/reconcile ---------------
 export * from './authz-compile';
 export * from './authz-contract';