@everystack/cli 0.4.99 → 0.4.102

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

@@ -34,6 +34,7 @@ import type { ModelDescriptor, DerivedDescriptor } from '@everystack/model';
 import { compileDeclaredState } from '../declared-diff';
 import { compileMigration } from '../migration-compile';
 import { compileDrizzleSource } from '../schema-source';
+import { modelMapPath, renderModelMap } from '../model-map';
 import { currentGitRef } from '../state-apply';
 import { createDatabase, dropDatabase, buildIntoDatabase, withDatabase } from '../db-build';
 import { resolveModelsPath } from '../models-path';
@@ -115,6 +116,15 @@ export interface StaticCheckInput {
   /** Raw `db/authz-baseline.json`, or null when there is none. The ARTIFACT half of the
    *  ungoverned-grantee gate — see the check below for what it deliberately does not do. */
   baselineSource?: string | null;
+  /** Where the model map lives: beside `artifactPath` (model-map.ts `modelMapPath`). */
+  modelMapPath?: string;
+  /**
+   * The committed model map, read raw. null = no file there (a NOTE, like the schema artifact at
+   * its default path: an app that upgraded and has not run db:generate yet is not broken; the
+   * map's path is never named on its own, so its absence is never a claim that vanished).
+   * Absent (undefined) = the caller did not read it (older callers): no map finding at all.
+   */
+  modelMapSource?: string | null;
 }
 
 export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
@@ -303,6 +313,27 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     });
   }
 
+  // F8 — the model map, the same regenerate-and-compare gate as the drizzle schema. Pure: the
+  // map is a function of the models, so nothing here reads a database (T2).
+  if (input.modelMapSource !== undefined) {
+    const mapPath = input.modelMapPath ?? modelMapPath(input.artifactPath);
+    if (input.modelMapSource === null) {
+      findings.push({
+        level: 'note',
+        area: 'artifact',
+        message: `no model map at ${mapPath} — nothing to match (\`everystack db:generate\` writes it beside the drizzle schema)`,
+      });
+    } else if (input.modelMapSource === renderModelMap(input.models)) {
+      findings.push({ level: 'ok', area: 'artifact', message: `${mapPath} matches regeneration byte-for-byte` });
+    } else {
+      findings.push({
+        level: 'fail',
+        area: 'artifact',
+        message: `${mapPath} does NOT match regeneration — the models moved without db:generate, or the artifact was hand-edited (generated artifacts are never edited). Run \`everystack db:generate\` (it rewrites the map from the models before it reads any database) and commit ${mapPath}.`,
+      });
+    }
+  }
+
   // B7 — db/sql is retired. Files still present would be silently unmanaged: fail
   // with the migration path. (Absence is the normal state; nothing to report.)
   if (input.sqlDirRetired) {
@@ -407,6 +438,14 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
   } catch {
     artifactSource = null;
   }
+  // F8 — the model map lives beside the drizzle schema, so it follows the same resolution.
+  const mapPath = modelMapPath(artifactPath);
+  let modelMapSource: string | null = null;
+  try {
+    modelMapSource = await fs.readFile(mapPath, 'utf8');
+  } catch {
+    modelMapSource = null;
+  }
   // B7 tombstone — a retired db/sql directory still carrying .sql files is a FAIL
   // finding (the message carries the migration path), never a silent skip. The retired
   // --sql-dir flag is itself a FAIL finding here (the sibling verbs refuse it outright);
@@ -438,6 +477,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
     sequences: declaredDb?.sequences, derived: declaredDb?.derived, derivedError,
     moduleModels: declaredDb?.models ?? null,
     baselineSource,
+    modelMapPath: mapPath, modelMapSource,
   });
   // Per-finding detail is the --verbose report. The quiet default answers the one question a
   // human asked — is anything pending? — and names the verb that shows it.

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

@@ -25,7 +25,8 @@ import { pathToFileURL } from 'node:url';
 import type { ModelDescriptor, Module } from '@everystack/model';
 import { linkModels } from '@everystack/model';
 import { introspectSchema } from '../schema-introspect';
