@everystack/cli 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -82,7 +82,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.0"
+    "@everystack/model": "0.4.1"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",

package/src/cli/aws.ts

@@ -6,6 +6,7 @@
  */
 
 import { isOpsHandlerCrash, extractCrashDiagnosis, formatOpsCrashReport } from './ops-diagnostics.js';
+import { tagInvokeTransport } from './ops-advice.js';
 
 let s3Client: InstanceType<typeof import('@aws-sdk/client-s3').S3Client> | null = null;
 let lambdaClient: InstanceType<typeof import('@aws-sdk/client-lambda').LambdaClient> | null = null;
@@ -262,6 +263,10 @@ export async function invokeAction(
   const invoke = (fnName: string) =>
     client.send(new InvokeCommand({ FunctionName: fnName, Payload: encoded }));
 
+  // A throw from the SDK means the Lambda NEVER RAN (credentials, permissions,
+  // network, missing function) — tagged as transport so the shells' IAM advice
+  // prints for THIS class only. A FunctionError below is the opposite: the
+  // handler ran and threw, and IAM advice would be a lie.
   let response;
   let invokedName = functionName;
   try {
@@ -272,7 +277,7 @@ export async function invokeAction(
     // then bust the stale cache so the next command discovers fresh.
     if (err && typeof err === 'object' && (err as { name?: string }).name === 'ResourceNotFoundException') {
       const live = await resolveFunctionName(region, functionName);
-      if (live === functionName) throw err;
+      if (live === functionName) throw tagInvokeTransport(err);
       try {
         const { invalidateCacheByFunctionName } = await import('./discover.js');
         await invalidateCacheByFunctionName(functionName);
@@ -280,9 +285,13 @@ export async function invokeAction(
         // Cache invalidation is best-effort
       }
       invokedName = live;
-      response = await invoke(live);
+      try {
+        response = await invoke(live);
+      } catch (err2: unknown) {
+        throw tagInvokeTransport(err2);
+      }
     } else {
-      throw err;
+      throw tagInvokeTransport(err);
     }
   }
 

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

@@ -15,8 +15,6 @@
  */
 
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import type { ModelDescriptor } from '@everystack/model';
 import {
   introspectContract,
   diffContracts,
@@ -47,6 +45,8 @@ import { resolveConfig, opsFunction } from '../config.js';
 import { resolveModelsPath } from '../models-path.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
+import { opsAdviceLines, IAM_ADVICE } from '../ops-advice.js';
+import { loadModels } from './db-generate.js';
 
 const DEFAULT_DIR = 'authz';
 
@@ -75,7 +75,7 @@ export async function dbAuthzPullCommand(flags: Record<string, string>): Promise
     contract = await introspectStage(flags);
   } catch (err: any) {
     fail(err.message);
-    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
     process.exit(1);
   }
 
@@ -207,20 +207,6 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
   process.exit(1);
 }
 
-/** Import the app's Model barrel and return its `models` array (runs under tsx, so TS imports work). */
-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 models = mod.models ?? mod.default;
-  if (!Array.isArray(models)) throw new Error(`${modelsPath} must export a \`models\` array (got ${typeof models}).`);
-  return models;
-}
-
 /**
  * `db:authz:owner` — the owner-aware red-team. Where `db:authz:test` proves grants (can a ROLE
  * do a command), this proves ISOLATION: can one user read or mutate another user's row? It is

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

@@ -31,8 +31,9 @@ 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 { loadDeclaredDerived, type DeclaredDerived } from '../declared-derived.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';
@@ -49,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;
 }
 
 /**
@@ -210,8 +217,10 @@ 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);
   }
 
@@ -233,12 +242,15 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   // 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('');
-    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.`);
     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);
   }
@@ -248,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);
@@ -298,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

@@ -1,7 +1,8 @@
 /**
  * `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>] [--abilities public-read]
+ *   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,19 +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 { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
-import { renderDerivedSource, type DerivedRenderResult } from '../derived-render.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).
@@ -51,6 +59,15 @@ 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';
@@ -92,8 +109,12 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     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);
   }
@@ -117,11 +138,34 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     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, abilities, derived });
+    const files = renderModelFiles(current, { schema, abilities, derived: embeddedDerived });
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));
@@ -138,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, abilities, derived });
+    source = renderModelSource(current, { schema, abilities, derived: embeddedDerived });
     try {
       await fs.mkdir(path.dirname(outPath), { recursive: true });
       await fs.writeFile(outPath, source, 'utf8');
@@ -148,7 +192,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, derived });
+    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).`);
   }

package/src/cli/commands/db.ts

@@ -8,6 +8,7 @@
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
+import { opsAdviceLines, IAM_ADVICE } from '../ops-advice.js';
 
 /** Secret-store keys that may hold the privileged (operator) connection URL,
  *  in precedence order. Names vary by deployment; --secret-name overrides. */
@@ -69,7 +70,7 @@ export async function dbMigrateCommand(flags: Record<string, string>): Promise<v
     }
   } catch (err: any) {
     fail(`Migration failed: ${err.message}`);
-    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
     process.exit(1);
   }
 }
