@everystack/cli 0.4.102 → 0.4.104

package/src/cli/lifecycle-pull.ts

@@ -2,9 +2,9 @@
  * db:pull's lifecycle fold — reads a lifecycle table back as `lifecycle: true`.
  *
  * `lifecycle: true` generates, per table: four columns, the reserved role's grants and policies,
- * a `deleted_at IS NULL` guard on every other role's SELECT policy, and two functions, a restore
- * function and two triggers. A pull that transcribed them would render the reserved role as an
- * authored ability and the columns as authored fields (defineModel refuses both), and the five
+ * a `deleted_at IS NULL` guard on every other role's SELECT policy, generated functions,
+ * and triggers. A pull that transcribed them would render the reserved role as an
+ * authored ability and the columns as authored fields (defineModel refuses both), and the generated
  * objects as derived descriptors (they would be generated twice).
  *
  * So the fold removes all of it from the pull's inputs, and the renderer writes `lifecycle: true`.
@@ -22,6 +22,8 @@ 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';
+import { functionIdentity } from './pg-argtypes';
 
 /** The generated columns as the catalog reports them (`format_type`), nullable, no default. */
 const GENERATED_COLUMNS: Record<string, string> = {
@@ -32,6 +34,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 +45,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 +84,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 +139,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,11 +165,12 @@ function foldContract(live: TableContract): TableContract | undefined {
     const { [role]: _eff, ...effectivePrivileges } = live.effectivePrivileges;
     folded.effectivePrivileges = effectivePrivileges;
   }
+  foldDeletedReadGrants(folded, table);
   return folded;
 }
 
 /**
- * The five generated objects of one lifecycle table, exactly as the derived catalog keys them. The
+ * The generated objects of one lifecycle table, and the older CLI's retired restrict pair, exactly as the derived catalog keys them. The
  * restore takes the primary key, and a function signature carries no type modifier
  * (`character varying(255)` is `character varying` there). An author's own overload stays.
  */
@@ -140,31 +181,97 @@ function generatedIdentities(table: TableSchema): string[] {
   return [
     `${schema}.${name}_lifecycle_transition()`,
     `${schema}.${name}_lifecycle_guard()`,
+    `${schema}.${name}_lifecycle_destroy_before()`,
+    functionIdentity(schema, `${name}_lifecycle_destroy`, [`${arg}[]`, 'timestamptz', 'integer']),
     `${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`,
+    // CLI 0.4.101 also generated a per-row restrict pair. The transition carries that check now and
+    // db:apply removes the pair, so a stage built by 0.4.101 must not pull it back as authored code.
+    `${schema}.${name}_lifecycle_restrict()`,
+    `${table.table}.${name}_lifecycle_restrict`,
   ];
 }
 
+/**
+ * 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 };
+}
+
+/** Fold only the exact read capability generated for a plain restricting child. */
+function foldReferenceContract(live: TableContract, table: TableSchema, lifecycleTables: ReadonlySet<string>): TableContract | undefined {
+  const columns = [...new Set(table.foreignKeys.filter(fk =>
+    lifecycleTables.has(fk.refTable.includes('.') ? fk.refTable : `public.${fk.refTable}`)
+    && (!fk.onDelete || fk.onDelete === 'no action' || fk.onDelete === 'restrict')).flatMap(fk => fk.columns))].sort();
+  if (!columns.length) return undefined;
+  const role = LIFECYCLE_OWNER_ROLE;
+  const grants = live.columnGrants?.[role] ?? {};
+  if ((live.grants[role]?.length ?? 0) !== 0 || sorted(Object.keys(grants)) !== sorted(['SELECT']) || sorted(grants.SELECT) !== sorted(columns)) return undefined;
+  const expected: PolicyContract = { name: `${split(table.table).name}_select_${role}`, command: 'SELECT', roles: [role], permissive: true, using: 'true', check: null };
+  const ownPolicies = live.policies.filter(p => p.roles.includes(role));
+  if (ownPolicies.length !== 1 || policyKey(ownPolicies[0]) !== policyKey(expected)) return undefined;
+  if (live.effectivePrivileges && sorted(live.effectivePrivileges[role]) !== sorted(['SELECT'])) return undefined;
+  const { [role]: _grant, ...tableGrants } = live.grants;
+  const { [role]: _cols, ...columnGrants } = live.columnGrants ?? {};
+  const { [role]: _effective, ...effectivePrivileges } = live.effectivePrivileges ?? {};
+  return { ...live, grants: tableGrants, columnGrants, policies: live.policies.filter(p => p !== ownPolicies[0]),
+    ...(live.effectivePrivileges ? { effectivePrivileges } : {}) };
+}
+
 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() };