-import { compileDrizzleSource } from '../schema-source';
+import { writeGeneratedArtifacts } from '../generated-artifacts';
+import { modelMapPath } from '../model-map';
 import { compileModuleMigration } from '../migration-compile';
 import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, resolveSchemaOut, HELD_DROP_PREFIX, type Journal } from '../migration-generate';
 import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract';
@@ -103,8 +104,8 @@ async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaO
   const models = modules.flatMap((m) => m.models);
   info(`${modules.length} module(s), ${models.length} model(s).`);
 
-  step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-  await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: modules.flatMap((m) => m.derived) }), 'utf8');
+  step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)} and the model map → ${path.relative(process.cwd(), modelMapPath(schemaOut))}...`);
+  await writeGeneratedArtifacts(schemaOut, models, modules.flatMap((m) => m.derived));
 
   const statements = compileModuleMigration(modules);
 
@@ -252,13 +253,13 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     models = await loadModels(modelsPath);
     declaredDb = await loadDeclaredDerived(flags.models);
     info(`${models.length} model(s).`);
-    // The drizzle runtime schema is a derived artifact — refresh it from the models
-    // every run (it needs no DB), so a relation-only change with no DDL diff still
-    // updates it. The drift-guard test asserts this file matches the models (and the
-    // typed derived relations — B6a). A dry run refreshes NOTHING — not even this.
+    // The drizzle runtime schema and the model map are derived artifacts — refresh them
+    // from the models every run (they need no DB), so a relation-only change with no DDL
+    // diff still updates them. db:check asserts both match the models byte for byte (the
+    // schema with the typed derived relations — B6a). A dry run refreshes NOTHING.
     if (!dryRun) {
-      step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-      await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: declaredDb?.derived }), 'utf8');
+      step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)} and the model map → ${path.relative(process.cwd(), modelMapPath(schemaOut))}...`);
+      await writeGeneratedArtifacts(schemaOut, models, declaredDb?.derived);
     }
     const dbSource: DbSource = resolveDbSource(flags);
     if (apply && dbSource.kind !== 'url') {

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

@@ -66,7 +66,7 @@ import { lambdaQueryRunner, lambdaSessionRunner } from '../aws';
 import { loadModels } from './db-generate';
 import { loadDeclaredDerived, type DeclaredDerived } from '../declared-derived';
 import { introspectDerived } from '../derived-introspect';
-import { planReconcile } from '../derived-plan';
+import { planReconcile, type ReconcilePlan } from '../derived-plan';
 import { checkFails, buildReconcileReport } from './db-reconcile';
 import { governedRoleSet, ungovernedGrants } from '../authz-reconcile';
 import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline';
@@ -462,27 +462,41 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       }
     }
 
-    // DERIVED-LAYER VISIBILITY — db:apply ALWAYS reconciles functions/views/matviews/triggers
+    // DERIVED-LAYER PREVIEW — db:apply ALWAYS reconciles functions/views/matviews/triggers
     // against the models, whether or not a --plan is passed; the edge this command mints never
