@everystack/cli 0.4.102 → 0.4.103

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [Unreleased]
+
+### Fixed
+
+- export compileDeclaredState from @everystack/cli/model
+
+## [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.103",
   "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.24"
   },
   "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.39"
   },
   "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)) {
@@ -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,
   };
 }
@@ -945,8 +967,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-plan.ts

@@ -525,6 +525,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

@@ -249,6 +249,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();
+  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. */
@@ -290,6 +291,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;
@@ -492,10 +494,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 })
           .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 });
       }
     }
   } catch (err: any) {

package/src/cli/declared-diff.ts

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

package/src/cli/edge-plan.ts

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

package/src/cli/index-lock.ts

@@ -0,0 +1,65 @@
+/**
+ * ⚠ LOCK — which of a plan's statements build an index on a table that already holds rows.
+ *
+ * db:apply runs a plain `CREATE INDEX` inside its one transaction. PostgreSQL takes a SHARE lock
+ * on the table for the whole build, whatever its size: reads go on, INSERT/UPDATE/DELETE wait until
+ * the build finishes and the transaction commits. On a large table that is a write outage, so the
+ * plan says so, with the catalog's row estimate (`pg_class.reltuples`) to let the reader judge.
+ *
+ * Informational only: no --confirm, no exit code, and the plan is still "Safe to apply". Applying
+ * is unchanged. The estimate rides beside the snapshot (`rowEstimates`), never inside a table, so
+ * no fingerprint reads it.
+ *
+ * A table the same plan creates is not live, so it gets no line; an estimate of 0 is an empty table,
+ * no line; -1 is a table with data that was never analyzed, "row count unknown"; a read without
+ * estimates (an older ops Lambda) still warns, without a count.
+ */
+
+import { statementBody } from './sql-statement';
+import type { SchemaSnapshot } from './schema-introspect';
+
+export interface LockWarning {
+  index: string;
+  /** Schema-qualified, as the snapshot names it. */
+  table: string;
+  /** The estimate; null when the table has data but was never analyzed; absent when not read. */
+  rows?: number | null;
+}
+
+const IDENT = '"(?:[^"]|"")+"|[A-Za-z_][\\w$]*';
+const CREATE_INDEX = new RegExp(
+  `^CREATE\\s+(?:UNIQUE\\s+)?INDEX\\s+(?!CONCURRENTLY\\b)(?:IF\\s+NOT\\s+EXISTS\\s+)?(${IDENT})\\s+ON\\s+(?:ONLY\\s+)?((?:${IDENT})(?:\\.(?:${IDENT}))?)`,
+  'i',
+);
+const unquote = (part: string): string => (part.startsWith('"') ? part.slice(1, -1).replace(/""/g, '"') : part);
+const qualified = (name: string): string => {
+  const parts = name.match(new RegExp(IDENT, 'g')) ?? [name];
+  const clean = parts.map(unquote);
+  return clean.length === 1 ? `public.${clean[0]}` : clean.join('.');
+};
+
+export function indexLockWarnings(statements: readonly string[], live: SchemaSnapshot): LockWarning[] {
+  const liveTables = new Set(live.tables.map((t) => t.table));
+  const out: LockWarning[] = [];
+  for (const statement of statements) {
+    const m = CREATE_INDEX.exec(statementBody(statement));
+    if (!m) continue;
+    const table = qualified(m[2]);
+    if (!liveTables.has(table)) continue;
+    const estimate = live.rowEstimates?.[table];
+    if (estimate === 0) continue;
+    out.push({ index: unquote(m[1]), table, ...(estimate === undefined ? {} : { rows: estimate < 0 ? null : estimate }) });
+  }
+  return out;
+}
+
+const display = (table: string): string => (table.startsWith('public.') ? table.slice('public.'.length) : table);
+
+export function lockLines(warnings: readonly LockWarning[]): string[] {
+  return warnings.map((w) => {
+    const count = w.rows === undefined ? ''
+      : w.rows === null ? ' (row count unknown)'
+        : ` (about ${w.rows.toLocaleString('en-US')} ${w.rows === 1 ? 'row' : 'rows'})`;
+    return `⚠ LOCK — CREATE INDEX ${w.index} on ${display(w.table)} blocks writes to that table until it is built${count}.`;
+  });
+}

package/src/cli/lifecycle-derived.ts

@@ -8,7 +8,14 @@
  *    owned by the lifecycle role stamps the four lifecycle columns and skips the delete. A row that
  *    is already deleted keeps its stamps. It refuses to run as a trigger on any other table: a
  *    role holding EXECUTE could otherwise attach it to its own table and soft-delete `<t>` rows by id.
+ *    It hands the batch to a caller that cannot read it: for a top-level DELETE (trigger depth 1) it
+ *    appends `<JSON-quoted key> <batch>` as a line to the transaction-local setting
+ *    `everystack.lifecycle_batch`, one line per stamped root. Informational, never a gate: any role
+ *    can set that name, and the stamp columns stay the truth.
  *  - `<t>_lifecycle_guard` (BEFORE INSERT OR UPDATE): refuses any direct write to those columns.
+ *  - `<t>_lifecycle_delete_when` (BEFORE UPDATE OF deleted_at, live -> deleted), only for
+ *    lifecycle: { deleteWhen }: refuses the stamp (23514) unless the predicate is TRUE for the row,
+ *    for a direct delete and a cascade alike. Its predicate rides on its own manifest only.
  *  - `<t>_restore(p_id)`: undoes a delete for whoever may delete p_id. A SECURITY DEFINER
  *    function owned by the lifecycle role, EXECUTE to exactly the roles with a delete rule. The
  *    caller is the SET ROLE role (session_user when none); a role branch passes when the caller
@@ -18,7 +25,8 @@
  *    the whole cascade subtree that delete stamped, on p_id's authority alone: the delete took
  *    those rows whatever the deleter's rights over them, so its undo must too, or a user's
  *    restore would leave the likes others put on their posts deleted for good. It never makes a
- *    live row under a deleted parent (see restoreFunction), and it returns counts, never ids.
+ *    live row under a deleted parent (see restoreFunction), and it returns counts and the batch it
+ *    restored (`{ restored, skipped, batch }`; batch null for a legacy row), never ids.
  *
  * A lifecycle parent's hasMany `dependent` cannot ride the foreign key: its DELETE never removes the
  * row, so the FK never fires (relationDeleteActions compiles a lifecycle parent's 'cascade' to
@@ -92,7 +100,7 @@ export interface LifecycleDeclaration {
   edges: LifecycleEdge[];
 }
 export const MANIFEST_VERSION = 1;
-export const LIFECYCLE_ROLES = ['transition', 'guard', 'restore', 'cascade', 'parent'] as const;
+export const LIFECYCLE_ROLES = ['transition', 'guard', 'restore', 'cascade', 'parent', 'delete_when'] as const;
 export type LifecycleRole = typeof LIFECYCLE_ROLES[number];
 export interface LifecycleManifest {
   everystack: 'lifecycle';
@@ -100,6 +108,9 @@ export interface LifecycleManifest {
   role: LifecycleRole;
   model: string;
   decl: LifecycleDeclaration;
+  /** The `delete_when` function's own input: lifecycle: { deleteWhen }'s predicate text. Carried on
+   *  that function's manifest only, so a guard added later changes no other function's manifest. */
+  deleteWhen?: string;
   defHash: string;
 }
 type TableName = Pick<LifecycleTable, 'schema' | 'table'>;
@@ -179,7 +190,7 @@ function lifecycleDependents(models: readonly ModelDescriptor[]): ModelDependent
   return out.sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
 }
 
-function lifecycleObjects(model: LifecycleTable, dependents: readonly LifecycleDependent[], decl: LifecycleDeclaration): LifecycleObject[] {
+function lifecycleObjects(model: LifecycleTable, dependents: readonly LifecycleDependent[], decl: LifecycleDeclaration, deleteWhen?: string): LifecycleObject[] {
   const table = qualified(model);
   const label = labelOf(model);
   const pk = pkOf(model);
@@ -200,6 +211,7 @@ function lifecycleObjects(model: LifecycleTable, dependents: readonly LifecycleD
 DECLARE
   claims text := pg_catalog.current_setting('request.jwt.claims', true);
   actor text;
+  batch uuid := pg_catalog.gen_random_uuid();
 ${check ? `${check.declare}\n` : ''}BEGIN
   IF TG_TABLE_SCHEMA <> ${literal(model.schema)} OR TG_TABLE_NAME <> ${literal(model.table)} THEN
     RAISE EXCEPTION USING ERRCODE = '42501', MESSAGE = ${literal(
@@ -212,9 +224,16 @@ ${check ? `  ${readCommittedOnly(model)}\n` : ''}  IF lc.claims IS NOT NULL AND
   UPDATE ${table}
      SET ${at} = pg_catalog.now(),
          ${by} = lc.actor,
-         ${batch} = ${check ? 'lc.batch' : 'pg_catalog.gen_random_uuid()'},
+         ${batch} = lc.batch,
          ${xid} = pg_catalog.txid_current()
    WHERE ${pk} = OLD.${pk} AND ${at} IS NULL;
+  -- The batch, for the caller that cannot read it: one line per root of a top-level DELETE,
+  -- appended to a transaction-local setting. Informational; the stamp columns are the truth.
+  IF FOUND AND pg_catalog.pg_trigger_depth() = 1 THEN
+    PERFORM pg_catalog.set_config('everystack.lifecycle_batch',
+      pg_catalog.concat_ws(E'\\n', NULLIF(pg_catalog.current_setting('everystack.lifecycle_batch', true), ''),
+        pg_catalog.to_jsonb(OLD.${pk}::text)::text || ' ' || lc.batch::text), true);
+  END IF;
 ${check ? `${check.body}\n` : ''}  RETURN NULL;
 END`,
   });
@@ -254,6 +273,7 @@ END`,
     }),
     ...cascadeObjects(model, dependents.filter((d) => d.parent === model && d.dependent === 'cascade')),
     ...parentLiveObjects(model, dependents.filter((d) => d.child === model)),
+    ...deleteWhenObjects(model, deleteWhen),
   ];
 }
 
@@ -439,7 +459,7 @@ ${parentsLive(m, `lc.r${i}`, 'lc.live := false;').replace(/^/gm, '      ')}
     lc.skipped := lc.skipped + lc.n;`).join('\n');
 
   const walk = edges.length === 0
-    ? `  RETURN pg_catalog.jsonb_build_object('restored', 1, 'skipped', 0);`
+    ? `  RETURN pg_catalog.jsonb_build_object('restored', 1, 'skipped', 0, 'batch', lc.root.b);`
     : `  lc.batch_id := lc.root.b;
   IF lc.batch_id IS NOT NULL THEN
     lc.s0 := ARRAY[${id}];
@@ -458,7 +478,7 @@ ${pass}
     END LOOP;
 ${left}
   END IF;
-  RETURN pg_catalog.jsonb_build_object('restored', lc.restored, 'skipped', lc.skipped);`;
+  RETURN pg_catalog.jsonb_build_object('restored', lc.restored, 'skipped', lc.skipped, 'batch', lc.batch_id);`;
 
   return defineFunction(`${model.schema}.${model.table}_restore`, {
     args: [{ name: 'p_id', type: pkType(model) }],
@@ -582,7 +602,6 @@ function restrictCheck(model: LifecycleTable, dependents: readonly LifecycleDepe
       || ${literal(` live row(s) of ${labelOf(d.child)} still reference it (dependent 'restrict' on ${d.column})`)};
   END IF;`).join('\n');
   const declare = [
-    'batch uuid := pg_catalog.gen_random_uuid();',
     'n bigint;',
     ...(walk ? ['grew boolean;', ...tables.flatMap((m, i) => [
       `s${i} ${pkType(m)}[] := '{}';`, `f${i} ${pkType(m)}[] := '{}';`, `nf${i} ${pkType(m)}[];`,
@@ -616,6 +635,52 @@ ${checks}`;
   return { declare, body };
 }
 
+/**
+ * `<t>_lifecycle_delete_when` — lifecycle: { deleteWhen }'s guard. BEFORE UPDATE OF deleted_at on
+ * the live -> deleted stamp, so it fires for the row's own stamp (the transition's UPDATE) and for
+ * a parent's cascade stamp alike (a cascaded child's BEFORE DELETE transition never runs). The
+ * predicate is read with bare column names against the row as it still stands (a BEFORE trigger:
+ * the table holds the old values), one primary-key lookup per stamped row. The predicate sits on
+ * lines of its own, so a trailing `--` comment in it ends only its own line. Anything but TRUE
+ * refuses with 23514 and the constraint name, naming the table and never a row value; the whole
+ * statement rolls back, so one guarded child refuses its parent's delete. No role test: only the
+ * lifecycle role stamps (the guard), and restore and purge never make this transition.
+ */
+function deleteWhenObjects(model: LifecycleTable, deleteWhen: string | undefined): LifecycleObject[] {
+  if (deleteWhen === undefined) return [];
+  const name = `${model.schema}.${model.table}_lifecycle_delete_when`;
+  const pk = pkOf(model);
+  const guard = lifecycleTriggerFunction(name, `
+#variable_conflict use_column
+<<lc>>
+DECLARE
+  allowed boolean;
+BEGIN
+  ${ownTableOnly(model, name)}
+  SELECT (
+${deleteWhen}
+) INTO lc.allowed FROM ${qualified(model)} WHERE ${pk} = OLD.${pk};
+  IF lc.allowed IS NOT TRUE THEN
+    RAISE EXCEPTION USING ERRCODE = '23514', CONSTRAINT = ${literal(`${model.table}_lifecycle_delete_when`)},
+      SCHEMA = ${literal(model.schema)}, TABLE = ${literal(model.table)},
+      MESSAGE = ${literal(`delete of ${labelOf(model)} refused: the model's deleteWhen does not allow deleting this row`)};
+  END IF;
+  RETURN NEW;
+END`);
+  return [
+    guard,
+    lifecycleTrigger(`${model.table}_lifecycle_delete_when`, {
+      on: model,
+      timing: 'before',
+      events: ['update'],
+      of: [toSnakeCase(LIFECYCLE_COLUMNS[0])],
+      forEach: 'row',
+      condition: sql`OLD.${AT} IS NULL AND NEW.${AT} IS NOT NULL`,
+      execute: guard,
+    }),
+  ];
+}
+
 /**
  * `<t>_lifecycle_parent` on a lifecycle child: a live row may not reference a deleted parent of a
  * 'cascade' or 'restrict' relation. Only a lifecycle parent can be deleted and still be there.
@@ -686,7 +751,7 @@ export function declOf(model: ModelDescriptor, dependents: readonly ModelDepende
 }
 
 /** One generator for model emission and verification of recorded JSON inputs. */
-export function regenerateLifecycle(model: string, decl: LifecycleDeclaration): LifecycleObject[] {
+export function regenerateLifecycle(model: string, decl: LifecycleDeclaration, deleteWhen?: string): LifecycleObject[] {
   const root = decl.tables[model];
   if (!root) throw new Error(`lifecycle declaration misses ${model}`);
   const dependents = decl.edges.map(edge => {
@@ -696,7 +761,7 @@ export function regenerateLifecycle(model: string, decl: LifecycleDeclaration):
     const { schema, name: table } = parseQualified(edge.child);
     return { parent, child: decl.tables[edge.child] ?? { schema, table }, column: edge.column, dependent: edge.dependent };
   });
-  return lifecycleObjects(root, dependents, decl);
+  return lifecycleObjects(root, dependents, decl, deleteWhen);
 }
 
 /** The generated lifecycle objects, with comments stamped by the ordinary reconciler. */
@@ -707,12 +772,13 @@ export function lifecycleDerived(models: readonly ModelDescriptor[]): DerivedDes
     .sort((a, b) => labelOf(a) < labelOf(b) ? -1 : labelOf(a) > labelOf(b) ? 1 : 0)
     .flatMap(model => {
       const decl = declOf(model, dependents);
-      const generated = regenerateLifecycle(labelOf(model), decl);
+      const generated = regenerateLifecycle(labelOf(model), decl, model.deleteWhen);
       for (const object of generated) {
         if (object.kind !== 'function') continue;
         const role = lifecycleRole(object.name, labelOf(model));
         if (!role) throw new Error(`unknown lifecycle function ${object.name}`);
-        const manifest: LifecycleManifest = { everystack: 'lifecycle', v: MANIFEST_VERSION, role, model: labelOf(model), decl, defHash: canonHash(canonOfFunction(object)) };
+        const manifest: LifecycleManifest = { everystack: 'lifecycle', v: MANIFEST_VERSION, role, model: labelOf(model), decl,
+          ...(role === 'delete_when' && model.deleteWhen !== undefined ? { deleteWhen: model.deleteWhen } : {}), defHash: canonHash(canonOfFunction(object)) };
         object.comment = JSON.stringify(manifest);
       }
       // Only the emitter binds table references back to Models; the builders never see them.

package/src/cli/lifecycle-pull.ts

@@ -22,6 +22,7 @@ import type { SchemaSnapshot, TableSchema } from './schema-introspect';
 import type { AuthzContract, PolicyContract, TableContract } from './authz-contract';
 import type { DerivedCatalog } from './derived-introspect';
 import { compileTableContract } from './authz-compile';
+import { lifecycleFkIndexName } from './schema-compile';
 
 /** The generated columns as the catalog reports them (`format_type`), nullable, no default. */
 const GENERATED_COLUMNS: Record<string, string> = {
@@ -32,6 +33,7 @@ const GENERATED_COLUMNS: Record<string, string> = {
 };
 
 const GUARD = '(deleted_at IS NULL)';
+const DELETED_ONLY = '(deleted_at IS NOT NULL)';
 
 /** The commands the measured effective matrix reports (`effectivePrivileges`). */
 const EFFECTIVE_COMMANDS = new Set(['SELECT', 'INSERT', 'UPDATE', 'DELETE']);
@@ -42,6 +44,8 @@ export interface LifecycleFold {
   catalog: DerivedCatalog;
   /** Schema-qualified tables folded to `lifecycle: true`. */
   tables: Set<string>;
+  /** lifecycle: { deleteWhen }'s predicate per folded table, read from its delete_when function's manifest. */
+  deleteWhen: Map<string, string>;
 }
 
 const split = (qualified: string): { schema: string; name: string } => {
@@ -79,8 +83,31 @@ function columnsAreGenerated(table: TableSchema): boolean {
   });
 }
 
+/** The lifecycle columns a deleted reader is never granted (compileColumnGrants). */
+const DELETED_READ_HIDDEN = new Set(['deleted_by', 'deleted_batch', 'deleted_xid']);
+
+/**
+ * can('read', { role, deleted }) with no columns compiles to a column SELECT of every column but
+ * deleted_by, deleted_batch and deleted_xid. Fold exactly that grant back to the table SELECT the
+ * renderer reads as a plain role read, so the pull renders `deleted` without a columns list; the
+ * compile turns it back into the same column grant. Any other column set stays as it is.
+ */
+function foldDeletedReadGrants(folded: TableContract, table: TableSchema): void {
+  const every = sorted(table.columns.map((c) => c.name).filter((name) => !DELETED_READ_HIDDEN.has(name)));
+  for (const p of folded.policies) {
+    if (p.deleted === undefined || p.roles.length !== 1) continue;
+    const role = p.roles[0];
+    const cols = folded.columnGrants?.[role];
+    if (!cols || folded.grants[role]?.includes('SELECT') || sorted(cols.SELECT) !== every) continue;
+    folded.grants = { ...folded.grants, [role]: [...(folded.grants[role] ?? []), 'SELECT'].sort() };
+    const { SELECT: _select, ...rest } = cols;
+    const { [role]: _role, ...others } = folded.columnGrants!;
+    folded.columnGrants = Object.keys(rest).length ? { ...others, [role]: rest } : others;
+  }
+}
+
 /** The folded contract for one table, or undefined when the table is not exactly lifecycle. */
-function foldContract(live: TableContract): TableContract | undefined {
+function foldContract(live: TableContract, table: TableSchema): TableContract | undefined {
   const role = LIFECYCLE_OWNER_ROLE;
   const expected = reservedRoleContract(live.table);
   if (sorted(live.grants[role]) !== sorted(expected.grants[role])) return undefined;
@@ -111,8 +138,20 @@ function foldContract(live: TableContract): TableContract | undefined {
       continue;
     }
     const rest = unguarded(p.using);
-    if (rest === undefined) return undefined;
-    policies.push({ ...p, using: rest ?? 'true' });
+    if (rest !== undefined) {
+      policies.push({ ...p, using: rest ?? 'true' });
+      continue;
+    }
+    // can('read', { role, deleted }): a role's own read policy compiled without the guard
+    // ('include') or with (deleted_at IS NOT NULL) in its place ('only'). Any other SELECT policy
+    // without the guard leaves the table unfolded, as before.
+    const own = p.roles.length === 1 && !['anon', 'authenticated', 'public'].includes(p.roles[0])
+      && p.name === `${split(live.table).name}_select_${p.roles[0]}`;
+    if (!own) return undefined;
+    if (p.using === DELETED_ONLY) policies.push({ ...p, using: 'true', deleted: 'only' });
+    else if (p.using?.startsWith(`(${DELETED_ONLY} AND `) && p.using.endsWith(')')) {
+      policies.push({ ...p, using: p.using.slice(DELETED_ONLY.length + 6, -1), deleted: 'only' });
+    } else policies.push({ ...p, deleted: 'include' });
   }
 
   const { [role]: _grant, ...grants } = live.grants;
@@ -125,6 +164,7 @@ function foldContract(live: TableContract): TableContract | undefined {
     const { [role]: _eff, ...effectivePrivileges } = live.effectivePrivileges;
     folded.effectivePrivileges = effectivePrivileges;
   }
+  foldDeletedReadGrants(folded, table);
   return folded;
 }
 
@@ -143,28 +183,62 @@ function generatedIdentities(table: TableSchema): string[] {
     `${schema}.${name}_restore(${arg})`,
     `${table.table}.${name}_lifecycle_transition`,
     `${table.table}.${name}_lifecycle_guard`,
+    `${schema}.${name}_lifecycle_delete_when()`,
+    `${table.table}.${name}_lifecycle_delete_when`,
   ];
 }
 
+/**
+ * The generator's lifecycle FK index (lifecycleDependentIndexes): plain btree, exactly the columns of
+ * a foreign key into a folded lifecycle table, under exactly the generated name. Folded like the
+ * lifecycle columns, so the pull never renders it as an author index. Anything else stays.
+ */
+function withoutGeneratedFkIndexes(t: TableSchema, lifecycleTables: ReadonlySet<string>): TableSchema {
+  const name = t.table.slice(t.table.indexOf('.') + 1);
+  const indexes = t.indexes.filter((ix) => !(
+    !ix.unique && !ix.where && !ix.using && !ix.include?.length
+    && ix.name === lifecycleFkIndexName(name, ix.columns)
+    && t.foreignKeys.some((fk) => lifecycleTables.has(fk.refTable.includes('.') ? fk.refTable : `public.${fk.refTable}`)
+      && JSON.stringify(fk.columns) === JSON.stringify(ix.columns))));
+  return indexes.length === t.indexes.length ? t : { ...t, indexes };
+}
+
 export function foldLifecycle(snapshot: SchemaSnapshot, contract: AuthzContract, catalog: DerivedCatalog): LifecycleFold {
   const tables = new Set<string>();
   const foldedContracts = new Map<string, TableContract>();
   for (const table of snapshot.tables) {
     if (table.primaryKey.length !== 1 || !columnsAreGenerated(table)) continue;
     const live = contract.tables.find((t) => t.table === table.table);
-    const folded = live && live.rls.enabled ? foldContract(live) : undefined;
+    const folded = live && live.rls.enabled ? foldContract(live, table) : undefined;
     if (!folded) continue;
     tables.add(table.table);
     foldedContracts.set(table.table, folded);
   }
-  if (tables.size === 0) return { snapshot, contract, catalog, tables };
+  if (tables.size === 0) return { snapshot, contract, catalog, tables, deleteWhen: new Map() };
+
+  // A guarded table's predicate is the delete_when function's manifest input. The pull must render
+  // exactly that text, or the next plan would rebuild the guard; without it, refuse rather than drop
+  // the guard or render it as an author function.
+  const deleteWhen = new Map<string, string>();
+  for (const table of tables) {
+    const { schema, name } = split(table);
+    const fn = catalog.objects.find((o) => o.kind === 'function' && o.identity === `${schema}.${name}_lifecycle_delete_when()`);
+    if (!fn) continue;
+    let manifest: { role?: unknown; model?: unknown; deleteWhen?: unknown } | undefined;
+    try { manifest = typeof fn.comment === 'string' ? JSON.parse(fn.comment) : undefined; } catch { manifest = undefined; }
+    if (!manifest || manifest.role !== 'delete_when' || manifest.model !== table || typeof manifest.deleteWhen !== 'string' || manifest.deleteWhen.trim() === '') {
+      throw new Error(`db:pull: ${fn.identity} carries no readable deleteWhen in its lifecycle manifest, so ${table}'s lifecycle: { deleteWhen } `
+        + `cannot be rendered exactly. Run db:apply from the checkout that declared it (it rewrites the manifest), then pull again.`);
+    }
+    deleteWhen.set(table, manifest.deleteWhen);
+  }
 
   const generated = new Set(snapshot.tables.filter((t) => tables.has(t.table)).flatMap(generatedIdentities));
   return {
     snapshot: {
       ...snapshot,
-      tables: snapshot.tables.map((t) =>
-        tables.has(t.table) ? { ...t, columns: t.columns.filter((c) => !Object.hasOwn(GENERATED_COLUMNS, c.name)) } : t),
+      tables: snapshot.tables.map((t) => withoutGeneratedFkIndexes(
+        tables.has(t.table) ? { ...t, columns: t.columns.filter((c) => !Object.hasOwn(GENERATED_COLUMNS, c.name)) } : t, tables)),
     },
     contract: { ...contract, tables: contract.tables.map((t) => foldedContracts.get(t.table) ?? t) },
     catalog: {
@@ -173,5 +247,6 @@ export function foldLifecycle(snapshot: SchemaSnapshot, contract: AuthzContract,
       provenance: catalog.provenance.filter((p) => !generated.has(p.identity)),
     },
     tables,
+    deleteWhen,
   };
 }

package/src/cli/lifecycle-verify.ts

@@ -152,6 +152,8 @@ export async function verifyLifecycle(session: SessionRunner, governedRoles: rea
       && normalizeArgType(live.argTypes[0]) === normalizeArgType(pkTypes[0]);
   });
   const manifests = new Map<string, LifecycleManifest>();
+  /** lifecycle: { deleteWhen }'s predicate per model, from its delete_when function's own manifest. */
+  const deleteWhenOf = new Map<string, string>();
   const groups = new Map<string, { decl: LifecycleDeclaration; from: string }>();
   for (const [id, live] of liveFunctions) {
     let raw: unknown;
@@ -169,6 +171,10 @@ export async function verifyLifecycle(session: SessionRunner, governedRoles: rea
       || typeof raw.defHash !== 'string' || !/^[a-f0-9]{64}$/.test(raw.defHash) || !raw.decl.tables[raw.model]) { add(id, 'malformed lifecycle manifest'); continue; }
     if (lifecycleRole(live.name, raw.model) !== raw.role) { add(id, 'manifest role does not match function name'); continue; }
     const manifest = raw as unknown as LifecycleManifest;
+    if (manifest.role === 'delete_when') {
+      if (typeof manifest.deleteWhen !== 'string' || manifest.deleteWhen.trim() === '') { add(id, 'malformed lifecycle manifest'); continue; }
+      deleteWhenOf.set(manifest.model, manifest.deleteWhen);
+    }
     manifests.set(id, manifest);
     const prev = groups.get(manifest.model);
     if (prev && JSON.stringify(prev.decl) !== JSON.stringify(manifest.decl)) add(id, `conflicting declarations for ${manifest.model}`);
@@ -195,7 +201,7 @@ export async function verifyLifecycle(session: SessionRunner, governedRoles: rea
         && same(strings(actual.references), strings(parent?.pk_columns)) && actual.action === 'r')) add(`${edge.child}.${edge.column}`, 'foreign key differs from catalog');
     }
     let objects;
-    try { objects = regenerateLifecycle(model, decl); } catch { add(from, 'malformed declaration cannot regenerate'); continue; }
+    try { objects = regenerateLifecycle(model, decl, deleteWhenOf.get(model)); } catch { add(from, 'malformed declaration cannot regenerate'); continue; }
     for (const object of objects) {
       if (object.kind === 'function') expectedFunctions.set(canonOfFunction(object).identity, object);
       else { const canon = canonOfTrigger(object); expectedTriggers.set(canon.identity, canon); }

package/src/cli/migration-compile.ts

@@ -19,9 +19,9 @@
  * lands with whole-DB introspection. The emission is identical either way.
  */
 
-import { relationDeleteActions, type ModelDescriptor, type Module, type SequenceDescriptor } from '@everystack/model';
+import { lifecycleDependentIndexes, relationDeleteActions, type ModelDescriptor, type Module, type SequenceDescriptor } from '@everystack/model';
 import type { AuthzContract, TableContract } from './authz-contract';
-import { compileCreateTable, compileEnums, compileSequences, sequenceCreateSql, foreignKeySql, modelConstraintSpecs, qualifiedTable, toSnakeCase, type CompileTableOptions } from './schema-compile';
+import { compileCreateTable, compileEnums, compileSequences, sequenceCreateSql, foreignKeySql, modelConstraintSpecs, dependentIndexSpecs, qualifiedTable, toSnakeCase, type CompileTableOptions } from './schema-compile';
 import { compileTableContract } from './authz-compile';
 import { emitReconcileSql } from './authz-reconcile';
 import { emitSchemaSql, nextvalSequence, type SchemaChange } from './schema-diff';
@@ -48,6 +48,7 @@ export function compileMigration(
   // A parent's hasMany `dependent` sets a child FK's ON DELETE; resolved over the whole set
   // from THIS set, before any FK is compiled.
   const dependents = relationDeleteActions(models);
+  const dependentIndexes = lifecycleDependentIndexes(models);
 
   // 0. Extensions — the BOOTSTRAP, before any table that might use one of their types.
   //    compileModuleMigration has always emitted these; compileMigration had no way to,
@@ -113,7 +114,7 @@ export function compileMigration(
   //     schema-qualified table, so a non-public index targets the right table.
   const indexCreates: SchemaChange[] = [];
   for (const model of models) {
-    for (const ix of modelConstraintSpecs(model).indexes) {
+    for (const ix of [...modelConstraintSpecs(model).indexes, ...dependentIndexSpecs(model, dependentIndexes)]) {
       indexCreates.push({
         kind: 'createIndex', table: qualifiedTable(model), name: ix.name, columns: ix.columns, unique: ix.unique,
         ...(ix.where ? { where: ix.where } : {}),

package/src/cli/migration-generate.ts

@@ -16,7 +16,7 @@
  */
 
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
-import { assertExternalTargets, relationDeleteActions } from '@everystack/model';
+import { assertExternalTargets, lifecycleDependentIndexes, relationDeleteActions } from '@everystack/model';
 import type { SchemaSnapshot, ColumnSchema } from './schema-introspect';
 import type { AuthzContract, SequenceGrantContract } from './authz-contract';
 import { compileTableSchema, compileRenames, compileTableRenames, compileTableMoves, compileCreateTable, compileEnums, compileSequences } from './schema-compile';
@@ -144,12 +144,13 @@ export function generateMigration(
   assertExternalTargets(models);
   // hasMany `dependent` → the child FK's ON DELETE, derived from THIS set (and checked, for the same reason).
   const dependents = relationDeleteActions(models);
+  const dependentIndexes = lifecycleDependentIndexes(models);
   const schema = opts.schema ?? 'public';
   // A table's schema comes from the model first (package tables live in dist/ops/auth),
   // then the call default — so one run spans schemas.
   const schemaOf = (m: ModelDescriptor): string => m.schema ?? schema;
   const desiredEnums = compileEnums(models);
-  const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema, dependents })), enums: desiredEnums, ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}) };
+  const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema, dependents, dependentIndexes })), enums: desiredEnums, ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}) };
   const declaredTables = new Set(desired.tables.map((t) => t.table));
   const declaredEnums = new Set(desiredEnums.map((e) => e.name));
   // Scope both tables and enums to what the Models declare — an undeclared table OR enum

