@everystack/cli 0.3.28 → 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,9 +23,11 @@
 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, type DbSource } from '../db-source.js';
+import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { fail } from '../output.js';
@@ -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,11 +68,12 @@ 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;
     if (dbSource.kind === 'url') {
-      note(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+      note(connectingVia(dbSource));
       ({ runner, end } = await createUrlRunner(dbSource.url));
     } else {
       note('Resolving deployed config...');
@@ -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, type DbSource } from '../db-source.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;
 }
@@ -70,13 +78,38 @@ export interface ReconcileRun {
  * Plan — and under `apply`, execute — one reconcile. Pure orchestration over
  * an injected QueryRunner; the CLI shell below owns flags, files, and exits.
  */
+/** 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. 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.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);
 
@@ -94,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: [] };
   }
 
@@ -102,14 +135,92 @@ export async function executeReconcile(
   await runner(ENSURE_RECONCILER_SQL.join(';\n'));
 
   const started = now();
-  let outcome = 'applied';
+
+  // Atomicity: the DDL and the provenance/schema_log that describe it go in ONE transaction, so a
+  // failure rolls the whole thing back — live and its bookkeeping can never diverge. That divergence
+  // (objects changed, provenance stale) is exactly the drift that strands a stage after a partial
+  // apply. The one exception is a batch with statements Postgres forbids inside a transaction block
+  // (CONCURRENTLY index builds, VACUUM); those self-commit, so we fall back to the unwrapped path.
+  const atomic = isTransactionalBatch(rendered.statements);
+
+  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
+    // would exist. Inside the transaction this reads the batch's own not-yet-committed writes.
+    const after = await introspectDerived(runner);
+    const liveById = new Map(after.objects.map((o) => [o.identity, o]));
+    const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
+
+    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 (!liveObj) {
+        throw new Error(`reconcile applied but ${identity} is not introspectable afterwards — provenance not recorded, investigate`);
+      }
+      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/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');
   } catch (err: any) {
-    outcome = 'failed';
-    // The batch rolled back; record the attempt, then surface the failure.
+    // Roll the whole batch back — no half-applied DDL, no stale provenance — THEN record the failed
+    // attempt in its own transaction (the memoir must survive the rollback).
+    if (atomic) {
+      try { await runner('ROLLBACK'); } catch { /* the connection may already be aborted */ }
+    }
     try {
       await runner(renderSchemaLogInsert({
         kind: 'compute reconcile', sql: rendered.statements.join(';\n'),
@@ -118,37 +229,31 @@ export async function executeReconcile(
         durationMs: now() - started,
       }));
     } catch { /* the memoir is best-effort on failure */ }
-    throw err;
-  }
-
-  // The batch committed — re-read the catalog so provenance records the def
-  // hashes of what NOW exists, not what we hoped would exist.
-  const after = await introspectDerived(runner);
-  const liveById = new Map(after.objects.map((o) => [o.identity, o]));
-  const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
-
-  const bookkeeping: string[] = [];
-  for (const identity of rendered.record) {
-    const src = srcById.get(identity);
-    const liveObj = liveById.get(identity);
-    if (!src || !liveObj) {
-      throw new Error(`reconcile applied but ${identity} is not introspectable afterwards — provenance not recorded, investigate`);
-    }
-    bookkeeping.push(renderProvenanceUpsert(identity, src.hash, liveObj.defHash));
+    throw explainReconcileError(err);
   }
-  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)',
-    outcome,
-    actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
-    durationMs: now() - started,
-  }));
-  await runner(bookkeeping.join(';\n'));
 
   return { plan, applied: true, statements: rendered.statements };
 }
 
+/**
+ * reconcile's `create` is a bare `CREATE` (no drop-first, no IF NOT EXISTS), so when its plan
+ * and reality disagree — a partial earlier run, a hand-created object — Postgres answers with a
+ * cryptic unique-violation on `pg_type`/`pg_class` instead of anything actionable. Turn that into
+ * a message that tells the operator what to do.
+ */
+export function explainReconcileError(err: unknown): Error {
+  const msg = String((err as any)?.message ?? err);
+  if (/pg_type_typname_nsp_index|pg_class_relname_nsp_index|already exists/i.test(msg)) {
+    return new Error(
+      `${msg}\n\nreconcile tried to CREATE a derived object whose name already exists — usually a partial `
+      + `earlier run or a hand-created object (its create is not idempotent). Resolve by explicitly dropping `
+      + `the colliding object (DROP MATERIALIZED VIEW / VIEW … CASCADE) and re-running, or, if the plan reports `
+      + `it as drift, re-run with --overwrite-drift.`,
+    );
+  }
+  return err instanceof Error ? err : new Error(msg);
+}
+
 // ---------------------------------------------------------------------------
 // Report rendering (pure).
 // ---------------------------------------------------------------------------
@@ -161,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[] {
@@ -176,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`);
   }
@@ -188,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -209,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);
@@ -241,18 +361,41 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     process.exit(1);
   }
 
-  let sources: SourceFile[];
+  // --baseline only writes under --apply (executeReconcile returns the plan and executes nothing
+  // when apply=false). Passing it alone used to print "recording provenance…" and exit 0 while
+  // persisting nothing — a silent no-op. Fail loudly instead; the plan already lists needsBaseline.
+  if (flags.baseline === 'true' && !apply) {
+    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') {
+    fail('--rebuild and --baseline are opposites: --baseline TRUSTS that live already matches source, --rebuild REBUILDS from source to guarantee it. Pick one.');
+    process.exit(1);
+  }
+
+  // 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;
   if (dbSource.kind === 'url') {
-    step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+    step(connectingVia(dbSource));
     ({ runner, end } = await createUrlRunner(dbSource.url));
   } else {
     step('Resolving deployed config...');
@@ -261,9 +404,13 @@ 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,
       gitRef: currentGitRef(),
@@ -277,6 +424,12 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
         fail(`not applied: ${run.refusal}`);
       } 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 == 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.');
       } else if (run.statements.length > 0) {