+  for (const table of snapshot.tables) {
+    if (tables.has(table.table)) continue;
+    const live = contract.tables.find(t => t.table === table.table);
+    const folded = live && foldReferenceContract(live, table, tables);
+    if (folded) foldedContracts.set(table.table, folded);
+  }
+
+  // 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 +280,6 @@ export function foldLifecycle(snapshot: SchemaSnapshot, contract: AuthzContract,
       provenance: catalog.provenance.filter((p) => !generated.has(p.identity)),
     },
     tables,
+    deleteWhen,
   };
 }

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,10 @@ 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 children detected even when the default pull leaves their columns unfolded. */
+  lifecycleForeignKeyTables?: ReadonlySet<string>;
+  /** lifecycle: { deleteWhen }'s predicate per folded table (lifecycle-pull.ts), rendered verbatim. */
+  lifecycleDeleteWhen?: ReadonlyMap<string, string>;
 }
 
 /**
@@ -391,6 +395,48 @@ function knownSet(tables: Iterable<string>): Set<string> {
   return new Set([...tables].map(qualifiedName));
 }
 
+/** A key into a rendered lifecycle parent, declared on that parent as a hasMany dependent. */
+interface RenderedDependent { child: string; column: string; dependent: 'cascade' | 'restrict' | 'nullify' }
+const DEPENDENT_OF: Record<string, RenderedDependent['dependent']> = { cascade: 'cascade', 'set null': 'nullify', restrict: 'restrict' };
+
+/**
+ * Every one-column foreign key from a table rendered `lifecycle: true` into another, grouped by the
+ * parent: the parent declares each one as a dependent (a key into a lifecycle table with none is
+ * refused), read from the live ON DELETE: CASCADE -> 'cascade', SET NULL -> 'nullify', RESTRICT or
+ * NO ACTION -> 'restrict'. A plain table's key into one has no dependent (only a lifecycle table may
+ * hold one): it renders as it is, with a comment, and the model's own refusal names it. So do SET
+ * DEFAULT and composite keys.
+ */
+function lifecycleDependentsOf(tables: readonly TableSchema[], lifecycleTables: ReadonlySet<string> | undefined): Map<string, RenderedDependent[]> {
+  const out = new Map<string, RenderedDependent[]>();
+  const rendered = new Set([...(lifecycleTables ?? [])].map(qualifiedName));
+  const known = knownSet(tables.map((t) => t.table));
+  for (const table of tables) {
+    for (const fk of table.foreignKeys) {
+      const parent = qualifiedName(fk.refTable);
+      const dependent = DEPENDENT_OF[fk.onDelete ?? 'restrict'];
+      if (fk.columns.length !== 1 || !dependent || !rendered.has(parent) || !known.has(parent) || !rendered.has(qualifiedName(table.table))) continue;
+      out.set(parent, [...(out.get(parent) ?? []), { child: qualifiedName(table.table), column: fk.columns[0], dependent }]);
+    }
+  }
+  return out;
+}
+
+/** The parent's `relations: { … }` stanza for its dependents ('' when none). Thunks, like `.references()`: a pulled barrel is not linked. */
+function dependentsStanza(table: TableSchema, dependents: readonly RenderedDependent[]): string {
+  if (dependents.length === 0) return '';
+  const fieldKeys = new Set(table.columns.map((c) => toCamelCase(c.name)));
+  const base = (d: RenderedDependent): string => toCamelCase(schemaOf(d.child) === 'public' ? bareName(d.child) : `${schemaOf(d.child)}_${bareName(d.child)}`);
+  const lines = [...dependents].sort((a, b) => (`${a.child}\u0000${a.column}` < `${b.child}\u0000${b.column}` ? -1 : 1)).map((d) => {
+    const field = toCamelCase(d.column);
+    const plain = base(d);
+    const shared = dependents.filter((o) => base(o) === plain).length > 1 || fieldKeys.has(plain);
+    const key = shared ? `${plain}By${field[0].toUpperCase()}${field.slice(1)}` : plain;
+    return `    ${safeKey(key, `the relation for ${liveObject('table', d.child)}`)}: hasMany(() => ${modelVarName(d.child)}, ${tsLiteral(field)}, { dependent: ${tsLiteral(d.dependent)} }),`;
+  });
+  return `\n  relations: {\n${lines.join('\n')}\n  },`;
+}
+
 /**
  * A table name → its model variable: PascalCase, naively singularized (one trailing
  * `s` strips, whatever the word). `image_variants` → `ImageVariant`.
@@ -423,7 +469,7 @@ export function modelVarName(table: string): string {
  * phantom rename for every digit-boundary column and COLLIDED distinct columns
  * (`a_1` and `a1`) onto one key.
  */
