@everystack/cli 0.3.31 → 0.4.0

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

@@ -1,7 +1,7 @@
 /**
  * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
  *
- *   db:pull [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>]
+ *   db:pull [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--abilities public-read]
  *
  * The reverse of db:generate: that writes migrations FROM Models; this writes Models FROM the
  * database. It introspects the deployed schema through the read-only ops Lambda `db:query`
@@ -23,7 +23,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { introspectSchema } from '../schema-introspect.js';
-import { renderModelSource, renderModelFiles, pullableTables } from '../model-render.js';
+import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
+import { renderDerivedSource, type DerivedRenderResult } from '../derived-render.js';
+import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
@@ -49,6 +51,14 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
 export async function dbPullCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema || 'public';
 
+  // The read-model scaffold: default 'commented' surfaces the authz decision in every
+  // model; a preset stamps it. Validated up front so a typo fails before introspection.
+  const abilities = flags.abilities || 'commented';
+  if (abilities !== 'commented' && !ABILITY_PRESETS[abilities]) {
+    fail(`Unknown --abilities preset '${abilities}'. Known: ${Object.keys(ABILITY_PRESETS).join(', ')} (omit the flag to scaffold the decision as comments).`);
+    process.exit(1);
+  }
+
   let dbSource: DbSource;
   try {
     dbSource = resolveDbSource(flags);
@@ -58,6 +68,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   }
 
   let current;
+  let derivedCatalog: DerivedCatalog | undefined;
   try {
     let runner: QueryRunner;
     let end: (() => Promise<void>) | undefined;
@@ -72,6 +83,9 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     note(`Introspecting live database (schema: ${schema})...`);
     current = await introspectSchema(runner);
+    // The derived layer rides the same pull (B5) — views/matviews/functions/sequences
+    // render as descriptors; adoption is pull → commit → --baseline → clean reconcile.
+    derivedCatalog = await introspectDerived(runner);
     await end?.();
   } catch (err: any) {
     fail(err.message);
@@ -90,11 +104,24 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // The derived layer (B5): rendered from the live catalog with dependsOn from the real
+  // edge graph. Everything inexpressible is a stderr warning AND an inline FIXME.
+  const knownTables = new Map(pulled.map((t) => [t.table, modelVarName(t.table)]));
+  const derived: DerivedRenderResult = renderDerivedSource(derivedCatalog ?? { objects: [], edges: [], provenance: [] }, {
+    knownTables,
+    sequences: current.sequences,
+  });
+  for (const w of derived.warnings) caution(w);
+  const derivedCount = derived.names.length + derived.sequenceNames.length;
+  if (derivedCount > 0) {
+    detail(`Derived layer: ${derived.names.length} descriptor(s) + ${derived.sequenceNames.length} sequence(s) rendered (adopt with db:reconcile --baseline after committing).`);
+  }
+
   let source: string;
   if (flags.out && !flags.out.endsWith('.ts')) {
     // A directory: one file per model + index.ts — the default shape for a real app.
     const dir = path.resolve(flags.out);
-    const files = renderModelFiles(current, { schema });
+    const files = renderModelFiles(current, { schema, abilities, derived });
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));
@@ -111,7 +138,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     source = files.map((f) => f.source).join('\n');
   } else if (flags.out) {
     const outPath = path.resolve(flags.out);
-    source = renderModelSource(current, { schema });
+    source = renderModelSource(current, { schema, abilities, derived });
     try {
       await fs.mkdir(path.dirname(outPath), { recursive: true });
       await fs.writeFile(outPath, source, 'utf8');
@@ -121,12 +148,17 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${pulled.length} model(s).`);
   } else {
-    source = renderModelSource(current, { schema });
+    source = renderModelSource(current, { schema, abilities, derived });
     process.stdout.write(source);
     ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
   }
 
   const flagged = (source.match(/\/\/ (FIXME|TODO|composite|CHECK|FK →)/g) ?? []).length;
   if (flagged) caution(`${flagged} inline comment(s) flag things to review (unmapped types, checks, cross-schema FKs).`);
+  if (abilities === 'commented') {
+    note(`Each model scaffolds its authz decision as comments — author them (db:check fails until every model declares), or stamp the common case: db:pull --abilities public-read.`);
+  } else {
+    note(`Stamped '${abilities}' abilities into every model — review the generated stanzas; they are code, not defaults.`);
+  }
   process.exit(0);
 }

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

@@ -1,9 +1,13 @@
 /**
  * `everystack db:reconcile` — deploy the derived layer (functions, views,
- * matviews) by reconciling the live database against the db/sql sources.
+ * matviews, triggers, escape-hatch objects) by reconciling the live database
+ * against the DECLARED descriptors (defineView / defineMaterializedView /
+ * defineFunction / defineSql / trigger() on the models). Descriptors are the
+ * single home — a checkout still carrying db/sql *.sql files fails loudly with
+ * the migration path (B7).
  *
- *   db:reconcile [--sql-dir db/sql] [--stage <name> | --database-url <url>]
- *                [--apply] [--check] [--baseline] [--overwrite-drift] [--json]
+ *   db:reconcile [--stage <name> | --database-url <url>]
+ *                [--apply] [--check] [--baseline] [--rebaseline] [--overwrite-drift] [--json]
  *
  * Derived objects do not migrate; they deploy. The plan is computed fresh
  * every run: source objects (hashed, comment/whitespace-insensitive) joined
@@ -16,33 +20,35 @@
  *
  * Hand-edited live objects are DRIFT — reported, applied over only with
  * `--overwrite-drift`. Never-reconciled matches need `--baseline` once (the
- * explicit trust that live == source, recorded). `--apply` needs a direct
+ * explicit trust that live == source, recorded). A source RE-RENDER over an
+ * untouched live object — the db/sql-era → descriptor migration — needs
+ * `--rebaseline` once: live is verified (defHash match), the new source hash
+ * is re-recorded, nothing rebuilds. `--apply` needs a direct
  * connection (`--database-url` / DATABASE_URL): the ops Lambda `db:query`
  * path is read-only by design, so plan/check work anywhere but writes go
  * through a credentialed connection you chose to hold.
  */
 
