@everystack/cli 0.4.102 → 0.4.104

package/src/cli/commands/db-reconcile.ts

@@ -32,6 +32,7 @@
 import type { QueryRunner } from '../authz-contract';
 import type { SourceObject } from '../derived-source';
 import { introspectDerived } from '../derived-introspect';
+import { catalogInputsFromModels, lifecycleReconcileRefusal } from '../lifecycle-preflight';
 import { planReconcile, objectGrantDelta, TRIGGER_ENABLED_STATE, type ReconcilePlan, type ReconcileOptions } from '../derived-plan';
 import {
   renderReconcileSql,
@@ -77,6 +78,18 @@ export interface ExecuteOptions extends ReconcileOptions {
   planRef?: string | null;
   /** Descriptor-compiled objects (the declared derived layer) — the ONE source stream. */
   declared?: SourceObject[];
+  /**
+   * The application roles for the lifecycle catalog check (catalogInputsFromModels). Required
+   * whenever a declared object is lifecycle-owned: absent, the reconcile refuses rather than skip
+   * the check. `unknown` because the ops Lambda passes it straight off the wire.
+   */
+  applicationRoles?: unknown;
+  /**
+   * The caller already ran lifecycleApplyRefusal with the full models, on this runner, in this
+   * process (executeSync does, first thing), so the reconcile does not run the catalog check again.
+   * Never set from a wire payload.
+   */
+  lifecyclePreflighted?: boolean;
   /** Injectable clock for tests. */
   now?: () => number;
 }
@@ -89,6 +102,8 @@ export interface ReconcileRun {
   statements: string[];
   /** Why apply was refused, when it was. */
   refusal?: string;
+  /** A plan-only run: what the lifecycle catalog check found (the text an apply would refuse with). */
+  lifecycleFindings?: string;
   /**
    * Which mechanism enacted the declared owners, when any were enacted. Reported because the two
    * make different demands of the operator: `set-role` needs membership plus CREATE-on-schema for
@@ -140,13 +155,21 @@ export async function executeReconcile(
   // catalog and re-renders if this builder can use the cheaper one; a plan that is never applied
   // (or is refused) shows the conservative form, which is the honest default.
   let rendered = renderReconcileSql(plan, parsed.objects);
-
-  if (!options.apply) return { plan, applied: false, statements: rendered.statements };
+  // Every mode that writes or adopts a lifecycle-owned object (--apply with --baseline,
+  // --rebaseline, --only, --overwrite-drift or none) refuses on it below; a plan-only run reports
+  // it as a finding. See lifecycleCatalogRefusal for what it defends and from whom.
+  const lifecycleGate = (): Promise<string | null> => (options.lifecyclePreflighted ? Promise.resolve(null)
+    : lifecycleReconcileRefusal(runner, parsed.objects, { applicationRoles: options.applicationRoles }));
+
+  if (!options.apply) {
+    const lifecycleFindings = await lifecycleGate();
+    return { plan, applied: false, statements: rendered.statements, ...(lifecycleFindings ? { lifecycleFindings } : {}) };
+  }
 
   if (plan.blocked.length > 0) {
     return {
       plan, applied: false, statements: rendered.statements,
-      refusal: `blocked chains: ${plan.blocked.map((b) => b.identity).join(', ')} — resolve the unmanaged dependents first`,
+      refusal: `blocked chains: ${plan.blocked.map((b) => `${b.identity} (${b.reason})`).join('; ')} — resolve the dependents first`,
     };
   }
   if (plan.drift.length > 0 && !options.overwriteDrift) {
@@ -155,6 +178,8 @@ export async function executeReconcile(
       refusal: `drift on ${plan.drift.map((d) => d.identity).join(', ')} — inspect, then re-run with --overwrite-drift to rebuild from source`,
     };
   }
+  const lifecycleRefusal = await lifecycleGate();
+  if (lifecycleRefusal) return { plan, applied: false, statements: rendered.statements, refusal: lifecycleRefusal };
   if (rendered.statements.length === 0 && rendered.record.length === 0 && rendered.remove.length === 0 && rendered.migrate.length === 0) {
     return { plan, applied: false, statements: [] };
   }
@@ -740,6 +765,9 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
   const reconcileOptions = {
     apply,
     declared: declared?.objects,
+    // The lifecycle catalog check's roles, from the barrel's models. The tables come from the
+    // declared transition triggers inside the reconcile, the same derivation the ops Lambda runs.
+    applicationRoles: declared?.models ? catalogInputsFromModels(declared.models).applicationRoles : undefined,
     renamedTables: declared?.renamedTables,
     baseline: flags.baseline === 'true',
     rebaseline: flags.rebaseline === 'true',
@@ -820,9 +848,10 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     }
 
     if (flags.json === 'true') {
-      console.log(JSON.stringify({ ...run.plan, applied: run.applied, refusal: run.refusal ?? null }, null, 2));
+      console.log(JSON.stringify({ ...run.plan, applied: run.applied, refusal: run.refusal ?? null, lifecycleFindings: run.lifecycleFindings ?? null }, null, 2));
     } else {
       for (const line of buildReconcileReport(run.plan)) info(line);
+      if (run.lifecycleFindings) warn(`lifecycle: ${run.lifecycleFindings}`);
       if (run.refusal) {
         fail(`not applied: ${run.refusal}`);
       } else if (run.applied) {
@@ -848,7 +877,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     }
 
     if (run.refusal) process.exit(1);
-    if (check && checkFails(run.plan)) process.exit(1);
+    if (check && (checkFails(run.plan) || run.lifecycleFindings)) process.exit(1);
   } catch (err: any) {
     if (err instanceof MutationLeaseError) {
       // The lease refused before any DDL — nothing was reconciled.

package/src/cli/commands/db-sync.ts

@@ -31,7 +31,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { ModelDescriptor } from '@everystack/model';
 import { introspectContract, type QueryRunner } from '../authz-contract';
-import { introspectSchema } from '../schema-introspect';
+import { catalogInputsFromModels, lifecycleApplyRefusal } from '../lifecycle-preflight';
+import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
 import { generateMigrationSql, unmodeledTables } from '../migration-generate';
 import type { SequenceDescriptor } from '@everystack/model';
@@ -112,6 +113,18 @@ export interface SyncRun {
   converged: boolean;
 }
 
+/** The live keys into a lifecycle model whose drop the generated statements hold back, as `<constraint> on <table> references lifecycle table <parent>`. */
+function heldLifecycleKeyDrops(heldDrops: readonly string[], current: SchemaSnapshot, models: readonly ModelDescriptor[]): string[] {
+  if (heldDrops.length === 0) return [];
+  const lifecycle = new Set(models.filter(model => model.lifecycle === true).map(model => `${model.schema}.${model.table}`));
+  const qualify = (name: string): string => (name.includes('.') ? name : `public.${name}`);
+  const escape = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return current.tables.flatMap(table => table.foreignKeys
+    .filter(fk => fk.name && lifecycle.has(qualify(fk.refTable))
+      && heldDrops.some(held => new RegExp(`DROP CONSTRAINT (IF EXISTS )?"?${escape(fk.name!)}"?;`).test(held)))
+    .map(fk => `${fk.name} on ${qualify(table.table)} references lifecycle table ${qualify(fk.refTable)}`));
+}
+
 /**
  * One sync: state first (derived objects may depend on new columns), then
  * compute, then the verdict. The exception is the declared functions the
@@ -132,13 +145,23 @@ async function syncOnce(
     allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
     governedRoles: options.governedRoles, extensions: options.extensions,
   });
-  hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements), pass);
+  const classified = classifyGeneratedStatements(statements);
+  hooks.onStatePlan?.(statements, classified, pass);
+  // A held drop of a key into a lifecycle table leaves a key the after-state catalog check refuses,
+  // after the rest of the state has landed and before any lifecycle function is installed. Refuse
+  // here instead, before anything is written.
+  const heldKeys = heldLifecycleKeyDrops(classified.heldDrops, current, models);
+  if (heldKeys.length > 0) {
+    throw new Error(`db:sync would hold back the drop of ${heldKeys.length === 1 ? 'a foreign key' : 'foreign keys'} into a lifecycle table, `
+      + `and the lifecycle catalog check refuses ${heldKeys.length === 1 ? 'it' : 'them'} after the state apply: ${heldKeys.join('; ')}. `
+      + 'Nothing was written. Only a lifecycle table may hold a key into one; re-run with --allow-drops to drop it.');
+  }
 
   // The one derived → state edge: a declared function a pending policy (or default, or check)
   // calls must exist before that statement is created. Only those functions, only when absent.
   if (options.declared?.length) {
     await createStateReferencedFunctions(runner, session, statements, options.declared, {
-      actor: options.actor, gitRef: options.gitRef, now: options.now,
+      actor: options.actor, gitRef: options.gitRef, now: options.now, lifecyclePreflighted: true,
     });
   }
 
@@ -157,6 +180,9 @@ async function syncOnce(
     declared: options.declared,
     renamedTables: options.renamedTables,
     actor: options.actor, gitRef: options.gitRef, now: options.now,
+    // The catalog check runs again here, after the state apply: a table this sync just created can
+    // carry a finding (a default privilege, its owner) the check before the state apply could not see.
+    applicationRoles: catalogInputsFromModels(models).applicationRoles,
   });
 
   const declaredFingerprint = fingerprintModels(models, { sequences: options.sequences }).hash;
@@ -213,6 +239,9 @@ export async function executeSync(
   options: SyncOptions = {},
   hooks: SyncHooks = {},
 ): Promise<SyncRun> {
+  // State runs before compute, so without this a lifecycle table would land with no transition trigger.
+  const lifecycleRefusal = await lifecycleApplyRefusal(runner, models);
+  if (lifecycleRefusal) throw new Error(lifecycleRefusal);
   const first = await syncOnce(runner, session, models, options, hooks, 1);
   // The trigger is the STATE bar, not the combined verdict. The cause above is state-layer
   // only, so a compute refusal or an unadopted object cannot be settled by looking again —

package/src/cli/commands/db.ts

@@ -98,6 +98,28 @@ export function pgKeepaliveConninfo(dbName?: string): string {
   return parts.join(' ');
 }
 
+/**
+ * The verdict for a fire-and-forget ops-Lambda action (migrate, reset, seed) — DB-free. The one
+ * guarantee it holds: a result carrying `error` is a FAILURE and never reports success. Extracted
+ * from the dispatcher shells so the "error never reports success" boundary is asserted by a test
+ * (closing-gate F1 method); the shell still owns the IO, the exit code, and the thrown-error path.
+ */
+export type OpsActionVerdict =
+  | { ok: true; message: string; warnings: string[] }
+  | { ok: false; message: string };
+
+export function opsActionResultVerdict(
+  result: { error?: unknown; message?: unknown; warnings?: unknown } | null | undefined,
+  opts: { failPrefix: string; successFallback: string },
+): OpsActionVerdict {
+  if (result?.error) return { ok: false, message: `${opts.failPrefix}: ${result.error}` };
+  return {
+    ok: true,
+    message: typeof result?.message === 'string' && result.message ? result.message : opts.successFallback,
+    warnings: Array.isArray(result?.warnings) ? (result!.warnings as string[]) : [],
+  };
+}
+
 export async function dbMigrateCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
   let config;
@@ -118,14 +140,15 @@ export async function dbMigrateCommand(flags: Record<string, string>): Promise<v
       'migrate',
       {},
     );
-    if (result?.error) {
-      fail(`Migration failed: ${result.error}`);
+    const verdict = opsActionResultVerdict(result, { failPrefix: 'Migration failed', successFallback: 'Migrations applied' });
+    if (!verdict.ok) {
+      fail(verdict.message);
       process.exit(1);
     }
-    success(result?.message || 'Migrations applied');
+    success(verdict.message);
     // Journal drift warnings — a migration file the journal doesn't list
     // will silently never apply. Never swallow these.
-    for (const warning of result?.warnings ?? []) {
+    for (const warning of verdict.warnings) {
       warn(warning);
     }
   } catch (err: any) {
@@ -192,11 +215,12 @@ export async function dbResetCommand(flags: Record<string, string>): Promise<voi
       'db:reset',
       {},
     );
-    if (result?.error) {
-      fail(`Reset failed: ${result.error}`);
+    const verdict = opsActionResultVerdict(result, { failPrefix: 'Reset failed', successFallback: 'Database reset and migrations applied' });
+    if (!verdict.ok) {
+      fail(verdict.message);
       process.exit(1);
     }
-    success(result?.message || 'Database reset and migrations applied');
+    success(verdict.message);
   } catch (err: any) {
     fail(`Reset failed: ${err.message}`);
     for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
@@ -1382,10 +1406,10 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
 }
 
 /** Parse the explicit day window once, before choosing a connection venue. */
-export function purgeAfterMilliseconds(days: string | undefined): number | undefined {
+export function destroyAfterMilliseconds(days: string | undefined): number | undefined {
   if (days === undefined) return undefined;
   const milliseconds = Number(days) * 86400000;
-  if (!Number.isFinite(milliseconds) || milliseconds <= 0) throw new Error('--purge-after needs a positive number of days');
+  if (!Number.isFinite(milliseconds) || milliseconds <= 0) throw new Error('--destroy-after needs a positive number of days');
   return milliseconds;
 }
 
@@ -1397,8 +1421,8 @@ async function doctorOverdueRows(
   if (after === undefined) return undefined;
   const { loadModels } = await import('./db-generate');
   const { resolveModelsPath } = await import('../models-path');
-  const spec = '@everystack/server/purge';
-  const { overdueLifecycleRows } = await import(spec) as typeof import('@everystack/server/purge');
+  const spec = '@everystack/server/destroy';
+  const { overdueLifecycleRows } = await import(spec) as typeof import('@everystack/server/destroy');
   const { PgDialect } = await import('drizzle-orm/pg-core');
   const dialect = new PgDialect();
   const models = await loadModels(resolveModelsPath(modelsPath));
@@ -1420,10 +1444,11 @@ export function printDoctorReport(report: any): void {
   }
 
   console.log('');
-  if (report.overdueLifecycleRows === undefined) info('Lifecycle purge: skipped; pass --purge-after <days> to count overdue rows');
+  if (report.overdueLifecycleRows === undefined) info('Lifecycle destroy: skipped; pass --destroy-after <days> to count overdue rows');
   else {
-    info('Lifecycle purge: overdue rows');
+    info('Lifecycle destroy: overdue rows');
     for (const [table, count] of Object.entries(report.overdueLifecycleRows)) info(`  ${table}: ${count}`);
+    info('  Why roots are skipped is reported by destroyExpired (see the destroy cron log); doctor counts overdue rows only.');
   }
   console.log('');
   if (report.ok) {
@@ -1453,7 +1478,7 @@ export function printDoctorReport(report: any): void {
  * forceRlsCarveouts/functionSchemas are unknown to the CLI, so the functions teeth run at
  * their safe default (unpinned SECDEF warns rather than fails). Returns report.ok.
  */
-async function runDoctorDirect(apiUrl: string, adminUrl: string, sourceLabel: string, purgeAfter: number | undefined, modelsPath: string | undefined): Promise<boolean> {
+async function runDoctorDirect(apiUrl: string, adminUrl: string, sourceLabel: string, destroyAfter: number | undefined, modelsPath: string | undefined): Promise<boolean> {
   const { runDoctorProbe } = await loadServerDoctor();
   const { createUrlRunner } = await import('../db-source');
   step('Probing database connections (api + operator)...');
@@ -1464,7 +1489,7 @@ async function runDoctorDirect(apiUrl: string, adminUrl: string, sourceLabel: st
       { api: apiConn.runner, ops: opsConn.runner },
       { apiSourceLabel: sourceLabel },
     );
-    const overdueLifecycleRows = await doctorOverdueRows(purgeAfter, modelsPath, opsConn.runner);
+    const overdueLifecycleRows = await doctorOverdueRows(destroyAfter, modelsPath, opsConn.runner);
     printDoctorReport({ ...report, overdueLifecycleRows });
     return report.ok;
   } finally {
@@ -1474,9 +1499,9 @@ async function runDoctorDirect(apiUrl: string, adminUrl: string, sourceLabel: st
 }
 
 export async function dbDoctorCommand(flags: Record<string, string>): Promise<void> {
-  let purgeAfter: number | undefined;
+  let destroyAfter: number | undefined;
   try {
-    purgeAfter = purgeAfterMilliseconds(flags['purge-after']);
+    destroyAfter = destroyAfterMilliseconds(flags['destroy-after']);
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error));
     process.exit(1);
@@ -1495,7 +1520,7 @@ export async function dbDoctorCommand(flags: Record<string, string>): Promise<vo
     info('venue: direct connection (explicit --database-url)');
     let ok = false;
     try {
-      ok = await runDoctorDirect(venue!.apiUrl, venue!.adminUrl, '--database-url', purgeAfter, flags.models);
+      ok = await runDoctorDirect(venue!.apiUrl, venue!.adminUrl, '--database-url', destroyAfter, flags.models);
     } catch (err: any) {
       fail(`db:doctor failed: ${err.message}`);
       process.exit(1);
@@ -1535,7 +1560,7 @@ export async function dbDoctorCommand(flags: Record<string, string>): Promise<vo
     info(`Region: ${config.region}, venue: direct connection (stage secrets)`);
     let ok = false;
     try {
-      ok = await runDoctorDirect(venue!.apiUrl, venue!.adminUrl, 'DATABASE_URL secret', purgeAfter, flags.models);
+      ok = await runDoctorDirect(venue!.apiUrl, venue!.adminUrl, 'DATABASE_URL secret', destroyAfter, flags.models);
     } catch (err: any) {
       fail(`db:doctor failed: ${err.message}`);
       process.exit(1);
@@ -1560,7 +1585,7 @@ export async function dbDoctorCommand(flags: Record<string, string>): Promise<vo
       info('No Ops Lambda (the deployed handler has no dbPlugin) — verifying directly over the stage secrets.');
       let ok = false;
       try {
-        ok = await runDoctorDirect(venue.apiUrl, venue.adminUrl, 'DATABASE_URL secret', purgeAfter, flags.models);
+        ok = await runDoctorDirect(venue.apiUrl, venue.adminUrl, 'DATABASE_URL secret', destroyAfter, flags.models);
       } catch (err: any) {
         fail(`db:doctor failed: ${err.message}`);
         process.exit(1);
@@ -1590,7 +1615,7 @@ export async function dbDoctorCommand(flags: Record<string, string>): Promise<vo
 
   const { lambdaSessionRunner } = await import('../aws');
   const session = lambdaSessionRunner(config.region, opsFunction(config));
-  report.overdueLifecycleRows = await doctorOverdueRows(purgeAfter, flags.models, async query => {
+  report.overdueLifecycleRows = await doctorOverdueRows(destroyAfter, flags.models, async query => {
     const [rows] = await session([query], { readOnly: true, searchPath: 'pg_catalog' });
     if (!Array.isArray(rows)) throw new Error('overdue lifecycle count failed');
     return rows;

package/src/cli/db-build.ts

@@ -10,7 +10,7 @@
  * state lands EXACTLY on the models' fingerprint.
  */
 
-import type { ModelDescriptor } from '@everystack/model';
+import { ENSURE_DESTROY_LOG_SQL, type ModelDescriptor } from '@everystack/model';
 import type { TableContract, QueryRunner } from './authz-contract';
 import type { SourceObject } from './derived-source';
 import type { SequenceDescriptor } from '@everystack/model';
@@ -18,6 +18,7 @@ import { compileDeclaredState } from './declared-diff';
 import { createUrlRunner } from './db-source';
 import { executeSync, buildSyncReport } from './commands/db-sync';
 import { executeReconcile } from './commands/db-reconcile';
+import { lifecycleApplyRefusal } from './lifecycle-preflight';
 
 const SAFE_NAME = /^[a-z_][a-z0-9_$]*$/;
 
@@ -143,6 +144,9 @@ export async function buildIntoDatabase(
     // legacy apps do create objects in `public` at runtime.
     await runner('REVOKE CREATE ON SCHEMA public FROM PUBLIC');
     const createdRoles = await ensureContractRoles(runner, models);
+    if (models.some(model => model.lifecycle)) {
+      for (const statement of ENSURE_DESTROY_LOG_SQL) await runner(statement);
+    }
 
     // FUNCTIONS BEFORE STATE. An RLS policy's predicate is resolved when the policy is
     // created, so `USING (user_id = auth.user_id())` cannot be created before
@@ -180,11 +184,17 @@ export async function buildIntoDatabase(
     const declaredFunctions = (options.declared ?? [])
       .filter((o) => o.kind === 'function' && !o.signatureDeps?.length);
     if (declaredFunctions.length > 0) {
+      // The lifecycle catalog check, with the full models, before any lifecycle-owned function
+      // lands: this pass declares functions only, so it carries no transition trigger for the
+      // reconcile to read the lifecycle tables from. executeSync runs the same check again below.
+      const lifecycleRefusal = await lifecycleApplyRefusal(runner, models);
+      if (lifecycleRefusal) throw new Error(lifecycleRefusal);
       await runner('SET check_function_bodies = off');
       try {
         const pre = await executeReconcile(runner, session, {
           declared: declaredFunctions,
           only: declaredFunctions.map(object => object.identity),
+          lifecyclePreflighted: true,
           apply: true,
           actor: options.actor ?? 'db-build',
           gitRef: options.gitRef ?? null,

package/src/cli/declared-diff.ts

@@ -27,7 +27,7 @@
  */
 
 import type { ModelDescriptor } from '@everystack/model';
-import { assertExternalTargets, relationDeleteActions } from '@everystack/model';
+import { assertExternalTargets, lifecycleDependentIndexes, relationDeleteActions } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect';
 import type { AuthzContract } from './authz-contract';
 import { compileTableSchema, compileEnums } from './schema-compile';
@@ -57,10 +57,11 @@ export function compileDeclaredState(
 ): DeclaredState {
   assertExternalTargets(models);
   const dependents = relationDeleteActions(models);
+  const dependentIndexes = lifecycleDependentIndexes(models);
   const schema = opts.schema ?? 'public';
   return {
     snapshot: {
-      tables: models.map((m) => compileTableSchema(m, { schema, dependents })),
+      tables: models.map((m) => compileTableSchema(m, { schema, dependents, dependentIndexes })),
       enums: compileEnums(models),
     },
     contract: {

package/src/cli/derived-apply.ts

@@ -607,7 +607,11 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[],
         // The new kinds carry their drop on the action (triggers: composed from structure;
         // 'sql' objects: the recorded/declared drop_sql) — the legacy kinds keep the
         // keyword rendering they always had.
-        statements.push(action.dropSql ?? `DROP ${DROP_KEYWORD[action.kind]} IF EXISTS ${dropTarget(action.kind, action.identity)}`);
+        const dropSql = action.dropSql ?? `DROP ${DROP_KEYWORD[action.kind]} IF EXISTS ${dropTarget(action.kind, action.identity)}`;
+        // A rebuilt function with a declared owner drops AS that owner, as its create runs: DROP
+        // needs ownership, and an operator holding the owner WITH INHERIT FALSE, SET TRUE has none.
+        const owner = action.kind === 'function' && ownerMode === 'set-role' ? srcById.get(action.identity)?.owner : undefined;
+        statements.push(...(owner ? [`SET ROLE ${owner}`, dropSql, 'RESET ROLE'] : [dropSql]));
         // A rebuild's drop is followed by its create; only a true removal loses provenance.
         if (!plan.actions.some((a) => a.action === 'create' && a.identity === action.identity)) {
           remove.push(action.identity);

package/src/cli/derived-catchup.ts

@@ -35,6 +35,7 @@ import { MODEL_WIRE_CONTRACT, type ReconcileWirePayload } from '../wire';
 import { resolveConfig, opsFunction } from './config';
 import { invokeAction } from './aws';
 import { currentGitRef } from './state-apply';
+import { catalogInputsFromModels } from './lifecycle-preflight';
 
 /** Where the catch-up runs. The two lanes db:apply itself already has. */
 export type CatchUpVenue =
@@ -108,6 +109,9 @@ export async function catchUpDerived(
     apply: true,
     declared: objects,
     renamedTables: declared?.renamedTables,
+    // The lifecycle catalog check's roles; the reconcile, here or in the ops Lambda, refuses
+    // lifecycle-owned objects without them.
+    applicationRoles: declared?.models ? catalogInputsFromModels(declared.models).applicationRoles : undefined,
     actor: process.env.USER ?? null,
     gitRef: currentGitRef(),
   };

package/src/cli/derived-compile.ts

@@ -207,7 +207,8 @@ function renderFunction(fn: FunctionDescriptor): { sql: string; attachments: Att
   const pin = Array.isArray(fn.searchPath) && fn.searchPath.length > 0
     ? ` SET search_path = ${fn.searchPath.join(', ')}`
     : '';
-  const security = `${definer}${pin}`;
+  const lockTimeout = fn.lockTimeout === undefined ? '' : ` SET lock_timeout = '${escapeLiteral(fn.lockTimeout)}'`;
+  const security = `${definer}${pin}${lockTimeout}`;
   const tag = dollarTag(fn.body);
   const signature = functionSignature(target, fn);
   return {

package/src/cli/derived-introspect.ts

@@ -112,8 +112,17 @@ export interface LiveObject {
     volatility: string;
     /** The pinned search_path value, when set ('pg_catalog, public'). */
     searchPath?: string;
+    /** Function-scoped lock_timeout, when set. */
+    lockTimeout?: string;
     /** prosrc — the raw body. */
     src: string;
+    /**
+     * Every object pg_depend records as depending on this function (normal and auto edges), as
+     * pg_describe_object prints it: a view's rule, a trigger, another function's argument default,
+     * a column default, a policy. What a DROP FUNCTION without CASCADE would refuse over. Absent
+     * when not measured (an older read or fixture).
+     */
+    dependents?: string[];
   };
 }
 
@@ -241,7 +250,14 @@ SELECT
   (pg_get_userbyid(p.proowner) IN (CURRENT_USER, SESSION_USER)) AS owner_is_connected_role,
   (SELECT split_part(cfg, '=', 2) FROM unnest(COALESCE(p.proconfig, '{}'::text[])) cfg
     WHERE cfg LIKE 'search_path=%' LIMIT 1) AS search_path,
-  p.prosrc AS src
+  (SELECT split_part(cfg, '=', 2) FROM unnest(COALESCE(p.proconfig, '{}'::text[])) cfg
+    WHERE cfg LIKE 'lock_timeout=%' LIMIT 1) AS lock_timeout,
+  p.prosrc AS src,
+  ARRAY(
+    SELECT pg_describe_object(d.classid, d.objid, d.objsubid) FROM pg_depend d
+    WHERE d.refclassid = 'pg_proc'::regclass AND d.refobjid = p.oid AND d.deptype IN ('n', 'a')
+    ORDER BY 1
+  ) AS dependents
 FROM pg_proc p
 JOIN pg_namespace n ON n.oid = p.pronamespace
 JOIN pg_language l ON l.oid = p.prolang
@@ -550,6 +566,9 @@ export interface FunctionRow {
   secdef?: unknown;
   volatility?: unknown;
   search_path?: unknown;
+  lock_timeout?: unknown;
+  /** See LiveObject.fn.dependents. Optional: absent means not measured. */
+  dependents?: unknown;
   /** `pg_get_userbyid(proowner)` — see LiveObject.owner. Optional: pre-owner fixtures omit it. */
   owner?: unknown;
   /** See LiveObject.ownerIsSuperuser. Optional: absent means not measured. */
@@ -743,7 +762,9 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
           secdef: row.secdef === true || row.secdef === 't' || row.secdef === 'true',
           volatility: String(row.volatility ?? 'v'),
           ...(row.search_path != null && String(row.search_path) !== '' ? { searchPath: String(row.search_path) } : {}),
+          ...(row.lock_timeout != null ? { lockTimeout: String(row.lock_timeout) } : {}),
           src: String(row.src),
+          ...(row.dependents !== undefined ? { dependents: pgTextArray(row.dependents) } : {}),
         },
       } : {}),
     });

package/src/cli/derived-plan.ts

@@ -647,6 +647,29 @@ export function planReconcile(
     }
   }
 
+  // A replace whose RESULT type changes cannot be a CREATE OR REPLACE: PostgreSQL refuses it
+  // (42P13). Decided here, before any DDL: it becomes DROP + CREATE (the rebuild lane, so the
+  // create runs its owner block and attachments like a fresh build), and is refused, naming
+  // them, while anything depends on the function. The drop never cascades.
+  for (const id of [...fnReplace.keys()]) {
+    const src = srcById.get(id);
+    const liveObj = liveById.get(id);
+    const declared = src ? declaredResult(src.sql) : undefined;
+    const current = liveObj?.fn?.returns;
+    if (declared === undefined || current === undefined || sameResult(declared, current)) continue;
+    fnReplace.delete(id);
+    const change = `result type changes (live ${current}, declared ${declared})`;
+    const dependentsOf = [...new Set([...closureOf(id), ...(liveObj?.fn?.dependents ?? [])])].sort();
+    if (dependentsOf.length > 0) {
+      blocked.push({
+        identity: id,
+        reason: `${change}, which needs DROP + CREATE; refused while other objects depend on it: ${dependentsOf.join(', ')}. Drop or change them first; nothing is dropped with CASCADE`,
+      });
+      continue;
+    }
+    rebuild.set(id, `${change}: replaced by DROP + CREATE`);
+  }
+
   // Matviews that call a replaced function hold stale rows — refresh them,
   // unless the rebuild already recreates them fresh.
   const refresh = new Map<string, string>();
@@ -773,3 +796,44 @@ export function planReconcile(
     ...(reenables.length ? { reenables: reenables.sort((a, b) => a.identity.localeCompare(b.identity)) } : {}),
   };
 }
+
+/** The RETURNS clause of a function's CREATE statement, or undefined when it cannot be read. */
+export function declaredResult(createSql: string): string | undefined {
+  const header = createSql.split(/\bAS\s+\$/i)[0];
+  const m = /\bRETURNS\s+([\s\S]+?)\s+LANGUAGE\s/i.exec(header);
+  return m ? m[1].trim() : undefined;
+}
+
+const TYPE_ALIASES: Array<[RegExp, string]> = [
+  [/\btimestamptz\b/g, 'timestamp with time zone'],
+  [/\btimestamp\b(?!\s*\(?\d*\)?\s*with(out)?\s+time\s+zone)/g, 'timestamp without time zone'],
+  [/\btimetz\b/g, 'time with time zone'],
+  [/(?<!with |without )\btime\b(?!\s+with(out)?\s+time\s+zone)/g, 'time without time zone'],
+  [/\bbpchar\b|\bchar\b/g, 'character'],
+  [/\bint4\b|\bint\b/g, 'integer'],
+  [/\bint8\b/g, 'bigint'],
+  [/\bint2\b/g, 'smallint'],
+  [/\bbool\b/g, 'boolean'],
+  [/\bfloat8\b/g, 'double precision'],
+  [/\bfloat4\b/g, 'real'],
+  [/\bvarchar\b/g, 'character varying'],
+  [/\bdecimal\b/g, 'numeric'],
+];
+
+/**
+ * Whether a declared RETURNS clause and pg_get_function_result name the same result: case,
+ * quotes, whitespace, schema qualifiers, type modifiers (which the catalog does not keep on a
+ * result) and the common type aliases are not differences. A
+ * spelling this misses only turns an already-planned replace into DROP + CREATE.
+ */
+export function sameResult(declared: string, live: string): boolean {
+  const norm = (text: string): string => {
+    let out = text.toLowerCase().replace(/"/g, '').replace(/\s+/g, ' ').trim();
+    out = out.replace(/\b[a-z_][a-z0-9_$]*\.(?=[a-z_])/g, '');
+    // pg_get_function_result drops type modifiers: numeric(10,2) prints as numeric.
+    out = out.replace(/\s*\(\s*\d+\s*(,\s*\d+\s*)?\)/g, '');
+    for (const [pattern, to] of TYPE_ALIASES) out = out.replace(pattern, to);
+    return out.replace(/\s*([(),])\s*/g, '$1');
+  };
+  return norm(declared) === norm(live);
+}

package/src/cli/derived-render.ts

@@ -754,6 +754,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       } else if (f.secdef) {
         props.push(`searchPath: 'unpinned',`);
       }
+      if (f.lockTimeout !== undefined) props.push(`lockTimeout: ${tsString(f.lockTimeout)},`);
       // Ownership sits beside security because it IS the other half of it: `security: 'definer'`
       // says the function runs as its owner, and this says who that is.
       if (ownership.prop) props.push(ownership.prop);

package/src/cli/edge-plan.ts

@@ -24,6 +24,7 @@
  * JSON — recorded as `plan_ref` on the schema_log row the apply writes.
  */
 
+import { indexLockWarnings, type LockWarning } from './index-lock';
 import { createHash } from 'node:crypto';
 import type { Attachment } from './derived-source';
 import type { OwnerApplyMode } from './derived-apply';
@@ -253,6 +254,18 @@ export interface EdgePlan {
    * plans minted before this field existed; the summary falls back to the text-only reading.
    */
   dark?: string[];
+  /**
+   * The plain CREATE INDEX statements that build on a live table with rows, with the catalog's row
+   * estimate — db:plan's ⚠ LOCK lines. Read at mint, like `dark`; informational, never a gate, and
+   * outside both fingerprints. Absent on plans minted before it, or when there is nothing to warn.
+   */
+  lockWarnings?: LockWarning[];
+  /**
+   * The read policies this plan creates or replaces for a can('read', { role, deleted }) ability:
+   * db:plan's `⚠ ACCESS — role <r> can read deleted rows of <table>` lines. Informational, outside
+   * both fingerprints. Absent when there is none, and on plans minted before it.
+   */
+  deletedReads?: DeletedRead[];
   /** Live tables no model declares — untouched by the edge, riding into `to` as-is. */
   unmodeled: string[];
   gitRef: string | null;
@@ -564,6 +577,26 @@ function unplannableReason(change: SchemaChange): string | null {
   }
 }
 
+/** A read policy, created or replaced by this plan, that lets a role see deleted lifecycle rows. */
+export interface DeletedRead { table: string; role: string; deleted: 'include' | 'only' }
+
+/** The can('read', { role, deleted }) policies whose CREATE POLICY this plan runs. */
+export function deletedReadChanges(models: readonly ModelDescriptor[], statements: readonly string[]): DeletedRead[] {
+  const out: DeletedRead[] = [];
+  for (const m of models) {
+    if (m.lifecycle !== true) continue;
+    for (const a of m.abilities) {
+      if (a.action !== 'read' || !a.condition.deleted || !a.condition.role) continue;
+      const name = `${m.table}_select_${a.condition.role.toLowerCase()}`;
+      // The emitter writes the name bare when it is a plain identifier, quoted otherwise.
+      const created = new RegExp(`^\\s*CREATE POLICY (?:"${name}"|${name}) `, 'm');
+      if (!statements.some((st) => created.test(st))) continue;
+      out.push({ table: m.schema && m.schema !== 'public' ? `${m.schema}.${m.table}` : m.table, role: a.condition.role, deleted: a.condition.deleted });
+    }
+  }
+  return out;
+}
+
 export function mintEdgePlan(
   models: ModelDescriptor[],
   snapshot: SchemaSnapshot,
@@ -660,6 +693,8 @@ export function mintEdgePlan(
     // contract. The summary is rendered later from the plan alone, and answering "does a read
     // survive?" from statement text is what produced three false positives on a real plan.
     dark: tablesLeftWithoutARead(statements, contract),
+    ...(() => { const lockWarnings = indexLockWarnings(statements, snapshot); return lockWarnings.length ? { lockWarnings } : {}; })(),
+    ...(() => { const deletedReads = deletedReadChanges(models, statements); return deletedReads.length ? { deletedReads } : {}; })(),
     unmodeled: unmodeledTables(models, snapshot),
     gitRef: opts.gitRef ?? null,
     mintedBy: opts.actor ?? null,