-function toCamelCase(name: string): string {
+export function toCamelCase(name: string): string {
   return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
 
@@ -792,7 +838,17 @@ 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, lifecycleForeignKeys = Boolean(lifecycle), dependents: ReadonlyMap<string, readonly RenderedDependent[]> = new Map(), lifecycleTables: ReadonlySet<string> = new Set()): string {
+  const self = qualifiedName(table.table);
+  const asParent = dependents.get(self) ?? [];
+  // A key a lifecycle parent declares as a dependent carries no onDelete of its own: the dependent derives it.
+  const declared = new Set([...dependents.values()].flat().filter((d) => d.child === self).map((d) => d.column));
+  // Copy for rendering only; the raw catalog still owns the adoption fingerprint.
+  if (declared.size) table = { ...table, foreignKeys: table.foreignKeys.map(fk =>
+    fk.columns.length === 1 && declared.has(fk.columns[0]) ? { ...fk, onDelete: undefined } : fk) };
+  // A pull cannot infer the parent relation that makes any other lifecycle cascade legal.
+  if (lifecycleForeignKeys) table = { ...table, foreignKeys: table.foreignKeys.map(fk =>
+    fk.onDelete === 'cascade' ? { ...fk, onDelete: 'restrict' } : fk) };
   // 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>();
@@ -811,14 +867,24 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   }
 
   const pulled = knownSet(known);
-  const fields = table.columns.map((c) => renderField(table, c, pulled, enums, validates, fkTargets)).join('\n');
+  // A plain table's key into a table rendered lifecycle: the models refuse it; say why and the fix.
+  const intoLifecycle = new Set(lifecycle ? [] : table.foreignKeys
+    .filter((fk) => fk.columns.length === 1 && lifecycleTables.has(qualifiedName(fk.refTable)))
+    .map((fk) => fk.columns[0]));
+  const fields = table.columns.map((c) => (intoLifecycle.has(c.name)
+    ? `    // ${commentText(`${c.name} references a lifecycle table, and only a lifecycle table may hold a key into one: make this model lifecycle: true (and declare the dependent on the parent), or refer to it by value (drop .references())`)}\n`
+    : '') + renderField(table, c, pulled, enums, validates, fkTargets)).join('\n');
   const constraints = renderConstraintsBlock(table, tableChecks, pulled, fkTargets);
   // The authz decision renders FIRST — before fields — because it is the first thing a
   // reviewer must resolve about a model (and where the field-report consumer's codemod
   // 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
@@ -828,7 +894,7 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   // already uses for defineMaterializedTable.
   const owner = schemaOf(table.table);
   const schemaProp = owner === 'public' ? '' : `  schema: ${tsLiteral(owner)},\n`;
-  return `export const ${modelVarName(table.table)} = defineModel(${tsLiteral(bareName(table.table))}, {\n${stanza.text}\n${schemaProp}${writtenBy}${softDelete}  fields: {\n${fields}\n  },${constraints}\n});`;
+  return `export const ${modelVarName(table.table)} = defineModel(${tsLiteral(bareName(table.table))}, {\n${stanza.text}\n${schemaProp}${writtenBy}${softDelete}  fields: {\n${fields}\n  },${constraints}${dependentsStanza(table, asParent)}\n});`;
 }
 
 /** The `import` lines a rendered body needs — only what it actually uses, so the file reads clean. */