package/src/cli/model-api.ts

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

package/src/cli/model-render.ts

@@ -112,6 +112,8 @@ export interface RenderOptions {
   externalDerived?: ExternalDerived;
   /** Tables db:pull folded to `lifecycle: true` (lifecycle-pull.ts): rendered with that key, no softDelete line. */
   lifecycleTables?: ReadonlySet<string>;
+  /** lifecycle: { deleteWhen }'s predicate per folded table (lifecycle-pull.ts), rendered verbatim. */
+  lifecycleDeleteWhen?: ReadonlyMap<string, string>;
 }
 
 /**
@@ -792,7 +794,7 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
 }
 
 /** One `export const X = defineModel(...)` block for a table. */
-export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map(), abilities = 'commented', liveAuthz?: Map<string, TableContract>, governRoles?: ReadonlySet<string>, fkTargets?: FkTargets, lifecycle = false): string {
+export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map(), abilities = 'commented', liveAuthz?: Map<string, TableContract>, governRoles?: ReadonlySet<string>, fkTargets?: FkTargets, lifecycle: boolean | string = false): string {
   // A CHECK that reverses to a single field's .validate() is rendered on the field (ergonomic);
   // the rest stay table-level check(). Both round-trip — this only chooses the nicer form.
   const validates = new Map<string, string>();
@@ -818,7 +820,11 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   // put it, proving the position is mechanical-edit-friendly).
   const stanza = abilitiesStanza(abilities, table, liveAuthz, governRoles);
   const writtenBy = writtenByStanza(table, liveAuthz);
-  const softDelete = lifecycle ? '  lifecycle: true,\n' : softDeleteStanza(table, stanza.publicRead, stanza.grantsDelete);
+  // A guarded table renders its predicate inside sql`…`, escaped so the template's cooked string
+  // is the predicate text exactly (the model stores it verbatim; the generated guard hashes it).
+  const softDelete = typeof lifecycle === 'string'
+    ? `  lifecycle: { deleteWhen: sql\`${lifecycle.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')}\` },\n`
+    : lifecycle ? '  lifecycle: true,\n' : softDeleteStanza(table, stanza.publicRead, stanza.grantsDelete);
 
   // A non-public table carries `schema:` — defineModel stores the name VERBATIM, so the
   // qualification cannot ride in the first argument (that would make the table literally
@@ -945,7 +951,7 @@ export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions
   const known = knownSet(tables.map((t) => t.table));
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
-  const blocks = tables.map((t) => renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz, opts.governRoles && new Set(opts.governRoles), opts.fkTargets, opts.lifecycleTables?.has(t.table)));
+  const blocks = tables.map((t) => renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz, opts.governRoles && new Set(opts.governRoles), opts.fkTargets, opts.lifecycleDeleteWhen?.get(t.table) ?? opts.lifecycleTables?.has(t.table)));
   // The derived layer (B5): sequences + views/matviews/functions, after the models they
   // reference, before the module wrapper that composes all three.
   if (opts.derived?.block) blocks.push(opts.derived.block);
