@everystack/cli 0.4.103 → 0.4.104

package/CHANGELOG.md

@@ -4,11 +4,52 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [Unreleased]
+## [0.4.104] - 2026-10-30
+
+### BREAKING CHANGES
+
+- destroy is one generated SQL function per lifecycle table; purgeExpired is removed
+- only a lifecycle table may hold a foreign key into a lifecycle table
+
+### Added
+
+- db:restore and db:fork name the repair a lifecycle app needs
+- a destroy call removes only rows soft-deleted before its cutoff
+- close destroy_log to the lifecycle role; the marker functions refuse inside a trigger
+- a lifecycle model refuses TRIGGER and REFERENCES in privileges
+- the apply preflight refuses a live catalog that breaks the soft delete
+- a skipped destroy root says why: reason and blocker
+- say where skip reasons are reported
+- db:reconcile runs the live catalog check on every write path
 
 ### Fixed
 
 - export compileDeclaredState from @everystack/cli/model
+- db:pull only warns about a lifecycle table it cannot fold when it tried to fold
+- db:pull does not render an older CLI's lifecycle_restrict pair as authored code
+- provisioning clears committed destroy_log rows and validates the transaction check
+- a DELETE as the lifecycle role is soft outside a destroy call
+- a destroy call whose marker was removed mid-call fails whole (55000)
+- review nits for lifecycle/testing
+- refuse an out-of-date destroy_log before applying lifecycle objects
+- refuse a destroy_log provisioned before the marker functions
+- <t>_lifecycle_destroy_before() is executable by its owner alone
+- catalog checks pass the RDS shape and see owner, log and settings holes
+- the parent check's 23503 names its table and constraint
+- a function whose result type changes is rebuilt, not replaced
+- cap each blocker name part at 63 characters
+- result types compare without type modifiers; bare time is time without time zone
+- db:sync re-checks the catalog after its state apply; tables match by exact name
+- analytics.post_metrics refers to posts by value, not by key
+- destroy eligibility follows the root
+- review nits for soft-delete-decides
+- destroy_before is internal, so db:check passes on a lifecycle app
+
+### Changed
+
+- db:pull no longer refuses on lifecycle drift; the verifier is removed
+- one catalog check over tables and roles, with a models adapter
+- a destroy skip is an alarm, not an operator workflow
 
 ## [0.4.103] - 2026-10-23
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.103",
+  "version": "0.4.104",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -145,7 +145,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.24"
+    "@everystack/model": "0.4.25"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",
@@ -192,7 +192,7 @@
     "react": "19.2.0",
     "ts-jest": "29.4.9",
     "zod": "3.25.67",
