@everystack/cli 0.3.31 → 0.4.1

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

@@ -3,6 +3,8 @@
  *
  *   db:generate --stage <name> [--name <label>]   introspect the live DB → diff the Models
  *                                                  → write the next drizzle migration file
+ *   db:generate --dry-run                          the same edge, printed — NOTHING written
+ *                                                  (no migration, no journal, no schema refresh)
  *
  * The one generator — both layers in one ordered migration. It compiles the app's Models,
  * introspects the deployed database through the ops Lambda `db:query` action (the same
@@ -24,12 +26,14 @@ import type { ModelDescriptor, Module } from '@everystack/model';
 import { introspectSchema } from '../schema-introspect.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import { compileModuleMigration } from '../migration-compile.js';
-import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, HELD_DROP_PREFIX, type Journal } from '../migration-generate.js';
+import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, resolveSchemaOut, HELD_DROP_PREFIX, type Journal } from '../migration-generate.js';
 import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
-import { applyStateAndVerify, classifyGeneratedStatements, currentGitRef, type StateSyncOutcome } from '../state-apply.js';
+import { loadDeclaredDerived, assertNoHoles, type DeclaredDerived } from '../declared-derived.js';
+import { asModelComposeError, opsAdviceLines } from '../ops-advice.js';
+import { applyStateAndVerify, classifyGeneratedStatements, renderStatementHistogram, currentGitRef, type StateSyncOutcome } from '../state-apply.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
@@ -46,18 +50,24 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
   };
 }
 
-/** Import the app's Model barrel and return its `models` array (runs under tsx, so TS imports work). */
+/** Import the app's Model barrel and return its `models` array (runs under tsx, so TS imports work).
+ *  Every failure is the operator's own barrel — ModelComposeError, never dressed as IAM. */
 export async function loadModels(modelsPath: string): Promise<ModelDescriptor[]> {
-  const abs = path.resolve(modelsPath);
-  let mod: any;
   try {
-    mod = await import(pathToFileURL(abs).href);
-  } catch (err: any) {
-    throw new Error(`Could not load models from ${modelsPath}: ${err.message}`);
+    const abs = path.resolve(modelsPath);
+    let mod: any;
+    try {
+      mod = await import(pathToFileURL(abs).href);
+    } catch (err: any) {
+      throw new Error(`Could not load models from ${modelsPath}: ${err.message}`);
+    }
+    const models = mod.models ?? mod.default;
+    if (!Array.isArray(models)) throw new Error(`${modelsPath} must export a \`models\` array (got ${typeof models}).`);
+    assertNoHoles(modelsPath, 'models', models);
+    return models;
+  } catch (err) {
+    throw asModelComposeError(modelsPath, err);
   }
-  const models = mod.models ?? mod.default;
-  if (!Array.isArray(models)) throw new Error(`${modelsPath} must export a \`models\` array (got ${typeof models}).`);
-  return models;
 }
 
 /**
@@ -76,7 +86,7 @@ async function loadModules(modelsPath: string): Promise<Module[]> {
   }
   if (Array.isArray(mod.modules)) return mod.modules;
   const models = mod.models ?? mod.default;
-  if (Array.isArray(models)) return [{ models, extensions: [], functions: [] }];
+  if (Array.isArray(models)) return [{ models, extensions: [], sequences: [], derived: [], functions: [] }];
   throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
 }
 
@@ -87,14 +97,14 @@ async function loadModules(modelsPath: string): Promise<Module[]> {
  * `drizzle/`. Roles are excluded by design (they are `db:provision`). Use it to (re)initialize
  * a clean migration history: clear `drizzle/`, then `db:generate --init`.
  */
-async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaOut: string, name: string): Promise<void> {
+async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaOut: string, name: string, schemaOutRecord: string): Promise<void> {
   step(`Loading modules from ${modelsPath}...`);
   const modules = await loadModules(modelsPath);
   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), 'utf8');
+  await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: modules.flatMap((m) => m.derived) }), 'utf8');
 
   const statements = compileModuleMigration(modules);
 