@@ -841,6 +907,7 @@ function importHeader(body: string, extra: string[] = []): string {
   if (/\bcheck\(/.test(body)) symbols.push('check');
   if (/\bindex\(/.test(body)) symbols.push('index');
   if (/\bforeignKey\(/.test(body)) symbols.push('foreignKey');
+  if (/\bhasMany\(/.test(body)) symbols.push('hasMany');
   if (/\bdefineModule\(/.test(body)) symbols.push('defineModule');
   if (/\bsql`/.test(body)) symbols.push('sql');
   for (const s of extra) if (!symbols.includes(s)) symbols.push(s);
@@ -945,7 +1012,9 @@ 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 dependents = lifecycleDependentsOf(tables, opts.lifecycleTables);
+  const rendered = new Set([...(opts.lifecycleTables ?? [])].map(qualifiedName));
+  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), opts.lifecycleForeignKeyTables?.has(t.table) || opts.lifecycleTables?.has(t.table), dependents, rendered));
   // 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);
@@ -1021,9 +1090,12 @@ export function renderModelFiles(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 dependents = lifecycleDependentsOf(tables, opts.lifecycleTables);
+  const rendered = new Set([...(opts.lifecycleTables ?? [])].map(qualifiedName));
   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 crossImports = referencedTables(t, known).map(
+    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), opts.lifecycleForeignKeyTables?.has(t.table) || opts.lifecycleTables?.has(t.table), dependents, rendered);
+    const children = (dependents.get(qualifiedName(t.table)) ?? []).map((d) => d.child).filter((c) => c !== qualifiedName(t.table));
+    const crossImports = [...new Set([...referencedTables(t, known), ...children])].sort().map(
       (target) => `import { ${modelVarName(target)} } from '${modelImportPath(target)}';`,
     );
     const header = [importHeader(block), ...crossImports].join('\n');

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,8 +19,9 @@
  * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
  */
 
-import type { ModelDescriptor, FieldSpec, SequenceDescriptor, DependentActions } from '@everystack/model';
-import { positionalCheckName } from '@everystack/model';
+import { createHash } from 'node:crypto';
+import type { ModelDescriptor, FieldSpec, SequenceDescriptor, DependentActions, DependentIndexes } from '@everystack/model';
+import { pgType, 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';
 import { normalizeDeparsedExpr } from './deparse-normal';
@@ -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[] = [];
@@ -126,69 +154,8 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
   return { uniques, checks, indexes };
 }
 
-/**
- * Postgres type for a field, with the precision drizzle-kit would emit — in
- * `format_type`'s vocabulary, because this feeds the IR that diffs against
- * introspection. A serial field's *column type* is integer/bigint (`serial` is
- * DDL shorthand, not a type — `format_type` never reports it); the sequence
- * default is carried separately (see compileTableSchema), and the DDL renderers
- * spell the shorthand (see SERIAL_DDL).
- */
-const PG_TYPE: Record<string, string> = {
-  text: 'text',
-  uuid: 'uuid',
-  integer: 'integer',
-  boolean: 'boolean',
-  json: 'json',
-  jsonb: 'jsonb',
-  bigint: 'bigint',
-  serial: 'integer',
-  bigserial: 'bigint',
-  real: 'real',
-  doublePrecision: 'double precision',
-  timestamptz: 'timestamp with time zone',
-  // `format_type` canonicalizes a bare `timestamp` column to this spelling, and
-  // introspection compares against it — so the compiler must emit the same, or an
-  // unchanged `timestamp` column round-trips to a spurious ALTER COLUMN TYPE.
-  timestamp: 'timestamp without time zone',
-  date: 'date',
-};
-
-export function pgType(spec: FieldSpec): string {
-  // An array is the base type with `[]` appended — `text` → `text[]`, exactly as
-  // `format_type` spells it.
-  return spec.isArray ? `${scalarPgType(spec)}[]` : scalarPgType(spec);
-}
-
-function scalarPgType(spec: FieldSpec): string {
-  // Parameterized types build their own canonical string — exactly as `format_type`
-  // spells it (no space after the comma; `varchar` is `character varying`; a
-  // precision-only numeric carries scale 0), so an unchanged column round-trips clean.
-  if (spec.type === 'numeric') {
-    if (spec.precision != null) return `numeric(${spec.precision},${spec.scale ?? 0})`;
-    return 'numeric';
-  }
-  if (spec.type === 'varchar') {
-    return spec.length != null ? `character varying(${spec.length})` : 'character varying';
-  }
-  if (spec.type === 'enum') {
-    // The column's type is the enum's own type name; `format_type` reports the same bare
-    // name, so it round-trips. The `CREATE TYPE` is emitted separately, before the table.
-    if (!spec.enumName) throw new Error('field bridge: an enum field needs a type name — field.enum(name, values)');
-    return spec.enumName;
-  }
-  if (spec.type === 'pgType') {
-    // A verbatim type: the declared string IS the canonical `format_type` spelling
-    // (the factory refused anything else), so it round-trips byte-for-byte.
-    if (!spec.pgTypeName) throw new Error('field bridge: a pgType field needs its type name — field.pgType(name)');
-    return spec.pgTypeName;
-  }
-  const t = PG_TYPE[spec.type];
-  if (!t) {
-    throw new Error(`field bridge: no DDL mapping for field type '${spec.type}' yet`);
-  }
-  return t;
-}
+// Shared with the runtime destroy wrapper: casts and generated signatures must agree.
+export { pgType } from '@everystack/model';
 
 /**
  * The FK referential actions declared on a field or a table-level `foreignKey(...)`, dropping
@@ -547,7 +514,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 +574,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)],
   };
 }