@@ -105,7 +106,7 @@ export async function dbSeedCommand(flags: Record<string, string>): Promise<void
     }
   } catch (err: any) {
     fail(`Seed failed: ${err.message}`);
-    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
     process.exit(1);
   }
 }
@@ -138,7 +139,7 @@ export async function dbResetCommand(flags: Record<string, string>): Promise<voi
     success(result?.message || 'Database reset and migrations applied');
   } catch (err: any) {
     fail(`Reset failed: ${err.message}`);
-    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
     process.exit(1);
   }
 }
@@ -172,7 +173,7 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     result = await invokeAction(config.region, opsFunction(config), 'db:provision', { authPassword });
   } catch (err: any) {
     fail(`db:provision failed: ${err.message}`);
-    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
     process.exit(1);
   }
   if (result?.error) {
@@ -236,7 +237,7 @@ export async function dbDoctorCommand(flags: Record<string, string>): Promise<vo
     report = await invokeAction(config.region, opsFunction(config), 'db:doctor', {});
   } catch (err: any) {
     fail(`db:doctor failed: ${err.message}`);
-    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
     process.exit(1);
   }
 
@@ -327,7 +328,7 @@ export async function dbPsqlCommand(flags: Record<string, string>): Promise<void
       process.exit(0);
     } catch (err: any) {
       fail(`Query failed: ${err.message}`);
-      info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+      for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
       process.exit(1);
     }
   }

package/src/cli/commands/update.ts

@@ -8,6 +8,7 @@ import { spawn } from 'node:child_process';
 import { resolveConfig, type CliConfig } from '../config.js';
 import { uploadToS3, headS3, invokeAction } from '../aws.js';
 import { step, success, warn, fail, info } from '../output.js';
+import { opsAdviceLines, IAM_ADVICE } from '../ops-advice.js';
 import { exportApp } from '../utils/export.js';
 import { walkDirectory } from '../utils/walk.js';
 import { loadSstSecrets } from '../utils/secrets.js';
@@ -301,7 +302,7 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
         }
       } catch (err: any) {
         fail(`Registration failed for ${platform}: ${err.message}`);
-        info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+        for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
         process.exit(1);
       }
     }

package/src/cli/declared-derived.ts

@@ -16,6 +16,7 @@ import { compileDerived } from './derived-compile.js';
 import { compileTableRenames } from './schema-compile.js';
 import type { SourceObject } from './derived-source.js';
 import { resolveModelsPath } from './models-path.js';
