@everystack/cli 0.4.43 → 0.4.44

package/package.json

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

package/src/cli/authz-compile.ts

@@ -66,7 +66,11 @@ function claimExpr(claim: string): string {
  *   uuid: (author_id = (((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))::uuid)
  *   text: (user_id   =  ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))
  */
-function ownerPredicate(sqlColumn: string, type: string, claim: string): string {
+function ownerPredicate(sqlColumn: string, type: string, claim: string, expr: string | null = null): string {
+  // A declared `ownerExpr` is the accessor the database already has (`auth.user_id()`),
+  // emitted verbatim and uncast: the function returns the owner column's type, and a cast
+  // the deparser would not print is a DROP + CREATE on every owner policy in the schema.
+  if (expr) return `(${sqlColumn} = ${expr})`;
   const ce = claimExpr(claim);
   if (type === 'text') return `(${sqlColumn} = ${ce})`;
   return `(${sqlColumn} = (${ce})::${castForType(type)})`;
@@ -89,7 +93,7 @@ function softDeleteGuard(sqlColumn: string): string {
  *     WHERE (uploads.user_id = ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))))
  */
 function viaPredicate(v: ViaRef): string {
-  const parentOwner = ownerPredicate(`${v.parentTable}.${v.parentOwner.sqlColumn}`, v.parentOwner.type, v.parentOwner.claim);
+  const parentOwner = ownerPredicate(`${v.parentTable}.${v.parentOwner.sqlColumn}`, v.parentOwner.type, v.parentOwner.claim, v.parentOwner.expr);
   return `(${v.fkColumn} IN ( SELECT ${v.parentTable}.${v.parentPk}\n   FROM ${v.parentTable}\n  WHERE ${parentOwner}))`;
 }
 
@@ -103,6 +107,8 @@ interface OwnerRef {
   type: string;
   /** JWT claim holding the owner id. */
   claim: string;
+  /** A declared accessor for the caller's id (`auth.user_id()`), or null for the inline claim. */
+  expr: string | null;
 }
 
 /**
@@ -135,6 +141,7 @@ function resolveOwner(model: ModelDescriptor): OwnerRef | null {
     sqlColumn: toSnakeCase(fieldKey),
     type: model.fields[fieldKey]?.spec.type ?? 'uuid',
     claim: ownerAbility.condition.userField ?? 'sub',
+    expr: rawExpr(ownerAbility.condition.ownerExpr, `${model.table}: can({ ownerExpr })`),
   };
 }
 
@@ -244,6 +251,23 @@ function rawPredicate(value: unknown, where: string): string | null {
   return parenthesizeOnce(text.trim());
 }
 
+/**
+ * Unwrap a sql fragment to its text, UNparenthesized — for an expression that is not a
+ * predicate. `ownerExpr` is the right-hand side of `<col> = …`; parenthesizing it would
+ * emit `(user_id = (auth.user_id()))`, which is not what the deparser prints, and the
+ * whole point of declaring it is to match the live text exactly.
+ */
+function rawExpr(value: unknown, where: string): string | null {
+  if (value == null) return null;
+  const text = (value as { sql?: unknown }).sql;
+  if (typeof text !== 'string' || !text.trim()) {
+    throw new Error(
+      `${where}: expected a sql\`…\` fragment (import { sql } from '@everystack/model'), got ${typeof value}. A bare string is rejected on purpose — the expression that decides who owns a row is authored, never stringly assembled.`,
+    );
+  }
+  return text.trim();
+}
+
 /** AND-compose predicates, dropping the vacuous ones. A condition only ever NARROWS. */
 function andPredicates(...parts: (string | null)[]): string | null {
   const real = parts.filter((p): p is string => Boolean(p) && p !== '(true)' && p !== 'true');
@@ -270,7 +294,7 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // parent subquery. Both drive the same owner-gated policies (select/insert/
   // update/delete_own); only the predicate text differs.
   const rowPred = owner
-    ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim)
+    ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim, owner.expr)
     : via
       ? viaPredicate(via)
       : null;
@@ -298,6 +322,33 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     }
     return null;
   };
