@everystack/cli 0.4.100 → 0.4.103

package/src/cli/model-render.ts

@@ -9,22 +9,25 @@
  * It renders what the field builder can express today (type, primary key, not-null,
  * single-column unique, single-column references, the common defaults) and SURFACES what it
  * can't as inline comments rather than faking it: an unmapped column type, a composite
- * unique, a CHECK that needs a manual `.validate()`, a foreign key to a table outside the
- * pulled set. Reversing a CHECK back to its Zod refinement is a later increment.
+ * unique, a CHECK that needs a manual `.validate()`. A foreign key to a table outside the
+ * pulled set is declared in the external `{ schema, table, column }` form.
  *
  * Pure and deterministic — the command shell (commands/db-pull.ts) does the IO.
  */
 
 import type { SchemaSnapshot, TableSchema, ColumnSchema, CheckConstraint } from './schema-introspect';
+import { foreignKeyTargetKey } from './schema-introspect';
 import type { DerivedRenderResult } from './derived-render';
 import type { TableContract } from './authz-contract';
 import { deriveAbilities, renderDerivedAbilities } from './authz-derive';
 import { normalizeDefault, normalizeCheck } from './schema-diff';
 import { generatedIndexName, generatedForeignKeyName } from './schema-compile';
+import { templateBody, tsString as tsLiteral, commentText } from './ts-template';
+import { safeBinding, safeKey, safeFileStem, liveObject } from './generated-names';
 // The soft-delete RULE itself — one boolean combination, shared with `defineModel`'s refusal.
 // Only the FACT EXTRACTION is duplicated here (this renderer holds text, not descriptors);
 // the rule is not, so the two surfaces cannot drift on when a declaration is required.
-import { needsSoftDeleteDeclaration, privilegesGrantDelete, positionalCheckName } from '@everystack/model';
+import { needsSoftDeleteDeclaration, privilegesGrantDelete, positionalCheckName, externalIdentifierRefusal } from '@everystack/model';
 
 /**
  * Reverse a CHECK predicate back into the `.validate(z…)` that produced it — the inverse of
@@ -85,13 +88,21 @@ export interface RenderOptions {
    */
   liveAuthz?: Map<string, TableContract>;
   /**
-   * `--govern-roles` — the operator's explicit decision to transcribe these foreign roles'
-   * grants into `privileges`, which GOVERNS them. Required for migration deletion when the
-   * migrations created grants to roles outside the vocabulary (an ops/connection role): a
-   * fresh build from models must recreate them or the deletion loses the ops lane its
-   * access. Never inferred — see deriveAbilities. Complete-or-refuse per role.
+   * `--govern-roles` — the operator's explicit decision to GOVERN these foreign roles: their
+   * grants and policies render as role-scoped `can()` where they pair exactly, `privileges`
+   * otherwise, and the module footer declares them in `governedRoles`. Required for migration
+   * deletion when the migrations created grants to roles outside the vocabulary (an
+   * ops/connection role): a fresh build from models must recreate them or the deletion loses
+   * the ops lane its access. Never inferred — see deriveAbilities. Complete-or-refuse per role.
    */
   governRoles?: string[];
+  /**
+   * Each FK's target as the CATALOG names it (FK_TARGETS_SQL → foreignKeyTargets). db:pull always
+   * passes it: an external target is then declared from these exact names, and a key it does not
+   * hold renders as a comment. Absent (a pure caller), the deparsed `refTable` is split instead,
+   * which is ambiguous for a quoted name holding a dot.
+   */
+  fkTargets?: FkTargets;
   /** The rendered derived layer (B5) — rides the barrel: block after the models,
    *  sequences/derived arrays on the module wrapper, symbols on the import header. */
   derived?: DerivedRenderResult;