+import { asModelComposeError } from './ops-advice.js';
 
 export interface DeclaredDerived {
   /** Descriptor-compiled derived objects, in dependency order. */
@@ -28,19 +29,44 @@ export interface DeclaredDerived {
   renamedTables: Record<string, string>;
 }
 
-/** Barrel → normalized Module list (a bare `models` export wraps into one module). */
+/**
+ * The loud undefined gate at the barrel boundary: a bare `export const models = [...]`
+ * never passes through defineModule, so a missing named import (undefined under CJS
+ * interop) survives to the loader. Name the file, the list, and the index here.
+ */
+export function assertNoHoles(source: string, listName: string, list: readonly unknown[]): void {
+  list.forEach((entry, i) => {
+    if (entry == null) {
+      throw new Error(`${source}: ${listName}[${i}] is ${entry === undefined ? 'undefined' : 'null'} — renamed or missing import?`);
+    }
+  });
+}
+
+/** Barrel → normalized Module list (a bare `models` export wraps into one module).
+ *  Every failure here is the operator's own barrel — thrown as ModelComposeError so
+ *  the command shells never dress it as an IAM/Lambda problem. */
 export async function loadModulesFrom(modelsPath: string): Promise<Module[]> {
-  const abs = path.resolve(modelsPath);
-  let mod: any;
   try {
-    mod = await import(pathToFileURL(abs).href);
-  } catch (err: any) {
-    throw new Error(`Could not load modules 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 modules from ${modelsPath}: ${err.message}`);
+    }
+    if (Array.isArray(mod.modules)) {
+      assertNoHoles(modelsPath, 'modules', mod.modules);
+      return mod.modules;
+    }
+    const models = mod.models ?? mod.default;
+    if (Array.isArray(models)) {
+      assertNoHoles(modelsPath, 'models', models);
+      return [{ models, extensions: [], sequences: [], derived: [], functions: [] }];
+    }
+    throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
+  } catch (err) {
+    throw asModelComposeError(modelsPath, err);
   }
-  if (Array.isArray(mod.modules)) return mod.modules;
-  const models = mod.models ?? mod.default;
-  if (Array.isArray(models)) return [{ models, extensions: [], sequences: [], derived: [], functions: [] }];
-  throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
 }
 
 /**
@@ -125,12 +151,23 @@ export async function loadDeclaredDerived(modelsFlag?: string): Promise<Declared
     return null;
   }
   const modules = await loadModulesFrom(modelsPath);
-  const models = modules.flatMap((m) => m.models);
-  const derived = modules.flatMap((m) => m.derived);
-  return {
-    objects: compileDerived(models, derived),
-    derived,
-    sequences: modules.flatMap((m) => m.sequences),
-    renamedTables: compileTableRenames(models, {}),
-  };
+  return composeDeclaredDerived(modules, modelsPath);
+}
+
+/** The pure compose half of {@link loadDeclaredDerived} — every gate failure in the
+ *  compile (holes, reachability, cycles, undeclared trigger functions) is the
+ *  operator's own declaration, wrapped as ModelComposeError naming the barrel. */
+export function composeDeclaredDerived(modules: Module[], modelsPath: string): DeclaredDerived {
+  try {
+    const models = modules.flatMap((m) => m.models);
+    const derived = modules.flatMap((m) => m.derived);
+    return {
+      objects: compileDerived(models, derived),
+      derived,
+      sequences: modules.flatMap((m) => m.sequences),
+      renamedTables: compileTableRenames(models, {}),
+    };
+  } catch (err) {
+    throw asModelComposeError(modelsPath, err);
+  }
 }

package/src/cli/derived-compile.ts

@@ -192,6 +192,50 @@ function derivedIdentity(d: DerivedDescriptor): string {
   return `${schema}.${name}`;
 }
 
