@everystack/cli 0.4.103 → 0.4.105

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, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError } 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,13 @@ 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);
+  // Before anything is written, so before both places a pass creates derived objects (the
+  // functions the state batch calls, then the reconcile).
+  const ownerRefusal = await lifecycleDeclaredOwnerRefusal(runner, session, options.declared ?? [], models, { stateApplied: false });
+  if (ownerRefusal) throw new LifecycleFindingsError(ownerRefusal);
   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, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError, lifecyclePostApplyRefusal } 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
@@ -177,14 +181,25 @@ export async function buildIntoDatabase(
     // declared state: 20 such pairs, `type "…_row" does not exist`, from-scratch only. Their
     // explicit `dependsOn` could not have helped — this pass dropped the view from the wave, so
     // no edge could order it back in.
+    // Before the first derived write: the owners the reconcile will give the declared trigger
+    // functions on lifecycle tables. This pass runs before executeSync, which judges them again
+    // first thing, before its own state apply.
+    const ownerRefusal = await lifecycleDeclaredOwnerRefusal(runner, session, options.declared ?? [], models, { stateApplied: false });
+    if (ownerRefusal) throw new LifecycleFindingsError(ownerRefusal);
     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,
@@ -204,6 +219,10 @@ export async function buildIntoDatabase(
       actor: options.actor ?? 'db-build',
       gitRef: options.gitRef ?? null,
     });