-    "@everystack/server": "0.4.39"
+    "@everystack/server": "0.4.40"
   },
   "scripts": {
     "test": "jest",

package/src/cli/authz-compile.ts

@@ -460,7 +460,7 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // A lifecycle model hides deleted rows from every read policy but the lifecycle role's own.
   // Unlike softDelete there is no owner escape: the guard is AND-ed into each SELECT policy as
   // compiled. A `manage` role's ALL policy is NOT guarded, on purpose: it sees deleted rows (to
-  // restore or purge them), exactly as it does under softDelete.
+  // restore or destroy them), exactly as it does under softDelete.
   const lifecycleCol = model.lifecycle ? 'deleted_at' : null;
   const lifecycleGuard = lifecycleCol ? softDeleteGuard(lifecycleCol) : null;
 
@@ -899,6 +899,20 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
  * derivation. The lifecycle role is left out: it is the machinery, not an author's role.
  * A policy with no USING admits nothing here, so it is skipped (fail closed).
  */
+/**
+ * The roles whose `manage` covers every row: each one holds an ALL policy USING true WITH CHECK
+ * true. Read back from {@link compileTableContract}, so a `manage` that desugars to manage-own
+ * (owner-scoped, or role-less on a row-scoped model) is never in it. The lifecycle role is left out.
+ */
+export function allRowsManageRoles(model: ModelDescriptor, opts: CompileOptions = {}): string[] {
+  const roles = new Set<string>();
+  for (const p of compileTableContract(model, opts).policies) {
+    if (p.command !== 'ALL' || p.using !== 'true' || p.check !== 'true') continue;
+    for (const role of p.roles) if (role !== LIFECYCLE_OWNER_ROLE) roles.add(role);
+  }
+  return [...roles].sort();
+}
+
 export function deleteRulePredicates(model: ModelDescriptor, opts: CompileOptions = {}): Record<string, string> {
   const byRole = new Map<string, string[]>();
   for (const p of compileTableContract(model, opts).policies) {

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

@@ -77,6 +77,7 @@ import { readStageStateTwice } from '../stage-read-consistency';
 import { renderApplyReceipt, renderCatchUpFailure } from '../plain-output';
 import { renderFkOrphanAdvisory, ownershipColumns } from '../fk-orphan-advisory';
 import { catchUpDerived, type CatchUpVenue } from '../derived-catchup';
+import { lifecycleApplyRefusal, lifecycleStateOnlyRefusal } from '../lifecycle-preflight';
 import { buildReconcileReport } from './db-reconcile';
 import { step, success, fail, info, warn, line as printLine } from '../output';
 
@@ -259,10 +260,12 @@ async function runCatchUp(
   flags: Record<string, string>,
   applied: number,
   onRefusal: 'exit' | 'throw',
+  declared?: Awaited<ReturnType<typeof loadDeclaredDerived>>,
 ): Promise<CatchUpReport> {
   const verbose = flags.verbose === 'true';
   try {
     const outcome = await catchUpDerived(venue, {
+      ...(declared !== undefined ? { declared } : {}),
       ...(flags.models ? { models: flags.models } : {}),
       onStart: () => step('Catching the functions, views and triggers up to the checkout...'),
       onRefusal,
@@ -328,6 +331,7 @@ async function catchUpAfterApply(
   plan: EdgePlan,
   venue: CatchUpVenue,
   flags: Record<string, string>,
+  declared?: Awaited<ReturnType<typeof loadDeclaredDerived>>,
 ): Promise<CatchUpReport> {
   if (!LANDED.has(result.status)) return { ok: true, statements: [] };
   if (flags['state-only'] === 'true') return { ok: true, statements: [] };
@@ -337,7 +341,7 @@ async function catchUpAfterApply(
   const applied = result.status === 'already-applied'
     ? 0
     : classifyGeneratedStatements((plan.statements ?? []).filter((s) => !unapplied.has(s))).executable.length;
-  return runCatchUp(venue, flags, applied, 'throw');
+  return runCatchUp(venue, flags, applied, 'throw', declared);
 }
 
 /**
@@ -510,6 +514,13 @@ async function applyPlanViaStage(
   const config = await resolveConfig(flags.stage);
   const { region } = config;
   const fn = opsFunction(config);
+  const declared = await loadDeclaredDerived(flags.models);
+  const lifecycleRefusal = await lifecycleApplyRefusal(lambdaQueryRunner(region, fn), declared?.models ?? [])
+    ?? (flags['state-only'] === 'true' ? await lifecycleStateOnlyRefusal(lambdaQueryRunner(region, fn), declared?.models ?? []) : null);
+  if (lifecycleRefusal) {
+    fail(lifecycleRefusal);
+    process.exit(1);
+  }
   const attestLineageLost = flags['attest-lineage-lost']; // validated (not bare 'true') in dbApplyCommand
 
   // The edge as hashes — internal bookkeeping, not what a reader came for. Verbose only.
@@ -653,7 +664,7 @@ async function applyPlanViaStage(
   }
 
   // Then the functions, views and triggers — on the same stage, credential-free, always.
-  const catchUp = await catchUpAfterApply(landedResult!, plan, { kind: 'stage', stage: flags.stage }, flags);
+  const catchUp = await catchUpAfterApply(landedResult!, plan, { kind: 'stage', stage: flags.stage }, flags, declared);
   exitOnCatchUpFailure(catchUp);
   const declaredGrantees = await declaredGranteesForReceipt(plan, flags);
   const advisoryModels = await modelsForAdvisory(landedResult!, flags);
@@ -934,6 +945,21 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     }
   }
 
+  step(connectingVia(dbSource));
+  const { runner, session, transaction, end } = await createUrlRunner(dbSource.url);
+  // Every gate below needs the declared derived bundle. Never evaluate the models barrel twice.
+  let declaredDbPromise: ReturnType<typeof loadDeclaredDerived> | undefined;
+  const declaredDb = (): ReturnType<typeof loadDeclaredDerived> =>
+    declaredDbPromise ??= loadDeclaredDerived(flags.models);
+  // Read-only, before the rollback point: a refused apply must not first take a snapshot, backup or dump.
+  const lifecycleRefusal = await lifecycleApplyRefusal(runner, (await declaredDb())?.models ?? [])
+    ?? (flags['state-only'] === 'true' ? await lifecycleStateOnlyRefusal(runner, (await declaredDb())?.models ?? []) : null);
+  if (lifecycleRefusal) {
+    fail(lifecycleRefusal);
+    await end();
+    process.exit(1);
+  }
+
   // Losing data should be hard (decision 11): a destructive plan applies
   // only confirmed (--confirm, always), with a durable rollback point, and —
   // when the stage declares an approver set — identity-approved (decision 12).
@@ -1051,16 +1077,8 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     }
   }
 
-  step(connectingVia(dbSource));
-  const { runner, session, transaction, end } = await createUrlRunner(dbSource.url);
-
   let landed: ApplyPlanResult | undefined;
   let catchUp: CatchUpReport = { ok: true, statements: [] };
-  // Both gates below need the declared derived bundle. Keep its existing lazy timing — the
-  // baseline gate is still the first reader — but never evaluate the models barrel twice.
-  let declaredDbPromise: ReturnType<typeof loadDeclaredDerived> | undefined;
-  const declaredDb = (): ReturnType<typeof loadDeclaredDerived> =>
-    declaredDbPromise ??= loadDeclaredDerived(flags.models);
   try {
     // The edge as hashes — internal bookkeeping, not what a reader came for. Verbose only.
   if (flags.verbose === 'true') info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
@@ -1090,6 +1108,12 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       runner,
       { verb: 'db:apply', actor: process.env.USER ?? 'unknown' },
       async () => {
+        // Re-checked under the lease, where the writes happen.
+        const leasedRefusal = await lifecycleApplyRefusal(runner, (await declaredDb())?.models ?? []);
+        if (leasedRefusal) {
+          fail(leasedRefusal);
+          process.exit(1);
+        }
         const result = await executeApplyPlan(runner, session, plan, {
           transaction,
           actor: process.env.USER ?? null,

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

@@ -28,7 +28,7 @@ import {
   backupKey, backupId, metaKey, utcStamp,
 } from '../backup';
 import { pgEnvFromUrl, pgKeepaliveConninfo } from './db';
-import { pollTaskUntilStopped } from '../task-poll';
+import { pollTaskUntilStopped, type TaskPollResult } from '../task-poll';
 import { step, success, fail, info, warn } from '../output';
 
 /** Which database db:backup dumps. LOCAL requires a target --stage (its bucket receives the upload
@@ -327,29 +327,70 @@ export function printRestoreWitness(
  * it requires --confirm; restoring production-tier data downward or into a production target raises
  * a louder warning (the S0 guards). The id encodes the source stage.
  */
-export async function dbRestoreCommand(flags: Record<string, string>): Promise<void> {
+/**
+ * The db:restore preflight — the destructive gate, DB-free. A restore DROPS and replaces a
+ * database, so this decides who is allowed to proceed before anything connects: the id must be
+ * present and well-formed, and `--confirm` is mandatory (with the cross-stage / prod-target
+ * warnings escalated). Extracted from the shell so the gate itself is asserted by a test — a
+ * refactor that let the write dispatch without --confirm goes red (closing-gate F1 method).
+ */
+export type RestorePreflight =
+  | { ok: true; fromStage: string; toStage: string }
+  | { ok: false; kind: 'usage'; message: string }
+  | { ok: false; kind: 'needs-confirm'; warnings: string[]; hint: string };
+
+export function restorePreflight(flags: Record<string, string>): RestorePreflight {
   const id = flags.from;
-  if (!id) {
-    fail('db:restore requires --from <backup-id> (see `everystack db:backups`).');
-    process.exit(1);
-  }
+  if (!id) return { ok: false, kind: 'usage', message: 'db:restore requires --from <backup-id> (see `everystack db:backups`).' };
   const ref = parseBackupRef(id);
-  if (!ref || !keyForId(id)) {
-    fail(`Malformed backup id: ${id}`);
-    process.exit(1);
-  }
+  if (!ref || !keyForId(id)) return { ok: false, kind: 'usage', message: `Malformed backup id: ${id}` };
   const fromStage = ref.stage;
   const toStage = flags.stage ?? fromStage;
-
-  // Destructive — always require --confirm. Production-tier source/target escalate the warning.
   if (!flags.confirm) {
-    warn(`Restore is DESTRUCTIVE — it drops and replaces ${toStage}'s database with backup ${id}.`);
+    // Destructive — always require --confirm. Production-tier source/target escalate the warning.
+    const warnings = [`Restore is DESTRUCTIVE — it drops and replaces ${toStage}'s database with backup ${id}.`];
     for (const g of [crossStageGuard(fromStage, toStage), restoreTargetGuard(toStage)]) {
-      if (g.requiresConfirm && g.warning) warn(g.warning);
+      if (g.requiresConfirm && g.warning) warnings.push(g.warning);
+    }
+    return { ok: false, kind: 'needs-confirm', warnings, hint: 'Re-run with --confirm to proceed.' };
+  }
+  return { ok: true, fromStage, toStage };
+}
+
+/**
+ * Map the restore task's poll outcome to an exit verdict — DB-free. The one guarantee it exists to
+ * hold: a restore that timed out, errored, or exited non-zero NEVER reports success. Only a clean
+ * `stopped` with exitCode 0 is a success; every other outcome is exit 1 with the intent to reconcile.
+ */
+export type RestoreVerdict = { exitCode: 0 | 1; kind: 'ok' | 'timeout' | 'error' | 'nonzero'; message: string };
+
+export function restorePollVerdict(poll: TaskPollResult, ctx: { id: string; toStage: string; intentKey: string }): RestoreVerdict {
+  if (poll.outcome === 'timeout')
+    return { exitCode: 1, kind: 'timeout', message: `db:restore timed out (last status: ${poll.lastStatus}). Intent ${ctx.intentKey} — reconcile via ECS/the S3 intent.` };
+  if (poll.outcome === 'error')
+    return { exitCode: 1, kind: 'error', message: `task:status failed repeatedly: ${poll.status.error}. The restore may still be running — reconcile intent ${ctx.intentKey}.` };
+  if (poll.status.exitCode !== 0)
+    return { exitCode: 1, kind: 'nonzero', message: `Restore failed (exit ${poll.status.exitCode ?? 'unknown'})${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}. The target DB may be partially restored — check the S3 intent ${ctx.intentKey} and the task logs.` };
+  return { exitCode: 0, kind: 'ok', message: `Restored ${ctx.id} into ${ctx.toStage}.` };
+}
+
+/** What a restored lifecycle app needs; shared by db:restore and db:fork. */
+export const LIFECYCLE_RESTORE_REPAIR =
+  'If the app declares lifecycle: true, DELETEs on those tables fail until you run db:apply, then db:reconcile --apply --overwrite-drift (docs/backups.md).';
+
+export async function dbRestoreCommand(flags: Record<string, string>): Promise<void> {
+  const id = flags.from;
+  const pre = restorePreflight(flags);
+  if (!pre.ok) {
+    if (pre.kind === 'usage') fail(pre.message);
+    else {
+      for (const w of pre.warnings) warn(w);
+      info(pre.hint);
     }
-    info('Re-run with --confirm to proceed.');
     process.exit(1);
+    return; // process.exit is mocked to throw in tests; keep the narrowing honest for callers
   }
+  const { toStage } = pre;
 
   step('Resolving deployed config...');
   let config: CliConfig;
@@ -383,19 +424,14 @@ export async function dbRestoreCommand(flags: Record<string, string>): Promise<v
 
   step(`Restoring ${id} into ${toStage} (pg_restore in the Task; this may take a while)...`);
   const poll = await pollTaskUntilStopped(config.region, fn, { runId, taskArn });
-  if (poll.outcome === 'timeout') {
-    fail(`db:restore timed out (last status: ${poll.lastStatus}). Intent ${intentKey} — reconcile via ECS/the S3 intent.`);
-    process.exit(1);
-  }
-  if (poll.outcome === 'error') {
-    fail(`task:status failed repeatedly: ${poll.status.error}. The restore may still be running — reconcile intent ${intentKey}.`);
-    process.exit(1);
-  }
-  if (poll.status.exitCode !== 0) {
-    fail(`Restore failed (exit ${poll.status.exitCode ?? 'unknown'})${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}. The target DB may be partially restored — check the S3 intent ${intentKey} and the task logs.`);
+  const verdict = restorePollVerdict(poll, { id, toStage, intentKey });
+  if (verdict.exitCode !== 0) {
+    fail(verdict.message);
     process.exit(1);
   }
-  success(`Restored ${id} into ${toStage}.`);
+  success(verdict.message);
+  // The dump carries no owners or grants, so a lifecycle table refuses every DELETE (never hard-deletes) until repaired.
+  info(LIFECYCLE_RESTORE_REPAIR);
 }
 
 /** db:backup:download — print (or save) a presigned URL to a backup's dump for local download. */

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

@@ -24,7 +24,7 @@ import { invokeAction, presignGet } from '../aws';
 import { keyForId, metaKey, parseBackupRef, isProductionTier, crossStageGuard } from '../backup';
 import { pollTaskUntilStopped } from '../task-poll';
 import { runStageBackup, stageBackupDeps } from '../stage-backup';
-import { printRestoreWitness } from './db-backup';
+import { LIFECYCLE_RESTORE_REPAIR, printRestoreWitness } from './db-backup';
 import { step, success, fail, info, warn } from '../output';
 
 export type ForkGuardVerdict =
@@ -157,5 +157,6 @@ export async function dbForkCommand(flags: Record<string, string>): Promise<void
   info('Next:');
   info(`  everystack db:fingerprint --stage ${target}     # where the fork is (a state some main commit declares)`);
   info(`  everystack db:plan --stage ${target}            # your branch's edge on top — descent composes for free`);
+  info(`  ${LIFECYCLE_RESTORE_REPAIR}`);
   info(`  sst remove --stage ${target}                    # teardown takes the database with it`);
 }

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

@@ -63,6 +63,7 @@ import { resolveModelsPath } from '../models-path';
 import { resolveConfig, opsFunction } from '../config';
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { lambdaQueryRunner, lambdaSessionRunner } from '../aws';
+import { lifecycleApplyRefusal } from '../lifecycle-preflight';
 import { loadModels } from './db-generate';
 import { loadDeclaredDerived, type DeclaredDerived } from '../declared-derived';
 import { introspectDerived } from '../derived-introspect';
@@ -237,6 +238,8 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
   }
 
   try {
+    const lifecycleNote = await lifecycleApplyRefusal(runner, models);
+    if (lifecycleNote) warn(lifecycleNote);
     let snapshot: SchemaSnapshot;
     let contract: AuthzContract;
     if (dbSource.kind === 'url') {

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

@@ -43,13 +43,12 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, FK_TARGETS_SQL, foreignKeyTargets, type ColumnRow, type ColumnSchema, type ForeignKeyTargetRow } from '../schema-introspect';
+import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, FK_TARGETS_SQL, foreignKeyTargets, type ColumnRow, type ColumnSchema, type ForeignKeyTargetRow, type TableSchema } from '../schema-introspect';
 import { fingerprintLive } from '../schema-fingerprint';
 import { ungovernedGrants, vestigialSequenceGrants, renderVestigialSequenceGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile';
 import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect';
 import { foldLifecycle } from '../lifecycle-pull';
-import { verifyLifecycle, LifecycleDriftError } from '../lifecycle-verify';
 import { LIFECYCLE_OWNER_ROLE } from '@everystack/model';
 
 /**
@@ -86,7 +85,7 @@ import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, typ
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
 import { renderDerivedSource, renderDerivedFile, renderDerivedDirectory, type DerivedRenderResult, type RenderedDerivedFile } from '../derived-render';
 import { containedPath } from '../generated-names';
-import { renderModelSource, renderModelFiles, pullableTables, skippedInfrastructureTables, modelVarName, externalForeignKeyWarnings, ABILITY_PRESETS, type RenderedModelFile } from '../model-render';
+import { renderModelSource, renderModelFiles, pullableTables, skippedInfrastructureTables, modelVarName, toCamelCase, externalForeignKeyWarnings, ABILITY_PRESETS, type RenderedModelFile } from '../model-render';
 import { deriveAbilities } from '../authz-derive';
 import type { QueryRunner } from '../authz-contract';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source';
@@ -249,6 +248,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   let derivedCatalog: DerivedCatalog | undefined;
   /** Tables folded to `lifecycle: true` (lifecycle-pull.ts). */
   let lifecycleTables: ReadonlySet<string> = new Set();
+  const lifecycleForeignKeyTables = new Set<string>();
   let lifecycleDeleteWhen: ReadonlyMap<string, string> = new Map();
   let matviewColumns: Map<string, ColumnSchema[]> | undefined;
   let candidatesByIdentity: Map<string, string[]> | undefined;
@@ -274,9 +274,6 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     // The derived layer rides the same pull (B5) — views/matviews/functions/sequences
     // render as descriptors; adoption is pull → commit → --baseline → clean reconcile.
     derivedCatalog = await introspectDerived(session);
-    const lifecycle = await verifyLifecycle(session, ['anon', 'authenticated', 'admin', LIFECYCLE_OWNER_ROLE, ...governRoles]);
-    if (lifecycle.failures.length) throw new LifecycleDriftError(lifecycle.failures);
-    for (const warning of lifecycle.notes) caution(warning);
     // --abilities live: the authz half of the on-ramp. Same connection, one more read —
     // the grants and policies that already exist become the models' declared abilities,
     // instead of a human transcribing them by hand.
@@ -351,6 +348,47 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       for (const line of renderVestigialSequenceGrants(vestigialSequenceGrants(contract), governedAtPull)) caution(line);
       pulledFingerprint = fingerprintLive(rawSnapshot, rawContract).hash;
     }
+    const tables = pullableTables(current, schema);
+    const derivedObjects = derivedCatalog.objects;
+    const isLifecycleTable = (table: TableSchema): boolean => {
+      const name = table.table.slice(table.table.indexOf('.') + 1);
+      return lifecycleTables.has(table.table) || (['deleted_at', 'deleted_by', 'deleted_batch', 'deleted_xid'].every(column => table.columns.some(c => c.name === column))
+        && derivedObjects.some(object => object.kind === 'trigger' && object.identity === `${table.table}.${name}_lifecycle_transition`));
+    };
+    for (const table of tables) {
+      const name = table.table.slice(table.table.indexOf('.') + 1);
+      if (isLifecycleTable(table)) {
+        lifecycleForeignKeyTables.add(table.table);
+        for (const fk of table.foreignKeys) {
+          if (fk.onDelete !== 'cascade') continue;
+          const parent = fk.refTable.includes('.') ? fk.refTable : `public.${fk.refTable}`;
+          const key = `${table.table}.${fk.columns.join(',')}`;
+          const parentTable = tables.find(t => t.table === parent);
+          // A one-column key into a parent rendered lifecycle: true renders as its hasMany dependent.
+          if (fk.columns.length === 1 && lifecycleTables.has(parent)) continue;
+          // Only a one-column key from a lifecycle parent can be declared: hasMany joins on one
+          // column, and a lifecycle child cannot cascade from a table without lifecycle. The
+          // pulled barrel does not link models, so the advice names the thunk form the pull uses.
+          if (fk.columns.length === 1 && parentTable && isLifecycleTable(parentTable)) {
+            const child = modelVarName(table.table);
+            const field = toCamelCase(fk.columns[0]);
+            caution(`${key} cascades from lifecycle table ${parent} in the database; db:pull cannot render ` + '`dependent`'
+              + `, so it is rendered as restrict. Declare \`hasMany(() => ${child}, '${field}', { dependent: 'cascade' })\` in ${modelVarName(parent)}'s relations`
+              + ` and remove \`onDelete\` from ${child}'s ${field} field; then db:plan shows no foreign-key change.`);
+          } else {
+            caution(`${key} cascades from ${parent} in the database; db:pull renders it as restrict, and the models cannot declare this cascade, so db:plan shows this key changing to restrict.`);
+          }
+        }
+      }
+      if (!lifecycleTables.has(table.table) && derivedCatalog.objects.some(object =>
+        object.kind === 'trigger' && object.identity === `${table.table}.${name}_lifecycle_transition`)) {
+        if (abilities === 'live') {
+          caution(`${table.table} has lifecycle objects but they are not exactly what the compiler writes. Rendered as a plain table. Run db:apply from the checkout that declared it, or review db:plan.`);
+        } else {
+          note(`${table.table} is a lifecycle table. The default pull renders it as a plain table; pass --abilities live to render lifecycle: true.`);
+        }
+      }
+    }
     // --matviews-as-tables: the flip needs real fields — one extra catalog read for the
     // matview columns the derived layer (definition-only) doesn't carry.
     if (matviewsAsTables) {
@@ -372,10 +410,6 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     await end?.();
   } catch (err: any) {
     await end?.().catch(() => {});
-    if (err instanceof LifecycleDriftError) {
-      for (const line of err.lines) console.error(line);
-      process.exit(1);
-    }
     fail(err.message);
     if (dbSource.kind === 'url') {
       detail('Check the connection string and that the database is accepting connections.');
@@ -494,10 +528,10 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
         : undefined;
       if (flags.out && !flags.out.endsWith('.ts')) {
         const dir = path.resolve(flags.out);
-        modelFiles = renderModelFiles(current, { schema, abilities, liveAuthz, governRoles, fkTargets, derived: embeddedDerived, externalDerived, lifecycleTables, lifecycleDeleteWhen })
+        modelFiles = renderModelFiles(current, { schema, abilities, liveAuthz, governRoles, fkTargets, derived: embeddedDerived, externalDerived, lifecycleTables, lifecycleDeleteWhen, lifecycleForeignKeyTables })
           .map((f) => ({ ...f, target: containedPath(dir, f.file) }));
       } else {
-        modelSource = renderModelSource(current, { schema, abilities, liveAuthz, governRoles, fkTargets, derived: embeddedDerived, lifecycleTables, lifecycleDeleteWhen });
+        modelSource = renderModelSource(current, { schema, abilities, liveAuthz, governRoles, fkTargets, derived: embeddedDerived, lifecycleTables, lifecycleDeleteWhen, lifecycleForeignKeyTables });
       }
     }
   } catch (err: any) {

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.