+/** What a bad ref IS, for the gate's message — null if the value is a usable object. */
+function badRef(r: unknown): string | null {
+  if (r === undefined) return 'undefined';
+  if (r === null) return 'null';
+  if (typeof r !== 'object') return `not a descriptor (${typeof r})`;
+  return null;
+}
+
+/**
+ * The loud undefined gate — every list compileDerived walks, checked up front. The
+ * message shape mirrors the define-time gate in @everystack/model: owner, list,
+ * index, and the likely cause (a missing named import evaluates to undefined).
+ */
+function rejectBadRefs(models: readonly ModelDescriptor[], derived: readonly DerivedDescriptor[]): void {
+  const hole = (context: string, listName: string, list: readonly unknown[], indexed = true): void => {
+    list.forEach((entry, i) => {
+      const bad = badRef(entry);
+      if (bad) throw new Error(`${context}: ${listName}${indexed ? `[${i}]` : ''} is ${bad} — renamed or missing import?`);
+    });
+  };
+  hole('compileDerived', 'models', models);
+  hole('compileDerived', 'derived', derived);
+  for (const d of derived) {
+    hole(`${d.kind} '${d.name}'`, 'dependsOn', d.dependsOn ?? []);
+    if (d.kind === 'function' && typeof d.returns !== 'string') {
+      hole(`function '${d.name}'`, 'returns.setof', [d.returns.setof], false);
+    }
+  }
+  const triggerOwners = [
+    ...models.map((m) => ({ owner: `${m.schema}.${m.table}`, triggers: m.triggers ?? [] })),
+    ...derived.filter((d): d is ViewDescriptor => d.kind === 'view').map((v) => {
+      const q = parseQualified(v.name);
+      return { owner: `${q.schema}.${q.name}`, triggers: v.triggers ?? [] };
+    }),
+  ];
+  for (const { owner, triggers } of triggerOwners) {
+    hole(owner, 'triggers', triggers);
+    for (const t of triggers) {
+      const bad = badRef(t.execute);
+      if (bad) throw new Error(`trigger '${t.name}' on ${owner}: execute is ${bad} — renamed or missing import?`);
+    }
+  }
+}
+
 function make(kind: SourceObject['kind'], rawName: string, sql: string, attachments: Attachment[], extra: Partial<SourceObject> = {}): (seq: number) => SourceObject {
   const { schema, name } = parseQualified(rawName);
   return (seq) => ({
@@ -210,6 +254,12 @@ function make(kind: SourceObject['kind'], rawName: string, sql: string, attachme
  * the derived set — a trigger cannot draw on a function nothing declares.
  */
 export function compileDerived(models: readonly ModelDescriptor[], derived: readonly DerivedDescriptor[]): SourceObject[] {
+  // The loud undefined gate, compile-side. Define-time already rejects holes, but
+  // hand-rolled descriptors and a stale @everystack/model can carry them here — so a
+  // bad ref is a HARD error naming the descriptor and index, never a silent drop
+  // (the old non-object filter dropped the edge and let the lint crash on it later).
+  rejectBadRefs(models, derived);
+
   // Invoker-view reachability is a COMPILE fail (B2): a granted-but-unreadable view is
   // structurally broken — every verb that consumes descriptors refuses, not just db:check.
   const unreachable = findInvokerReachabilityGaps(derived);
@@ -220,9 +270,9 @@ export function compileDerived(models: readonly ModelDescriptor[], derived: read
   const identities = new Set(derived.map(derivedIdentity));
   const nodes: Node[] = [];
 
-  const depIdentities = (refs: readonly unknown[]): string[] =>
+  const depIdentities = (refs: readonly DependsOnRef[]): string[] =>
     refs
-      .filter((r): r is DerivedDescriptor => typeof r === 'object' && r != null && !('table' in (r as object)))
+      .filter((r): r is DerivedDescriptor => !('table' in r))
       .map((r) => derivedIdentity(r))
       .filter((id) => identities.has(id));
 

package/src/cli/derived-render.ts

@@ -16,6 +16,7 @@
 import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
 import type { SequenceSchema } from './schema-introspect.js';
 import { parseIndexDefinition } from './schema-introspect.js';
+import { modelFileName } from './model-render.js';
 
 export interface DerivedRenderResult {
   /** The source block: `export const … = defineView(…)` etc., dependency-ordered. */
@@ -26,6 +27,9 @@ export interface DerivedRenderResult {
   sequenceNames: string[];
   /** Model-package symbols the block uses (defineView, can, sql, arg, index, …). */
   imports: string[];
+  /** Qualified tables the block references through knownTables — what a standalone
+   *  derived file must import (sorted). */
+  modelRefs: string[];
   /** Everything skipped or flagged — mirrored as FIXME comments in the block. */
   warnings: string[];
 }
@@ -39,6 +43,12 @@ export interface DerivedRenderOptions {
 
 const PLAIN_IDENT = /^[a-z_][a-z0-9_$]*$/;
 
+/**
+ * Derived symbols are camelCase VERBATIM — never singularized (deliberately distinct
+ * from modelVarName's rule; a matview named `user_sessions` is `userSessions`).
+ * NAMING CONTRACT — a rename here breaks consumer splices; pinned by
+ * naming-contract.test.ts.
+ */
 function toCamelCase(name: string): string {
   return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
 }
@@ -186,6 +196,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
 
   // -- per-object rendering ----------------------------------------------------
 
+  const modelRefs = new Set<string>();
   const depsFor = (identity: string): { refs: string[]; fixmes: string[] } => {
     const refs: string[] = [];
     const fixmes: string[] = [];
@@ -195,8 +206,10 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       seen.add(e.referenced);
       const model = opts.knownTables.get(e.referenced);
       const derived = varOf.get(e.referenced);
-      if (model) refs.push(model);
-      else if (derived) refs.push(derived);
+      if (model) {
+        refs.push(model);
+        modelRefs.add(e.referenced);
+      } else if (derived) refs.push(derived);
       else fixmes.push(`// FIXME: dependsOn ${e.referenced} — not in the pulled set; declare it by hand.`);
     }
     return { refs: refs.sort(), fixmes };
@@ -315,6 +328,39 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     names,
     sequenceNames,
     imports: [...used].sort(),
+    modelRefs: [...modelRefs].sort(),
     warnings,
   };
 }
+
+/**
+ * The standalone derived module — `db:pull --derived-out <file>` (the brownfield
+ * splice, first-class). A consumer with an existing hand-maintained barrel wants the
+ * derived layer as its OWN file, not spliced out of a rendered monolith by hand: this
+ * renders exactly the shape their module wires — model-package imports, model-var
+ * imports from the contract kebab files (naming-contract.test.ts), the descriptors,
+ * and the `sequences`/`derived` arrays for `defineModule({ models, sequences, derived })`.
+ */
+export function renderDerivedFile(result: DerivedRenderResult, knownTables: Map<string, string>): string {
+  const lines: string[] = [
+    '// Derived layer (views, materialized views, functions, sequences) — rendered by `everystack db:pull`.',
+    '// Bodies are the catalog\'s canonical deparse (they never match an authored spelling byte-for-byte);',
+    '// commit, wire it on your module — defineModule({ models, sequences, derived }) — then adopt with',
+    '// `db:reconcile --apply --baseline` (or --rebaseline over db/sql-era provenance). docs/derived-objects.md.',
+  ];
+  if (result.imports.length) {
+    lines.push(`import { ${result.imports.join(', ')} } from '@everystack/model';`);
+  }
+  const refs = result.modelRefs
+    .map((table) => ({ varName: knownTables.get(table)!, path: `./${modelFileName(table).replace(/\.ts$/, '')}` }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  for (const ref of refs) lines.push(`import { ${ref.varName} } from '${ref.path}';`);
+  lines.push('', result.block, '');
+  if (result.sequenceNames.length) {
+    lines.push(`export const sequences = [\n${result.sequenceNames.map((n) => `  ${n},`).join('\n')}\n];`);
+  }
+  if (result.names.length) {
+    lines.push(`export const derived = [\n${result.names.map((n) => `  ${n},`).join('\n')}\n];`);
+  }
+  return lines.join('\n') + '\n';
+}

package/src/cli/edge-plan.ts

@@ -29,7 +29,7 @@ import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
 import { generateMigrationSql, unmodeledTables } from './migration-generate.js';
-import { classifyGeneratedStatements, classifyDestructive } from './state-apply.js';
+import { classifyGeneratedStatements, classifyDestructive, renderStatementHistogram } from './state-apply.js';
 import { fingerprintLive, fingerprintState, fingerprintModels, stableStringify } from './schema-fingerprint.js';
 import { compileDeclaredState } from './declared-diff.js';
 import { compileTableRenames } from './schema-compile.js';
@@ -202,6 +202,9 @@ export function buildPlanSummary(plan: EdgePlan): string[] {
     return lines;
   }
   lines.push(`${plan.executable} executable statement(s), ${plan.notices} notice(s)`);
+  // The shape first — a four-digit edge is reviewable as a histogram, not a wall.
+  const histogram = renderStatementHistogram(classifyGeneratedStatements(plan.statements).executable);
+  if (histogram) lines.push(`shape: ${histogram}`);
   if (plan.destructive > 0) {
     const { drops, narrowings } = classifyDestructive(classifyGeneratedStatements(plan.statements).executable);
     lines.push(

package/src/cli/index.ts

@@ -354,7 +354,7 @@ Usage:
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
-  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default
+  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (direct connection only, atomic — DDL + provenance in one transaction) and records provenance + schema_log. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive.

package/src/cli/model-render.ts

@@ -166,7 +166,16 @@ export function pullableTables(snapshot: SchemaSnapshot, schema: string): TableS
   return snapshot.tables.filter((t) => t.table.startsWith(`${schema}.`) && !INFRASTRUCTURE_TABLES.has(bareName(t.table)));
 }
 
-/** A table name → its model variable: PascalCase, naively singularized. `image_variants` → `ImageVariant`. */
+/**
+ * A table name → its model variable: PascalCase, naively singularized (one trailing
+ * `s` strips, whatever the word). `image_variants` → `ImageVariant`.
+ *
+ * NAMING CONTRACT — changing this rule is a BREAKING CHANGE. Consumer barrels build
+ * on the rendered symbols (derived dependsOn refs, cross-file FK imports, index
+ * re-exports); a rename here breaks every brownfield splice on the next pull. The
+ * exact vocabulary — including the naive `status` → `Statu` and the singular/plural
+ * collision — is pinned by naming-contract.test.ts.
+ */
 export function modelVarName(table: string): string {
   const bare = bareName(table);
   const singular = bare.endsWith('s') ? bare.slice(0, -1) : bare;
@@ -177,7 +186,7 @@ export function modelVarName(table: string): string {
  * `author_id` → `authorId` — a SQL column to its field key, LOSSLESSLY: the compiler's
  * snake_case must reconstruct the exact column (`snake(key) === column`, always). Only a
  * letter after `_` camelizes, because only a capital letter survives the trip back — an
- * underscore before a digit is preserved (`yardline_100` stays `yardline_100`,
+ * underscore before a digit is preserved (`percentile_100` stays `percentile_100`,
  * `top_3_best` → `top_3Best`). Swallowing it (the old `_([a-z0-9])` rule) generated a
  * phantom rename for every digit-boundary column and COLLIDED distinct columns
  * (`a_1` and `a1`) onto one key.
@@ -397,8 +406,15 @@ export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions
   return [header, ...blocks, footer].join('\n\n') + '\n';
 }
 
-/** `image_variants` → `image-variants.ts` — the repo's kebab-case file convention. */
-function modelFileName(table: string): string {
+/**
+ * `image_variants` → `image-variants.ts` — kebab of the bare table, NEVER singularized
+ * (the file carries the table name, greppable against the database; the var carries
+ * the singularized model name — the two disagree on number, on purpose).
+ *
+ * NAMING CONTRACT — changing this rule is a BREAKING CHANGE: index.ts and cross-file
+ * FK imports reference these paths. Pinned by naming-contract.test.ts.
+ */
+export function modelFileName(table: string): string {
   return `${bareName(table).replace(/_/g, '-')}.ts`;
 }
 

package/src/cli/ops-advice.ts

@@ -0,0 +1,66 @@
+/**
+ * Bimodal failure advice — which advice a command shell may print after `fail()`.
+ *
+ * The failure taxonomy behind every deployed-stage verb has exactly three classes,
+ * and the advice must match the class (a model-compose error dressed as an IAM
+ * problem sends the operator to AWS for a typo in their own models file):
+ *
+ *   - MODEL COMPOSE — the barrel failed to load, or the descriptors failed a
+ *     define/compile gate. Thrown as {@link ModelComposeError} by the loaders.
+ *     Advice: fix the models file. Never mention IAM.
+ *   - INVOKE TRANSPORT — the AWS SDK threw before the Lambda ran (credentials,
+ *     permissions, network, missing function). Tagged by `invokeAction` via
+ *     {@link tagInvokeTransport}. Advice: the classic IAM line.
+ *   - EVERYTHING ELSE — the Lambda RAN and returned an error, a SQL statement
+ *     failed, a local connection refused. No advice; the message is the truth.
+ *
+ * Pure (printer-agnostic): shells print the returned lines with their own channel —
+ * `info` for report commands, stderr `detail` for codegen commands like db:pull.
+ */
+
+/** The classic transport advice line — callers compose extras around it. */
+export const IAM_ADVICE = 'Ensure your IAM user/role has lambda:InvokeFunction permission.';
+
+/** A failure in the operator's OWN declared models — load or compose. */
+export class ModelComposeError extends Error {
+  readonly modelsPath: string;
+  constructor(modelsPath: string, cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.name = 'ModelComposeError';
+    this.modelsPath = modelsPath;
+    if (cause instanceof Error && cause.stack) this.stack = cause.stack;
+  }
+}
+
+/** Wrap as compose unless already wrapped (nesting would bury the models path). */
+export function asModelComposeError(modelsPath: string, err: unknown): ModelComposeError {
+  return err instanceof ModelComposeError ? err : new ModelComposeError(modelsPath, err);
+}
+
+const INVOKE_TRANSPORT = Symbol.for('everystack.invokeTransport');
+
+/** Mark an error as thrown by the AWS transport — the Lambda never ran. */
+export function tagInvokeTransport<T>(err: T): T {
+  if (typeof err === 'object' && err !== null) {
+    (err as Record<symbol, unknown>)[INVOKE_TRANSPORT] = true;
+  }
+  return err;
+}
+
+export function isInvokeTransport(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as Record<symbol, unknown>)[INVOKE_TRANSPORT] === true;
+}
+
+/**
+ * The advice for a failure, by class: compose → the models file; transport → the
+ * caller's IAM lines; anything else → nothing.
+ */
+export function opsAdviceLines(err: unknown, iamLines: readonly string[]): string[] {
+  if (err instanceof ModelComposeError) {
+    return [
+      `The failure is in your declared models — fix ${err.modelsPath}. Nothing was invoked in AWS.`,
+    ];
+  }
+  if (isInvokeTransport(err)) return [...iamLines];
+  return [];
+}

package/src/cli/state-apply.ts

@@ -87,6 +87,54 @@ export function classifyDestructive(executable: string[]): DestructiveBreakdown
   return { drops, narrowings };
 }
 
+/**
+ * The kind histogram — what a plan IS, before anyone reads its SQL. A real edge can
+ * run to four digits of statements (a consumer's adoption edge was 1,671), and the
+ * reviewable fact is the shape: how many policies, grants, RLS toggles, tables. The
+ * kind is decided by the first non-comment line, so WARNING prologues don't hide it.
+ */
+const KIND_MATCHERS: Array<[RegExp, string]> = [
+  [/ROW LEVEL SECURITY/, 'rls'],
+  [/^(CREATE|DROP|ALTER)\s+POLICY\b/, 'policies'],
+  [/^(GRANT|REVOKE)\b/, 'grants'],
+  [/^CREATE\s+TABLE\b/, 'create table'],
+  [/^DROP\s+TABLE\b/, 'drop table'],
+  [/^ALTER\s+TABLE\b/, 'alter table'],
+  [/^(CREATE\s+(UNIQUE\s+)?INDEX|DROP\s+INDEX|ALTER\s+INDEX)\b/, 'indexes'],
+  [/^(CREATE|ALTER|DROP)\s+SEQUENCE\b/, 'sequences'],
+  [/^CREATE\s+EXTENSION\b/, 'extensions'],
+  [/^(CREATE|ALTER|DROP)\s+TYPE\b/, 'types'],
+  [/^COMMENT\s+ON\b/, 'comments'],
+];
+
+function statementKind(statement: string): string {
+  const first = statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? '';
+  const s = first.trim().toUpperCase();
+  for (const [re, kind] of KIND_MATCHERS) {
+    if (re.test(s)) return kind;
+  }
+  return 'other';
+}
+
+/** Bucket executable statements by kind — largest bucket first, ties by name. */
+export function histogramStatements(executable: string[]): Array<{ kind: string; count: number }> {
+  const counts = new Map<string, number>();
+  for (const statement of executable) {
+    const kind = statementKind(statement);
+    counts.set(kind, (counts.get(kind) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([kind, count]) => ({ kind, count }))
+    .sort((a, b) => b.count - a.count || a.kind.localeCompare(b.kind));
+}
+
+/** The one-line rendering (`402 policies, 398 grants, 201 rls, …`); null when empty. */
+export function renderStatementHistogram(executable: string[]): string | null {
+  const kinds = histogramStatements(executable);
+  if (kinds.length === 0) return null;
+  return kinds.map(({ kind, count }) => `${count} ${kind}`).join(', ');
+}
+
 /** The current git HEAD, for schema_log's intent pointer. Null outside a repo. */
 export function currentGitRef(): string | null {
   try {