@everystack/cli 0.4.102 → 0.4.104

package/CHANGELOG.md

@@ -4,6 +4,68 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [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
+
+### BREAKING CHANGES
+
+- lifecycle delete and restore hand the batch id to the caller
+- lifecycle: { deleteWhen } refuses deleting a row its predicate does not allow
+- refuse dependent + where on a lifecycle parent's hasMany
+- can('read', { role, deleted: 'include' | 'only' }) on a lifecycle model
+- deleteWhen spliced on its own lines; a deleted reader is not granted deleted_by
+
+### Added
+
+- index the FK column of every lifecycle dependent
+- db:plan warns when a CREATE INDEX will block writes to a live table
+
 ## [0.4.102] - 2026-10-23
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.102",
+  "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.23"
+    "@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.38"
+    "@everystack/server": "0.4.40"
   },
   "scripts": {
     "test": "jest",

package/src/cli/authz-compile.ts

@@ -278,21 +278,38 @@ const granteeKey = (role: string): string => (isPseudoPublic(role) ? 'PUBLIC' :
 /** The policy-side spelling of a declared role — what `pg_policies` would report. */
 const policyRole = (role: string): string => (isPseudoPublic(role) ? 'public' : role);
 
+/**
+ * Who deleted a row, in which batch and which transaction: the lifecycle columns a deleted reader
+ * never selects. Only a `manage` role sees them; `deletedAt` stays visible to every reader.
+ */
+const DELETED_READ_HIDDEN = new Set(['deletedBy', 'deletedBatch', 'deletedXid']);
+
+/**
+ * `can('read', { role, deleted })` with no `columns`: it reaches deleted rows, whose deleted_by,
+ * deleted_batch and deleted_xid are set, so it grants SELECT on every other column instead of the
+ * whole table. Grants are a union: defineModel refuses a `manage` for the same role, and the policy
+ * compile refuses a second read for it, so nothing re-grants the table.
+ */
+const isDeletedReadOfEveryColumn = (a: Ability): boolean =>
+  a.action === 'read' && a.condition.deleted !== undefined && !isColumnAbility(a);
+
 /**
  * Column grants from column abilities. The action determines the PostgreSQL verb; the named role
  * (or authenticated for an owner-only ability) is the grantee. Field keys are snake-cased and
  * deduplicated, matching the introspected contract.
  */
-function compileColumnGrants(abilities: readonly Ability[]): Record<string, Record<string, string[]>> | undefined {
+function compileColumnGrants(abilities: readonly Ability[], fields: readonly string[] = []): Record<string, Record<string, string[]>> | undefined {
   // Null-prototype maps, as on the introspected side (assembleContract): a role is a key, and
   // '__proto__' passes the role-name guard, so a plain object would lose it.
   const out: Record<string, Record<string, Set<string>>> = Object.create(null);
+  const add = (role: string, verb: string, columns: readonly string[]): void => {
+    const cols = ((out[role] ??= Object.create(null) as Record<string, Set<string>>)[verb] ??= new Set<string>());
+    for (const column of columns) cols.add(toSnakeCase(column));
+  };
   for (const a of abilities) {
+    if (isDeletedReadOfEveryColumn(a)) add(granteeKey(a.condition.role!), 'SELECT', fields.filter((f) => !DELETED_READ_HIDDEN.has(f)));
     if (!isColumnAbility(a)) continue;
-    const role = granteeKey(a.condition.role ?? 'authenticated');
-    const verb = a.action === 'read' ? 'SELECT' : 'UPDATE';
-    const cols = ((out[role] ??= Object.create(null) as Record<string, Set<string>>)[verb] ??= new Set<string>());
-    for (const column of a.condition.columns!) cols.add(toSnakeCase(column));
+    add(granteeKey(a.condition.role ?? 'authenticated'), a.action === 'read' ? 'SELECT' : 'UPDATE', a.condition.columns!);
   }
   const grants: Record<string, Record<string, string[]>> = Object.create(null);
   for (const [role, verbs] of Object.entries(out)) {
@@ -443,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;
 
@@ -541,9 +558,13 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   const policy = (
     name: string, command: PolicyCommand, roles: string[],
     using: string | null, check: string | null,
+    deleted?: 'include' | 'only',
   ): void => {
-    if (lifecycleGuard && command === 'SELECT' && !roles.includes(LIFECYCLE_OWNER_ROLE)) {
-      using = andPredicates(lifecycleGuard, using) ?? lifecycleGuard;
+    // can('read', { deleted }): 'include' leaves the guard off this role's policy (its other
+    // restrictions stay); 'only' puts `(deleted_at IS NOT NULL)` in its place. Omitted: the guard.
+    if (lifecycleGuard && lifecycleCol && command === 'SELECT' && !roles.includes(LIFECYCLE_OWNER_ROLE) && deleted !== 'include') {
+      const state = deleted === 'only' ? `(${lifecycleCol} IS NOT NULL)` : lifecycleGuard;
+      using = andPredicates(state, using) ?? state;
     }
     // Same normalization the live producer applies (authz-contract's `predicate`): a model
     // pulled on one PostgreSQL major carries that major's deparse spelling in its predicates,
@@ -661,6 +682,7 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
         rawPredicate(a.condition.sql ?? a.condition.where, where),
       ) ?? 'true',
       null,
+      a.condition.deleted,
     );
   }
 
@@ -865,7 +887,7 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     // security downgrade via version skew.
     rls: { enabled: model.rls !== false, forced: model.rls !== false && model.writtenBy === 'app' },
     grants: compileGrants(model.abilities, model.privileges),
-    ...(compileColumnGrants(model.abilities) ? { columnGrants: compileColumnGrants(model.abilities) } : {}),
+    ...(compileColumnGrants(model.abilities, Object.keys(model.fields)) ? { columnGrants: compileColumnGrants(model.abilities, Object.keys(model.fields)) } : {}),
     policies,
   };
 }
@@ -877,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) {
@@ -945,8 +981,9 @@ function compileGrants(
     for (const v of verbs) set.add(v);
   };
   for (const a of abilities) {
-    // A column ability grants only its listed columns, never a table-level privilege.
-    if (isColumnAbility(a)) continue;
+    // A column ability grants only its listed columns, never a table-level privilege; nor does
+    // a deleted read (compileColumnGrants grants it every column but the three it may not see).
+    if (isColumnAbility(a) || isDeletedReadOfEveryColumn(a)) continue;
     const verbs = verbsFor(a.action);
     if (a.condition.role) {
       add(granteeKey(a.condition.role), verbs);

package/src/cli/authz-contract.ts

@@ -102,6 +102,12 @@ export interface PolicyContract {
   using: string | null;
   /** `WITH CHECK` predicate (deparsed), or null when absent. */
   check: string | null;
+  /**
+   * Set only by db:pull's lifecycle fold, never by the catalog read or the compiler: this role's
+   * read policy on a lifecycle table carries no `(deleted_at IS NULL)` guard ('include') or carries
+   * `(deleted_at IS NOT NULL)` instead ('only'), so it renders as can('read', { role, deleted }).
+   */
+  deleted?: 'include' | 'only';
 }
 
 /**

package/src/cli/authz-derive.ts

@@ -587,7 +587,9 @@ function deriveGovernedRole(contract: TableContract, role: string): {
         continue;
       }
       const frag = sqlFragment(p.using);
-      out.abilities.push(frag ? `can('${DML[priv]}', { role: ${tsString(role)}, sql: ${frag} })` : `can('${DML[priv]}', { role: ${tsString(role)} })`);
+      // A lifecycle read without the guard (or with deleted_at IS NOT NULL), marked by the fold.
+      const deleted = priv === 'SELECT' && p.deleted ? `, deleted: '${p.deleted}'` : '';
+      out.abilities.push(frag ? `can('${DML[priv]}', { role: ${tsString(role)}, sql: ${frag}${deleted} })` : `can('${DML[priv]}', { role: ${tsString(role)}${deleted} })`);
     }
     out.asAbility.add(priv);
     out.usedPolicies.add(p.name);

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') {
@@ -525,6 +528,8 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       // Only when the checkout declares objects: db:apply's catch-up does nothing at all for a
       // checkout that declares none (derived-catchup.ts), so listing drops there would be untrue.
       derived: declaredDerived && declaredDerived.objects.length > 0 ? derivedPlan : undefined,
+      lockWarnings: plan.lockWarnings,
+      deletedReads: plan.deletedReads,
     })) printLine(text);
 
     if (out !== '-') {

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,8 @@ 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;
   /** Each FK's exact target, by confrelid: an external target is declared from these names. */
@@ -273,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.
@@ -290,6 +288,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       current = fold.snapshot;
       derivedCatalog = fold.catalog;
       lifecycleTables = fold.tables;
+      lifecycleDeleteWhen = fold.deleteWhen;
       if (lifecycleTables.size) note(`Lifecycle: ${[...lifecycleTables].sort().join(', ')} rendered as lifecycle: true (generated columns, grants and functions folded).`);
       const contract = fold.contract;
       liveContract = rawContract;
@@ -349,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) {
@@ -370,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.');
@@ -492,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 })
+        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 });
+        modelSource = renderModelSource(current, { schema, abilities, liveAuthz, governRoles, fkTargets, derived: embeddedDerived, lifecycleTables, lifecycleDeleteWhen, lifecycleForeignKeyTables });
       }
     }
   } catch (err: any) {