@@ -106,6 +116,7 @@ async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaO
     journal = { version: '7', dialect: 'postgresql', entries: [] };
   }
   const { filename, journal: nextJournal } = planMigrationFile(journal, name, Date.now());
+  nextJournal.schemaOut = schemaOutRecord; // D2 — flag-less later runs reuse it
   const filePath = path.join(migrationsDir, filename);
   await fs.mkdir(path.join(migrationsDir, 'meta'), { recursive: true });
   await fs.writeFile(filePath, formatMigrationFile(statements), 'utf8');
@@ -117,18 +128,43 @@ async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaO
   process.exit(0);
 }
 
+/** Read the journal if present (null = no history yet). */
+async function readJournal(migrationsDir: string): Promise<Journal | null> {
+  try {
+    return JSON.parse(await fs.readFile(path.join(migrationsDir, 'meta', '_journal.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 export async function dbGenerateCommand(flags: Record<string, string>): Promise<void> {
   const modelsPath = resolveModelsPath(flags.models);
   const migrationsDir = path.resolve(flags.dir || DEFAULT_MIGRATIONS);
-  const schemaOut = path.resolve(flags['schema-out'] || DEFAULT_SCHEMA_OUT);
   const name = flags.name || 'generated';
   const allowDrops = flags['allow-drops'] === 'true';
+  const dryRun = flags['dry-run'] === 'true';
+
+  // D2 — schema-out resolution: flag > journal-recorded > default. Recording the
+  // resolved path in the journal makes the relocated-artifact orphan unmintable:
+  // a later run without the flag keeps writing where the project writes.
+  const journal = await readJournal(migrationsDir);
+  const schemaOutRes = resolveSchemaOut(flags['schema-out'], journal, DEFAULT_SCHEMA_OUT);
+  const schemaOut = path.resolve(schemaOutRes.path);
+  if (schemaOutRes.source === 'recorded') {
+    info(`schema-out: ${schemaOutRes.path} (recorded in the journal; override with --schema-out)`);
+  } else if (schemaOutRes.source === 'flag' && schemaOutRes.updateRecord && journal?.schemaOut) {
+    warn(`schema-out moves: ${journal.schemaOut} → ${schemaOutRes.path} — the journal record updates with this run; delete the old artifact.`);
+  }
 
   // --init: greenfield, no live DB — the model emits the whole migration (extensions + schema +
   // authz + package functions). The brownfield path below introspects the deployed DB and diffs.
   if (flags.init === 'true') {
+    if (dryRun) {
+      fail('--dry-run previews the brownfield diff — --init is the greenfield generator (its output IS the whole migration; there is nothing cheaper to preview).');
+      process.exit(1);
+    }
     try {
-      await dbGenerateInit(modelsPath, migrationsDir, schemaOut, flags.name || 'init');
+      await dbGenerateInit(modelsPath, migrationsDir, schemaOut, flags.name || 'init', schemaOutRes.path);
     } catch (err: any) {
       fail(err.message);
       process.exit(1);
@@ -137,7 +173,12 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   }
 
   const apply = flags.apply === 'true';
+  if (dryRun && apply) {
+    fail('--dry-run and --apply are opposites — a dry run writes and executes nothing. Pick one.');
+    process.exit(1);
+  }
   let models: ModelDescriptor[];
+  let declaredDb: DeclaredDerived | null = null;
   let current;
   let liveAuthz;
   let runner!: QueryRunner;
@@ -145,12 +186,16 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   try {
     step(`Loading models from ${modelsPath}...`);
     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.
-    step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-    await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
+    // 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.
+    if (!dryRun) {
+      step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
+      await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: declaredDb?.derived }), 'utf8');
+    }
     const dbSource: DbSource = resolveDbSource(flags);
     if (apply && dbSource.kind !== 'url') {
       fail('--apply needs a direct connection (--database-url or DATABASE_URL) — the ops Lambda query path is read-only by design.');
@@ -172,21 +217,41 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     if (!apply) await end?.();
   } catch (err: any) {
     fail(err.message);
-    info('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
-    info('Diffing against a local database instead? Pass --database-url or set DATABASE_URL.');
+    for (const line of opsAdviceLines(err, [
+      'Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.',
+      'Diffing against a local database instead? Pass --database-url or set DATABASE_URL.',
+    ])) info(line);
     process.exit(1);
   }
 
   // One ordered migration carries both layers: data DDL first, then the authz reconcile
   // (RLS/policies/grants) the Models' abilities declare, diffed against the live contract.
-  const statements = generateMigrationSql(models, current, { allowDrops, liveAuthz });
+  const statements = generateMigrationSql(models, current, { allowDrops, liveAuthz, sequences: declaredDb?.sequences });
   const unmodeled = unmodeledTables(models, current);
   if (unmodeled.length) {
     info(`${unmodeled.length} table(s) in the database are not declared by any model — left untouched (db:generate manages only declared tables).`);
   }
   console.log('');
   if (statements.length === 0) {
-    success('db:generate — the live database already matches the models. No migration written.');
+    success(`db:generate — the live database already matches the models. ${dryRun ? 'Nothing to preview.' : 'No migration written.'}`);
+    process.exit(0);
+  }
+
+  // D1 — --dry-run: the edge as SQL, nothing else. No migration file, no journal
+  // entry, no schema refresh — preview traffic belongs here (and db:diff computes
+  // the models-vs-models edge with no database at all).
+  if (dryRun) {
+    const classified = classifyGeneratedStatements(statements);
+    // Summary FIRST — the shape of the edge is the review surface; the SQL wall follows.
+    info(`dry run — ${statements.length} statement(s), nothing written:`);
+    const histogram = renderStatementHistogram(classified.executable);
+    if (histogram) info(`shape: ${histogram}`);
+    if (classified.heldDrops.length) warn(`${classified.heldDrops.length} destructive change(s) held back (shown as comments) — --allow-drops includes them.`);
+    if (classified.notices.length) info(`${classified.notices.length} notice(s) — manual follow-ups.`);
+    console.log('');
+    for (const s of statements) console.log(s.endsWith(';') ? s : `${s};`);
+    console.log('');
+    info('Nothing was written. Drop --dry-run to mint the migration, or `db:generate --apply` to run it directly on a dev database.');
     process.exit(0);
   }
 
@@ -195,12 +260,15 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   // means db:generate is a no-op again, not "a file was written".
   if (apply) {
     const classified = classifyGeneratedStatements(statements);
+    // Summary FIRST — the shape of the edge is the review surface; the SQL wall follows.
     info(`Plan — ${statements.length} statement(s):`);
+    const histogram = renderStatementHistogram(classified.executable);
+    if (histogram) info(`shape: ${histogram}`);
+    if (classified.heldDrops.length) warn(`${classified.heldDrops.length} destructive change(s) held back — NOT executed (re-run with --allow-drops to include them).`);
+    if (classified.notices.length) info(`${classified.notices.length} notice(s) — manual follow-ups, nothing executed for them.`);
     console.log('');
     for (const s of statements) console.log(s.endsWith(';') ? s : `${s};`);
     console.log('');
-    if (classified.heldDrops.length) warn(`${classified.heldDrops.length} destructive change(s) held back — NOT executed (re-run with --allow-drops to include them).`);
-    if (classified.notices.length) info(`${classified.notices.length} notice(s) — manual follow-ups, nothing executed for them.`);
     if (classified.executable.length === 0) {
       success('Nothing executable — only held/notice items differ.');
       process.exit(0);
@@ -209,7 +277,7 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     let outcome: StateSyncOutcome;
     try {
       outcome = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
-        allowDrops, actor: process.env.USER ?? null, gitRef: currentGitRef(),
+        allowDrops, sequences: declaredDb?.sequences, actor: process.env.USER ?? null, gitRef: currentGitRef(),
       });
     } catch (err: any) {
       fail(`Apply failed and rolled back: ${err.message}`);
@@ -228,14 +296,12 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   }
 
   const journalPath = path.join(migrationsDir, 'meta', '_journal.json');
-  let journal: Journal;
-  try {
-    journal = JSON.parse(await fs.readFile(journalPath, 'utf8'));
-  } catch {
-    journal = { version: '7', dialect: 'postgresql', entries: [] };
-  }
-
-  const { filename, journal: nextJournal } = planMigrationFile(journal, name, Date.now());
+  const { filename, journal: nextJournal } = planMigrationFile(
+    journal ?? { version: '7', dialect: 'postgresql', entries: [] }, name, Date.now(),
+  );
+  // D2 — the resolved schema-out path rides the journal, so the next flag-less run
+  // keeps writing where this project writes.
+  nextJournal.schemaOut = schemaOutRes.path;
   const filePath = path.join(migrationsDir, filename);
   try {
     await fs.mkdir(path.join(migrationsDir, 'meta'), { recursive: true });
@@ -247,6 +313,8 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   }
 
   success(`Wrote ${path.relative(process.cwd(), filePath)} (${statements.length} statement(s)).`);
+  const tapeHistogram = renderStatementHistogram(classifyGeneratedStatements(statements).executable);
+  if (tapeHistogram) info(`shape: ${tapeHistogram}`);
   const warnings = statements.filter((s) => s.includes('-- WARNING')).length;
   const notices = statements.filter((s) => s.startsWith('-- NOTICE')).length;
   const held = statements.filter((s) => s.startsWith(HELD_DROP_PREFIX)).length;

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

@@ -2,6 +2,7 @@
  * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
  *
  *   db:pull [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>]
+ *           [--derived-out <file.ts>] [--abilities public-read]
  *
  * The reverse of db:generate: that writes migrations FROM Models; this writes Models FROM the
  * database. It introspects the deployed schema through the read-only ops Lambda `db:query`
@@ -18,17 +19,26 @@
  * `--out` the single module goes to stdout (so `db:pull > models.ts` works). Every
  * progress/diagnostic line goes to stderr, so the stdout pipe stays pure source. The
  * renderers (model-render.ts) are pure; this shell is the IO.
+ *
+ * `--derived-out <file.ts>` is the brownfield splice, first-class: the derived layer
+ * (descriptors + sequences) lands as its own self-contained module — model imports from
+ * the contract kebab files, `export const derived/sequences` arrays — instead of riding
+ * the models render. Alone, it leaves the models untouched (the hand-maintained-barrel
+ * case); with `--out`, the models render omits the now-external derived layer.
  */
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { introspectSchema } from '../schema-introspect.js';
-import { renderModelSource, renderModelFiles, pullableTables } from '../model-render.js';
+import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
+import { renderDerivedSource, renderDerivedFile, type DerivedRenderResult } from '../derived-render.js';
+import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { fail } from '../output.js';
+import { opsAdviceLines } from '../ops-advice.js';
 
 // Progress → stderr, so stdout carries only the rendered source (this command is codegen,
 // not a report — the shared output helpers write to stdout, which would corrupt a redirect).
@@ -49,6 +59,23 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
 export async function dbPullCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema || 'public';
 
+  // --derived-out: the brownfield splice, first-class. A consumer with an existing
+  // hand-maintained barrel wants the derived layer as its own file — not codemodded
+  // out of a rendered monolith. Validated before any introspection.
+  const derivedOut = flags['derived-out'];
+  if (derivedOut && !derivedOut.endsWith('.ts')) {
+    fail(`--derived-out must name a .ts file (got '${derivedOut}') — e.g. --derived-out db/models/derived.ts.`);
+    process.exit(1);
+  }
+
+  // The read-model scaffold: default 'commented' surfaces the authz decision in every
+  // model; a preset stamps it. Validated up front so a typo fails before introspection.
+  const abilities = flags.abilities || 'commented';
+  if (abilities !== 'commented' && !ABILITY_PRESETS[abilities]) {
+    fail(`Unknown --abilities preset '${abilities}'. Known: ${Object.keys(ABILITY_PRESETS).join(', ')} (omit the flag to scaffold the decision as comments).`);
+    process.exit(1);
+  }
+
   let dbSource: DbSource;
   try {
     dbSource = resolveDbSource(flags);
@@ -58,6 +85,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   }
 
   let current;
+  let derivedCatalog: DerivedCatalog | undefined;
   try {
     let runner: QueryRunner;
     let end: (() => Promise<void>) | undefined;
@@ -72,14 +100,21 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     note(`Introspecting live database (schema: ${schema})...`);
     current = await introspectSchema(runner);
+    // 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(runner);
     await end?.();
   } catch (err: any) {
     fail(err.message);
     if (dbSource.kind === 'url') {
       detail('Check the connection string and that the database is accepting connections.');
     } else {
-      detail('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
-      detail('Introspecting a local database instead? Pass --database-url or set DATABASE_URL.');
+      // IAM advice only when the AWS transport actually threw — an introspection
+      // failure inside a Lambda that RAN is not a permissions problem.
+      for (const line of opsAdviceLines(err, [
+        'Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.',
+        'Introspecting a local database instead? Pass --database-url or set DATABASE_URL.',
+      ])) detail(line);
     }
     process.exit(1);
   }
@@ -90,11 +125,47 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // 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,
+  });
+  for (const w of derived.warnings) caution(w);
+  const derivedCount = derived.names.length + derived.sequenceNames.length;
+  if (derivedCount > 0) {
+    detail(`Derived layer: ${derived.names.length} descriptor(s) + ${derived.sequenceNames.length} sequence(s) rendered (adopt with db:reconcile --baseline after committing).`);
+  }
+
+  // The standalone derived file. The models output (below) then omits the derived
+  // layer — it lives here, and the module wires both: defineModule({ models, sequences, derived }).
+  if (derivedOut) {
+    const outPath = path.resolve(derivedOut);
+    try {
+      await fs.mkdir(path.dirname(outPath), { recursive: true });
+      await fs.writeFile(outPath, renderDerivedFile(derived, knownTables), 'utf8');
+    } catch (err: any) {
+      fail(`Could not write ${derivedOut}: ${err.message}`);
+      process.exit(1);
+    }
+    ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${derived.names.length} descriptor(s) + ${derived.sequenceNames.length} sequence(s), self-contained.`);
+    note(`Wire it on your module — defineModule({ models${derived.sequenceNames.length ? ', sequences' : ''}, derived }) — then adopt with db:reconcile --apply --baseline (--rebaseline over db/sql-era provenance).`);
+    if (!flags.out) {
+      // The brownfield case: the barrel is hand-maintained; leave the models alone.
+      note('Models were NOT rendered (--derived-out extracts the derived layer only; add --out to render models too).');
+      process.exit(0);
+    }
+  }
+  // With --derived-out, the embedded copy would duplicate every descriptor — the
+  // models output carries models only.
+  const embeddedDerived = derivedOut ? undefined : derived;
+
   let source: string;
   if (flags.out && !flags.out.endsWith('.ts')) {
     // 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 });
+    const files = renderModelFiles(current, { schema, abilities, derived: embeddedDerived });
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));
@@ -111,7 +182,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 });
+    source = renderModelSource(current, { schema, abilities, derived: embeddedDerived });
     try {
       await fs.mkdir(path.dirname(outPath), { recursive: true });
       await fs.writeFile(outPath, source, 'utf8');
@@ -121,12 +192,17 @@ 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 });
+    source = renderModelSource(current, { schema, abilities, derived: embeddedDerived });
     process.stdout.write(source);
     ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
   }
 
   const flagged = (source.match(/\/\/ (FIXME|TODO|composite|CHECK|FK →)/g) ?? []).length;
   if (flagged) caution(`${flagged} inline comment(s) flag things to review (unmapped types, checks, cross-schema FKs).`);
+  if (abilities === 'commented') {
+    note(`Each model scaffolds its authz decision as comments — author them (db:check fails until every model declares), or stamp the common case: db:pull --abilities public-read.`);
+  } else {
+    note(`Stamped '${abilities}' abilities into every model — review the generated stanzas; they are code, not defaults.`);
+  }
   process.exit(0);
 }