@everystack/cli 0.3.31 → 0.4.0

package/README.md

@@ -216,7 +216,7 @@ everystack db:psql --stage dev [-c SQL] # interactive psql / one-off query via L
 # Model-driven schema (@everystack/model)
 everystack db:generate                  # diff Models vs the live DB → next migration
 everystack db:pull                      # introspect a live DB → field() Models (brownfield on-ramp)
-everystack db:reconcile                 # deploy the derived layer (functions/views/matviews) from db/sql — no migrations
+everystack db:reconcile                 # deploy the derived layer (functions/views/matviews/triggers) from the declared descriptors in db/models — no migrations
 everystack db:fingerprint               # content-address the live base schema vs the Models — MATCH/MISMATCH
 everystack db:sync                      # make the database match your checkout — state + compute, one verb (dev DBs)
 everystack db:diff                      # the state edge between two declared states — no DB, CI-pure; reverse = computed rollback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.31",
+  "version": "0.4.0",
   "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.3.6"
+    "@everystack/model": "0.4.0"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",

package/src/cli/authz-compile.ts

@@ -308,8 +308,10 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
 /** The four DML privileges, sorted — the expansion of a `manage` ability. */
 const CRUD = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
 
-/** The SQL privilege a single CRUD verb grants. `manage` expands to all of CRUD. */
-const VERB: Record<Exclude<Ability['action'], 'manage'>, string> = {
+/** The SQL privilege a single CRUD verb grants. `manage` expands to all of CRUD.
+ *  `execute` is a FUNCTION ability — defineModel rejects it on tables, so it never
+ *  reaches the table grant compiler (the throw below keeps that contract loud). */
+const VERB: Record<Exclude<Ability['action'], 'manage' | 'execute'>, string> = {
   read: 'SELECT',
   create: 'INSERT',
   update: 'UPDATE',
@@ -318,6 +320,7 @@ const VERB: Record<Exclude<Ability['action'], 'manage'>, string> = {
 
 /** The privileges an ability's action grants (a single verb, or all of CRUD for `manage`). */
 function verbsFor(action: Ability['action']): string[] {
+  if (action === 'execute') throw new Error(`can('execute') is a function ability — it has no table privilege (defineModel rejects it; this is unreachable).`);
   return action === 'manage' ? [...CRUD] : [VERB[action]];
 }
 

package/src/cli/backfill.ts

@@ -8,7 +8,7 @@
  * unlike `schema_log`, which stays a write-only memoir. The distrust that
  * killed the migration tape doesn't transfer: nothing is numbered, nothing
  * is watermarked, and identity is the NORMALIZED CONTENT HASH (the same
- * comment-insensitive, dollar-quote-aware lexing as db/sql) — renaming a
+ * comment-insensitive, dollar-quote-aware lexing as the reconciler) — renaming a
  * file or editing a comment is a no-op, never a re-run.
  *
  * One-shot jobs are IMMUTABLE. A file whose name already ran on this

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

@@ -4,7 +4,7 @@
  * decision 14).
  *
  *   db:template:refresh [--database-url <url>] [--models <barrel>]
- *                       [--sql-dir db/sql] [--seed "<cmd>"] [--no-seed]
+ *                       [--seed "<cmd>"] [--no-seed]
  *   db:branch                       # mint (or find) the current branch's DB
  *   db:branch --list                # every branch DB, mapped to its branch
  *   db:branch --drop --confirm      # drop the current branch's DB
@@ -39,7 +39,7 @@ import { currentGitRef } from '../state-apply.js';
 import { fingerprintModels } from '../schema-fingerprint.js';
 import { resolveDbSource, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
-import { readSqlDirIfPresent } from './db-sync.js';
+import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import { loadModels } from './db-generate.js';
 import { step, success, fail, info, warn } from '../output.js';
 
@@ -92,7 +92,30 @@ export async function dbTemplateRefreshCommand(flags: Record<string, string>): P
     fail(err.message);
     process.exit(1);
   }
-  const sources = await readSqlDirIfPresent(flags['sql-dir'] || 'db/sql');
+  // B7 tombstone — db/sql is retired and no longer read.
+  try {
+    if (flags['sql-dir']) {
+      fail(await retiredSqlDirFlagRefusal(flags['sql-dir']));
+      process.exit(1);
+    }
+    const retired = await retiredSqlDirAnywhere(flags.models);
+    if (retired) {
+      fail(retired);
+      process.exit(1);
+    }
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  // The declared derived layer + sequences — branch/template DBs carry the SAME stream
+  // every other verb deploys, or a minted branch is silently missing its compute.
+  let declaredDb: DeclaredDerived | null = null;
+  try {
+    declaredDb = await loadDeclaredDerived(flags.models);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
 
   let seedCommand: string | null = null;
   if (flags['no-seed'] === 'true') {
@@ -109,7 +132,8 @@ export async function dbTemplateRefreshCommand(flags: Record<string, string>): P
   step(`Rebuilding ${template} from the declared state (drop → create → sync both layers → seed)...`);
   try {
     const result = await executeTemplateRefresh(url, models, {
-      sources,
+      declared: declaredDb?.objects,
+      sequences: declaredDb?.sequences,
       actor: process.env.USER ?? null,
       gitRef: currentGitRef(),
       seed: seedCommand === null ? null : (templateUrl) => {

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

@@ -3,7 +3,7 @@
  * invariant: the merged declared state must compose, and generated
  * artifacts must match regeneration).
  *
- *   db:check [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>]
+ *   db:check [--models <barrel>] [--schema-out <file.ts>]
  *            [--database-url <url>] [--json]
  *
  * Two rings, both from the checkout alone (no target database is ever
@@ -13,7 +13,8 @@
  *   git can't see, like two branches declaring the same table, fails
  *   here); the generated drizzle schema matches a byte-for-byte
  *   regeneration (hand-edited artifacts and forgotten `db:generate` runs
- *   fail loudly); the derived sources in db/sql parse.
+ *   fail loudly); a leftover db/sql directory fails with the migration
+ *   path (B7 — descriptors are the single home).
  *
  *   EPHEMERAL COMPOSE — with a scratch PostgreSQL (`--database-url` /
  *   DATABASE_URL), build the merged declared state FROM SCRATCH on an
@@ -28,24 +29,25 @@
  */
 
 import fs from 'node:fs/promises';
-import type { ModelDescriptor } from '@everystack/model';
+import type { ModelDescriptor, DerivedDescriptor } from '@everystack/model';
 import { compileDeclaredState } from '../declared-diff.js';
 import { compileMigration } from '../migration-compile.js';
 import { compileDrizzleSource } from '../schema-source.js';
-import { parseSqlSources, type SourceFile } from '../derived-source.js';
 import { currentGitRef } from '../state-apply.js';
 import { createDatabase, dropDatabase, buildIntoDatabase, withDatabase } from '../db-build.js';
 import { resolveModelsPath } from '../models-path.js';
-import { readSqlDirIfPresent } from './db-sync.js';
 import { loadModels } from './db-generate.js';
+import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
+import type { SequenceDescriptor } from '@everystack/model';
+import type { SourceObject } from '../derived-source.js';
 import { findReadAuthzGaps } from '../authz-lint.js';
+import { findDerivedReadGaps, findSecdefExecuteGaps, findMatviewSnapshotWarnings } from '../derived-lint.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 // The role derivation moved to the shared builder (db-build) with brick
 // 5-remainder; re-exported here because db:check is where it grew up.
 export { rolesFromContract } from '../db-build.js';
 
-const DEFAULT_SQL_DIR = 'db/sql';
 const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 
 // ---------------------------------------------------------------------------
@@ -53,7 +55,8 @@ const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 // ---------------------------------------------------------------------------
 
 export interface CheckFinding {
-  level: 'ok' | 'note' | 'fail';
+  /** `warn` is visible-but-never-fatal — the matview snapshot gate's channel. */
+  level: 'ok' | 'note' | 'warn' | 'fail';
   area: 'models' | 'compose' | 'artifact' | 'compute' | 'authz';
   message: string;
 }
@@ -66,8 +69,15 @@ export interface StaticCheckInput {
   artifactPath: string;
   /** null = no generated schema artifact on disk. */
   artifactSource: string | null;
-  /** null = no db/sql directory. */
-  sources: SourceFile[] | null;
+  /** Set when a retired db/sql directory still carries .sql files — the tombstone
+   *  message (with the migration path); a hard fail, never a shrug. */
+  sqlDirRetired?: string | null;
+  /** Standalone sequences the modules declare (state — in the from-scratch compose). */
+  sequences?: SequenceDescriptor[];
+  /** The declared derived descriptors (raw — the B2 gates read abilities, not SQL). */
+  derived?: DerivedDescriptor[] | null;
+  /** Set when the derived layer failed to COMPILE (e.g. reachability) — a hard fail. */
+  derivedError?: string;
 }
 
 export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
@@ -98,7 +108,7 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
   }
   try {
     compileDeclaredState(input.models);
-    const statements = compileMigration(input.models);
+    const statements = compileMigration(input.models, { sequences: input.sequences });
     findings.push({ level: 'ok', area: 'compose', message: `declared state composes — ${statements.length} statement(s) from scratch` });
   } catch (err: any) {
     findings.push({ level: 'fail', area: 'compose', message: `the merged declared state does NOT compose: ${err.message}` });
@@ -116,13 +126,43 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     }
   }
 
+  // The derived layer failing to COMPILE (reachability, cycles, undeclared trigger
+  // functions) is a hard fail — CI cannot shrug at a compile error.
+  if (input.derivedError) {
+    findings.push({
+      level: 'fail',
+      area: 'compute',
+      message: `the declared derived layer does NOT compile: ${input.derivedError}`,
+    });
+  }
+
+  // The B2 gates over the declared derived layer: every relation makes its read decision
+  // (fail), every SECURITY DEFINER declares its callers (fail), and a matview over
+  // row-scoped sources is named for what it is — a snapshot with the refresher's eyes (warn).
+  if (input.derived?.length) {
+    const derivedGaps = [...findDerivedReadGaps(input.derived), ...findSecdefExecuteGaps(input.derived)];
+    for (const gap of derivedGaps) {
+      findings.push({ level: 'fail', area: 'authz', message: gap.message });
+    }
+    for (const warning of findMatviewSnapshotWarnings(input.derived)) {
+      findings.push({ level: 'warn', area: 'authz', message: warning.message });
+    }
+    if (derivedGaps.length === 0) {
+      findings.push({
+        level: 'ok',
+        area: 'authz',
+        message: `every derived relation declares its read surface and every SECURITY DEFINER its callers (${input.derived.length} descriptor(s))`,
+      });
+    }
+  }
+
   if (input.artifactSource === null) {
     findings.push({
       level: 'note',
       area: 'artifact',
       message: `no generated schema at ${input.artifactPath} — nothing to match (db:generate writes it)`,
     });
-  } else if (input.artifactSource === compileDrizzleSource(input.models)) {
+  } else if (input.artifactSource === compileDrizzleSource(input.models, { derived: input.derived ?? undefined })) {
     findings.push({ level: 'ok', area: 'artifact', message: `${input.artifactPath} matches regeneration byte-for-byte` });
   } else {
     findings.push({
@@ -132,20 +172,10 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     });
   }
 
-  if (input.sources === null) {
-    findings.push({ level: 'note', area: 'compute', message: 'no db/sql directory — derived layer not declared, nothing to parse' });
-  } else {
-    try {
-      const parsed = parseSqlSources(input.sources);
-      findings.push({
-        level: 'ok',
-        area: 'compute',
-        message: `${parsed.objects.length} derived object(s) parsed from ${input.sources.length} db/sql file(s)`,
-      });
-      for (const w of parsed.warnings) findings.push({ level: 'note', area: 'compute', message: w });
-    } catch (err: any) {
-      findings.push({ level: 'fail', area: 'compute', message: `db/sql does not parse: ${err.message}` });
-    }
+  // B7 — db/sql is retired. Files still present would be silently unmanaged: fail
+  // with the migration path. (Absence is the normal state; nothing to report.)
+  if (input.sqlDirRetired) {
+    findings.push({ level: 'fail', area: 'compute', message: input.sqlDirRetired });
   }
 
   return findings;
@@ -177,14 +207,14 @@ export interface EphemeralComposeResult {
 export async function executeEphemeralCompose(
   adminUrl: string,
   models: ModelDescriptor[],
-  sources: SourceFile[] | null,
-  opts: { actor?: string | null; gitRef?: string | null } = {},
+  opts: { actor?: string | null; gitRef?: string | null; declared?: SourceObject[]; sequences?: SequenceDescriptor[] } = {},
 ): Promise<EphemeralComposeResult> {
   const database = `escheck_${process.pid}_${Date.now()}`;
   await createDatabase(adminUrl, database);
   try {
     const built = await buildIntoDatabase(withDatabase(adminUrl, database), models, {
-      sources,
+      declared: opts.declared,
+      sequences: opts.sequences,
       actor: opts.actor ?? 'db:check',
       gitRef: opts.gitRef ?? null,
     });
@@ -198,7 +228,7 @@ export async function executeEphemeralCompose(
 // The CLI shell.
 // ---------------------------------------------------------------------------
 
-const MARK: Record<CheckFinding['level'], string> = { ok: '=', note: '·', fail: '!' };
+const MARK: Record<CheckFinding['level'], string> = { ok: '=', note: '·', warn: '~', fail: '!' };
 
 export async function dbCheckCommand(flags: Record<string, string>): Promise<void> {
   const modelsPath = resolveModelsPath(flags.models);
@@ -218,11 +248,30 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
   } catch {
     artifactSource = null;
   }
-  const sources = await readSqlDirIfPresent(flags['sql-dir'] || DEFAULT_SQL_DIR);
+  // B7 tombstone — a retired db/sql directory still carrying .sql files is a FAIL
+  // finding (the message carries the migration path), never a silent skip. The retired
+  // --sql-dir flag is itself a FAIL finding here (the sibling verbs refuse it outright);
+  // detector errors (an unreadable directory) surface as the finding, never disarm it.
+  const sqlDirRetired = flags['sql-dir']
+    ? await retiredSqlDirFlagRefusal(flags['sql-dir'])
+    : await retiredSqlDirAnywhere(flags.models).catch((err: any) => String(err?.message ?? err));
+
+  // The declared derived layer + sequences — the same stream every other verb consumes.
+  // A compile failure here (reachability, cycles) is a FAIL finding, not a shrug.
+  let declaredDb: DeclaredDerived | null = null;
+  let derivedError: string | undefined;
+  try {
+    declaredDb = await loadDeclaredDerived(flags.models);
+  } catch (err: any) {
+    derivedError = err.message;
+  }
 
-  const findings = runStaticChecks({ modelsPath, models, modelsError, artifactPath, artifactSource, sources });
+  const findings = runStaticChecks({
+    modelsPath, models, modelsError, artifactPath, artifactSource, sqlDirRetired,
+    sequences: declaredDb?.sequences, derived: declaredDb?.derived, derivedError,
+  });
   for (const f of findings) {
-    (f.level === 'fail' ? warn : info)(`${MARK[f.level]} ${f.area}: ${f.message}`);
+    (f.level === 'fail' || f.level === 'warn' ? warn : info)(`${MARK[f.level]} ${f.area}: ${f.message}`);
   }
 
   let ephemeral: EphemeralComposeResult | null = null;
@@ -236,9 +285,11 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
   } else {
     step('Composing the declared state from scratch on an ephemeral database...');
     try {
-      ephemeral = await executeEphemeralCompose(url, models!, sources, {
+      ephemeral = await executeEphemeralCompose(url, models!, {
         actor: process.env.USER ?? 'db:check',
         gitRef: currentGitRef(),
+        declared: declaredDb?.objects,
+        sequences: declaredDb?.sequences,
       });
       for (const line of ephemeral.report) info(`  ${line}`);
     } catch (err: any) {

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

@@ -30,6 +30,8 @@ import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 import { loadModels } from './db-generate.js';
+import { loadDeclaredDerived } from '../declared-derived.js';
+import type { SequenceDescriptor } from '@everystack/model';
 
 export interface FingerprintStatus {
   live: string;
@@ -42,11 +44,12 @@ export interface FingerprintStatus {
 export async function computeFingerprintStatus(
   runner: QueryRunner,
   models: ModelDescriptor[] | null,
+  sequences?: SequenceDescriptor[],
 ): Promise<FingerprintStatus> {
   const snapshot = await introspectSchema(runner);
   const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
   const live = fingerprintLive(snapshot, contract).hash;
-  const declared = models ? fingerprintModels(models).hash : null;
+  const declared = models ? fingerprintModels(models, { sequences }).hash : null;
   const unfingerprinted = mapUnfingerprintedRows((await runner(UNFINGERPRINTED_SQL)) as any[]);
   return { live, declared, match: declared === null ? null : live === declared, unfingerprinted };
 }
@@ -71,8 +74,10 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
 
   const modelsPath = resolveModelsPath(flags.models);
   let models: ModelDescriptor[] | null = null;
+  let sequences: SequenceDescriptor[] | undefined;
   try {
     models = await loadModels(modelsPath);
+    sequences = (await loadDeclaredDerived(flags.models))?.sequences;
   } catch {
     // Live-only mode: no models barrel — still useful (what fingerprint is this DB at?).
   }
@@ -89,7 +94,7 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
   }
 
   try {
-    const status = await computeFingerprintStatus(runner, models);
+    const status = await computeFingerprintStatus(runner, models, sequences);
 
     if (flags.json === 'true') {
       console.log(JSON.stringify(status, null, 2));

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

@@ -3,6 +3,8 @@
  *
  *   db:generate --stage <name> [--name <label>]   introspect the live DB → diff the Models
  *                                                  → write the next drizzle migration file
+ *   db:generate --dry-run                          the same edge, printed — NOTHING written
+ *                                                  (no migration, no journal, no schema refresh)
  *
  * The one generator — both layers in one ordered migration. It compiles the app's Models,
  * introspects the deployed database through the ops Lambda `db:query` action (the same
@@ -24,11 +26,12 @@ import type { ModelDescriptor, Module } from '@everystack/model';
 import { introspectSchema } from '../schema-introspect.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import { compileModuleMigration } from '../migration-compile.js';
-import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, HELD_DROP_PREFIX, type Journal } from '../migration-generate.js';
+import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, resolveSchemaOut, HELD_DROP_PREFIX, type Journal } from '../migration-generate.js';
 import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
+import { loadDeclaredDerived, type DeclaredDerived } from '../declared-derived.js';
 import { applyStateAndVerify, classifyGeneratedStatements, currentGitRef, type StateSyncOutcome } from '../state-apply.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
@@ -76,7 +79,7 @@ async function loadModules(modelsPath: string): Promise<Module[]> {
   }
   if (Array.isArray(mod.modules)) return mod.modules;
   const models = mod.models ?? mod.default;
-  if (Array.isArray(models)) return [{ models, extensions: [], functions: [] }];
+  if (Array.isArray(models)) return [{ models, extensions: [], sequences: [], derived: [], functions: [] }];
   throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
 }
 
@@ -87,14 +90,14 @@ async function loadModules(modelsPath: string): Promise<Module[]> {
  * `drizzle/`. Roles are excluded by design (they are `db:provision`). Use it to (re)initialize
  * a clean migration history: clear `drizzle/`, then `db:generate --init`.
  */
-async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaOut: string, name: string): Promise<void> {
+async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaOut: string, name: string, schemaOutRecord: string): Promise<void> {
   step(`Loading modules from ${modelsPath}...`);
   const modules = await loadModules(modelsPath);
   const models = modules.flatMap((m) => m.models);
   info(`${modules.length} module(s), ${models.length} model(s).`);
 
   step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-  await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
+  await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: modules.flatMap((m) => m.derived) }), 'utf8');
 
   const statements = compileModuleMigration(modules);
 
@@ -106,6 +109,7 @@ async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaO
     journal = { version: '7', dialect: 'postgresql', entries: [] };
   }
   const { filename, journal: nextJournal } = planMigrationFile(journal, name, Date.now());
+  nextJournal.schemaOut = schemaOutRecord; // D2 — flag-less later runs reuse it
   const filePath = path.join(migrationsDir, filename);
   await fs.mkdir(path.join(migrationsDir, 'meta'), { recursive: true });
   await fs.writeFile(filePath, formatMigrationFile(statements), 'utf8');
@@ -117,18 +121,43 @@ async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaO
   process.exit(0);
 }
 
+/** Read the journal if present (null = no history yet). */
+async function readJournal(migrationsDir: string): Promise<Journal | null> {
+  try {
+    return JSON.parse(await fs.readFile(path.join(migrationsDir, 'meta', '_journal.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 export async function dbGenerateCommand(flags: Record<string, string>): Promise<void> {
   const modelsPath = resolveModelsPath(flags.models);
   const migrationsDir = path.resolve(flags.dir || DEFAULT_MIGRATIONS);
-  const schemaOut = path.resolve(flags['schema-out'] || DEFAULT_SCHEMA_OUT);
   const name = flags.name || 'generated';
   const allowDrops = flags['allow-drops'] === 'true';
+  const dryRun = flags['dry-run'] === 'true';
+
+  // D2 — schema-out resolution: flag > journal-recorded > default. Recording the
+  // resolved path in the journal makes the relocated-artifact orphan unmintable:
+  // a later run without the flag keeps writing where the project writes.
+  const journal = await readJournal(migrationsDir);
+  const schemaOutRes = resolveSchemaOut(flags['schema-out'], journal, DEFAULT_SCHEMA_OUT);
+  const schemaOut = path.resolve(schemaOutRes.path);
+  if (schemaOutRes.source === 'recorded') {
+    info(`schema-out: ${schemaOutRes.path} (recorded in the journal; override with --schema-out)`);
+  } else if (schemaOutRes.source === 'flag' && schemaOutRes.updateRecord && journal?.schemaOut) {
+    warn(`schema-out moves: ${journal.schemaOut} → ${schemaOutRes.path} — the journal record updates with this run; delete the old artifact.`);
+  }
 
   // --init: greenfield, no live DB — the model emits the whole migration (extensions + schema +
   // authz + package functions). The brownfield path below introspects the deployed DB and diffs.
   if (flags.init === 'true') {
+    if (dryRun) {
+      fail('--dry-run previews the brownfield diff — --init is the greenfield generator (its output IS the whole migration; there is nothing cheaper to preview).');
+      process.exit(1);
+    }
     try {
-      await dbGenerateInit(modelsPath, migrationsDir, schemaOut, flags.name || 'init');
+      await dbGenerateInit(modelsPath, migrationsDir, schemaOut, flags.name || 'init', schemaOutRes.path);
     } catch (err: any) {
       fail(err.message);
       process.exit(1);
@@ -137,7 +166,12 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   }
 
   const apply = flags.apply === 'true';
+  if (dryRun && apply) {
+    fail('--dry-run and --apply are opposites — a dry run writes and executes nothing. Pick one.');
+    process.exit(1);
+  }
   let models: ModelDescriptor[];
+  let declaredDb: DeclaredDerived | null = null;
   let current;
   let liveAuthz;
   let runner!: QueryRunner;
@@ -145,12 +179,16 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   try {
     step(`Loading models from ${modelsPath}...`);
     models = await loadModels(modelsPath);
+    declaredDb = await loadDeclaredDerived(flags.models);
     info(`${models.length} model(s).`);
     // The drizzle runtime schema is a derived artifact — refresh it from the models
     // every run (it needs no DB), so a relation-only change with no DDL diff still
-    // updates it. The drift-guard test asserts this file matches the models.
-    step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-    await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
+    // updates it. The drift-guard test asserts this file matches the models (and the
+    // typed derived relations — B6a). A dry run refreshes NOTHING — not even this.
+    if (!dryRun) {
+      step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
+      await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: declaredDb?.derived }), 'utf8');
+    }
     const dbSource: DbSource = resolveDbSource(flags);
     if (apply && dbSource.kind !== 'url') {
       fail('--apply needs a direct connection (--database-url or DATABASE_URL) — the ops Lambda query path is read-only by design.');
@@ -179,14 +217,29 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
 
   // One ordered migration carries both layers: data DDL first, then the authz reconcile
   // (RLS/policies/grants) the Models' abilities declare, diffed against the live contract.
-  const statements = generateMigrationSql(models, current, { allowDrops, liveAuthz });
+  const statements = generateMigrationSql(models, current, { allowDrops, liveAuthz, sequences: declaredDb?.sequences });
   const unmodeled = unmodeledTables(models, current);
   if (unmodeled.length) {
     info(`${unmodeled.length} table(s) in the database are not declared by any model — left untouched (db:generate manages only declared tables).`);
   }
   console.log('');
   if (statements.length === 0) {
-    success('db:generate — the live database already matches the models. No migration written.');
+    success(`db:generate — the live database already matches the models. ${dryRun ? 'Nothing to preview.' : 'No migration written.'}`);
+    process.exit(0);
+  }
+
+  // D1 — --dry-run: the edge as SQL, nothing else. No migration file, no journal
+  // entry, no schema refresh — preview traffic belongs here (and db:diff computes
+  // the models-vs-models edge with no database at all).
+  if (dryRun) {
+    const classified = classifyGeneratedStatements(statements);
+    info(`dry run — ${statements.length} statement(s), nothing written:`);
+    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);
   }
 
@@ -209,7 +262,7 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     let outcome: StateSyncOutcome;
     try {
       outcome = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
-        allowDrops, actor: process.env.USER ?? null, gitRef: currentGitRef(),
+        allowDrops, sequences: declaredDb?.sequences, actor: process.env.USER ?? null, gitRef: currentGitRef(),
       });
     } catch (err: any) {
       fail(`Apply failed and rolled back: ${err.message}`);
@@ -228,14 +281,12 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   }
 
   const journalPath = path.join(migrationsDir, 'meta', '_journal.json');
-  let journal: Journal;
-  try {
-    journal = JSON.parse(await fs.readFile(journalPath, 'utf8'));
-  } catch {
-    journal = { version: '7', dialect: 'postgresql', entries: [] };
-  }
-
-  const { filename, journal: nextJournal } = planMigrationFile(journal, name, Date.now());
+  const { filename, journal: nextJournal } = planMigrationFile(
+    journal ?? { version: '7', dialect: 'postgresql', entries: [] }, name, Date.now(),
+  );
+  // D2 — the resolved schema-out path rides the journal, so the next flag-less run
+  // keeps writing where this project writes.
+  nextJournal.schemaOut = schemaOutRes.path;
   const filePath = path.join(migrationsDir, filename);
   try {
     await fs.mkdir(path.join(migrationsDir, 'meta'), { recursive: true });