-    // covers that layer. Without this, an empty table/column/grant edge reads as "the target
-    // matches the checkout" even when a function body changed underneath it — an operator who
-    // trusts an empty plan never learns db:apply still has work to do. Read-only: the same pure
-    // planReconcile() that backs `db:reconcile --check`, applied to nothing here — advisory
-    // only, like the FK-orphan and backfill checks above, so it can go stale between mint and
-    // apply without corrupting the plan file (see the file header's rationale for why nothing
-    // read-time-only belongs in the artifact).
+    // covers that layer. Those objects can enforce access (a SECURITY DEFINER function, a
+    // trigger that turns a DELETE into a soft delete), so the reviewer is shown each one in the
+    // default report below — not a count. Read-only: the same pure planReconcile() that backs
+    // `db:reconcile --check`, with the same declared objects and options db:apply's catch-up
+    // passes (derived-catchup.ts), over the session this mint already holds.
+    //
+    // NOT IN THE PLAN FILE, deliberately: db:apply re-plans this layer from the checkout at
+    // apply time and never reads it from the file, and it can go stale between mint and apply
+    // (see the header's rationale for why nothing read-time-only belongs in the artifact).
+    // Adding it would also move planHash for every such plan. The report header names the file
+    // so it is never read as the whole change.
+    let derivedPlan: ReconcilePlan | undefined;
     if (declaredDerived) {
       try {
         const liveDerived = await introspectDerived(session);
-        const derivedPlan = planReconcile(
+        derivedPlan = planReconcile(
           { objects: declaredDerived.objects, warnings: [] },
           liveDerived,
           { renamedTables: declaredDerived.renamedTables },
         );
         if (checkFails(derivedPlan)) {
-          warn('derived layer out of sync (functions/views/matviews/triggers) — this plan does not preview these, only tables/columns/grants:');
-          for (const line of buildReconcileReport(derivedPlan)) warn(`  ${line}`);
-          warn('db:apply always catches up the derived layer, --plan or not — run it to reconcile the above.');
+          // The objects themselves are change lines in the report. What is left here are the
+          // problems (`!` lines: drift, blocked chains, objects that need a baseline) — they
+          // stay in the quiet default, as the ownership report's do. --verbose keeps the whole
+          // internal report.
+          const report = buildReconcileReport(derivedPlan);
+          const shown = verbose ? report : report.filter((line) => line.startsWith('!'));
+          if (shown.length > 0) {
+            warn(verbose
+              ? 'functions/views/matviews/triggers — the reconcile db:apply runs after the plan:'
+              : 'functions/views/matviews/triggers — problems db:apply will report (drift or a blocked chain refuses the apply):');
+            for (const line of shown) warn(`  ${line}`);
+          }
         }
       } catch (err: any) {
         warn(`derived-layer check could not run against this target (${err?.message ?? err}) — db:plan cannot say whether functions/views/matviews/triggers are in sync.`);
@@ -508,6 +522,9 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       stage: flags.stage ?? null,
       planPath: out === '-' ? null : out,
       verbose,
+      // 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,
     })) printLine(text);
 
     if (out !== '-') {

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

@@ -43,11 +43,14 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, type ColumnRow, type ColumnSchema } from '../schema-introspect';
+import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, FK_TARGETS_SQL, foreignKeyTargets, type ColumnRow, type ColumnSchema, type ForeignKeyTargetRow } from '../schema-introspect';
 import { fingerprintLive } from '../schema-fingerprint';
 import { ungovernedGrants, vestigialSequenceGrants, renderVestigialSequenceGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile';
 import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect';
+import { foldLifecycle } from '../lifecycle-pull';
+import { verifyLifecycle, LifecycleDriftError } from '../lifecycle-verify';
+import { LIFECYCLE_OWNER_ROLE } from '@everystack/model';
 
 /**
  * The on-ramp runbook, printed last so the operator is never left guessing what a pull is FOR.
@@ -81,8 +84,9 @@ export function pullOnRampRunbook(opts: { stage?: string; out?: string; abilitie
 import { introspectContract, type TableContract, type AuthzContract } from '../authz-contract';
 import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
-import { renderDerivedSource, renderDerivedFile, renderDerivedDirectory, type DerivedRenderResult } from '../derived-render';
-import { renderModelSource, renderModelFiles, pullableTables, skippedInfrastructureTables, modelVarName, ABILITY_PRESETS } from '../model-render';
+import { renderDerivedSource, renderDerivedFile, renderDerivedDirectory, type DerivedRenderResult, type RenderedDerivedFile } from '../derived-render';
+import { containedPath } from '../generated-names';
+import { renderModelSource, renderModelFiles, pullableTables, skippedInfrastructureTables, modelVarName, externalForeignKeyWarnings, ABILITY_PRESETS, type RenderedModelFile } from '../model-render';
 import { deriveAbilities } from '../authz-derive';
 import type { QueryRunner } from '../authz-contract';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source';
@@ -193,12 +197,14 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
-  // --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: a fresh build from
-  // models must recreate them. Never inferred from the database (a re-pull must not turn
-  // a rendering decision into an access decision); complete-or-refuse per role — a listed
-  // role holding a column-scoped grant fails the pull (see deriveAbilities).
+  // --govern-roles: the operator's EXPLICIT decision to govern these foreign roles: their
+  // grants and policies render into the models (role-scoped can() where they pair exactly,
+  // `privileges` otherwise) and the module declares them in `governedRoles`. Required for
+  // migration deletion when the migrations created grants to roles outside the vocabulary: a
+  // fresh build from models must recreate them. Never inferred from the database (a re-pull
+  // must not turn a rendering decision into an access decision); complete-or-refuse per role —
+  // a column-scoped grant with no exactly-paired policy, or a restrictive policy, fails the
+  // pull (see deriveAbilities).
   const governRoles = (flags['govern-roles'] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
   if (governRoles.length && abilities !== 'live') {
     fail(`--govern-roles transcribes LIVE grants, so it requires --abilities live.`);
@@ -209,6 +215,12 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       fail(`--govern-roles ${r}: the vocabulary roles and PUBLIC are always governed — name only foreign roles (an ops/connection role the migrations granted to).`);
       process.exit(1);
     }
+    // The name is written into generated source (`can(..., { role: '<r>' })`) and the compiler
+    // emits it unquoted into GRANT/CREATE POLICY, which accepts only a bare lowercase identifier.
+    if (!/^[a-z_][a-z0-9_]*$/.test(r)) {
+      fail(`--govern-roles ${JSON.stringify(r)}: a governed role must be a bare lowercase identifier ([a-z_][a-z0-9_]*) — the compiler emits it unquoted.`);
+      process.exit(1);
+    }
   }
 
   let dbSource: DbSource;
@@ -235,12 +247,16 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   let liveContract: AuthzContract | undefined;
   let liveOwners: TableOwner[] = [];
   let derivedCatalog: DerivedCatalog | undefined;
+  /** Tables folded to `lifecycle: true` (lifecycle-pull.ts). */
+  let lifecycleTables: ReadonlySet<string> = new Set();
   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. */
+  let fkTargets: Map<string, { schema: string; table: string }> = new Map();
+  let end: (() => Promise<void>) | undefined;
   try {
     let runner: QueryRunner;
     let session: SessionRunner;
-    let end: (() => Promise<void>) | undefined;
     if (dbSource.kind === 'url') {
       note(connectingVia(dbSource));
       ({ runner, session, end } = await createUrlRunner(dbSource.url));
@@ -253,16 +269,30 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     note(`Introspecting live database (schema: ${schemas.join(", ")})...`);
     current = await introspectSchema(session);
+    fkTargets = foreignKeyTargets((await runner(FK_TARGETS_SQL)) as ForeignKeyTargetRow[]);
     // The derived layer rides the same pull (B5) — views/matviews/functions/sequences
     // render as descriptors; adoption is pull → commit → --baseline → clean reconcile.
     derivedCatalog = await introspectDerived(session);
+    const lifecycle = await verifyLifecycle(session, ['anon', 'authenticated', 'admin', LIFECYCLE_OWNER_ROLE, ...governRoles]);
+    if (lifecycle.failures.length) throw new LifecycleDriftError(lifecycle.failures);
+    for (const warning of lifecycle.notes) caution(warning);
     // --abilities live: the authz half of the on-ramp. Same connection, one more read —
     // the grants and policies that already exist become the models' declared abilities,
     // instead of a human transcribing them by hand.
     if (abilities === 'live') {
       note('Introspecting live authorization (grants + policies)...');
-      const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
-      liveContract = contract;
+      const rawSnapshot = current;
+      const rawContract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
+      // A lifecycle table folds back to `lifecycle: true` here only: proving the table is exactly
+      // what the compiler writes needs its grants and policies. Only the renderers and the adoption
+      // findings see the folded inputs; the fingerprint below is the raw one.
+      const fold = foldLifecycle(current, rawContract, derivedCatalog);
+      current = fold.snapshot;
+      derivedCatalog = fold.catalog;
+      lifecycleTables = fold.tables;
+      if (lifecycleTables.size) note(`Lifecycle: ${[...lifecycleTables].sort().join(', ')} rendered as lifecycle: true (generated columns, grants and functions folded).`);
+      const contract = fold.contract;
+      liveContract = rawContract;
       // The owner is NOT rendered into the models — it is the dev user here and the
       // operator role on a stage, so a model that declared it would drift everywhere.
       // It is read to be SAID, on the one surface that is looking at the database.
@@ -272,18 +302,32 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       // Roles outside the model vocabulary (anon/authenticated/admin) are usually ONE
       // operator account granted across the whole schema. Said once here rather than
       // repeated in all N models, where it would bury the per-table findings.
+      // A folded lifecycle table makes the pulled module govern the reserved role (moduleGovernedRoles),
+      // so db:plan governs it on EVERY table: its grants on a table that did not fold are revoked.
+      const governsLifecycle = lifecycleTables.size > 0;
       const unmapped = new Set<string>();
       for (const t of contract.tables) {
         for (const r of Object.keys(t.grants)) {
+          if (governsLifecycle && r === LIFECYCLE_OWNER_ROLE) continue;
           if (!['anon', 'authenticated', 'admin', 'PUBLIC', 'public'].includes(r) && !governRoles.includes(r)) unmapped.add(r);
         }
       }
+      // Said whether or not anything folded: with no fold the role is not governed, and its grants
+      // would otherwise pass into the adoption baseline under a generic "Grants exist" note.
+      const unfoldedLifecycleGrants = contract.tables
+        .filter((t) => t.grants[LIFECYCLE_OWNER_ROLE] || t.columnGrants?.[LIFECYCLE_OWNER_ROLE]).map((t) => t.table).sort();
+      if (unfoldedLifecycleGrants.length) {
+        const unfolded = `${LIFECYCLE_OWNER_ROLE} holds grants on ${unfoldedLifecycleGrants.join(', ')}, which did not fold to lifecycle: true (not exactly what the compiler writes).`;
+        caution(governsLifecycle
+          ? `${unfolded} The pulled module governs that role, so db:plan will revoke them.`
+          : `${unfolded} No table folded, so the pulled module does not govern that role: those grants are recorded as adoption exemptions and left as they are.`);
+      }
       if (governRoles.length) {
-        note(`--govern-roles ${governRoles.join(', ')}: their grants are transcribed as privileges — the models now OWN them, and a fresh build recreates them.`);
+        note(`--govern-roles ${governRoles.join(', ')}: the models now OWN these roles (defineModule governedRoles) — a grant and its policy render as a role-scoped can() where they pair exactly, any other grant as privileges; a fresh build recreates them.`);
       }
       if (unmapped.size) {
         note(`Grants exist for ${[...unmapped].sort().join(', ')} — not rendered: abilities name the roles the model knows (anon/authenticated/admin).`);
-        detail(`These are left exactly as they are in the database. Add can(..., { role }) to own them, or re-pull with --govern-roles to transcribe their grants as privileges.`);
+        detail(`These are left exactly as they are in the database. Add can(..., { role }) to own them, or re-pull with --govern-roles to govern them.`);
       }
       // ADOPTION: record the foreign grantees that were already here, per stage. The
       // reconciler exempts them from revocation, so this artifact is what stops that
@@ -294,15 +338,16 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       // The governed set at ADOPTION is the fixed vocabulary plus any --govern-roles: a
       // governed role's grants are DECLARED (transcribed as privileges), so recording them
       // as exemptions too would double-book them — declared and exempted at once.
-      pulledExemptions = ungovernedGrants(contract, new Set([...ALWAYS_GOVERNED, ...governRoles]));
+      const governedAtPull = new Set<string>([...ALWAYS_GOVERNED, ...governRoles, ...(governsLifecycle ? [LIFECYCLE_OWNER_ROLE] : [])]);
+      pulledExemptions = ungovernedGrants(contract, governedAtPull);
       // A6's advisory. A blanket `GRANT USAGE ON ALL SEQUENCES` beside a blanket SELECT is a
       // common brownfield shape. The advisory says exactly what the next db:plan will do with it,
-      // so it must see the SAME governed set the plan will use: the vocabulary plus --govern-roles.
-      // (With the default set, a --govern-roles grantee was told "not governed, nothing revokes
-      // it" while the plan minted the REVOKE — closing-gate review, 2026-09-07.)
-      const governedAtPull = new Set<string>([...ALWAYS_GOVERNED, ...governRoles]);
+      // so it must see the SAME governed set the plan will use: the vocabulary plus --govern-roles,
+      // plus the reserved role when a table folded. (With the default set, a --govern-roles grantee
+      // was told "not governed, nothing revokes it" while the plan minted the REVOKE — closing-gate
+      // review, 2026-09-07.)
       for (const line of renderVestigialSequenceGrants(vestigialSequenceGrants(contract), governedAtPull)) caution(line);
-      pulledFingerprint = fingerprintLive(current, contract).hash;
+      pulledFingerprint = fingerprintLive(rawSnapshot, rawContract).hash;
     }
     // --matviews-as-tables: the flip needs real fields — one extra catalog read for the
     // matview columns the derived layer (definition-only) doesn't carry.
@@ -324,6 +369,11 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     await end?.();
   } catch (err: any) {
+    await end?.().catch(() => {});
+    if (err instanceof LifecycleDriftError) {
+      for (const line of err.lines) console.error(line);
+      process.exit(1);
+    }
     fail(err.message);
     if (dbSource.kind === 'url') {
       detail('Check the connection string and that the database is accepting connections.');
@@ -359,18 +409,27 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   // The --govern-roles complete-or-refuse gate, run BEFORE any file is written: a refusal
   // mid-render would leave a half-written models directory. Pure re-derivation, pulled
   // tables only — a governed role's column grant on an UNPULLED table is safe (that table
-  // is not declared, so nothing reconciles it).
+  // is not declared, so nothing reconciles it). The same pass prints every governed grant or
+  // policy can() could not state exactly: it is never silently approximated.
   if (governRoles.length && liveAuthz) {
     const pulledNames = new Set(pulled.map((t) => t.table));
+    const warnings: string[] = [];
     try {
       const govern = new Set(governRoles);
-      for (const [name, c] of liveAuthz) if (pulledNames.has(name)) deriveAbilities(c, { governRoles: govern });
+      for (const [name, c] of liveAuthz) {
+        if (pulledNames.has(name)) warnings.push(...deriveAbilities(c, { governRoles: govern }).warnings);
+      }
     } catch (err: any) {
       fail(err.message);
       process.exit(1);
     }
+    for (const w of warnings) caution(`WARNING: ${w}`);
   }
 
+  // F3e — an FK out of the pulled set is declared in the external form; one that CASCADES on
+  // delete means a delete in a table this declared state does not govern removes rows here.
+  for (const w of externalForeignKeyWarnings(current, schema, fkTargets)) caution(`WARNING: ${w}`);
+
   // WHO owns the tables being pulled. Nothing is FLAGGED here: flagging needs a declared
   // write principal to contradict, and the models this pull is about to write do not exist
   // yet. Naming the owner is the half the pull genuinely saw — and the half that vanishes
@@ -381,20 +440,68 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     )) note(line);
   }
 
-  // The derived layer (B5): rendered from the live catalog with dependsOn from the real
-  // edge graph. Everything inexpressible is a stderr warning AND an inline FIXME.
-  const knownTables = new Map(pulled.map((t) => [t.table, modelVarName(t.table)]));
-  const derived: DerivedRenderResult = renderDerivedSource(derivedCatalog ?? { objects: [], edges: [], provenance: [] }, {
-    knownTables,
-    sequences: current.sequences,
-    ...(matviewsAsTables ? {
-      matviewsAsTables: {
-        columns: matviewColumns ?? new Map(),
-        enums: new Map((current.enums ?? []).map((e) => [e.name, e.values])),
-        ...(candidatesByIdentity ? { keyCandidates: candidatesByIdentity } : {}),
-      },
-    } : {}),
-  });
+  // RENDER EVERYTHING, THEN WRITE. A live name with no safe spelling as a generated identifier
+  // or file name (generated-names.ts) refuses inside a renderer; rendering every output first,
+  // and resolving every directory write target (containedPath, the second wall), means that a
+  // refusal leaves --out and --derived-out exactly as they were.
+  let knownTables: Map<string, string>;
+  let derived: DerivedRenderResult;
+  let derivedFiles: Array<RenderedDerivedFile & { target: string }> | undefined;
+  let derivedFileSource: string | undefined;
+  let modelFiles: Array<RenderedModelFile & { target: string }> | undefined;
+  let modelSource: string | undefined;
+  try {
+    // The derived layer (B5): rendered from the live catalog with dependsOn from the real
+    // edge graph. Everything inexpressible is a stderr warning AND an inline FIXME.
+    knownTables = new Map(pulled.map((t) => [t.table, modelVarName(t.table)]));
+    derived = renderDerivedSource(derivedCatalog ?? { objects: [], edges: [], provenance: [] }, {
+      knownTables,
+      sequences: current.sequences,
+      ...(matviewsAsTables ? {
+        matviewsAsTables: {
+          columns: matviewColumns ?? new Map(),
+          enums: new Map((current.enums ?? []).map((e) => [e.name, e.values])),
+          ...(candidatesByIdentity ? { keyCandidates: candidatesByIdentity } : {}),
+        },
+      } : {}),
+    });
+    if (derivedOut && derivedOutIsDir) {
+      // A cycle between split files is fatal at import time (TDZ) — refused here, before
+      // anything is written, rather than shipping a barrel nobody can import.
+      const outPath = path.resolve(derivedOut);
+      derivedFiles = renderDerivedDirectory(derived, knownTables, outPath)
+        .map((f) => ({ ...f, target: containedPath(outPath, f.file) }));
+    } else if (derivedOut) {
+      derivedFileSource = renderDerivedFile(derived, knownTables);
+    }
+    // The models render unless --derived-out alone was asked for (that path writes no models).
+    if (!derivedOut || flags.out) {
+      // With --derived-out, the embedded copy would duplicate every descriptor — the models
+      // output carries models only, and the barrel IMPORTS the layer from its own file. It used
+      // to carry neither, so the same command that wrote 120 descriptors emitted a
+      // `defineModule({ models })` that excluded every one of them, and db:plan then compared
+      // against a fraction of the database while printing a confident statement count.
+      const embeddedDerived = derivedOut ? undefined : derived;
+      const externalDerived = derivedOut && flags.out
+        ? {
+          specifier: derivedImportSpecifier(flags.out, derivedOut),
+          sequences: derived.sequenceNames.length > 0,
+          materializedTables: derived.materializedTableNames.length > 0,
+          derived: derived.names.length > 0,
+        }
+        : 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 })
+          .map((f) => ({ ...f, target: containedPath(dir, f.file) }));
+      } else {
+        modelSource = renderModelSource(current, { schema, abilities, liveAuthz, governRoles, fkTargets, derived: embeddedDerived, lifecycleTables });
+      }
+    }
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
   for (const w of derived.warnings) caution(w);
   const derivedCount = derived.names.length + derived.sequenceNames.length;
   if (derivedCount > 0) {
@@ -412,10 +519,8 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     const outPath = path.resolve(derivedOut);
     let fileCount = 1;
     try {
-      if (derivedOutIsDir) {
-        // A cycle between split files is fatal at import time (TDZ) — refused here, before
-        // anything is written, rather than shipping a barrel nobody can import.
-        const files = renderDerivedDirectory(derived, knownTables, outPath);
+      if (derivedFiles) {
+        const files = derivedFiles;
         await fs.mkdir(outPath, { recursive: true });
         // The split set SHRINKS: drop the last function in `auth` and this pull no longer
         // writes functions-auth.ts, but the previous pull's copy is still on disk declaring
@@ -424,7 +529,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
         // as the --out <dir> model writer below, which leaves stray files alone and says so.
         const written = new Set(files.map((f) => f.file));
         const stale = (await fs.readdir(outPath)).filter((f) => f.endsWith('.ts') && !written.has(f));
-        for (const f of files) await fs.writeFile(path.join(outPath, f.file), f.source, 'utf8');
+        for (const f of files) await fs.writeFile(f.target, f.source, 'utf8');
         fileCount = files.length;
         if (stale.length) {
           caution(
@@ -435,7 +540,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
         }
       } else {
         await fs.mkdir(path.dirname(outPath), { recursive: true });
-        await fs.writeFile(outPath, renderDerivedFile(derived, knownTables), 'utf8');
+        await fs.writeFile(outPath, derivedFileSource!, 'utf8');
       }
     } catch (err: any) {
       fail(`Could not write ${derivedOut}: ${err.message}`);
@@ -451,31 +556,16 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       process.exit(0);
     }
   }
-  // With --derived-out, the embedded copy would duplicate every descriptor — the models
-  // output carries models only, and the barrel IMPORTS the layer from its own file. It used
-  // to carry neither, so the same command that wrote 120 descriptors emitted a
-  // `defineModule({ models })` that excluded every one of them, and db:plan then compared
-  // against a fraction of the database while printing a confident statement count.
-  const embeddedDerived = derivedOut ? undefined : derived;
-  const externalDerived = derivedOut && flags.out
-    ? {
-      specifier: derivedImportSpecifier(flags.out, derivedOut),
-      sequences: derived.sequenceNames.length > 0,
-      materializedTables: derived.materializedTableNames.length > 0,
-      derived: derived.names.length > 0,
-    }
-    : undefined;
-
   let source: string;
-  if (flags.out && !flags.out.endsWith('.ts')) {
+  if (modelFiles) {
     // A directory: one file per model + index.ts — the default shape for a real app.
-    const dir = path.resolve(flags.out);
-    const files = renderModelFiles(current, { schema, abilities, liveAuthz, governRoles, derived: embeddedDerived, externalDerived });
+    const dir = path.resolve(flags.out!);
+    const files = modelFiles;
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));
       const existing = (await fs.readdir(dir)).filter((f) => f.endsWith('.ts') && !written.has(f));
-      for (const f of files) await fs.writeFile(path.join(dir, f.file), f.source, 'utf8');
+      for (const f of files) await fs.writeFile(f.target, f.source, 'utf8');
       if (existing.length) {
         caution(`${existing.length} existing .ts file(s) in ${path.relative(process.cwd(), dir)} were not part of this pull and were left untouched: ${existing.join(', ')}`);
       }
@@ -487,7 +577,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     source = files.map((f) => f.source).join('\n');
   } else if (flags.out) {
     const outPath = path.resolve(flags.out);
-    source = renderModelSource(current, { schema, abilities, liveAuthz, governRoles, derived: embeddedDerived });
+    source = modelSource!;
     try {
       await fs.mkdir(path.dirname(outPath), { recursive: true });
       await fs.writeFile(outPath, source, 'utf8');
@@ -497,7 +587,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${pulled.length} model(s).`);
   } else {
-    source = renderModelSource(current, { schema, abilities, liveAuthz, governRoles, derived: embeddedDerived });
+    source = modelSource!;
     process.stdout.write(source);
     ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
   }