@@ -99,6 +110,10 @@ export interface RenderOptions {
    *  wires it instead of embedding it. Mutually exclusive with `derived` in practice —
    *  passing neither is what silently produced `defineModule({ models })`. */
   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>;
 }
 
 /**
@@ -363,6 +378,21 @@ function schemaOf(table: string): string {
   return dot === -1 ? 'public' : table.slice(0, dot);
 }
 
+/** `users` / `public.users` → `public.users`; `a6.users` stays. pg_get_constraintdef leaves a public ref bare. */
+function qualifiedName(table: string): string {
+  return `${schemaOf(table)}.${bareName(table)}`;
+}
+
+/**
+ * The pulled set, keyed on QUALIFIED names: an FK renders as a model reference exactly when its
+ * qualified target is pulled. Keyed on bare names, a pull of `a6` alone (holding `a6.users`)
+ * rendered an FK into `public.users` as `() => User` and imported it from a file the pull never
+ * wrote. A caller's bare entry still reads as public.
+ */
+function knownSet(tables: Iterable<string>): Set<string> {
+  return new Set([...tables].map(qualifiedName));
+}
+
 /**
  * A table name → its model variable: PascalCase, naively singularized (one trailing
  * `s` strips, whatever the word). `image_variants` → `ImageVariant`.
@@ -383,7 +413,7 @@ export function modelVarName(table: string): string {
   // nothing renames when a second schema arrives. Same rule the derived renderer already
   // uses for its own symbols.
   const owner = schemaOf(table);
-  return owner === 'public' ? pascal(singular) : pascal(owner) + pascal(singular);
+  return safeBinding(owner === 'public' ? pascal(singular) : pascal(owner) + pascal(singular), liveObject('table', table));
 }
 
 /**
@@ -489,11 +519,6 @@ function parsePgArrayElements(literal: string): Array<{ raw: string; quoted: boo
   return out;
 }
 
-/** A single-quoted TS string literal (the model idiom), escaping embedded quotes. */
-function tsLiteral(value: string): string {
-  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-}
-
 /**
  * The `field.serial()`/`field.bigserial()` factory for an integer/bigint column whose
  * default is its own conventional sequence (`<table>_<column>_seq`, optionally
@@ -509,7 +534,7 @@ function serialFactoryCall(table: TableSchema, col: ColumnSchema): string | null
 }
 
 /** One field line: `    authorId: field.uuid().notNull().references(() => Profile),` (+ any surfacing comment). */