@@ -1022,7 +1028,7 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
   const files: RenderedModelFile[] = tables.map((t) => {
-    const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz, opts.governRoles && new Set(opts.governRoles), opts.fkTargets, opts.lifecycleTables?.has(t.table));
+    const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz, opts.governRoles && new Set(opts.governRoles), opts.fkTargets, opts.lifecycleDeleteWhen?.get(t.table) ?? opts.lifecycleTables?.has(t.table));
     const crossImports = referencedTables(t, known).map(
       (target) => `import { ${modelVarName(target)} } from '${modelImportPath(target)}';`,
     );

package/src/cli/plain-output.ts

@@ -17,6 +17,9 @@
  *   ⚠ ACCESS        db:plan only: one summary line when the plan removes a policy, revokes a
  *                   grant, turns row security off, or removes a function, view or trigger. Not destructive (no --confirm), but such a
  *                   plan is never called "Safe to apply".
+ *   ⚠ LOCK          db:plan only: one line per plain CREATE INDEX on a live table with rows (it
+ *                   blocks writes while it builds), with the row estimate. Informational: the plan
+ *                   is still "Safe to apply", needs no --confirm and exits the same (index-lock.ts).
  *   ⚠ CONSTRAINT    db:plan only: one line per primary key the plan replaces, naming the old key.
  *                   Read from the replacement note the emitter writes from the change itself
  *                   (schema-diff's parsePrimaryKeyReplacement), never from the DDL. Not
@@ -36,6 +39,7 @@
 
 import { statementBody } from './sql-statement';
 import { parsePrimaryKeyReplacement } from './schema-diff';
+import { lockLines, type LockWarning } from './index-lock';
 import type { ReconcileAction, ReconcilePlan } from './derived-plan';
 import type { DerivedKind } from './derived-source';
 
@@ -440,6 +444,10 @@ export interface PlanReportInput {
    * Absent, or with nothing that changes an object, the report is byte-identical to one without it.
    */
   derived?: Pick<ReconcilePlan, 'actions' | 'regrants'>;
+  /** The plan's ⚠ LOCK data (EdgePlan.lockWarnings). Informational; absent or empty prints nothing. */
+  lockWarnings?: readonly LockWarning[];
+  /** The plan's deleted-row reads (EdgePlan.deletedReads): one ⚠ ACCESS line each. */
+  deletedReads?: readonly { table: string; role: string }[];
 }
 
 // ---------------------------------------------------------------------------
@@ -617,12 +625,17 @@ export function renderPlanReport(input: PlanReportInput): string[] {
 
   const keys = constraintLines(executable);
   lines.push(...keys);
+  lines.push(...lockLines(input.lockWarnings ?? []));
   const access = accessLine(accessChanges([...executable, ...derived.statements]), derived.removed);
   if (access) lines.push(access);
+  // can('read', { deleted }): a role that can now read deleted rows. Not destructive (no --confirm);
+  // like every other ACCESS line, the plan is then not called "Safe to apply".
+  const deletedReads = (input.deletedReads ?? []).map((d) => `${ACCESS_MARK} — role ${d.role} can read deleted rows of ${d.table}.`);
+  lines.push(...deletedReads);
   lines.push(
     destructive.size > 0
       ? `Verify the destructive ${plural(destructive.size, 'change', 'changes')}, then run db:backup before applying.`
-      : access
+      : access || deletedReads.length > 0
         ? 'Non-destructive. Verify the access changes before applying.'
         : keys.length > 0
           ? 'Non-destructive. Verify the replaced keys before applying.'

package/src/cli/schema-compile.ts

@@ -19,7 +19,8 @@
  * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
  */
 
-import type { ModelDescriptor, FieldSpec, SequenceDescriptor, DependentActions } from '@everystack/model';
+import { createHash } from 'node:crypto';
+import type { ModelDescriptor, FieldSpec, SequenceDescriptor, DependentActions, DependentIndexes } from '@everystack/model';
 import { positionalCheckName } from '@everystack/model';
 import type { TableSchema, EnumType, SequenceSchema, UniqueConstraint, CheckConstraint, IndexSchema, ForeignKey } from './schema-introspect';
 import { nextvalSequence, identityClause, primaryKeyConstraintName, type RenameMap } from './schema-diff';
@@ -54,6 +55,33 @@ export function generatedIndexName(table: string, columns: string[]): string {
   return `${table}_${parts.join('_')}_index`;
 }
 
+/**
+ * The name of a generated lifecycle FK index: `<table>_<columns>_lifecycle_fk_idx`. The suffix keeps
+ * it apart from author names (an author's generated name ends `_index`) and marks it generated, so
+ * db:pull folds it. Over PostgreSQL's 63 bytes it keeps 56 and appends `_` and 6 hex of a sha256 of
+ * the full name, branch-db's convention, so two long names never truncate to one.
+ */
+export function lifecycleFkIndexName(table: string, columns: readonly string[]): string {
+  const name = `${table}_${columns.join('_')}_lifecycle_fk_idx`;
+  if (Buffer.byteLength(name) <= 63) return name;
+  // 56 BYTES, never inside a character: a multi-byte name cut by characters overran 63 bytes, and
+  // PostgreSQL then truncated it to a name the generator never planned. ASCII cuts as before.
+  let prefix = '';
+  for (const ch of name) {
+    if (Buffer.byteLength(prefix + ch) > 56) break;
+    prefix += ch;
+  }
+  return `${prefix}_${createHash('sha256').update(name).digest('hex').slice(0, 6)}`;
+}
+
+/** The set's generated FK indexes for one model (`lifecycleDependentIndexes(models)`), as IR. */
+export function dependentIndexSpecs(model: ModelDescriptor, dependentIndexes?: DependentIndexes): IndexSchema[] {
+  return (dependentIndexes?.get(model) ?? []).map((keys) => {
+    const columns = keys.map(toSnakeCase);
+    return { name: lifecycleFkIndexName(model.table, columns), columns, unique: false };
+  });
+}
+
 export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueConstraint[]; checks: CheckConstraint[]; indexes: IndexSchema[] } {
   const uniques: UniqueConstraint[] = [];
   const checks: CheckConstraint[] = [];
@@ -547,7 +575,7 @@ export function compileCreateTable(model: ModelDescriptor, opts: CompileTableOpt
  * structured form for the brownfield diff. They share the field→type/default/check
  * helpers, so they never disagree.)
  */
-export function compileTableSchema(model: ModelDescriptor, opts: { schema?: string; dependents?: DependentActions } = {}): TableSchema {
+export function compileTableSchema(model: ModelDescriptor, opts: { schema?: string; dependents?: DependentActions; dependentIndexes?: DependentIndexes } = {}): TableSchema {
   const schema = model.schema ?? opts.schema ?? 'public';
   const entries = Object.entries(model.fields);
 
@@ -607,7 +635,7 @@ export function compileTableSchema(model: ModelDescriptor, opts: { schema?: stri
     uniques,
     checks,
     foreignKeys: modelForeignKeys(model, opts.dependents),
-    indexes: tableConstraints.indexes,
+    indexes: [...tableConstraints.indexes, ...dependentIndexSpecs(model, opts.dependentIndexes)],
   };
 }
 

package/src/cli/schema-fingerprint.ts

@@ -53,7 +53,7 @@
 import { createHash } from 'node:crypto';
 import { canonicalAuthz } from './authz-canonical';
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
-import { assertExternalTargets, relationDeleteActions } from '@everystack/model';
+import { assertExternalTargets, lifecycleDependentIndexes, relationDeleteActions } from '@everystack/model';
 import type { EnumType, SchemaSnapshot, TableSchema } from './schema-introspect';
 import type { AuthzContract, TableContract, SequenceGrantContract } from './authz-contract';
 import { compileTableSchema, compileEnums, compileSequences } from './schema-compile';
@@ -498,9 +498,10 @@ export function fingerprintModels(
   assertExternalTargets(models);
   // Also over the whole set: a parent's hasMany `dependent` sets the ON DELETE of a child's FK.
   const dependents = relationDeleteActions(models);
+  const dependentIndexes = lifecycleDependentIndexes(models);
   const scoped = opts.schemas ? models.filter((m) => opts.schemas!.includes(m.schema)) : models;
   const snapshot: SchemaSnapshot = {
-    tables: scoped.map((m) => compileTableSchema(m, { schema: opts.schema, dependents })),
+    tables: scoped.map((m) => compileTableSchema(m, { schema: opts.schema, dependents, dependentIndexes })),
     enums: compileEnums(scoped),
     ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}),
   };

package/src/cli/schema-introspect.ts

@@ -166,12 +166,35 @@ export interface SchemaSnapshot {
   sequences?: SequenceSchema[];
   /** Installed extensions, `plpgsql` excluded. Absent when the read predates this. */
   extensions?: string[];
+  /**
+   * The catalog's row estimate per table (`pg_class.reltuples`): > 0 an estimate, 0 empty, -1 a
+   * table with data that was never analyzed. For the plan's ⚠ LOCK line only. Beside the tables,
+   * never inside one, so no fingerprint or diff reads it. Absent when the read predates it.
+   */
+  rowEstimates?: Record<string, number>;
 }
 
 // ---------------------------------------------------------------------------
 // Introspection SQL.
 // ---------------------------------------------------------------------------
 
+/**
+ * Row estimates for the plan's ⚠ LOCK line — catalog statistics, no table scan. reltuples is -1
+ * before the first VACUUM/ANALYZE; a table that has pages then is reported -1 (data, unknown count).
+ */
+export const ROW_ESTIMATES_SQL = `
+SELECT n.nspname AS schema, c.relname AS "table",
+  CASE WHEN c.reltuples > 0 THEN c.reltuples::bigint
+       WHEN pg_catalog.pg_relation_size(c.oid) > 0 THEN -1
+       ELSE 0 END AS estimate
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind = 'r'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+ORDER BY 1, 2;
+`.trim();
+
 /**
  * Every column of every base table, with its precise type (`format_type`),
  * nullability, and default. Extension-owned tables are excluded via pg_depend,
@@ -711,6 +734,8 @@ export interface SchemaRows {
   indexes?: IndexRow[];
   sequences?: SequenceRow[];
   extensions?: ExtensionRow[];
+  /** Absent on a read that predates ROW_ESTIMATES_SQL (an older ops Lambda reply). */
+  estimates?: Array<{ schema: string; table: string; estimate: unknown }>;
 }
 
 /**
@@ -804,6 +829,9 @@ export function assembleSchema(rows: SchemaRows): SchemaSnapshot {
     enums,
     ...(sequences.length ? { sequences } : {}),
     ...(extensions !== undefined ? { extensions } : {}),
+    ...(rows.estimates !== undefined
+      ? { rowEstimates: Object.fromEntries(rows.estimates.map((r) => [`${r.schema}.${r.table}`, Number(r.estimate)])) }
+      : {}),
   };
 }
 
@@ -820,8 +848,10 @@ export async function introspectSchema(session: SessionRunner): Promise<SchemaSn
   // search_path. Column defaults, CHECK constraints and index expressions all deparse
   // relative to that path — spread across separate connections these five rows can render
   // the same schema two ways, and a fingerprint minted from the mix describes nothing.
-  const [columns, constraints, enums, indexes, sequences, extensions] = await session(
-    [COLUMNS_SQL, CONSTRAINTS_SQL, ENUMS_SQL, INDEXES_SQL, SEQUENCES_SQL, EXTENSIONS_SQL],
+  // The row estimates ride the same session and snapshot; a reply without them (fewer result
+  // sets) assembles without `rowEstimates`, and the plan then warns without a count.
+  const [columns, constraints, enums, indexes, sequences, extensions, estimates] = await session(
+    [COLUMNS_SQL, CONSTRAINTS_SQL, ENUMS_SQL, INDEXES_SQL, SEQUENCES_SQL, EXTENSIONS_SQL, ROW_ESTIMATES_SQL],
     INTROSPECTION_SESSION,
   );
   return assembleSchema({
@@ -831,5 +861,6 @@ export async function introspectSchema(session: SessionRunner): Promise<SchemaSn
     indexes: indexes as IndexRow[],
     sequences: sequences as SequenceRow[],
     extensions: extensions as ExtensionRow[],
+    ...(Array.isArray(estimates) ? { estimates: estimates as SchemaRows['estimates'] } : {}),
   });
 }