+    // Verification: the live catalog check again, over what the derived layer just made live. A
+    // throw, so no caller (db:check's compose ring, the dev template, a test database) can miss it.
+    const post = await lifecyclePostApplyRefusal(session, models);
+    if (post) throw new LifecycleFindingsError(post);
     return {
       converged: run.converged,
       fingerprintMatch: run.fingerprintMatch,

package/src/cli/derived-apply.ts

@@ -181,6 +181,16 @@ function objectSql(obj: SourceObject, ownerMode: OwnerApplyMode = 'set-role', re
   return [`SET ROLE ${obj.owner}`, ...statements, 'RESET ROLE'];
 }
 
+/**
+ * The role that owns an object once the reconcile has created it: its declared owner (objectSql
+ * enacts it), else `builder`, the role the reconcile runs as, which creates it as itself. The
+ * lifecycle pre-exposure gate reads owners through this too, so the role it judges is the role the
+ * reconcile makes.
+ */
+export function reconcileOwner(obj: Pick<SourceObject, 'owner'>, builder: string): string {
+  return obj.owner || builder;
+}
+
 const ALTER_OWNER: Record<string, string> = {
   function: 'ALTER FUNCTION',
   view: 'ALTER VIEW',
@@ -228,7 +238,8 @@ export function triggerFunctionOf(trigger: SourceObject, source: readonly Source
 function withTransientExecute(obj: SourceObject, statements: string[], source: readonly SourceObject[], grantee?: string): string[] {
   if (!grantee || obj.kind !== 'trigger') return statements;
   const fn = triggerFunctionOf(obj, source);
-  if (!fn?.owner) return statements;
+  // The builder owns a function it creates for itself, and an owner holds EXECUTE.
+  if (!fn || reconcileOwner(fn, grantee) === grantee) return statements;
   const declared = parseGrantAttachments(fn.attachments).grants[grantee] ?? [];
   if (declared.includes('EXECUTE') || declared.includes('ALL')) return statements;
   const target = dropTarget('function', fn.identity);
@@ -607,7 +618,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

@@ -33,8 +33,9 @@ import { loadDeclaredDerived, type DeclaredDerived } from './declared-derived';
 import { modelContractPreflight } from './model-wire-lane';
 import { MODEL_WIRE_CONTRACT, type ReconcileWirePayload } from '../wire';
 import { resolveConfig, opsFunction } from './config';
-import { invokeAction } from './aws';
+import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from './aws';
 import { currentGitRef } from './state-apply';
+import { catalogInputsFromModels, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError, lifecyclePostApplyRefusal } from './lifecycle-preflight';
 
 /** Where the catch-up runs. The two lanes db:apply itself already has. */
 export type CatchUpVenue =
@@ -76,6 +77,12 @@ export interface CatchUpOptions {
    * wrongly handed an exit loses the sentence its operator was owed.
    */
   onRefusal: 'exit' | 'throw';
+  /**
+   * Whether THIS run committed table or column changes before the catch-up: a lifecycle refusal
+   * then says so. False for db:apply with no --plan, and for a plan that was already applied.
+   * Required for the same reason as `onRefusal`: only the caller knows what it wrote.
+   */
+  stateApplied: boolean;
 }
 
 export interface CatchUpOutcome {
@@ -108,15 +115,28 @@ 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(),
   };
 
+  // Before the first derived write, judge the owners the reconcile will give the declared trigger
+  // functions on lifecycle tables.
+  const config = venue.kind === 'stage' ? await resolveConfig(venue.stage) : undefined;
+  const reader: QueryRunner = (q) => (venue.kind === 'direct' ? venue.runner : lambdaQueryRunner(config!.region, opsFunction(config!)))(q);
+  // The builder is read on the reconcile's own connection: on a stage, db:session runs on the
+  // operator connection, while db:query may run on a reader.
+  const operator: SessionRunner = (statements, opts) =>
+    (venue.kind === 'direct' ? venue.session : lambdaSessionRunner(config!.region, opsFunction(config!)))(statements, opts);
+  const gate = await lifecycleDeclaredOwnerRefusal(reader, operator, objects, declared?.models ?? [], { stateApplied: opts.stateApplied });
+  if (gate) throw new LifecycleFindingsError(gate);
+
   let run: ReconcileRun;
   if (venue.kind === 'direct') {
     run = await executeReconcile(venue.runner, venue.session, options);
   } else {
-    const config = await resolveConfig(venue.stage);
     // The ops Lambda CREATES AND REPLACES database objects from these descriptors, so verify the
     // deployed stage understands their shape before sending them — the same handshake
     // db:reconcile --apply --stage runs, for the same payload.
@@ -126,14 +146,14 @@ export async function catchUpDerived(
     // before the process ends. A catch-up that is the whole command has written nothing, and
     // asks to exit: print the skew, say nothing was sent, exit.
     await modelContractPreflight({
-      region: config.region,
-      fn: opsFunction(config),
+      region: config!.region,
+      fn: opsFunction(config!),
       directCommand: `everystack db:apply --stage ${venue.stage} --direct`,
       onRefusal: opts.onRefusal,
     })('db:apply');
     const result: any = await invokeAction(
-      config.region,
-      opsFunction(config),
+      config!.region,
+      opsFunction(config!),
       'db:reconcile',
       { ...options, modelContract: MODEL_WIRE_CONTRACT } satisfies ReconcileWirePayload,
     );
@@ -150,5 +170,10 @@ export async function catchUpDerived(
   // not land, so db:apply must say so and exit the same way.
   if (run.refusal) throw new CatchUpError(run.refusal);
 
+  // Verification: the live catalog check again, over what the reconcile just made live. On the
+  // operator session, where the commit is: db:query may read a replica that has not caught up.
+  const post = await lifecyclePostApplyRefusal(operator, declared?.models ?? []);
+  if (post) throw new LifecycleFindingsError(post);
+
   return { declared: objects.length, run, statements: run.applied ? (run.statements ?? []) : [] };
 }

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/index.ts

@@ -44,6 +44,8 @@ import { auditLighthouseCommand } from './commands/lighthouse';
 import { auditCommand } from './commands/audit';
 import { uiAuditCommand } from './commands/ui-audit';
 import { runbookCommand } from './commands/runbook';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { fail } from './output';
 import { parseFlags } from './parse-flags';
 
@@ -56,6 +58,13 @@ async function main() {
     process.exit(0);
   }
 
+  if (command === '--version' || command === '-v') {
+    // tsx polyfills __dirname in ESM (see runbook.ts cliVersion).
+    const pkg = JSON.parse(readFileSync(path.join(eval('__dirname') as string, '..', '..', 'package.json'), 'utf8'));
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
   const flags = parseFlags(args.slice(1));
 
   // `everystack <command> --help` shows help instead of running the command
@@ -312,7 +321,7 @@ Usage:
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
   everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)
   everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (read-only). Runs as the SELECT-only 'reader' role when the stage has one (db:provision --with-reader + QUERY_DATABASE_URL wired to dbPlugin's queryDatabaseUrl); WITHOUT one it runs on the OPERATOR connection, fenced only by a read-only transaction — see docs/cli.md
-  everystack db:doctor         [--purge-after <days>] [--models <barrel>] [--stage <name>] [--direct | --database-url <api> [--admin-database-url <ops>]]  Check the DB is least-privilege + RLS-subject (api vs operator connection). No flag = ops-Lambda venue (auto-falls to direct via the stage secrets if the handler has no dbPlugin). --direct = probe both connections from the stage's DATABASE_URL + ADMIN_DATABASE_URL secrets; --database-url = explicit local venue (a lone URL is probed as both)
+  everystack db:doctor         [--destroy-after <days>] [--models <barrel>] [--stage <name>] [--direct | --database-url <api> [--admin-database-url <ops>]]  Check the DB is least-privilege + RLS-subject (api vs operator connection). No flag = ops-Lambda venue (auto-falls to direct via the stage secrets if the handler has no dbPlugin). --direct = probe both connections from the stage's DATABASE_URL + ADMIN_DATABASE_URL secrets; --database-url = explicit local venue (a lone URL is probed as both)
   everystack db:provision      --stage <name> [--direct | --database-url <url>] [--rotation-pairs] [--with-reader]  Create the least-privilege role chain (idempotent). --rotation-pairs creates A/B pairs for live rotation. --with-reader adds the SELECT-only 'reader' login db:query runs as, grants it read on the declared schemas, and writes QUERY_DATABASE_URL (opt-in once, then kept converged on every re-provision)
   everystack db:provision      --rotate --stage <name> [--slot api|ops|both] [--grace 60]  Rotate credentials live (A/B role swap, no deploy, no downtime)
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
@@ -405,6 +414,7 @@ Auth:
 
 Options:
   --help, -h    Show this help message
+  --version, -v Print the @everystack/cli version
 `);
 }
 

package/src/cli/lifecycle-canon.ts

@@ -29,7 +29,8 @@ export function canonOfFunction(fn: FunctionDescriptor): FunctionCanon {
     language: fn.language, secdef: fn.security === 'definer',
     volatility: { immutable: 'i', stable: 's', volatile: 'v' }[fn.volatility],
     strict: false, leakproof: false,
-    config: Array.isArray(fn.searchPath) ? [`search_path=${fn.searchPath.join(', ')}`] : [],
+    config: [...(Array.isArray(fn.searchPath) ? [`search_path=${fn.searchPath.join(', ')}`] : []),
+      ...(fn.lockTimeout === undefined ? [] : [`lock_timeout=${fn.lockTimeout}`])],
     owner: fn.owner ?? '(ambient)', execute: [...execute].sort(),
     // renderFunction adds exactly one newline on each side of the authored body.
     body: `\n${fn.body}\n`,