-function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>, enums: Map<string, string[]>, validates: Map<string, string>): string {
+function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>, enums: Map<string, string[]>, validates: Map<string, string>, fkTargets?: FkTargets): string {
   // An enum column's type is the enum's name; render the explicit-name field.enum with its
   // values (the always-explicit form round-trips the name and the value order).
   const enumValues = enums.get(col.type);
@@ -522,7 +547,7 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
   // type is the identity, so the round trip is clean: no coercion, no FIXME, no
   // plan statement. The note stays — a verbatim type is a fact worth seeing.
   let expr = call ?? verbatimFieldCall(col.type);
-  let comment = call ? '' : ` // verbatim: no first-class field for '${col.type}' — carried as-is`;
+  let comment = call ? '' : ` // verbatim: no first-class field for '${commentText(col.type)}' — carried as-is`;
 
   // The auto-value the database actually holds. Rendered BEFORE .primaryKey()/.notNull() so a
   // pulled surrogate key reads the way one is authored, and rendered at all because without it
@@ -540,26 +565,20 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
 
   const fk = table.foreignKeys.find((f) => f.columns.length === 1 && f.columns[0] === col.name);
   if (fk) {
-    if (known.has(bareName(fk.refTable))) {
-      const actions = [
-        fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
-        fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
-      ].filter(Boolean);
-      // A8 — the FK's own name, said only when it is not the one the compiler would generate.
-    if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
-      actions.push(`name: ${tsLiteral(fk.name)}`);
-    }
-    // The key is live and has NEVER been checked against the rows already in the table. Rendering
-    // it as an ordinary reference would declare a state this database is not in — and the FIRST
-    // plan after the pull would then emit a `VALIDATE` the legacy rows cannot pass. On the schema
-    // this was measured against that was 12 of 23 keys, every one of them deliberately NOT VALID
-    // in the app's own migration ("enforce forward, grandfather legacy"). So the pull SAYS what it
-    // found, the adoption plan comes out empty, and removing the flag later is how an operator
-    // opts into the scan. Same rule as the index and constraint names one line up: be faithful.
-    if (fk.notValid) actions.push('validate: false');
-    const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
+    const opts = foreignKeyOptions(table, fk);
+    if (known.has(qualifiedName(fk.refTable))) {
       expr += `.references(() => ${modelVarName(fk.refTable)}${opts})`;
-    } else comment += ` // FK → ${fk.refTable} (not in the pulled set)`;
+    } else {
+      // F3e — the target is outside the pulled set, so it is declared as what it is: a table no
+      // model declares. The FK stays in the declared state, so pull then plan is empty; as a
+      // comment it was undeclared, and the first plan proposed to drop it.
+      const target = externalTarget(table, fk, fkTargets);
+      if (target.ok) {
+        expr += `.references({ schema: ${tsLiteral(target.schema)}, table: ${tsLiteral(target.table)}, `
+          + `column: ${tsLiteral(fk.refColumns[0])} }${opts})`;
+        comment += externalCascadeComment(table, fk);
+      } else comment += ` // FK → ${commentText(target.shown)} (not in the pulled set)`;
+    }
   }
 
   if (col.default != null && !serial) {
@@ -568,13 +587,125 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
     // normalized form — stripping a trailing cast here could change semantics
     // (`'7 days'::interval`); the diff normalizes both sides for comparison instead.
     // Drift closed by construction: pull output converges instead of shedding a TODO.
-    expr += d ?? `.defaultSql(sql\`${col.default}\`)`;
+    expr += d ?? `.defaultSql(sql\`${templateBody(col.default)}\`)`;
   }
 
   const validate = validates.get(col.name);
   if (validate) expr += `.validate(${validate})`;
 