+  /**
+   * The predicate on the PUBLIC read — a read ability with neither a role nor a row scope.
+   *
+   * Read separately from {@link ownerReadPred} because the two are different BRANCHES of
+   * the same authenticated policy. Taking both from one ordered lookup made the anon
+   * policy depend on the order the abilities happened to be declared in: put the owner
+   * read first and `anon` inherited the owner branch's guard as its whole public rule.
+   */
+  const publicReadPred = (): string | null => {
+    for (const a of model.abilities) {
+      if (a.action !== 'read' || a.condition.role || rowScoped(a)) continue;
+      const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('read')`);
+      if (p) return p;
+    }
+    return null;
+  };
+
+  /** The predicate the OWNER read narrows ITSELF by — `can('read', { owner, sql })`. */
+  const ownerReadPred = (): string | null => {
+    for (const a of model.abilities) {
+      if (a.action !== 'read' || !rowScoped(a) || isColumnRead(a)) continue;
+      const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('read', { owner })`);
+      if (p) return p;
+    }
+    return null;
+  };
+
   /** The WRITE half, when the author declared one distinct from the read half. */
   const checkFor = (action: Ability['action']): string | null => {
     for (const a of model.abilities) {
@@ -334,18 +385,37 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   if (hasPublicRead) {
     // public read on a soft-delete table — split per role; authenticated owners
     // also see their own (soft-deleted) rows, hence the OR'd owner check.
-    const readPred = predFor('read');
+    const readPred = publicReadPred();
     const anonUsing = andPredicates(sdGuard, readPred) ?? 'true';
     policy(`${t}_select_anon`, 'SELECT', ['anon'], anonUsing, null);
 
-    // The owner predicate may only ever WIDEN a public read (the soft-delete OR:
-    // owners also see their own deleted rows). It must never REPLACE it — an owner
-    // condition on a WRITE ability used to narrow the authenticated SELECT to
-    // own-rows-only, so anon saw the whole table and a signed-in user lost it.
-    // Without a soft-delete guard, `true OR owner` is just `true`.
-    const authedUsing = sdGuard && rowPred
-      ? andPredicates(`(${sdGuard} OR ${rowPred})`, readPred)!
-      : anonUsing;
+    let authedUsing: string;
+    if (hasOwnerRead && rowPred && anonUsing !== 'true') {
+      // PUBLIC **OR** MINE. Two read abilities on one model — a public read and an
+      // owner read — are two branches of one authenticated policy, not a contest the
+      // public one wins. They used to be exactly that contest: `hasPublicRead` took
+      // the branch and the owner read was computed and discarded, so a signed-in
+      // author could not see their own non-public rows. On a real brownfield schema
+      // that hid ~13k legacy `pending` rows from the people who wrote them.
+      //
+      // The owner branch escapes the public predicate (that is the whole point) and
+      // carries its OWN guard — `can('read', { owner: 'userId', sql: … })` — so the
+      // author says what "mine" means without loosening what "public" means.
+      const ownBranch = andPredicates(rowPred, ownerReadPred())!;
+      authedUsing = `(${anonUsing} OR ${ownBranch})`;
+    } else {
+      // The owner predicate may only ever WIDEN a public read (the soft-delete OR:
+      // owners also see their own deleted rows). It must never REPLACE it — an owner
+      // condition on a WRITE ability used to narrow the authenticated SELECT to
+      // own-rows-only, so anon saw the whole table and a signed-in user lost it.
+      // Without a soft-delete guard, `true OR owner` is just `true` — and an
+      // unfiltered public read already contains every row an owner could add, which
+      // is why `anonUsing === 'true'` skips the disjunction rather than emitting a
+      // branch that can never change the answer.
+      authedUsing = sdGuard && rowPred
+        ? andPredicates(`(${sdGuard} OR ${rowPred})`, readPred)!
+        : anonUsing;
+    }
     policy(`${t}_select_authenticated`, 'SELECT', ['authenticated'], authedUsing, null);
   } else if (hasOwnerRead && rowPred) {
     // owner-scoped read — no anon visibility; you see only the rows you own

package/src/cli/authz-derive.ts

@@ -65,11 +65,120 @@ const KNOWN_ROLES = new Set(['anon', 'authenticated', 'admin']);
 const OWNER_RE =
   /^\(?([a-z_][a-z0-9_]*)\s*=\s*\(*\(current_setting\('request\.jwt\.claims'::text,\s*true\)\)::jsonb\s*->>\s*'([a-z_]+)'::text\)*(?:::[a-z]+)?\)?$/i;
 
-/** Does this predicate say "the row is mine"? Returns the column and the claim if so. */
-export function parseOwnerPredicate(pred: string | null): { column: string; claim: string } | null {
+/**
+ * The OTHER owner shape: the database's own accessor, `(<col> = auth.user_id())`.
+ *
+ * A brownfield schema almost always has one — a STABLE SECURITY DEFINER function wrapping
+ * the same claim read — and every owner policy in it is written against that function, not
+ * against the claim inline. Rendering those as the inline claim would be a semantically
+ * similar but TEXTUALLY different predicate, and predicates are diffed as text: it would
+ * plan a DROP + CREATE on every owner policy in the schema.
+ *
+ * Deliberately narrow: the right side must be a zero-argument function call. That is what
+ * an "who am I" accessor looks like, and it is what a column-to-column comparison
+ * (`(user_id = reviewer_id)`) is not — so the matcher cannot mistake a join predicate for
+ * a statement of ownership.
+ */
+const OWNER_FN_RE = /^\(?([a-z_][a-z0-9_]*)\s*=\s*((?:[a-z_][a-z0-9_]*\.)?[a-z_][a-z0-9_]*\(\))\)?$/i;
+
+/**
+ * Does this predicate say "the row is mine"? Returns the column, the claim, and the
+ * accessor expression when the schema uses one (null = the claim read inline).
+ */
+export function parseOwnerPredicate(
+  pred: string | null,
+): { column: string; claim: string; expr: string | null } | null {
   if (!pred) return null;
-  const m = OWNER_RE.exec(pred.trim());
-  return m ? { column: m[1], claim: m[2] } : null;
+  const t = pred.trim();
+  const m = OWNER_RE.exec(t);
+  if (m) return { column: m[1], claim: m[2], expr: null };
+  const f = OWNER_FN_RE.exec(t);
+  return f ? { column: f[1], claim: 'sub', expr: f[2] } : null;
+}
+
+/**
+ * Split a predicate on a top-level operator, respecting parens and string literals.
+ *
+ * Needed because the shapes worth recognising are compositional — `(public) OR (mine AND
+ * guard)` — and a naive `.split(' OR ')` cuts inside a nested disjunction, which is how a
+ * template matcher silently mis-reads `((state <> 'deleted') AND ((user_id = …) OR (…)))`
+ * as a top-level OR it is not.
+ */
+function splitTopLevel(pred: string, op: 'OR' | 'AND'): string[] {
+  const needle = ` ${op} `;
+  const parts: string[] = [];
+  let depth = 0;
+  let quoted = false;
+  let start = 0;
+  // Strip one enclosing paren pair so the operator we want is genuinely at depth 0.
+  const s = unwrapOnce(pred.trim());
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "'") { quoted = !quoted; continue; }
+    if (quoted) continue;
+    if (c === '(') depth++;
+    else if (c === ')') depth--;
+    else if (depth === 0 && s.startsWith(needle, i)) {
+      parts.push(s.slice(start, i));
+      i += needle.length - 1;
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+/** Drop one enclosing paren pair, but only when it spans the WHOLE expression. */
+function unwrapOnce(s: string): string {
+  if (!s.startsWith('(') || !s.endsWith(')')) return s;
+  let depth = 0;
+  let quoted = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "'") { quoted = !quoted; continue; }
+    if (quoted) continue;
+    if (c === '(') depth++;
+    else if (c === ')') {
+      depth--;
+      if (depth === 0 && i < s.length - 1) return s; // the pair closed early — not enclosing
+    }
+  }
+  return depth === 0 ? s.slice(1, -1).trim() : s;
+}
+
+/**
+ * Decompose an authenticated read of the form `(public) OR (mine [AND guard])`, given the
+ * public predicate the anon policy already states.
+ *
+ * Keyed on the ANON PREDICATE APPEARING VERBATIM as one of two top-level disjuncts, and an
+ * owner predicate appearing in the other — not on a shape template. The alternative,
+ * matching a `X OR (Y AND Z)` template, both over- and under-fires: it claims predicates it
+ * has not proven are a public branch, and it misses the schema whose OR is nested inside an
+ * AND. Anything that does not decompose EXACTLY returns null, and the caller says so.
+ */
+export function parsePublicOrOwn(
+  authedPred: string | null,
+  anonPred: string | null,
+): { owner: { column: string; claim: string; expr: string | null }; ownerSql: string | null } | null {
+  if (!authedPred || !anonPred) return null;
+  const branches = splitTopLevel(authedPred, 'OR');
+  if (branches.length !== 2) return null;
+
+  const anonNorm = unwrapOnce(anonPred.trim());
+  const publicIdx = branches.findIndex((b) => unwrapOnce(b) === anonNorm);
+  if (publicIdx === -1) return null;
+
+  const ownBranch = branches[1 - publicIdx];
+  const conjuncts = splitTopLevel(ownBranch, 'AND');
+  const ownerIdx = conjuncts.findIndex((c) => parseOwnerPredicate(c));
+  if (ownerIdx === -1) return null;
+
+  const owner = parseOwnerPredicate(conjuncts[ownerIdx])!;
+  const rest = conjuncts.filter((_, i) => i !== ownerIdx);
+  // More than one leftover conjunct would have to be re-ANDed, and the text the compiler
+  // then emits is not guaranteed to be the text that was read. Refuse rather than guess.
+  if (rest.length > 1) return null;
+  return { owner, ownerSql: rest[0] ?? null };
 }
 
 /** Is a privilege EFFECTIVE for a role — i.e. actually granted, not merely policed? */
@@ -135,15 +244,48 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
   if (anonRead) {
     // Public read. If the live policy narrows it (a soft-delete guard, a published flag),
     // carry that predicate — a public read with a filter is still a public read.
-    const pol = policiesFor(contract, 'anon', 'SELECT')[0];
-    const frag = sqlFragment(pol?.using ?? null);
+    const anonPol = policiesFor(contract, 'anon', 'SELECT')[0];
+    const anonPred = anonPol?.using ?? null;
+    const frag = sqlFragment(anonPred);
     abilities.push(frag ? `can('read', { sql: ${frag} })` : `can('read')`);
+
+    // The authenticated SELECT is a SEPARATE policy and routinely says MORE than the anon
+    // one — `(public) OR (mine)`, so an author sees their own not-yet-public rows. Reading
+    // only the anon policy dropped that branch and rendered a model that meant strictly
+    // less than the database did, with nothing said. On a real schema it hid ~13,184
+    // legacy rows from the people who wrote them.
+    const authedPol = authedRead
+      ? policiesFor(contract, 'authenticated', 'SELECT').find((p) => p.name !== anonPol?.name)
+      : undefined;
+    const authedPred = authedPol?.using ?? null;
+    if (authedPol && (authedPred ?? 'true') !== (anonPred ?? 'true')) {
+      const own = parsePublicOrOwn(authedPred, anonPred);
+      if (own) {
+        const parts = [`owner: '${own.owner.column}'`];
+        if (own.owner.claim !== 'sub') parts.push(`userField: '${own.owner.claim}'`);
+        if (own.owner.expr) parts.push(`ownerExpr: sql\`${own.owner.expr}\``);
+        const guard = sqlFragment(own.ownerSql);
+        if (guard) parts.push(`sql: ${guard}`);
+        abilities.push(`can('read', { ${parts.join(', ')} })`);
+      } else {
+        // P6: it must SAY SO. An unexpressible predicate becomes a comment naming the
+        // policy and its text, never a model that quietly means less.
+        notes.push(
+          `policy "${authedPol.name}" (SELECT) grants authenticated MORE than the anon read,`,
+        );
+        notes.push(`  and its shape is not expressible as abilities. Live USING:`);
+        notes.push(`    ${authedPred}`);
+        notes.push(`  Declare it by hand, or leave the table adopted. NOT rendered above.`);
+      }
+    }
   } else if (authedRead) {
     const pol = policiesFor(contract, 'authenticated', 'SELECT')[0];
     const owner = parseOwnerPredicate(pol?.using ?? null);
     if (owner) {
-      const claim = owner.claim === 'sub' ? '' : `, userField: '${owner.claim}'`;
-      abilities.push(`can('read', { owner: '${owner.column}'${claim} })`);
+      const parts = [`owner: '${owner.column}'`];
+      if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+      if (owner.expr) parts.push(`ownerExpr: sql\`${owner.expr}\``);
+      abilities.push(`can('read', { ${parts.join(', ')} })`);
     } else {
       const frag = sqlFragment(pol?.using ?? null);
       abilities.push(frag ? `can('read', { role: 'authenticated', sql: ${frag} })` : `can('read', { role: 'authenticated' })`);
@@ -165,6 +307,7 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     if (owner) {
       parts.push(`owner: '${owner.column}'`);
       if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+      if (owner.expr) parts.push(`ownerExpr: sql\`${owner.expr}\``);
     }
     // A predicate beyond the owner gate (a state guard, a tenant filter) rides as `sql`.
     const usingFrag = owner && parseOwnerPredicate(using) ? null : sqlFragment(using);
@@ -200,7 +343,11 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
 /** Render one table's derived stanza as the lines that sit inside a model literal. */
 export function renderDerivedAbilities(d: DerivedAbilities): string {
   const out: string[] = [];
-  for (const n of d.notes) out.push(`  // ${n}`);
+  // Split on newlines: a note may carry a live predicate verbatim, and `pg_get_expr`
+  // deparses a subquery across several lines. One `//` for the first line left the rest
+  // as bare SQL in the middle of a TypeScript object — a generated file that would not
+  // parse. Commenting per line here means no note, present or future, can do that.
+  for (const n of d.notes) for (const line of String(n).split('\n')) out.push(`  // ${line}`);
   if (d.abilities.length) {
     out.push(`  abilities: [${d.abilities.join(', ')}],`);
   } else {

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

@@ -83,6 +83,24 @@ export function keyCandidates(row: Record<string, unknown>, cols: string[]): str
   return cols.filter((_, i) => Number(row[`c${i}`]) === n && Number(row[`d${i}`]) === n);
 }
 
+/**
+ * The specifier the generated `index.ts` uses to import the `--derived-out` file.
+ *
+ * Both paths are resolved against CWD first, so this works whichever way either was written
+ * (`db/models` + `db/models/derived.ts`, or absolute, or `./db/models/`). Extension stripped
+ * (the barrel's own imports are extensionless), separators normalized for Windows, and a
+ * same-directory result gets the explicit `./` a bare `derived` would lack.
+ *
+ * `--out` may also name a single `.ts` file, in which case the barrel IS that file and the
+ * specifier is relative to its directory.
+ */
+export function derivedImportSpecifier(out: string, derivedOut: string): string {
+  const barrelDir = out.endsWith('.ts') ? path.dirname(path.resolve(out)) : path.resolve(out);
+  const target = path.resolve(derivedOut).replace(/\.ts$/, '');
+  const rel = path.relative(barrelDir, target).split(path.sep).join('/');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
 /** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
 function lambdaRunner(region: string, fn: string): QueryRunner {
   return async (sql: string) => {
@@ -269,15 +287,26 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       process.exit(0);
     }
   }
-  // With --derived-out, the embedded copy would duplicate every descriptor — the
-  // models output carries models only.
+  // With --derived-out, the embedded copy would duplicate every descriptor — the models
+  // output carries models only, and the barrel IMPORTS the layer from its own file. It used
+  // to carry neither, so the same command that wrote 120 descriptors emitted a
+  // `defineModule({ models })` that excluded every one of them, and db:plan then compared
+  // against a fraction of the database while printing a confident statement count.
   const embeddedDerived = derivedOut ? undefined : derived;
+  const externalDerived = derivedOut && flags.out
+    ? {
+      specifier: derivedImportSpecifier(flags.out, derivedOut),
+      sequences: derived.sequenceNames.length > 0,
+      materializedTables: derived.materializedTableNames.length > 0,
+      derived: derived.names.length > 0,
+    }
+    : undefined;
 
   let source: string;
   if (flags.out && !flags.out.endsWith('.ts')) {
     // A directory: one file per model + index.ts — the default shape for a real app.
     const dir = path.resolve(flags.out);
-    const files = renderModelFiles(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
+    const files = renderModelFiles(current, { schema, abilities, liveAuthz, derived: embeddedDerived, externalDerived });
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));

package/src/cli/model-render.ts

@@ -81,6 +81,10 @@ export interface RenderOptions {
   /** 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 `--derived-out` case: the layer lives in its own file, so the barrel imports and
+   *  wires it instead of embedding it. Mutually exclusive with `derived` in practice —
+   *  passing neither is what silently produced `defineModule({ models })`. */
+  externalDerived?: ExternalDerived;
 }
 
 /**
@@ -505,22 +509,42 @@ function importHeader(body: string, extra: string[] = []): string {
   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 {
+/**
+ * The barrel's module wrapper: models always; sequences/derived when the pull found any (B5).
+ *
+ * `external` is the `--derived-out` case — the descriptors live in their own file, so the
+ * barrel IMPORTS the arrays rather than re-declaring them. Before this the barrel simply
+ * omitted them, which meant the same pull that wrote 120 descriptors emitted a
+ * `defineModule({ models })` that excluded every one, and `db:plan` then compared against a
+ * fraction of the database while reporting a confident statement count. A plan scoped to
+ * something narrower than the reader assumes is the same false-completeness failure as a
+ * classification that defaults to safe.
+ */
+function moduleFooter(
+  modelNames: string[],
+  derived?: DerivedRenderResult,
+  multiline = false,
+  external?: ExternalDerived,
+): string {
   // A materialized table (--matviews-as-tables) is a MODEL — its block rides the derived
   // render (topo-ordered with the objects around it) but its name belongs in `models`.
-  const allModels = [...modelNames, ...(derived?.materializedTableNames ?? [])];
-  const models = multiline
-    ? `export const models = [\n${allModels.map((n) => `  ${n},`).join('\n')}\n];`
-    : `export const models = [${allModels.join(', ')}];`;
-  const parts = [models];
+  const hasMaterialized = external ? external.materializedTables : Boolean(derived?.materializedTableNames.length);
+  const inlineNames = external ? [] : (derived?.materializedTableNames ?? []);
+  const allModels = [...modelNames, ...inlineNames];
+  const rendered = multiline
+    ? `export const models = [\n${allModels.map((n) => `  ${n},`).join('\n')}\n${external && hasMaterialized ? '  ...materializedTables,\n' : ''}];`
+    : `export const models = [${[...allModels, ...(external && hasMaterialized ? ['...materializedTables'] : [])].join(', ')}];`;
+  const parts = [rendered];
   const keys = ['models'];
-  if (derived?.sequenceNames.length) {
-    parts.push(`export const sequences = [${derived.sequenceNames.join(', ')}];`);
+
+  const hasSequences = external ? external.sequences : Boolean(derived?.sequenceNames.length);
+  const hasDerived = external ? external.derived : Boolean(derived?.names.length);
+  if (hasSequences) {
+    if (!external) parts.push(`export const sequences = [${derived!.sequenceNames.join(', ')}];`);
     keys.push('sequences');
   }
-  if (derived?.names.length) {
-    parts.push(`export const derived = [${derived.names.join(', ')}];`);
+  if (hasDerived) {
+    if (!external) parts.push(`export const derived = [${derived!.names.join(', ')}];`);
     keys.push('derived');
   }
   parts.push(`export const appModule = defineModule({ ${keys.join(', ')} });`);
@@ -528,6 +552,24 @@ function moduleFooter(modelNames: string[], derived?: DerivedRenderResult, multi
   return parts.join('\n\n');
 }
 
+/** What an external (`--derived-out`) derived file exports, so the barrel can wire it. */
+export interface ExternalDerived {
+  /** Import specifier as written in the barrel, e.g. `'./derived'`. */
+  specifier: string;
+  sequences: boolean;
+  materializedTables: boolean;
+  derived: boolean;
+}
+
+/** The named exports to pull out of an external derived file, in a stable order. */
+function externalDerivedNames(e: ExternalDerived): string[] {
+  const names: string[] = [];
+  if (e.derived) names.push('derived');
+  if (e.materializedTables) names.push('materializedTables');
+  if (e.sequences) names.push('sequences');
+  return names;
+}
+
 /**
  * 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
@@ -610,14 +652,21 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   // their own model.
   const names = tables.map((t) => modelVarName(t.table));
   const modelSymbols = ['defineModule', ...(opts.derived?.imports ?? [])];
+  const ext = opts.externalDerived;
+  const extNames = ext ? externalDerivedNames(ext) : [];
   const index = [
     [
       `import { ${modelSymbols.join(', ')} } from '@everystack/model';`,
+      // The --derived-out layer, imported rather than re-declared — the barrel must WIRE it
+      // or db:plan silently compares against models only.
+      ...(extNames.length ? [`import { ${extNames.join(', ')} } from '${ext!.specifier}';`] : []),
       ...names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`),
     ].join('\n'),
     `export {\n${names.map((n) => `  ${n},`).join('\n')}\n};`,
+    // Re-exported so the barrel remains the one place that describes the database.
+    ...(extNames.length ? [`export { ${extNames.join(', ')} };`] : []),
     ...(opts.derived?.block ? [opts.derived.block] : []),
-    moduleFooter(names, opts.derived, true),
+    moduleFooter(names, opts.derived, true, ext),
   ].join('\n\n');
   files.push({ file: 'index.ts', source: index + '\n' });