@everystack/cli 0.3.31 → 0.4.1

package/src/cli/index.ts

@@ -353,21 +353,21 @@ Usage:
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   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]  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)
-  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>]  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
+  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>] [--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      [--sql-dir db/sql] [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--json]  Reconcile the derived layer (functions/views/matviews) against db/sql sources: 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.
-  everystack db:sync           [--database-url <url>] [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against db/sql, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
+  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.
+  everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   everystack db:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed
   everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + a snapshot (automatic via db:backup with --stage, else --snapshot-ref) + the stage's approver set when declared (STS identity-verified). Every refusal is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there; direct connection required
-  everystack db:check          [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, db/sql parses), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
+  everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
   everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only
   everystack db:backfill       [--database-url <url>] [--dir db/backfills] [--apply] [--mark-applied <file.sql>] [--json]  One-shot data jobs in their own lane: plan shows applied (by CONTENT identity — renames/comment edits are no-ops) / pending (in order, unbounded-pass advisories) / blocked (a name that already ran in a different form — one-shot jobs are immutable). --apply runs each pending job as its own transaction, recorded in everystack.backfill_log (a failure rolls back alone, is recorded, stops the run); --mark-applied records without running. Never runs as a schema side effect; direct connection required
   everystack pipeline:run      [--stage <name> | --database-url <url>] [--rebuild | --curate] [--only <substr> | --from <id> | --to <id>] [--resume [--run-id <id>]] [--dry-run] [--continue-on-error] [--json]  Reproduce data from committed source: run the pipeline's stages in topological order, each idempotent and inside its own transaction, recorded in everystack.pipeline_log. Lanes: --rebuild (automated+frozen) / --curate (curated) / neither (all in order). --resume picks up the latest run, skipping applied stages. With --stage the orchestrator runs credential-free IN the ops Lambda (no URL held; heavy stages refused — run those local); --database-url is local-direct and unbounded
   everystack pipeline:list     [--rebuild | --curate] [--only <substr> | --from <id> | --to <id>]  Show the pipeline's stages in run order (topological) with their lane and dependency edges — no execution, no database
-  everystack db:template:refresh [--database-url <url>] [--models <barrel>] [--sql-dir db/sql] [--seed "<cmd>"] [--no-seed]  (Re)build the dev template <base>_tpl FROM THE DECLARED STATE (both layers, fingerprint MATCH bar) + seed-as-code (the app's db:seed script, run with DATABASE_URL pointed at the template; --seed overrides). All or nothing: a failed build/seed leaves NO template. Never a data copy
+  everystack db:template:refresh [--database-url <url>] [--models <barrel>] [--seed "<cmd>"] [--no-seed]  (Re)build the dev template <base>_tpl FROM THE DECLARED STATE (both layers, fingerprint MATCH bar) + seed-as-code (the app's db:seed script, run with DATABASE_URL pointed at the template; --seed overrides). All or nothing: a failed build/seed leaves NO template. Never a data copy
   everystack db:branch         [--list | --drop --confirm | --prune --confirm] [--database-url <url>]  Mint (or find) the current git branch's database from the template (CREATE DATABASE … TEMPLATE — schema, authz, derived layer, and seed rows inherited), print its DATABASE_URL, then db:sync evolves it with the checkout. --list maps every branch DB to its branch; --prune drops the ones whose branch is gone (never guesses: unknown mappings are kept)
   everystack db:fork           --from-stage <src> --stage <target> --confirm [--backup <id>]  Fork one DEPLOYED stage's database into another: back up the source (or reuse --backup <id>), presign the dump (the operator's credentials ARE the cross-stage authorization; expires in 1h), restore into the target via its ops Lambda. Production is never a target (that's db:restore); forking FROM production warns about PII; the branch's schema edge then lands via db:plan → db:apply (descent composes). Teardown: sst remove --stage <target>
   everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files

package/src/cli/migration-compile.ts

@@ -19,12 +19,13 @@
  * lands with whole-DB introspection. The emission is identical either way.
  */
 
-import type { ModelDescriptor, Module } from '@everystack/model';
+import type { ModelDescriptor, Module, SequenceDescriptor } from '@everystack/model';
 import type { AuthzContract, TableContract } from './authz-contract.js';
-import { compileCreateTable, compileEnums, foreignKeySql, modelConstraintSpecs, qualifiedTable, type CompileTableOptions } from './schema-compile.js';
+import { compileCreateTable, compileEnums, compileSequences, sequenceCreateSql, foreignKeySql, modelConstraintSpecs, qualifiedTable, toSnakeCase, type CompileTableOptions } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
 import { emitReconcileSql } from './authz-reconcile.js';
-import { emitSchemaSql, type SchemaChange } from './schema-diff.js';
+import { emitSchemaSql, nextvalSequence, type SchemaChange } from './schema-diff.js';
+import { compileDerived } from './derived-compile.js';
 
 /** The empty (not-yet-created) authz state for a table — the greenfield baseline. */
 function emptyTable(table: string): TableContract {
@@ -36,7 +37,7 @@ function emptyTable(table: string): TableContract {
  * schema). Tables, then foreign keys, then authz — the order a fresh database must
  * apply them in.
  */
-export function compileMigration(models: ModelDescriptor[], opts: CompileTableOptions = {}): string[] {
+export function compileMigration(models: ModelDescriptor[], opts: CompileTableOptions & { sequences?: SequenceDescriptor[] } = {}): string[] {
   const sql: string[] = [];
   const schemaOf = (m: ModelDescriptor): string => m.schema ?? 'public';
 
@@ -71,9 +72,24 @@ export function compileMigration(models: ModelDescriptor[], opts: CompileTableOp
   const enumCreates: SchemaChange[] = compileEnums(models).map((e) => ({ kind: 'createType', name: e.name, values: e.values }));
   sql.push(...emitSchemaSql(enumCreates));
 
+  // 0c. Standalone sequences — before any table, so a column's defaultSql(nextval(…))
+  //     can draw on one from the first CREATE. State layer: these migrate, never reconcile.
+  sql.push(...compileSequences(opts.sequences ?? []).map(sequenceCreateSql));
+
   // 1. Tables (with columns, CHECKs, single/composite PK, uniques).
   for (const model of models) sql.push(compileCreateTable(model, opts));
 
+  // 1b. Foreign-sequence defaults — a `defaultSql` nextval draws from a sequence that
+  //     may be owned by a table created later in phase 1, so fieldColumnSql held it out
+  //     of the column line; every table (and its serial sequence) exists now.
+  for (const model of models) {
+    for (const [name, f] of Object.entries(model.fields)) {
+      const spec = f.spec;
+      if (spec.defaultKind !== 'sql' || nextvalSequence(String(spec.default)) == null) continue;
+      sql.push(`ALTER TABLE ${qualifiedTable(model)} ALTER COLUMN "${toSnakeCase(name)}" SET DEFAULT ${String(spec.default)};`);
+    }
+  }
+
   // 2. Foreign keys — after every table exists.
   for (const model of models) sql.push(...foreignKeySql(model));
 
@@ -82,7 +98,12 @@ export function compileMigration(models: ModelDescriptor[], opts: CompileTableOp
   const indexCreates: SchemaChange[] = [];
   for (const model of models) {
     for (const ix of modelConstraintSpecs(model).indexes) {
-      indexCreates.push({ kind: 'createIndex', table: qualifiedTable(model), name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) });
+      indexCreates.push({
+        kind: 'createIndex', table: qualifiedTable(model), name: ix.name, columns: ix.columns, unique: ix.unique,
+        ...(ix.where ? { where: ix.where } : {}),
+        ...(ix.using ? { using: ix.using } : {}),
+        ...(ix.include?.length ? { include: ix.include } : {}),
+      });
     }
   }
   sql.push(...emitSchemaSql(indexCreates));
@@ -119,15 +140,25 @@ export function compileModuleMigration(modules: Module[], opts: CompileTableOpti
   const extensions = [...new Set(modules.flatMap((m) => m.extensions))].sort();
   sql.push(...extensions.map((e) => `CREATE EXTENSION IF NOT EXISTS "${e}";`));
 
-  // 2. Schema + authz for every modeled table.
-  sql.push(...compileMigration(modules.flatMap((m) => m.models), opts));
+  // 2. Schema + authz for every modeled table (plus the modules' standalone sequences).
+  sql.push(...compileMigration(modules.flatMap((m) => m.models), { ...opts, sequences: modules.flatMap((m) => m.sequences) }));
 
   // 3. Package SQL — functions + triggers, after the tables they reference. Each thunk's
   //    output is a self-contained multi-statement block applied as one unit.
+  //    (@deprecated — the declared derived layer below supersedes it.)
   for (const fn of modules.flatMap((m) => m.functions)) {
     const text = fn().trim();
     if (text) sql.push(text);
   }
 
+  // 4. The DECLARED derived layer — views, matviews, functions, triggers, escape-hatch
+  //    objects — compiled in topological order, after every table. Greenfield = one
+  //    complete script: state + compute; from then on the layer deploys via db:reconcile.
+  const models = modules.flatMap((m) => m.models);
+  for (const obj of compileDerived(models, modules.flatMap((m) => m.derived))) {
+    sql.push(`${obj.sql};`);
+    for (const a of obj.attachments) sql.push(`${a.sql};`);
+  }
+
   return sql;
 }

package/src/cli/migration-generate.ts

@@ -15,10 +15,10 @@
  * so the command shell (commands/db-generate.ts) is a thin layer of IO over it.
  */
 
-import type { ModelDescriptor } from '@everystack/model';
+import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
-import { compileTableSchema, compileRenames, compileTableRenames, compileCreateTable, compileEnums } from './schema-compile.js';
+import { compileTableSchema, compileRenames, compileTableRenames, compileCreateTable, compileEnums, compileSequences } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
 import { emitReconcileSql } from './authz-reconcile.js';
 import { diffSchema, emitSchemaSql, type SchemaChange } from './schema-diff.js';
@@ -26,6 +26,8 @@ import { diffSchema, emitSchemaSql, type SchemaChange } from './schema-diff.js';
 export interface GenerateOptions {
   /** The Postgres schema the Models live in. Default: `public`. */
   schema?: string;
+  /** Standalone sequences the modules declare (state layer — created before tables). */
+  sequences?: SequenceDescriptor[];
   /**
    * Emit real `DROP COLUMN`/`DROP CONSTRAINT`/`DROP TABLE` for things present in the
    * database but absent from the Models. Default `false` — those are held back as
@@ -104,7 +106,7 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   // then the call default — so one run spans schemas.
   const schemaOf = (m: ModelDescriptor): string => m.schema ?? schema;
   const desiredEnums = compileEnums(models);
-  const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema })), enums: desiredEnums };
+  const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema })), enums: desiredEnums, ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}) };
   const declaredTables = new Set(desired.tables.map((t) => t.table));
   const declaredEnums = new Set(desiredEnums.map((e) => e.name));
   // Scope both tables and enums to what the Models declare — an undeclared table OR enum
@@ -116,6 +118,18 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   // its authz contract must be read under the NEW name (the policies/grants
   // ride the rename in Postgres; without the rewrite they would re-emit and
   // collide).
+  // 0. Non-public schemas the models declare but the live side lacks — created FIRST, or
+  //    a fresh-database build (db:check's ephemeral compose, db:branch templates) fails on
+  //    its own first CREATE TABLE. The diff analog of compileMigration's phase 0a; live
+  //    databases already have their schemas (their own migrations made them), so this is
+  //    invisible in the brownfield loop. IF NOT EXISTS keeps an empty-but-existing schema
+  //    (no tables for the live side to reveal it by) from failing the create.
+  const liveSchemas = new Set(current.tables.map((t) => t.table.split('.')[0]));
+  const schemaPhase = [...new Set(desired.tables.map((t) => t.table.split('.')[0]))]
+    .filter((s) => s !== 'public' && !liveSchemas.has(s))
+    .sort()
+    .map((s) => `CREATE SCHEMA IF NOT EXISTS "${s}"`);
+
   const tableRenames = compileTableRenames(models, { schema });
   const currentNames = new Set(current.tables.map((t) => t.table));
   const pendingRenameSources = new Set(
@@ -177,7 +191,7 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
     ? emitReconcileSql({ tables: models.map((m) => compileTableContract(m, { schema })), functions: [] }, liveAuthzRenamed)
     : [];
 
-  return [...dataPhase, ...authzPhase];
+  return [...schemaPhase, ...dataPhase, ...authzPhase];
 }
 
 /** The marker drizzle migration files put between statements. */
@@ -200,6 +214,31 @@ export interface Journal {
   version: string;
   dialect: string;
   entries: JournalEntry[];
+  /**
+   * D2 — the resolved `--schema-out` path, recorded at generate time. Later runs
+   * without the flag reuse it (flag > recorded > default), so a relocated artifact
+   * never leaves an orphan at the default path. Drizzle's migrator ignores the key.
+   */
+  schemaOut?: string;
+}
+
+/** How a schema-out path was chosen, and whether the journal record needs (re)writing. */
+export interface SchemaOutResolution {
+  path: string;
+  source: 'flag' | 'recorded' | 'default';
+  updateRecord: boolean;
+}
+
+/**
+ * Resolve where the generated drizzle schema lives: an explicit flag wins, then the
+ * journal's recorded path, then the default. The record updates whenever the resolved
+ * path is not already recorded — a differing flag overwrites it (the caller says so).
+ */
+export function resolveSchemaOut(flag: string | undefined, journal: Journal | null, fallback: string): SchemaOutResolution {
+  const recorded = journal?.schemaOut;
+  if (flag) return { path: flag, source: 'flag', updateRecord: flag !== recorded };
+  if (recorded) return { path: recorded, source: 'recorded', updateRecord: false };
+  return { path: fallback, source: 'default', updateRecord: recorded !== fallback };
 }
 
 /** Sanitize a migration name into the snake_case the `NNNN_<tag>.sql` convention uses. */

package/src/cli/model-render.ts

@@ -16,6 +16,7 @@
  */
 
 import type { SchemaSnapshot, TableSchema, ColumnSchema, CheckConstraint } from './schema-introspect.js';
+import type { DerivedRenderResult } from './derived-render.js';
 import { normalizeDefault, normalizeCheck } from './schema-diff.js';
 
 /**
@@ -59,6 +60,47 @@ export function checkToValidate(expr: string): { column: string; zod: string } |
 export interface RenderOptions {
   /** Only pull tables in this Postgres schema (others are framework-managed). Default: `public`. */
   schema?: string;
+  /**
+   * The read-model scaffold. Default `'commented'`: every model carries the authz decision
+   * as a commented stanza (same guidance as the db:check gate — the model fails the gate
+   * until it is authored). A preset name (`'public-read'`) stamps that stanza uncommented
+   * into every rendered model — an explicit, one-shot, operator-invoked choice that lands
+   * as reviewable code. Grants are authored, never inherited; there is no runtime default.
+   */
+  abilities?: string;
+  /** The rendered derived layer (B5) — rides the barrel: block after the models,
+   *  sequences/derived arrays on the module wrapper, symbols on the import header. */
+  derived?: DerivedRenderResult;
+}
+
+/**
+ * The `--abilities` presets db:pull can stamp. Deliberately few: `public-read` is the
+ * dominant brownfield shape (public reference data, admin-managed). Anything else is a
+ * per-model edit — the decision belongs in the file, not in a flag grammar.
+ */
+export const ABILITY_PRESETS: Record<string, string> = {
+  'public-read': `abilities: [can('read'), can('manage', { role: 'admin' })],`,
+};
+
+/**
+ * The scaffold stanza for one model: the commented decision surface (guide text says the
+ * same thing the db:check gate failure says — one voice, two doorways), or a preset
+ * stamped uncommented. An unknown preset throws — grants are authored, never guessed.
+ */
+function abilitiesStanza(mode: string): string {
+  if (mode === 'commented') {
+    return [
+      '  // Declare the read model — db:check fails this model until its authz is authored:',
+      `  // abilities: [can('read')],                          // public data`,
+      `  // abilities: [can('read', { owner: '<column>' })],   // rows owned by a user`,
+      '  // private: true,                                     // not part of the data API',
+    ].join('\n');
+  }
+  const preset = ABILITY_PRESETS[mode];
+  if (!preset) {
+    throw new Error(`Unknown --abilities preset '${mode}' — known: ${Object.keys(ABILITY_PRESETS).join(', ')} (or omit the flag for the commented scaffold).`);
+  }
+  return `  ${preset}`;
 }
 
 /** `format_type` → the `field.*()` factory that produces it (the non-parameterized types). */
@@ -124,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;
@@ -210,8 +261,11 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
 
   if (col.default != null && !serial) {
     const d = renderDefault(col.default);
-    if (d) expr += d;
-    else comment += ` // TODO: unmapped default ${col.default}`;
+    // No builder maps it → declare it verbatim with the escape hatch. RAW, not the
+    // normalized form — stripping a trailing cast here could change semantics
+    // (`'7 days'::interval`); the diff normalizes both sides for comparison instead.
+    // Drift closed by construction: pull output converges instead of shedding a TODO.
+    expr += d ?? `.defaultSql(sql\`${col.default}\`)`;
   }
 
   const validate = validates.get(col.name);
@@ -236,8 +290,14 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
     items.push(`check(sql\`${normalizeCheck(ck.expr)}\`)`);
   }
   for (const ix of table.indexes) {
-    let s = `index(${ix.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`;
+    // Plain entries render as field keys; canonical-text entries (expressions, DESC,
+    // opclass) render as raw sql`` args — the same form the builder declares (Brick E).
+    const entry = (c: string): string =>
+      /^[a-z_][a-z0-9_$]*$/i.test(c) ? tsLiteral(toCamelCase(c)) : `sql\`${c}\``;
+    let s = `index(${ix.columns.map(entry).join(', ')})`;
+    if (ix.using) s += `.using(${tsLiteral(ix.using)})`;
     if (ix.unique) s += '.unique()';
+    if (ix.include?.length) s += `.include(${ix.include.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`;
     if (ix.where) s += `.where(sql\`${normalizeCheck(ix.where)}\`)`;
     items.push(s);
   }
@@ -261,7 +321,7 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
 }
 
 /** One `export const X = defineModel(...)` block for a table. */
-export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map()): string {
+export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map(), abilities = 'commented'): string {
   // A CHECK that reverses to a single field's .validate() is rendered on the field (ergonomic);
   // the rest stay table-level check(). Both round-trip — this only chooses the nicer form.
   const validates = new Map<string, string>();
@@ -275,23 +335,52 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
 
   const fields = table.columns.map((c) => renderField(table, c, known, enums, validates)).join('\n');
   const constraints = renderConstraintsBlock(table, tableChecks, known);
+  // The authz decision renders FIRST — before fields — because it is the first thing a
+  // reviewer must resolve about a model (and where the field-report consumer's codemod
+  // put it, proving the position is mechanical-edit-friendly).
+  const stanza = abilitiesStanza(abilities);
 
-  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n  fields: {\n${fields}\n  },${constraints}\n});`;
+  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza}\n  fields: {\n${fields}\n  },${constraints}\n});`;
 }
 
 /** The `import` lines a rendered body needs — only what it actually uses, so the file reads clean. */
-function importHeader(body: string): string {
+function importHeader(body: string, extra: string[] = []): string {
   const symbols = ['defineModel', 'field'];
+  // `can` only when a stanza is stamped UNCOMMENTED (line starts with spaces, not `//`) —
+  // the commented scaffold must not leave an unused import behind.
+  if (/^\s*abilities: \[can\(/m.test(body)) symbols.push('can');
   if (/\bunique\(/.test(body)) symbols.push('unique');
   if (/\bcheck\(/.test(body)) symbols.push('check');
   if (/\bindex\(/.test(body)) symbols.push('index');
   if (/\bforeignKey\(/.test(body)) symbols.push('foreignKey');
+  if (/\bdefineModule\(/.test(body)) symbols.push('defineModule');
   if (/\bsql`/.test(body)) symbols.push('sql');
+  for (const s of extra) if (!symbols.includes(s)) symbols.push(s);
   const imports = [`import { ${symbols.join(', ')} } from '@everystack/model';`];
   if (/\.validate\(/.test(body)) imports.push(`import { z } from 'zod';`);
   return imports.join('\n');
 }
 
+/** The barrel's module wrapper: models always; sequences/derived when the pull found any (B5). */
+function moduleFooter(modelNames: string[], derived?: DerivedRenderResult, multiline = false): string {
+  const models = multiline
+    ? `export const models = [\n${modelNames.map((n) => `  ${n},`).join('\n')}\n];`
+    : `export const models = [${modelNames.join(', ')}];`;
+  const parts = [models];
+  const keys = ['models'];
+  if (derived?.sequenceNames.length) {
+    parts.push(`export const sequences = [${derived.sequenceNames.join(', ')}];`);
+    keys.push('sequences');
+  }
+  if (derived?.names.length) {
+    parts.push(`export const derived = [${derived.names.join(', ')}];`);
+    keys.push('derived');
+  }
+  parts.push(`export const appModule = defineModule({ ${keys.join(', ')} });`);
+  parts.push(`export const modules = [appModule];`);
+  return parts.join('\n\n');
+}
+
 /**
  * Render a whole snapshot as a single Models module: the import, one block per table (scoped
  * to `opts.schema`), and the `models` array the rest of the framework consumes. The tables
@@ -303,17 +392,29 @@ export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions
   const known = new Set(tables.map((t) => bareName(t.table)));
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
-  const blocks = tables.map((t) => renderModelBlock(t, known, enums));
-  const body = blocks.join('\n\n');
+  const blocks = tables.map((t) => renderModelBlock(t, known, enums, opts.abilities ?? 'commented'));
+  // The derived layer (B5): sequences + views/matviews/functions, after the models they
+  // reference, before the module wrapper that composes all three.
+  if (opts.derived?.block) blocks.push(opts.derived.block);
+
+  // Module composition is the norm: the pulled barrel exports `modules` alongside `models`,
+  // so a fresh brownfield project lands on the same shape the framework composes.
+  const footer = moduleFooter(tables.map((t) => modelVarName(t.table)), opts.derived);
 
-  const header = importHeader(body);
-  const footer = `export const models = [${tables.map((t) => modelVarName(t.table)).join(', ')}];`;
+  const header = importHeader([...blocks, footer].join('\n\n'), opts.derived?.imports ?? []);
 
   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`;
 }
 
@@ -349,7 +450,7 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
   const files: RenderedModelFile[] = tables.map((t) => {
-    const block = renderModelBlock(t, known, enums);
+    const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented');
     const crossImports = referencedTables(t, known).map(
       (target) => `import { ${modelVarName(target)} } from './${bareName(target).replace(/_/g, '-')}';`,
     );
@@ -357,11 +458,19 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
     return { file: modelFileName(t.table), source: `${header}\n\n${block}\n` };
   });
 
+  // The index carries the module wrapper (composition is the norm) and the derived layer
+  // (B5 — it references the model variables the index imports); model files carry only
+  // their own model.
   const names = tables.map((t) => modelVarName(t.table));
+  const modelSymbols = ['defineModule', ...(opts.derived?.imports ?? [])];
   const index = [
-    names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`).join('\n'),
+    [
+      `import { ${modelSymbols.join(', ')} } from '@everystack/model';`,
+      ...names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`),
+    ].join('\n'),
     `export {\n${names.map((n) => `  ${n},`).join('\n')}\n};`,
-    `export const models = [\n${names.map((n) => `  ${n},`).join('\n')}\n];`,
+    ...(opts.derived?.block ? [opts.derived.block] : []),
+    moduleFooter(names, opts.derived, true),
   ].join('\n\n');
   files.push({ file: 'index.ts', source: index + '\n' });
 

package/src/cli/models-path.ts

@@ -1,7 +1,7 @@
 /**
  * models-path — where the Models barrel lives.
  *
- * One home for schema: `db/models/` (state) beside `db/sql/` (compute). The
+ * One home for schema: `db/models/` — state (tables) and compute (descriptors). The
  * CLI looks there first, falling back to the legacy top-level `models/` so
  * existing consumers keep working without a flag. An explicit `--models`
  * always wins. When neither home exists, the NEW home is returned so error

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/pipeline-path.ts

@@ -1,7 +1,7 @@
 /**
  * pipeline-path — where the consumer's pipeline definition lives.
  *
- * Beside the schema homes (`db/models/`, `db/sql/`, `db/backfills/`), the
+ * Beside the schema homes (`db/models/`, `db/backfills/`), the
  * pipeline is authored at `db/pipeline.ts` (or `db/pipeline/index.ts`),
  * exporting a `pipeline` built with definePipeline. An explicit `--pipeline`
  * always wins; when neither home exists the primary is returned so error