-  return `    ${toCamelCase(col.name)}: ${expr},${comment}`;
+  const key = safeKey(toCamelCase(col.name), `${liveObject('column', col.name)} of ${liveObject('table', table.table)}`);
+  return `    ${key}: ${expr},${comment}`;
+}
+
+type LiveForeignKey = TableSchema['foreignKeys'][number];
+
+/**
+ * The `, { … }` options a pulled FK renders with, '' when it needs none. Shared by the model
+ * thunk, the external form and the composite form, so all three say the same things.
+ */
+function foreignKeyOptions(table: TableSchema, fk: LiveForeignKey): string {
+  const actions = [
+    fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
+    fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
+  ].filter(Boolean);
+  // A8 — the FK's own name, said only when it is not the one the compiler would generate.
+  if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
+    actions.push(`name: ${tsLiteral(fk.name)}`);
+  }
+  // The key is live and has NEVER been checked against the rows already in the table. Rendering
+  // it as an ordinary reference would declare a state this database is not in — and the FIRST
+  // plan after the pull would then emit a `VALIDATE` the legacy rows cannot pass. On the schema
+  // this was measured against that was 12 of 23 keys, every one of them deliberately NOT VALID
+  // in the app's own migration ("enforce forward, grandfather legacy"). So the pull SAYS what it
+  // found, the adoption plan comes out empty, and removing the flag later is how an operator
+  // opts into the scan. Same rule as the index and constraint names: be faithful.
+  if (fk.notValid) actions.push('validate: false');
+  return actions.length ? `, { ${actions.join(', ')} }` : '';
+}
+
+/** (owning table, FK name) → the target's exact schema and table, from the catalog. */
+export type FkTargets = ReadonlyMap<string, { schema: string; table: string }>;
+
+/** `schema.table`, with a part double-quoted when it holds a dot or a quote: public."a.b", never public.a.b. */
+function unambiguousName(...parts: string[]): string {
+  return parts.map((p) => (/[."]/.test(p) ? `"${p.replace(/"/g, '""')}"` : p)).join('.');
+}
+
+type ExternalTarget =
+  | { ok: true; schema: string; table: string }
+  | { ok: false; shown: string; reason: string };
+
+/**
+ * The exact target of an out-of-set FK, and whether the external form can declare it.
+ *
+ * The schema and table come from the CATALOG (`fkTargets`, by confrelid), never from splitting
+ * the deparsed `refTable`: quotes are stripped there, so public."a.b" reads as `a.b`, and a split
+ * declared it as { schema: 'a', table: 'b' }, another table, while plan and fingerprint agreed
+ * (both sides compile to `a.b`). A key the catalog map does not hold fails closed. Without a map
+ * (a pure caller), the split is the only answer there is.
+ *
+ * Each name must be one `@everystack/model` accepts (no quote, dot or control character; at most
+ * 63 bytes). One that is not keeps the comment it had before F3e, and db:pull warns.
+ */
+function externalTarget(table: TableSchema, fk: LiveForeignKey, fkTargets?: FkTargets): ExternalTarget {
+  const found = fkTargets
+    ? fkTargets.get(foreignKeyTargetKey(table.table, fk.name))
+    : { schema: schemaOf(fk.refTable), table: bareName(fk.refTable) };
+  if (!found) return { ok: false, shown: fk.refTable, reason: 'the catalog read names no target for it' };
+  const shown = unambiguousName(found.schema, found.table);
+  // A CHANGED target fails closed like a missing one: on --stage the catalog read and the
+  // snapshot are two reads at two moments. Compared in the deparse form (public bare, quotes
+  // stripped), which is exactly what the snapshot's refTable holds.
+  const deparsed = found.schema === 'public' ? found.table : `${found.schema}.${found.table}`;
+  if (fkTargets && deparsed !== fk.refTable) {
+    return {
+      ok: false, shown: fk.refTable,
+      reason: `the catalog read names ${shown}, a different target than the snapshot: the two reads disagree; pull again`,
+    };
+  }
+  const parts: Array<[string, string]> = [['schema', found.schema], ['table', found.table], ...fk.refColumns.map((c): [string, string] => ['column', c])];
+  for (const [what, name] of parts) {
+    const refusal = externalIdentifierRefusal(name);
+    if (refusal) return { ok: false, shown, reason: `${what} ${JSON.stringify(name)} ${refusal}` };
+  }
+  if (fk.refColumns.length !== fk.columns.length) return { ok: false, shown, reason: 'its column lists differ in length' };
+  return { ok: true, schema: found.schema, table: found.table };
+}
+
+/** The model comment for an external ON DELETE CASCADE ('' otherwise): a delete elsewhere reaches here. */
+function externalCascadeComment(table: TableSchema, fk: LiveForeignKey): string {
+  if (fk.onDelete !== 'cascade') return '';
+  return ` // external FK ON DELETE CASCADE: a delete in ${commentText(qualifiedName(fk.refTable))} cascades into ${commentText(qualifiedName(table.table))}`;
+}
+
+/**
+ * The pull's warnings about FKs that point OUTSIDE the pulled set: one per key the external form
+ * cannot declare (it stays a comment, so the next plan proposes to drop it), and one per key with
+ * ON DELETE CASCADE (deleting a row in another system's table deletes rows in this one; the model
+ * carries that fact as a comment too).
+ */
+export function externalForeignKeyWarnings(snapshot: SchemaSnapshot, schema: string | string[], fkTargets?: FkTargets): string[] {
+  const tables = pullableTables(snapshot, schema);
+  const known = knownSet(tables.map((t) => t.table));
+  const out: string[] = [];
+  for (const t of tables) {
+    for (const fk of t.foreignKeys) {
+      if (known.has(qualifiedName(fk.refTable))) continue;
+      const target = externalTarget(t, fk, fkTargets);
+      if (!target.ok) {
+        out.push(
+          `${qualifiedName(t.table)}: foreign key ${fk.name} references ${target.shown}, which the external form cannot declare (${target.reason}): `
+          + 'it is left as a comment, and the next plan proposes to drop it.',
+        );
+      }
+      if (fk.onDelete !== 'cascade') continue;
+      out.push(
+        `${qualifiedName(t.table)}: foreign key ${fk.name} references ${qualifiedName(fk.refTable)} (not pulled) with ON DELETE CASCADE: `
+        + `a delete in another system's table cascades into this one.`,
+      );
+    }
+  }
+  return out;
 }
 
 /**
@@ -584,7 +715,8 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
  * renders its introspected columns with the SAME field vocabulary a pulled table gets.
  */
 export function renderFieldLines(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map()): string[] {
-  return table.columns.map((c) => renderField(table, c, known, enums, new Map()));
+  const pulled = knownSet(known);
+  return table.columns.map((c) => renderField(table, c, pulled, enums, new Map()));
 }
 
 /**
@@ -592,9 +724,10 @@ export function renderFieldLines(table: TableSchema, known: Set<string>, enums:
  * multi-column foreign keys — the table-level surface a column-scoped `field()` can't carry.
  * Single-column uniques and FKs are rendered on the field (`.unique()` / `.references()`), so
  * only composite ones land here. A composite FK whose target isn't in the pulled set is
- * surfaced as a comment, not faked. Returns '' when there are none.
+ * declared in the external `{ schema, table }` form (a comment only when its names cannot be).
+ * Returns '' when there are none.
  */
-function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], known: Set<string>): string {
+function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], known: Set<string>, fkTargets?: FkTargets): string {
   const items: string[] = [];
   for (const u of table.uniques) {
     if (u.columns.length > 1) items.push(`unique(${u.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`);
@@ -604,7 +737,7 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
   // compiler counts only unnamed ones, so every pulled check compiles back to its live name.
   let position = 0;
   for (const ck of checks) {
-    const predicate = `sql\`${normalizeCheck(ck.expr)}\``;
+    const predicate = `sql\`${templateBody(normalizeCheck(ck.expr))}\``;
     if (ck.name === positionalCheckName(bareName(table.table), position)) {
       items.push(`check(${predicate})`);
       position++;
@@ -616,12 +749,12 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
     // Plain entries render as field keys; canonical-text entries (expressions, DESC,
     // opclass) render as raw sql`` args — the same form the builder declares (Brick E).
     const entry = (c: string): string =>
-      /^[a-z_][a-z0-9_$]*$/i.test(c) ? tsLiteral(toCamelCase(c)) : `sql\`${c}\``;
+      /^[a-z_][a-z0-9_$]*$/i.test(c) ? tsLiteral(toCamelCase(c)) : `sql\`${templateBody(c)}\``;
     let s = `index(${ix.columns.map(entry).join(', ')})`;
     if (ix.using) s += `.using(${tsLiteral(ix.using)})`;
     if (ix.unique) s += '.unique()';
     if (ix.include?.length) s += `.include(${ix.include.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`;
-    if (ix.where) s += `.where(sql\`${normalizeCheck(ix.where)}\`)`;
+    if (ix.where) s += `.where(sql\`${templateBody(normalizeCheck(ix.where))}\`)`;
     // A7 — keep the name the database actually has, but only say it when it is not the one the
     // compiler would generate anyway. A brownfield schema arrives with its previous tooling's
     // names (`index_contents_on_destination_id`), and rebuilding under ours renamed ~200 of one
@@ -633,33 +766,35 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
     }
     items.push(s);
   }
+  let target: ExternalTarget;
   for (const fk of table.foreignKeys) {
     if (fk.columns.length <= 1) continue; // single-column FKs are rendered on the field
     const cols = `[${fk.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')}]`;
     const refCols = `[${fk.refColumns.map((c) => tsLiteral(toCamelCase(c))).join(', ')}]`;
-    if (!known.has(bareName(fk.refTable))) {
-      items.push(`// FIXME: composite FK ${cols} → ${fk.refTable} ${refCols} (target not in the pulled set)`);
-      continue;
-    }
-    const actions = [
-      fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
-      fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
-    ].filter(Boolean);
-    // A8 — the FK's own name, said only when it is not the one the compiler would generate.
-    if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
-      actions.push(`name: ${tsLiteral(fk.name)}`);
+    const opts = foreignKeyOptions(table, fk);
+    if (known.has(qualifiedName(fk.refTable))) {
+      items.push(`foreignKey(${cols}, () => ${modelVarName(fk.refTable)}, ${refCols}${opts})`);
+    } else if ((target = externalTarget(table, fk, fkTargets)).ok) {
+      // F3e — the composite twin of the external `.references()`: the reference columns are the
+      // live PostgreSQL names, verbatim (there is no model whose field keys they could be).
+      const cascade = externalCascadeComment(table, fk);
+      if (cascade) items.push(cascade.trim());
+      items.push(
+        `foreignKey(${cols}, { schema: ${tsLiteral(target.schema)}, table: ${tsLiteral(target.table)} }, `
+        + `[${fk.refColumns.map(tsLiteral).join(', ')}]${opts})`,
+      );
+    } else {
+      const shown = target.ok ? fk.refTable : target.shown;
+      items.push(`// FIXME: composite FK ${cols} → ${commentText(shown)} ${refCols} (target not in the pulled set)`);
     }
-    // Faithful about validity, exactly as the single-column case above is — see there for why.
-    if (fk.notValid) actions.push('validate: false');
-    const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
-    items.push(`foreignKey(${cols}, () => ${modelVarName(fk.refTable)}, ${refCols}${opts})`);
   }
   if (!items.length) return '';
-  return `\n  constraints: [\n${items.map((i) => `    ${i},`).join('\n')}\n  ],`;
+  // A comment line takes no trailing comma.
+  return `\n  constraints: [\n${items.map((i) => (i.startsWith('//') ? `    ${i}` : `    ${i},`)).join('\n')}\n  ],`;
 }
 
 /** 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>): 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>();
@@ -677,14 +812,19 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
     else tableChecks.push(ck);
   }
 
-  const fields = table.columns.map((c) => renderField(table, c, known, enums, validates)).join('\n');
-  const constraints = renderConstraintsBlock(table, tableChecks, known);
+  const pulled = knownSet(known);
+  const fields = table.columns.map((c) => 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 = 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
@@ -693,8 +833,8 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   // selects FROM metrics.impressions then failed to build. Same idiom the derived renderer
   // already uses for defineMaterializedTable.
   const owner = schemaOf(table.table);
-  const schemaProp = owner === 'public' ? '' : `  schema: '${owner}',\n`;
-  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza.text}\n${schemaProp}${writtenBy}${softDelete}  fields: {\n${fields}\n  },${constraints}\n});`;
+  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});`;
 }
 
 /** The `import` lines a rendered body needs — only what it actually uses, so the file reads clean. */
@@ -732,6 +872,7 @@ function moduleFooter(
   multiline = false,
   external?: ExternalDerived,
   extensions?: string[],
+  governedRoles?: readonly string[],
 ): string {
   // A materialized table (--matviews-as-tables) is a MODEL — its block rides the derived
   // render (topo-ordered with the objects around it) but its name belongs in `models`.
@@ -767,9 +908,15 @@ function moduleFooter(
   if (extensions?.length) {
     // Sorted HERE, not just at the introspection: the renderer owns byte-stability, and a
     // caller passing an unsorted list must not produce a diff against an identical database.
-    parts.push(`export const extensions = [${[...extensions].sort().map((e) => `'${e}'`).join(', ')}];`);
+    parts.push(`export const extensions = [${[...extensions].sort().map(tsLiteral).join(', ')}];`);
     keys.push('extensions');
   }
+  // --govern-roles is an access decision, so it is DECLARED where db:plan reads it: the module.
+  // Without it a later re-pull, or a table where the role holds nothing yet, would leave the
+  // role ungoverned again. Sorted for byte-stability; absent (byte-identical) without the flag.
+  if (governedRoles?.length) {
+    keys.push(`governedRoles: [${[...new Set(governedRoles)].sort().map(tsLiteral).join(', ')}]`);
+  }
   parts.push(`export const appModule = defineModule({ ${keys.join(', ')} });`);
   parts.push(`export const modules = [appModule];`);
   return parts.join('\n\n');
@@ -801,17 +948,17 @@ function externalDerivedNames(e: ExternalDerived): string[] {
 export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions = {}): string {
   const schema = opts.schema ?? 'public';
   const tables = pullableTables(snapshot, schema);
-  const known = new Set(tables.map((t) => bareName(t.table)));
+  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)));
+  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);
 
   // Module composition is the norm: the pulled barrel exports `modules` alongside `models`,
   // so a fresh brownfield project lands on the same shape the framework composes.
-  const footer = moduleFooter(tables.map((t) => modelVarName(t.table)), opts.derived, false, undefined, snapshot.extensions);
+  const footer = moduleFooter(tables.map((t) => modelVarName(t.table)), opts.derived, false, undefined, snapshot.extensions, opts.governRoles);
 
   const header = importHeader([...blocks, footer].join('\n\n'), opts.derived?.imports ?? []);
 
@@ -837,15 +984,24 @@ export function modelImportPath(table: string): string {
 export function modelFileName(table: string): string {
   const owner = schemaOf(table);
   const bare = bareName(table).replace(/_/g, '-');
-  return owner === 'public' ? `${bare}.ts` : `${owner.replace(/_/g, '-')}-${bare}.ts`;
+  const stem = owner === 'public' ? bare : `${owner.replace(/_/g, '-')}-${bare}`;
+  // The stem is a path written under --out and an import specifier: a live name holding a
+  // separator or a dot would write, or import, outside the directory.
+  return `${safeFileStem(stem, liveObject('table', table))}.ts`;
 }
 
-/** The bare tables (other than itself) a table's rendered FKs reference within the pulled set. */
+/**
+ * The tables (other than itself) a table's rendered FKs reference within the pulled set,
+ * QUALIFIED — the `.references(() => …)` thunk names `modelVarName(fk.refTable)`, so the
+ * import must too. Keeping only the bare name imported `Group` from './groups' for a thunk
+ * naming `A6Group`, and a pulled non-public schema could not plan. pg_get_constraintdef
+ * leaves a public ref bare, so a bare ref is read as public.
+ */
 function referencedTables(table: TableSchema, known: Set<string>): string[] {
-  const self = bareName(table.table);
+  const self = qualifiedName(table.table);
   const refs = new Set<string>();
   for (const fk of table.foreignKeys) {
-    const target = bareName(fk.refTable);
+    const target = qualifiedName(fk.refTable);
     if (target !== self && known.has(target)) refs.add(target);
   }
   return [...refs].sort();
@@ -868,11 +1024,11 @@ export interface RenderedModelFile {
 export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions = {}): RenderedModelFile[] {
   const schema = opts.schema ?? 'public';
   const tables = pullableTables(snapshot, schema);
-  const known = new Set(tables.map((t) => bareName(t.table)));
+  const known = knownSet(tables.map((t) => t.table));
   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));
+    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)}';`,
     );
@@ -899,7 +1055,7 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
     // Re-exported so the barrel remains the one place that describes the database.
     ...(extNames.length ? [`export { ${extNames.join(', ')} };`] : []),
     ...(opts.derived?.block ? [opts.derived.block] : []),
-    moduleFooter(names, opts.derived, true, ext, snapshot.extensions),
+    moduleFooter(names, opts.derived, true, ext, snapshot.extensions, opts.governRoles),
   ].join('\n\n');
   files.push({ file: 'index.ts', source: index + '\n' });