-import fs from 'node:fs/promises';
-import path from 'node:path';
 import type { QueryRunner } from '../authz-contract.js';
-import { parseSqlSources, type SourceFile } from '../derived-source.js';
+import type { SourceObject } from '../derived-source.js';
 import { introspectDerived } from '../derived-introspect.js';
 import { planReconcile, type ReconcilePlan, type ReconcileOptions } from '../derived-plan.js';
 import {
   renderReconcileSql,
   renderProvenanceUpsert,
+  renderProvenanceMigrate,
+  triggerDropSql,
   renderProvenanceDelete,
   renderSchemaLogInsert,
   ENSURE_RECONCILER_SQL,
 } from '../derived-apply.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 
-const DEFAULT_SQL_DIR = 'db/sql';
-
 // ---------------------------------------------------------------------------
 // The testable core.
 // ---------------------------------------------------------------------------
@@ -52,6 +58,8 @@ export interface ExecuteOptions extends ReconcileOptions {
   actor?: string | null;
   gitRef?: string | null;
   planRef?: string | null;
+  /** Descriptor-compiled objects (the declared derived layer) — the ONE source stream. */
+  declared?: SourceObject[];
   /** Injectable clock for tests. */
   now?: () => number;
 }
@@ -73,22 +81,35 @@ export interface ReconcileRun {
 /** Statements Postgres forbids inside a transaction block — they implicitly commit. */
 export const NON_TRANSACTIONAL_RE = /\bCONCURRENTLY\b|\bVACUUM\b/i;
 
+/** Session identity — the guard against postgres-js's silent reconnect (see the apply path). */
+export const BACKEND_PID_SQL = 'SELECT pg_backend_pid() AS pid';
+
+// Dollar-quoted bodies and comments are CONTENT, not batch shape — a plpgsql helper whose
+// body says `REFRESH MATERIALIZED VIEW CONCURRENTLY …` is perfectly transactional to CREATE.
+// Stripping errs loud, never silent: over-stripping would wrongly WRAP a truly-concurrent
+// statement, and PostgreSQL then refuses it with its own clear error at apply time.
+const DOLLAR_BODY_RE = /\$([A-Za-z_][A-Za-z0-9_]*)?\$[\s\S]*?\$\1\$/g;
+const LINE_COMMENT_RE = /--[^\n]*/g;
+const BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+
 /**
  * Whether the whole batch can run inside one transaction. Almost always yes — the escape hatch
  * is a consumer whose matview source carries a `CREATE INDEX CONCURRENTLY` (rendered verbatim) or
- * a `VACUUM`, which self-commit and cannot live in a transaction block.
+ * a `VACUUM`, which self-commit and cannot live in a transaction block. Only the statement's own
+ * shape decides: dollar-quoted bodies and comments are stripped before the test.
  */
 export function isTransactionalBatch(statements: string[]): boolean {
-  return statements.every((s) => !NON_TRANSACTIONAL_RE.test(s));
+  return statements.every((s) => !NON_TRANSACTIONAL_RE.test(
+    s.replace(DOLLAR_BODY_RE, '').replace(BLOCK_COMMENT_RE, '').replace(LINE_COMMENT_RE, ''),
+  ));
 }
 
 export async function executeReconcile(
   runner: QueryRunner,
-  sources: SourceFile[],
   options: ExecuteOptions = {},
 ): Promise<ReconcileRun> {
   const live = await introspectDerived(runner);
-  const parsed = parseSqlSources(sources);
+  const parsed = { objects: options.declared ?? [], warnings: [] as string[] };
   const plan = planReconcile(parsed, live, options);
   const rendered = renderReconcileSql(plan, parsed.objects);
 
@@ -106,7 +127,7 @@ export async function executeReconcile(
       refusal: `drift on ${plan.drift.map((d) => d.identity).join(', ')} — inspect, then re-run with --overwrite-drift to rebuild from source`,
     };
   }
-  if (rendered.statements.length === 0 && rendered.record.length === 0 && rendered.remove.length === 0) {
+  if (rendered.statements.length === 0 && rendered.record.length === 0 && rendered.remove.length === 0 && rendered.migrate.length === 0) {
     return { plan, applied: false, statements: [] };
   }
 
@@ -124,8 +145,26 @@ export async function executeReconcile(
 
   if (atomic) await runner('BEGIN');
   try {
+    // The session guard: postgres-js `max: 1` is a pool of one, not a session lease — a
+    // connection that dies between runner calls silently reconnects, the open transaction
+    // aborts server-side, and every later call runs in autocommit on a fresh session. The
+    // bookkeeping would then record a state the DDL never reached, and the object would read
+    // as converged forever (the red-team's false-convergence finding). Pin the backend pid
+    // at BEGIN; refuse the bookkeeping if it moved. createUrlRunner also disables the
+    // driver's max_lifetime recycling — the deterministic trigger during long applies.
+    const pidAtBegin = atomic ? Number((await runner(BACKEND_PID_SQL))[0]?.pid) : null;
+
     if (rendered.statements.length > 0) {
-      await runner(rendered.statements.join(';\n'));
+      if (atomic) {
+        await runner(rendered.statements.join(';\n'));
+      } else {
+        // Self-committing statements (CONCURRENTLY, VACUUM) refuse ANY transaction block —
+        // including the implicit one a joined multi-statement simple query runs in, so the
+        // batch MUST go one statement per protocol message. A failure mid-way leaves the
+        // earlier statements committed: the documented cost of the unwrapped path; the next
+        // plan re-converges from what actually landed.
+        for (const statement of rendered.statements) await runner(statement);
+      }
     }
 
     // Re-read the catalog so provenance records the def hashes of what NOW exists, not what we hoped
@@ -137,20 +176,42 @@ export async function executeReconcile(
     const bookkeeping: string[] = [];
     for (const identity of rendered.record) {
       const src = srcById.get(identity);
+      if (!src) {
+        throw new Error(`reconcile applied but ${identity} has no source object — provenance not recorded, investigate`);
+      }
+      // 'sql'-kind objects are invisible to the catalog: provenance records the source
+      // hash on both sides plus HOW TO REMOVE it (the escape hatch's whole contract).
+      if (src.kind === 'sql') {
+        bookkeeping.push(renderProvenanceUpsert(identity, src.hash, src.hash, 'sql', src.drop));
+        continue;
+      }
       const liveObj = liveById.get(identity);
-      if (!src || !liveObj) {
+      if (!liveObj) {
         throw new Error(`reconcile applied but ${identity} is not introspectable afterwards — provenance not recorded, investigate`);
       }
-      bookkeeping.push(renderProvenanceUpsert(identity, src.hash, liveObj.defHash));
+      const dropSql = src.kind === 'trigger' && src.table ? triggerDropSql(src.name, src.table) : undefined;
+      bookkeeping.push(renderProvenanceUpsert(identity, src.hash, liveObj.defHash, src.kind, dropSql));
     }
+    for (const m of rendered.migrate) bookkeeping.push(renderProvenanceMigrate(m.from, m.to));
     for (const identity of rendered.remove) bookkeeping.push(renderProvenanceDelete(identity));
     bookkeeping.push(renderSchemaLogInsert({
       kind: 'compute reconcile',
-      sql: rendered.statements.join(';\n') || '-- provenance-only (baseline/prune)',
+      sql: rendered.statements.join(';\n') || '-- provenance-only (baseline/rebaseline/prune)',
       outcome: 'applied',
       actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
       durationMs: now() - started,
     }));
+
+    if (atomic) {
+      const pidNow = Number((await runner(BACKEND_PID_SQL))[0]?.pid);
+      if (pidNow !== pidAtBegin) {
+        throw new Error(
+          `the session changed mid-transaction (backend pid ${pidAtBegin} → ${pidNow}) — the connection `
+          + `was swapped or recycled under the open transaction (pooler restart? server restart?), PostgreSQL `
+          + `aborted it, and NOTHING from this batch is applied. No bookkeeping was written; re-run the apply.`,
+        );
+      }
+    }
     await runner(bookkeeping.join(';\n'));
 
     if (atomic) await runner('COMMIT');
@@ -205,7 +266,7 @@ export function formatBytes(bytes: number): string {
 }
 
 const VERB_GLYPH: Record<string, string> = {
-  create: '+', replace: '~', drop: '-', refresh: '↻', baseline: '◦', prune: '·',
+  create: '+', replace: '~', drop: '-', refresh: '↻', baseline: '◦', rebaseline: '≈', prune: '·',
 };
 
 export function buildReconcileReport(plan: ReconcilePlan): string[] {
@@ -220,6 +281,16 @@ export function buildReconcileReport(plan: ReconcilePlan): string[] {
     lines.push(`estimated rebuild: ${formatBytes(plan.totalRebuildBytes)} across ${rebuilt.length} matview(s)`);
   }
   for (const d of plan.drift) lines.push(`! drift ${d.identity} — ${d.detail}`);
+  for (const r of plan.regrants) {
+    lines.push(`≠ regrant ${r.identity} — live grants differ from source (${r.statements.join('; ')})`);
+  }
+  for (const d of plan.dependencyDrift) {
+    const parts = [
+      ...(d.missing.length ? [`reads ${d.missing.join(', ')} undeclared`] : []),
+      ...(d.stale.length ? [`declares ${d.stale.join(', ')} but never reads it`] : []),
+    ];
+    lines.push(`! depends ${d.identity} — ${parts.join('; ')} (fix dependsOn in the descriptor)`);
+  }
   if (plan.needsBaseline.length > 0) {
     lines.push(`! needs baseline (${plan.needsBaseline.length}): ${plan.needsBaseline.join(', ')} — run with --baseline to record trust, once`);
   }
@@ -232,12 +303,15 @@ export function buildReconcileReport(plan: ReconcilePlan): string[] {
   return lines;
 }
 
-/** Anything that makes `--check` fail: pending work or unresolved findings. */
+/** Anything that makes `--check` fail: pending work or unresolved findings.
+ *  Baseline and rebaseline are explicit adoption the operator asked for, not findings. */
 export function checkFails(plan: ReconcilePlan): boolean {
-  return plan.actions.some((a) => a.action !== 'baseline')
+  return plan.actions.some((a) => a.action !== 'baseline' && a.action !== 'rebaseline')
     || plan.drift.length > 0
     || plan.needsBaseline.length > 0
-    || plan.blocked.length > 0;
+    || plan.blocked.length > 0
+    || plan.regrants.length > 0
+    || plan.dependencyDrift.length > 0;
 }
 
 // ---------------------------------------------------------------------------
@@ -253,25 +327,27 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
   };
 }
 
-async function readSqlDir(dir: string): Promise<SourceFile[]> {
-  let entries: string[];
-  try {
-    entries = await fs.readdir(dir);
-  } catch {
-    throw new Error(`No SQL source directory at ${dir} (set --sql-dir).`);
-  }
-  const files = entries.filter((f) => f.endsWith('.sql')).sort();
-  return Promise.all(files.map(async (file) => ({
-    file: path.join(dir, file),
-    sql: await fs.readFile(path.join(dir, file), 'utf-8'),
-  })));
-}
-
 export async function dbReconcileCommand(flags: Record<string, string>): Promise<void> {
-  const sqlDir = flags['sql-dir'] || DEFAULT_SQL_DIR;
   const apply = flags.apply === 'true';
   const check = flags.check === 'true';
 
+  // B7 tombstone — db/sql is retired and no longer read. Failing beats silently
+  // skipping: skipped files would leave live objects unmanaged.
+  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);
+  }
+
   let dbSource: DbSource;
   try {
     dbSource = resolveDbSource(flags);
@@ -292,6 +368,10 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     fail('--baseline only persists with --apply — on its own it records nothing (it silently no-op\'d before). Re-run with --apply, or drop --baseline to just see the plan (it already lists what needs baseline).');
     process.exit(1);
   }
+  if (flags.rebaseline === 'true' && !apply) {
+    fail('--rebaseline only persists with --apply — on its own it records nothing. Re-run with --apply, or drop --rebaseline to see the plan (source re-renders show as drop+create with reason "source changed").');
+    process.exit(1);
+  }
 
   // --rebuild and --baseline are opposite answers to the same "can't verify first contact" question.
   if (flags.rebuild === 'true' && flags.baseline === 'true') {
@@ -299,13 +379,18 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     process.exit(1);
   }
 
-  let sources: SourceFile[];
+  // The DECLARED derived layer (descriptors from the models barrel) — the one source
+  // stream — plus the pending table renames, so trigger provenance migrates.
+  let declared: DeclaredDerived | null = null;
   try {
-    sources = await readSqlDir(sqlDir);
+    declared = await loadDeclaredDerived(flags.models);
   } catch (err: any) {
     fail(err.message);
     process.exit(1);
   }
+  if (declared && declared.objects.length > 0) {
+    info(`${declared.objects.length} declared derived object(s) from the models barrel.`);
+  }
 
   let runner: QueryRunner;
   let end: (() => Promise<void>) | undefined;
@@ -319,9 +404,12 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
   }
 
   try {
-    const run = await executeReconcile(runner, sources, {
+    const run = await executeReconcile(runner, {
       apply,
+      declared: declared?.objects,
+      renamedTables: declared?.renamedTables,
       baseline: flags.baseline === 'true',
+      rebaseline: flags.rebaseline === 'true',
       rebuild: flags.rebuild === 'true',
       overwriteDrift: flags['overwrite-drift'] === 'true',
       actor: process.env.USER ?? null,
@@ -337,7 +425,10 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
       } else if (run.applied) {
         success(`Applied ${run.statements.length} statement(s); provenance and schema_log recorded.`);
         if (run.plan.actions.some((a) => a.action === 'baseline')) {
-          warn('baseline recorded trust WITHOUT verifying live matches source — on first contact it CANNOT compare a source hash to a live deparse, so it trusts your assertion, it does not check. If you need a guarantee that live == db/sql, drop the object and let reconcile recreate it (or --overwrite-drift when the plan reports drift).');
+          warn('baseline recorded trust WITHOUT verifying live matches source — on first contact it CANNOT compare a source hash to a live deparse, so it trusts your assertion, it does not check. If you need a guarantee that live == the declared source, drop the object and let reconcile recreate it (or --overwrite-drift when the plan reports drift).');
+        }
+        if (run.plan.actions.some((a) => a.action === 'rebaseline')) {
+          warn('rebaseline VERIFIED the live side (each object is byte-identical to what the reconciler last applied) and TRUSTED the source side (that your re-rendered source produces the same object). If a descriptor actually differs — a changed body, a renamed index — that difference is now recorded as applied and will NOT deploy until the source changes again. When unsure, rebuild instead: drop the flag and let the plan drop+create.');
         }
       } else if (apply) {
         success('Nothing to apply — derived layer matches source.');

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

@@ -2,15 +2,15 @@
  * `everystack db:sync` — make the database match your checkout. One verb,
  * both layers, for dev-stage databases (brick 5's core).
  *
- *   db:sync [--database-url <url>] [--models <barrel>] [--sql-dir db/sql]
- *           [--allow-drops] [--overwrite-drift] [--baseline] [--json]
+ *   db:sync [--database-url <url>] [--models <barrel>]
+ *           [--allow-drops] [--overwrite-drift] [--baseline] [--rebaseline] [--json]
  *
  * The edit loop's verb: fingerprint the live base state, apply the state
  * diff (tables + authz, one transaction, verified by re-diff), reconcile
- * the derived layer (functions/views/matviews) against db/sql, and report
- * where the database now is — "at fingerprint X, matching your checkout"
- * when everything converged. Hot-reload for the database; no artifact
- * produced, every act recorded in `everystack.schema_log`.
+ * the derived layer against the declared descriptors, and report where the
+ * database now is — "at fingerprint X, matching your checkout" when
+ * everything converged. Hot-reload for the database; no artifact produced,
+ * every act recorded in `everystack.schema_log`.
  *
  * The verdict is two-tier, honestly: CONVERGED means the state re-diff is
  * empty and the compute layer is clean — that is the exit-0 bar. The
@@ -34,6 +34,8 @@ import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { introspectSchema } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { generateMigrationSql, unmodeledTables } from '../migration-generate.js';
+import type { SequenceDescriptor } from '@everystack/model';
+import type { SourceObject } from '../derived-source.js';
 import {
   applyStateAndVerify,
   classifyGeneratedStatements,
@@ -50,10 +52,10 @@ import { planBackfills, readBackfillLog } from '../backfill.js';
 import { resolveModelsPath } from '../models-path.js';
 import { executeReconcile, buildReconcileReport, type ReconcileRun } from './db-reconcile.js';
 import { loadModels } from './db-generate.js';
+import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import { reportPipelineLastRun } from './pipeline-run.js';
 import { step, success, fail, info, warn } from '../output.js';
 
-const DEFAULT_SQL_DIR = 'db/sql';
 const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 
 // ---------------------------------------------------------------------------
@@ -64,8 +66,17 @@ export interface SyncOptions {
   allowDrops?: boolean;
   overwriteDrift?: boolean;
   baseline?: boolean;
+  /** Re-record provenance for source re-renders over verifiably-untouched live objects
+   *  (the db/sql-era migration) — see ReconcileOptions.rebaseline. */
+  rebaseline?: boolean;
   actor?: string | null;
   gitRef?: string | null;
+  /** Descriptor-compiled derived objects (the declared layer) — the one compute stream. */
+  declared?: SourceObject[];
+  /** Standalone sequences the modules declare (state — created before tables, fingerprinted). */
+  sequences?: SequenceDescriptor[];
+  /** Pending table renames — trigger provenance migrates instead of drop+create. */
+  renamedTables?: Record<string, string>;
   /** Injectable clock for tests. */
   now?: () => number;
 }
@@ -79,7 +90,7 @@ export interface SyncHooks {
 
 export interface SyncRun {
   state: StateSyncOutcome;
-  /** null = no db/sql sources — the compute layer is not declared, skipped. */
+  /** null = no declared derived layer — the compute step is skipped. */
   compute: ReconcileRun | null;
   declaredFingerprint: string;
   fingerprintMatch: boolean;
@@ -100,31 +111,34 @@ export interface SyncRun {
 export async function executeSync(
   runner: QueryRunner,
   models: ModelDescriptor[],
-  sources: SourceFile[] | null,
   options: SyncOptions = {},
   hooks: SyncHooks = {},
 ): Promise<SyncRun> {
   const current = await introspectSchema(runner);
   const liveAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
   const statements = generateMigrationSql(models, current, {
-    allowDrops: options.allowDrops, liveAuthz,
+    allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
   });
   hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
 
   const state = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
-    allowDrops: options.allowDrops,
+    allowDrops: options.allowDrops, sequences: options.sequences,
     actor: options.actor, gitRef: options.gitRef, now: options.now,
   });
   hooks.onStateDone?.(state);
 
-  const compute = sources === null ? null : await executeReconcile(runner, sources, {
+  // The declared derived layer is the one compute stream; nothing declared = skipped.
+  const compute = !options.declared?.length ? null : await executeReconcile(runner, {
     apply: true,
     baseline: options.baseline,
+    rebaseline: options.rebaseline,
     overwriteDrift: options.overwriteDrift,
+    declared: options.declared,
+    renamedTables: options.renamedTables,
     actor: options.actor, gitRef: options.gitRef, now: options.now,
   });
 
-  const declaredFingerprint = fingerprintModels(models).hash;
+  const declaredFingerprint = fingerprintModels(models, { sequences: options.sequences }).hash;
   const stateConverged = state.remaining.length === 0;
   // The compute bar, judged AFTER the apply: no refusal (drift/blocked stop the
   // whole batch) and nothing left unadopted (needsBaseline objects were not
@@ -182,7 +196,7 @@ export function buildSyncReport(run: SyncRun): string[] {
 
   // Compute.
   if (compute === null) {
-    lines.push('· compute: no db/sql directory — derived layer not declared, skipped');
+    lines.push('· compute: no derived layer declared — nothing to reconcile');
   } else {
     lines.push('compute:');
     for (const line of buildReconcileReport(compute.plan)) lines.push(`  ${line}`);
@@ -250,21 +264,39 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
   const modelsPath = resolveModelsPath(flags.models);
   const schemaOut = path.resolve(flags['schema-out'] || DEFAULT_SCHEMA_OUT);
   let models: ModelDescriptor[];
+  // The declared derived layer + sequences + renames — the same stream db:reconcile
+  // consumes. Loaded before the schema write: typed derived relations emit into it.
+  let declaredDb: DeclaredDerived | null = null;
   try {
     step(`Loading models from ${modelsPath}...`);
     models = await loadModels(modelsPath);
+    declaredDb = await loadDeclaredDerived(flags.models);
     info(`${models.length} model(s).`);
     // Same contract as db:generate: the drizzle runtime schema is a derived
     // artifact, refreshed from the models on every run.
     step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-    await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
+    await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: declaredDb?.derived }), 'utf8');
   } catch (err: any) {
     fail(err.message);
     process.exit(1);
   }
 
-  const sqlDir = flags['sql-dir'] || DEFAULT_SQL_DIR;
-  const sources = await readSqlDirIfPresent(sqlDir);
+  // B7 tombstone — db/sql is retired and no longer read; failing beats silently
+  // skipping (skipped files would leave live objects unmanaged).
+  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);
+  }
 
   step(connectingVia(dbSource));
   const { runner, end } = await createUrlRunner(dbSource.url);
@@ -273,11 +305,14 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
     const run = await executeSync(
       runner,
       models,
-      sources,
       {
+        declared: declaredDb?.objects,
+        sequences: declaredDb?.sequences,
+        renamedTables: declaredDb?.renamedTables,
         allowDrops: flags['allow-drops'] === 'true',
         overwriteDrift: flags['overwrite-drift'] === 'true',
         baseline: flags.baseline === 'true',
+        rebaseline: flags.rebaseline === 'true',
         actor: process.env.USER ?? null,
         gitRef: currentGitRef(),
       },
@@ -296,7 +331,7 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
           }
         },
         onStateDone: () => {
-          if (sources !== null) step(`Reconciling the derived layer against ${sqlDir}...`);
+          if (declaredDb?.objects.length) step('Reconciling the declared derived layer...');
         },
       },
     );

package/src/cli/db-build.ts

@@ -12,7 +12,8 @@
 
 import type { ModelDescriptor } from '@everystack/model';
 import type { TableContract, QueryRunner } from './authz-contract.js';
-import type { SourceFile } from './derived-source.js';
+import type { SourceObject } from './derived-source.js';
+import type { SequenceDescriptor } from '@everystack/model';
 import { compileDeclaredState } from './declared-diff.js';
 import { createUrlRunner } from './db-source.js';
 import { executeSync, buildSyncReport } from './commands/db-sync.js';
@@ -88,7 +89,10 @@ export interface BuildResult {
 }
 
 export interface BuildOptions {
-  sources?: SourceFile[] | null;
+  /** Descriptor-compiled derived objects (the declared layer). */
+  declared?: SourceObject[];
+  /** Standalone sequences (state — created before tables, in the fingerprint bar). */
+  sequences?: SequenceDescriptor[];
   actor?: string | null;
   gitRef?: string | null;
 }
@@ -106,7 +110,9 @@ export async function buildIntoDatabase(
   const { runner, end } = await createUrlRunner(url);
   try {
     const createdRoles = await ensureContractRoles(runner, models);
-    const run = await executeSync(runner, models, options.sources ?? null, {
+    const run = await executeSync(runner, models, {
+      declared: options.declared,
+      sequences: options.sequences,
       actor: options.actor ?? 'db-build',
       gitRef: options.gitRef ?? null,
     });