@everystack/cli 0.3.15 → 0.3.18

package/README.md

@@ -217,6 +217,8 @@ everystack db:psql --stage dev [-c SQL] # interactive psql / one-off query via L
 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: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)
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.15",
+  "version": "0.3.18",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/authz-contract.ts

@@ -353,8 +353,11 @@ export function rlsRowToDescriptor(row: RlsRow): {
  * meaningful grants, and exists only when migrations ran through drizzle's migrator
  * (so it appears on a deployed stage but not on a raw-applied local DB — pure noise
  * that would read as local↔remote drift). Same intent as the pg_depend extension filter.
+ * `everystack` is the runner's own bookkeeping (`schema_log`, `derived_provenance`) —
+ * the memoir must not shift the schema's content address: a database the runner has
+ * written to and a fresh one declaring the same models are the SAME state.
  */
-export const IGNORED_SCHEMAS = new Set(['drizzle']);
+export const IGNORED_SCHEMAS = new Set(['drizzle', 'everystack']);
 
 export interface ContractRows {
   rls: RlsRow[];

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

@@ -42,7 +42,7 @@ import {
 import { modelOwner } from '../authz-compile.js';
 import { writeContract, loadContract } from '../authz-contract-io.js';
 import { renderContractMarkdown } from '../authz-render.js';
-import { FUNCTIONS_SQL, catalogFunctionToDescriptor } from '../security-catalog.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { resolveModelsPath } from '../models-path.js';
 import { invokeAction } from '../aws.js';
@@ -50,15 +50,6 @@ import { step, success, fail, info, warn } from '../output.js';
 
 const DEFAULT_DIR = 'authz';
 
-/** Map a FUNCTIONS_SQL row to the minimal shape the contract records. */
-const mapFunctionRow = (row: any) => {
-  const d = catalogFunctionToDescriptor(row);
-  return {
-    schema: d.schema, name: d.name, securityDefiner: d.securityDefiner, hasSearchPath: d.hasSearchPath,
-    owner: d.owner, ownerBypassesRls: d.ownerBypassesRls,
-  };
-};
-
 /** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
 function lambdaRunner(region: string, fn: string): QueryRunner {
   return async (sql: string) => {
@@ -74,7 +65,7 @@ async function introspectStage(flags: Record<string, string>): Promise<AuthzCont
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
   step('Introspecting authorization (rls + grants + policies + secdef)...');
   const runner = lambdaRunner(config.region, opsFunction(config));
-  return introspectContract(runner, mapFunctionRow, FUNCTIONS_SQL);
+  return introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
 }
 
 export async function dbAuthzPullCommand(flags: Record<string, string>): Promise<void> {

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

@@ -0,0 +1,116 @@
+/**
+ * `everystack db:fingerprint` — where is this database, and does it match the
+ * models? The seed of `db:status`.
+ *
+ *   db:fingerprint [--stage <name> | --database-url <url>] [--models <barrel>] [--json]
+ *
+ * Introspects the live base schema (tables + constraints + authz) and prints
+ * its content-addressed fingerprint; loads the Models and prints the DECLARED
+ * fingerprint; says MATCH or MISMATCH (exit 1 — CI-able). A mismatch's next
+ * step is always `db:generate`, which shows the difference as SQL. The
+ * unfingerprinted report keeps partial coverage honest, and the derived layer
+ * is deliberately absent here — `db:reconcile --check` is its verifier.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { QueryRunner } from '../authz-contract.js';
+import { introspectSchema } from '../schema-introspect.js';
+import { introspectContract } from '../authz-contract.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
+import {
+  fingerprintLive,
+  fingerprintModels,
+  mapUnfingerprintedRows,
+  UNFINGERPRINTED_SQL,
+  type UnfingerprintedObject,
+} from '../schema-fingerprint.js';
+import { resolveModelsPath } from '../models-path.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+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';
+
+export interface FingerprintStatus {
+  live: string;
+  declared: string | null;
+  match: boolean | null;
+  unfingerprinted: UnfingerprintedObject[];
+}
+
+/** The testable core: live fingerprint, declared fingerprint, verdict, honesty report. */
+export async function computeFingerprintStatus(
+  runner: QueryRunner,
+  models: ModelDescriptor[] | null,
+): 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 unfingerprinted = mapUnfingerprintedRows((await runner(UNFINGERPRINTED_SQL)) as any[]);
+  return { live, declared, match: declared === null ? null : live === declared, unfingerprinted };
+}
+
+/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
+function lambdaRunner(region: string, fn: string): QueryRunner {
+  return async (sql: string) => {
+    const result: any = await invokeAction(region, fn, 'db:query', { sql });
+    if (result?.error) throw new Error(`Query failed: ${result.error}`);
+    return result?.rows ?? [];
+  };
+}
+
+export async function dbFingerprintCommand(flags: Record<string, string>): Promise<void> {
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const modelsPath = resolveModelsPath(flags.models);
+  let models: ModelDescriptor[] | null = null;
+  try {
+    models = await loadModels(modelsPath);
+  } catch {
+    // Live-only mode: no models barrel — still useful (what fingerprint is this DB at?).
+  }
+
+  let runner: QueryRunner;
+  let end: (() => Promise<void>) | undefined;
+  if (dbSource.kind === 'url') {
+    step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+    ({ runner, end } = await createUrlRunner(dbSource.url));
+  } else {
+    step('Resolving deployed config...');
+    const config = await resolveConfig(flags.stage);
+    runner = lambdaRunner(config.region, opsFunction(config));
+  }
+
+  try {
+    const status = await computeFingerprintStatus(runner, models);
+
+    if (flags.json === 'true') {
+      console.log(JSON.stringify(status, null, 2));
+    } else {
+      info(`live:     ${status.live}`);
+      if (status.declared === null) {
+        warn(`declared: (no models barrel at ${modelsPath} — live-only)`);
+      } else {
+        info(`declared: ${status.declared}`);
+        if (status.match) success('MATCH — the database is the state the models declare.');
+        else fail('MISMATCH — run `everystack db:generate` to see the difference as SQL.');
+      }
+      if (status.unfingerprinted.length > 0) {
+        warn(`unfingerprinted (${status.unfingerprinted.length}) — outside the base fingerprint and the derived manifest:`);
+        for (const u of status.unfingerprinted) info(`  ${u.kind}: ${u.identity}`);
+      }
+      info('derived layer (functions/views/matviews): verified separately by `db:reconcile --check`.');
+    }
+
+    if (status.match === false) process.exit(1);
+  } finally {
+    await end?.();
+  }
+}

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

@@ -26,9 +26,10 @@ 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 { introspectContract, type QueryRunner } from '../authz-contract.js';
-import { FUNCTIONS_SQL, catalogFunctionToDescriptor } from '../security-catalog.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
+import { applyStateAndVerify, classifyGeneratedStatements, currentGitRef, type StateSyncOutcome } from '../state-apply.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
@@ -45,14 +46,8 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
   };
 }
 
-/** Map a FUNCTIONS_SQL row to the minimal shape the authz contract records. */
-const mapFunctionRow = (row: any) => {
-  const d = catalogFunctionToDescriptor(row);
-  return { schema: d.schema, name: d.name, securityDefiner: d.securityDefiner, hasSearchPath: d.hasSearchPath, owner: d.owner, ownerBypassesRls: d.ownerBypassesRls };
-};
-
 /** Import the app's Model barrel and return its `models` array (runs under tsx, so TS imports work). */
-async function loadModels(modelsPath: string): Promise<ModelDescriptor[]> {
+export async function loadModels(modelsPath: string): Promise<ModelDescriptor[]> {
   const abs = path.resolve(modelsPath);
   let mod: any;
   try {
@@ -141,9 +136,12 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     return;
   }
 
+  const apply = flags.apply === 'true';
   let models: ModelDescriptor[];
   let current;
   let liveAuthz;
+  let runner!: QueryRunner;
+  let end: (() => Promise<void>) | undefined;
   try {
     step(`Loading models from ${modelsPath}...`);
     models = await loadModels(modelsPath);
@@ -154,8 +152,10 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
     await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
     const dbSource: DbSource = resolveDbSource(flags);
-    let runner: QueryRunner;
-    let end: (() => Promise<void>) | undefined;
+    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.');
+      process.exit(1);
+    }
     if (dbSource.kind === 'url') {
       step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
       ({ runner, end } = await createUrlRunner(dbSource.url));
@@ -168,8 +168,8 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     step('Introspecting live database (columns + constraints)...');
     current = await introspectSchema(runner);
     step('Introspecting authorization (rls + grants + policies)...');
-    liveAuthz = await introspectContract(runner, mapFunctionRow, FUNCTIONS_SQL);
-    await end?.();
+    liveAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+    if (!apply) await end?.();
   } catch (err: any) {
     fail(err.message);
     info('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
@@ -190,6 +190,43 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     process.exit(0);
   }
 
+  // --apply: no tape. Print the plan, execute the executable subset as one
+  // transaction, record it in schema_log, then VERIFY by re-diffing — done
+  // means db:generate is a no-op again, not "a file was written".
+  if (apply) {
+    const classified = classifyGeneratedStatements(statements);
+    info(`Plan — ${statements.length} statement(s):`);
+    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 — NOT executed (re-run with --allow-drops to include them).`);
+    if (classified.notices.length) info(`${classified.notices.length} notice(s) — manual follow-ups, nothing executed for them.`);
+    if (classified.executable.length === 0) {
+      success('Nothing executable — only held/notice items differ.');
+      process.exit(0);
+    }
+    step(`Applying ${classified.executable.length} statement(s) as one transaction, then verifying by re-diff...`);
+    let outcome: StateSyncOutcome;
+    try {
+      outcome = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
+        allowDrops, actor: process.env.USER ?? null, gitRef: currentGitRef(),
+      });
+    } catch (err: any) {
+      fail(`Apply failed and rolled back: ${err.message}`);
+      process.exit(1);
+    }
+    await end?.();
+    if (outcome.remaining.length > 0) {
+      fail(`Verify FAILED — ${outcome.remaining.length} statement(s) still differ after apply:`);
+      for (const s of outcome.remaining) console.log(s);
+      process.exit(1);
+    }
+    const heldNote = classified.heldDrops.length ? ` (${classified.heldDrops.length} held drop(s) remain, by design)` : '';
+    success(`Applied and verified — db:generate is a no-op again${heldNote}. Recorded in everystack.schema_log.`);
+    info(`fingerprint: ${outcome.fromFingerprint.slice(0, 12)} → ${outcome.toFingerprint.slice(0, 12)}`);
+    process.exit(0);
+  }
+
   const journalPath = path.join(migrationsDir, 'meta', '_journal.json');
   let journal: Journal;
   try {

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

@@ -24,7 +24,6 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { execSync } from 'node:child_process';
 import type { QueryRunner } from '../authz-contract.js';
 import { parseSqlSources, type SourceFile } from '../derived-source.js';
 import { introspectDerived } from '../derived-introspect.js';
@@ -37,6 +36,7 @@ import {
   ENSURE_RECONCILER_SQL,
 } from '../derived-apply.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.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';
@@ -223,14 +223,6 @@ async function readSqlDir(dir: string): Promise<SourceFile[]> {
   })));
 }
 
-function currentGitRef(): string | null {
-  try {
-    return execSync('git rev-parse HEAD', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
-  } catch {
-    return null;
-  }
-}
-
 export async function dbReconcileCommand(flags: Record<string, string>): Promise<void> {
   const sqlDir = flags['sql-dir'] || DEFAULT_SQL_DIR;
   const apply = flags.apply === 'true';

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

@@ -0,0 +1,332 @@
+/**
+ * `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]
+ *
+ * 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 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
+ * fingerprint MATCH is the strong content-address claim on top, and every
+ * legitimate mismatch is explained by name: held drops (the checkout
+ * declares a removal `--allow-drops` hasn't confirmed) or unmodeled tables
+ * (live tables no model declares — untouched by design). Drift on derived
+ * objects refuses, exactly as `db:reconcile` does; nothing is ever
+ * overwritten silently.
+ *
+ * Sync applies, so it needs a direct connection (--database-url or
+ * DATABASE_URL) — the ops Lambda query path is read-only by design.
+ * Protected stages are the plan flow's territory (db:plan → db:apply,
+ * brick 7), not sync's.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { ModelDescriptor } from '@everystack/model';
+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 {
+  applyStateAndVerify,
+  classifyGeneratedStatements,
+  currentGitRef,
+  type ClassifiedStatements,
+  type StateSyncOutcome,
+} from '../state-apply.js';
+import { fingerprintModels } from '../schema-fingerprint.js';
+import { compileDrizzleSource } from '../schema-source.js';
+import type { SourceFile } from '../derived-source.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { resolveModelsPath } from '../models-path.js';
+import { executeReconcile, buildReconcileReport, type ReconcileRun } from './db-reconcile.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const DEFAULT_SQL_DIR = 'db/sql';
+const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
+
+// ---------------------------------------------------------------------------
+// The testable core.
+// ---------------------------------------------------------------------------
+
+export interface SyncOptions {
+  allowDrops?: boolean;
+  overwriteDrift?: boolean;
+  baseline?: boolean;
+  actor?: string | null;
+  gitRef?: string | null;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+export interface SyncHooks {
+  /** Fires after the state diff is computed, BEFORE anything executes — the review seam. */
+  onStatePlan?: (statements: string[], classified: ClassifiedStatements) => void;
+  /** Fires after the state layer applied and verified, before the compute reconcile. */
+  onStateDone?: (state: StateSyncOutcome) => void;
+}
+
+export interface SyncRun {
+  state: StateSyncOutcome;
+  /** null = no db/sql sources — the compute layer is not declared, skipped. */
+  compute: ReconcileRun | null;
+  declaredFingerprint: string;
+  fingerprintMatch: boolean;
+  /** Live tables no model declares — untouched, and an honest MISMATCH cause. */
+  unmodeled: string[];
+  /** The state bar: the post-apply re-diff is empty. */
+  stateConverged: boolean;
+  /** The compute bar: applied (or nothing to do), no refusal, no pending findings. */
+  computeClean: boolean;
+  converged: boolean;
+}
+
+/**
+ * One sync: state first (derived objects may depend on new columns), then
+ * compute, then the verdict. Pure orchestration over an injected QueryRunner;
+ * the CLI shell below owns flags, files, and exits.
+ */
+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,
+  });
+  hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
+
+  const state = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
+    allowDrops: options.allowDrops,
+    actor: options.actor, gitRef: options.gitRef, now: options.now,
+  });
+  hooks.onStateDone?.(state);
+
+  const compute = sources === null ? null : await executeReconcile(runner, sources, {
+    apply: true,
+    baseline: options.baseline,
+    overwriteDrift: options.overwriteDrift,
+    actor: options.actor, gitRef: options.gitRef, now: options.now,
+  });
+
+  const declaredFingerprint = fingerprintModels(models).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
+  // touched — --baseline records the trust). Executed actions are convergence,
+  // not pending work, so `checkFails` (the pre-apply CI lens) is wrong here.
+  const computeClean = compute === null
+    || (!compute.refusal && compute.plan.needsBaseline.length === 0);
+
+  return {
+    state,
+    compute,
+    declaredFingerprint,
+    fingerprintMatch: state.toFingerprint === declaredFingerprint,
+    unmodeled: unmodeledTables(models, state.after.snapshot),
+    stateConverged,
+    computeClean,
+    converged: stateConverged && computeClean,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Report rendering (pure).
+// ---------------------------------------------------------------------------
+
+const short = (hash: string): string => hash.slice(0, 12);
+
+export function buildSyncReport(run: SyncRun): string[] {
+  const lines: string[] = [];
+  const { state, compute } = run;
+
+  // State.
+  if (state.remaining.length > 0) {
+    lines.push(`! state: ${state.remaining.length} statement(s) still differ after apply — investigate (db:generate shows them as SQL)`);
+  } else if (state.applied) {
+    lines.push(`~ state: applied ${state.classified.executable.length} statement(s) — verified, re-diff empty`);
+  } else {
+    lines.push('= state: in sync — no table/authz changes');
+  }
+  if (state.classified.heldDrops.length > 0) {
+    lines.push(`! ${state.classified.heldDrops.length} destructive change(s) held back — NOT executed (re-run with --allow-drops to include them)`);
+  }
+  if (state.classified.notices.length > 0) {
+    lines.push(`· ${state.classified.notices.length} notice(s) — manual follow-ups, nothing executed for them`);
+  }
+
+  // Compute.
+  if (compute === null) {
+    lines.push('· compute: no db/sql directory — derived layer not declared, skipped');
+  } else {
+    lines.push('compute:');
+    for (const line of buildReconcileReport(compute.plan)) lines.push(`  ${line}`);
+    if (compute.refusal) lines.push(`! compute not applied: ${compute.refusal}`);
+    if (compute.plan.needsBaseline.length > 0) {
+      lines.push('! first contact with existing derived objects — re-run with --baseline to record trust, once');
+    }
+  }
+
+  // Fingerprint.
+  lines.push(
+    state.toFingerprint === state.fromFingerprint
+      ? `fingerprint: ${short(state.toFingerprint)} (unchanged)`
+      : `fingerprint: ${short(state.fromFingerprint)} → ${short(state.toFingerprint)}`,
+  );
+  if (run.fingerprintMatch) {
+    lines.push('MATCH — the database is the state your checkout declares');
+  } else if (run.stateConverged) {
+    const causes: string[] = [];
+    if (state.classified.heldDrops.length > 0) {
+      causes.push(`${state.classified.heldDrops.length} held drop(s) — the checkout declares their removal; --allow-drops completes it`);
+    }
+    if (run.unmodeled.length > 0) {
+      causes.push(`${run.unmodeled.length} unmodeled table(s): ${run.unmodeled.join(', ')} — undeclared, left untouched`);
+    }
+    lines.push(causes.length > 0
+      ? `MISMATCH vs declared ${short(run.declaredFingerprint)}, explained: ${causes.join('; ')}`
+      : `MISMATCH vs declared ${short(run.declaredFingerprint)} — run db:fingerprint for the honesty report, db:generate for the difference as SQL`);
+  }
+
+  return lines;
+}
+
+/** The exit-1 bar: sync failed iff it did not converge. */
+export function syncFailed(run: SyncRun): boolean {
+  return !run.converged;
+}
+
+// ---------------------------------------------------------------------------
+// The CLI shell.
+// ---------------------------------------------------------------------------
+
+async function readSqlDirIfPresent(dir: string): Promise<SourceFile[] | null> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return null;
+  }
+  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 dbSyncCommand(flags: Record<string, string>): Promise<void> {
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (dbSource.kind !== 'url') {
+    fail('db:sync applies — it needs a direct connection (--database-url or DATABASE_URL). The ops Lambda query path is read-only by design; protected stages take the plan flow, not sync.');
+    process.exit(1);
+  }
+
+  const modelsPath = resolveModelsPath(flags.models);
+  const schemaOut = path.resolve(flags['schema-out'] || DEFAULT_SCHEMA_OUT);
+  let models: ModelDescriptor[];
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    models = await loadModels(modelsPath);
+    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');
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const sqlDir = flags['sql-dir'] || DEFAULT_SQL_DIR;
+  const sources = await readSqlDirIfPresent(sqlDir);
+
+  step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+  const { runner, end } = await createUrlRunner(dbSource.url);
+
+  try {
+    const run = await executeSync(
+      runner,
+      models,
+      sources,
+      {
+        allowDrops: flags['allow-drops'] === 'true',
+        overwriteDrift: flags['overwrite-drift'] === 'true',
+        baseline: flags.baseline === 'true',
+        actor: process.env.USER ?? null,
+        gitRef: currentGitRef(),
+      },
+      {
+        onStatePlan: (statements, classified) => {
+          if (classified.executable.length > 0) {
+            info(`state plan — ${classified.executable.length} statement(s):`);
+            console.log('');
+            for (const s of statements) console.log(s.endsWith(';') ? s : `${s};`);
+            console.log('');
+            step('Applying state as one transaction, then verifying by re-diff...');
+          }
+        },
+        onStateDone: () => {
+          if (sources !== null) step(`Reconciling the derived layer against ${sqlDir}...`);
+        },
+      },
+    );
+
+    if (flags.json === 'true') {
+      console.log(JSON.stringify({
+        state: {
+          applied: run.state.applied,
+          executed: run.state.classified.executable.length,
+          heldDrops: run.state.classified.heldDrops.length,
+          notices: run.state.classified.notices.length,
+          remaining: run.state.remaining,
+          fromFingerprint: run.state.fromFingerprint,
+          toFingerprint: run.state.toFingerprint,
+        },
+        compute: run.compute === null ? null : {
+          ...run.compute.plan,
+          applied: run.compute.applied,
+          refusal: run.compute.refusal ?? null,
+        },
+        declaredFingerprint: run.declaredFingerprint,
+        fingerprintMatch: run.fingerprintMatch,
+        unmodeled: run.unmodeled,
+        converged: run.converged,
+      }, null, 2));
+    } else {
+      for (const line of buildSyncReport(run)) info(line);
+      console.log('');
+      if (!run.converged) {
+        fail('NOT converged — fix the findings above and re-run db:sync.');
+      } else if (run.fingerprintMatch) {
+        success(`In sync at fingerprint ${short(run.state.toFingerprint)} — the database matches your checkout.`);
+      } else {
+        success('Synced — state and compute converged (the content-address difference is explained above).');
+      }
+    }
+
+    if (syncFailed(run)) process.exit(1);
+  } catch (err: any) {
+    fail(`Sync failed and rolled back: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await end?.();
+  }
+}

package/src/cli/derived-apply.ts

@@ -153,10 +153,18 @@ export interface SchemaLogEntry {
   gitRef?: string | null;
   planRef?: string | null;
   durationMs?: number;
+  fromFingerprint?: string | null;
+  toFingerprint?: string | null;
 }
 
 export function renderSchemaLogInsert(entry: SchemaLogEntry): string {
   const duration = entry.durationMs === undefined ? 'NULL' : String(Math.round(entry.durationMs));
-  return `INSERT INTO everystack.schema_log (kind, actor, git_ref, plan_ref, sql, duration_ms, outcome)
-VALUES (${escapeLiteral(entry.kind)}, ${nullable(entry.actor)}, ${nullable(entry.gitRef)}, ${nullable(entry.planRef)}, ${escapeLiteral(entry.sql)}, ${duration}, ${escapeLiteral(entry.outcome)})`;
+  return `INSERT INTO everystack.schema_log (kind, actor, git_ref, plan_ref, from_fingerprint, to_fingerprint, sql, duration_ms, outcome)
+VALUES (${escapeLiteral(entry.kind)}, ${nullable(entry.actor)}, ${nullable(entry.gitRef)}, ${nullable(entry.planRef)}, ${nullable(entry.fromFingerprint)}, ${nullable(entry.toFingerprint)}, ${escapeLiteral(entry.sql)}, ${duration}, ${escapeLiteral(entry.outcome)})
+RETURNING id`;
+}
+
+/** Fill in the to-side fingerprint once post-apply introspection knows it. */
+export function renderSchemaLogFingerprintUpdate(id: number, toFingerprint: string): string {
+  return `UPDATE everystack.schema_log SET to_fingerprint = ${escapeLiteral(toFingerprint)} WHERE id = ${Math.floor(id)}`;
 }

package/src/cli/index.ts

@@ -12,6 +12,8 @@ import { dbAuthzPullCommand, dbAuthzDiffCommand, dbAuthzTestCommand, dbAuthzOwne
 import { dbGenerateCommand } from './commands/db-generate.js';
 import { dbPullCommand } from './commands/db-pull.js';
 import { dbReconcileCommand } from './commands/db-reconcile.js';
+import { dbFingerprintCommand } from './commands/db-fingerprint.js';
+import { dbSyncCommand } from './commands/db-sync.js';
 import { dbSnapshotCommand, dbSnapshotsCommand } from './commands/db-snapshot.js';
 import { dbBackupProbeCommand, dbBackupCommand, dbBackupsCommand, dbRestoreCommand, dbBackupDownloadCommand } from './commands/db-backup.js';
 import { consoleCommand } from './commands/console.js';
@@ -176,6 +178,12 @@ async function main() {
     case 'db:reconcile':
       await dbReconcileCommand(flags);
       break;
+    case 'db:fingerprint':
+      await dbFingerprintCommand(flags);
+      break;
+    case 'db:sync':
+      await dbSyncCommand(flags);
+      break;
     case 'db:authz:pull':
       await dbAuthzPullCommand(flags);
       break;
@@ -295,10 +303,12 @@ Usage:
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
-  everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--allow-drops]  Diff models vs the live DB → write the next migration (never touches the DB; DROPs held back unless --allow-drops)
+  everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops)
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
+  everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--sql-dir db/sql] [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--overwrite-drift] [--json]  Reconcile the derived layer (functions/views/matviews) against db/sql sources: plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (direct connection only) and records provenance + schema_log. Hand-edits are drift (never overwritten silently); first contact with existing objects wants --baseline, once.
+  everystack db:sync           [--database-url <url>] [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against db/sql, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
   everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
   everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)

package/src/cli/schema-fingerprint.ts

@@ -0,0 +1,243 @@
+/**
+ * schema-fingerprint — the content address of the base schema (brick 2 of the
+ * migration-authority plan).
+ *
+ * A schema STATE is a fingerprint: sha256 over the canonical form of the data
+ * layer (tables, columns with pg-precise types, PK, uniques, checks, FKs,
+ * indexes, enums) AND the authorization layer (RLS flags, grants, column
+ * grants, policies) — the security posture is part of the state. The prize is
+ * an identity: `fingerprintState(introspected) === fingerprintModels(models)`
+ * exactly when `db:generate` is a no-op. The database's actual schema — not
+ * any bookkeeping — is the authority; the fingerprint is how it testifies.
+ *
+ * Normalization decisions (the canonical form is versioned; changing any of
+ * these bumps FINGERPRINT_VERSION so hashes never lie across formats):
+ *
+ *  - CONTENT, NOT NAMES, for constraints and indexes: pg's default names
+ *    (`_fkey`, `_key`) and model-generated names describe the same state, and
+ *    the diff already matches by content. Constraint/index names are excluded.
+ *    Policy names ARE included — the authz compiler emits them
+ *    deterministically and they are the policy's identity in the contract.
+ *  - Column ORDER is ignored (sorted by name): a table built by CREATE and
+ *    the same table built by ALTER ADD COLUMN are the same state. Enum VALUE
+ *    order is kept — it is semantic. PK / unique / index column order is kept
+ *    — it is semantic.
+ *  - The handler-side `columns` exposure block (hidden/protected) is excluded
+ *    — it is not a database fact.
+ *  - FUNCTIONS are excluded — they belong to the derived layer, whose own
+ *    content hashes (derived-introspect) cover them. Base fingerprint + derived
+ *    manifest together are the full schema state.
+ *  - Deparse stability caveat, stated once: policy/check predicates hash as
+ *    Postgres deparses them; a major-version deparser change can shift
+ *    fingerprints. The version prefix plus the re-diff path keep that honest.
+ *
+ * Coverage is partial and SAYS SO: `UNFINGERPRINTED_SQL` enumerates what the
+ * base fingerprint does not see (standalone sequences, triggers, domains,
+ * composite types, foreign/partitioned tables, extensions) so partial
+ * coverage reads as a report, never as "covered everything".
+ */
+
+import { createHash } from 'node:crypto';
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot, TableSchema } from './schema-introspect.js';
+import type { AuthzContract, TableContract } from './authz-contract.js';
+import { compileTableSchema, compileEnums } from './schema-compile.js';
+import { compileTableContract } from './authz-compile.js';
+
+export const FINGERPRINT_VERSION = 1;
+
+// ---------------------------------------------------------------------------
+// Canonical form.
+// ---------------------------------------------------------------------------
+
+/** JSON.stringify with recursively sorted object keys — key order can never matter. */
+export function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const byKey = <T>(items: T[], key: (item: T) => string): T[] =>
+  [...items].sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+
+function canonicalTable(table: TableSchema): Record<string, unknown> {
+  return {
+    table: table.table,
+    columns: byKey(
+      table.columns.map((c) => ({ name: c.name, type: c.type, notNull: c.notNull, default: c.default })),
+      (c) => c.name,
+    ),
+    primaryKey: table.primaryKey,
+    // Content, not names: a pg-default `_key` and a model-named unique are the same state.
+    uniques: byKey(table.uniques.map((u) => ({ columns: u.columns })), (u) => u.columns.join(',')),
+    checks: byKey(table.checks.map((c) => ({ expr: c.expr })), (c) => c.expr),
+    foreignKeys: byKey(
+      table.foreignKeys.map((f) => ({
+        columns: f.columns, refTable: f.refTable, refColumns: f.refColumns,
+        ...(f.onDelete ? { onDelete: f.onDelete } : {}),
+        ...(f.onUpdate ? { onUpdate: f.onUpdate } : {}),
+      })),
+      (f) => stableStringify(f),
+    ),
+    indexes: byKey(
+      table.indexes.map((i) => ({ columns: i.columns, unique: i.unique, ...(i.where ? { where: i.where } : {}) })),
+      (i) => stableStringify(i),
+    ),
+  };
+}
+
+function canonicalAuthzTable(contract: TableContract): Record<string, unknown> {
+  return {
+    table: contract.table,
+    rls: { enabled: contract.rls.enabled, forced: contract.rls.forced },
+    grants: Object.fromEntries(
+      Object.entries(contract.grants)
+        .map(([role, privs]) => [role, [...privs].sort()] as const)
+        .sort(([a], [b]) => (a < b ? -1 : 1)),
+    ),
+    ...(contract.columnGrants && Object.keys(contract.columnGrants).length > 0
+      ? {
+          columnGrants: Object.fromEntries(
+            Object.entries(contract.columnGrants)
+              .map(([role, byPriv]) => [
+                role,
+                Object.fromEntries(
+                  Object.entries(byPriv)
+                    .map(([priv, cols]) => [priv, [...cols].sort()] as const)
+                    .sort(([a], [b]) => (a < b ? -1 : 1)),
+                ),
+              ] as const)
+              .sort(([a], [b]) => (a < b ? -1 : 1)),
+          ),
+        }
+      : {}),
+    policies: byKey(
+      contract.policies.map((p) => ({
+        name: p.name, command: p.command, roles: [...p.roles].sort(),
+        permissive: p.permissive, using: p.using, check: p.check,
+      })),
+      (p) => p.name,
+    ),
+    // The handler-side columns exposure block is NOT a database fact — excluded.
+  };
+}
+
+export interface CanonicalState {
+  v: number;
+  tables: Array<Record<string, unknown>>;
+  enums: Array<{ name: string; values: string[] }>;
+  authz: Array<Record<string, unknown>>;
+}
+
+export function canonicalizeState(
+  snapshot: SchemaSnapshot,
+  authzTables: TableContract[],
+): CanonicalState {
+  return {
+    v: FINGERPRINT_VERSION,
+    tables: byKey(snapshot.tables.map(canonicalTable), (t) => String(t.table)),
+    enums: byKey(
+      (snapshot.enums ?? []).map((e) => ({ name: e.name, values: e.values })),
+      (e) => e.name,
+    ),
+    authz: byKey(authzTables.map(canonicalAuthzTable), (t) => String(t.table)),
+  };
+}
+
+export interface Fingerprint {
+  /** sha256 hex over the canonical form. */
+  hash: string;
+  /** The canonical form itself — for diff display and debugging, never for storage. */
+  canonical: CanonicalState;
+}
+
+export function fingerprintState(
+  snapshot: SchemaSnapshot,
+  authzTables: TableContract[],
+): Fingerprint {
+  const canonical = canonicalizeState(snapshot, authzTables);
+  return { hash: createHash('sha256').update(stableStringify(canonical)).digest('hex'), canonical };
+}
+
+/** The DECLARED state: compile the models to the same canonical shape and hash it. */
+export function fingerprintModels(
+  models: ModelDescriptor[],
+  opts: { schema?: string } = {},
+): Fingerprint {
+  const snapshot: SchemaSnapshot = {
+    tables: models.map((m) => compileTableSchema(m, opts)),
+    enums: compileEnums(models),
+  };
+  const authzTables = models.map((m) => compileTableContract(m, opts));
+  return fingerprintState(snapshot, authzTables);
+}
+
+/** Convenience: the live side, from the two existing introspections. */
+export function fingerprintLive(snapshot: SchemaSnapshot, contract: AuthzContract): Fingerprint {
+  return fingerprintState(snapshot, contract.tables);
+}
+
+// ---------------------------------------------------------------------------
+// The honesty report: what the base fingerprint does NOT see.
+// ---------------------------------------------------------------------------
+
+/**
+ * Objects outside both the base fingerprint (this module) and the derived
+ * manifest (derived-introspect): standalone sequences (serial-owned ones are
+ * column defaults, already fingerprinted), triggers, domains, composite
+ * types, foreign tables, partitioned tables, and installed extensions.
+ */
+export const UNFINGERPRINTED_SQL = `
+SELECT 'sequence' AS kind, n.nspname || '.' || c.relname AS identity
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind = 'S'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend d
+    WHERE d.objid = c.oid AND d.deptype IN ('a', 'i') AND d.refobjsubid > 0
+  )
+UNION ALL
+SELECT 'trigger', n.nspname || '.' || c.relname || '.' || t.tgname
+FROM pg_trigger t
+JOIN pg_class c ON c.oid = t.tgrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE NOT t.tgisinternal
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'
+UNION ALL
+SELECT CASE ty.typtype WHEN 'd' THEN 'domain' ELSE 'composite type' END,
+       n.nspname || '.' || ty.typname
+FROM pg_type ty
+JOIN pg_namespace n ON n.oid = ty.typnamespace
+LEFT JOIN pg_class tc ON tc.oid = ty.typrelid
+WHERE (ty.typtype = 'd' OR (ty.typtype = 'c' AND tc.relkind = 'c'))
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = ty.oid AND d.deptype = 'e')
+UNION ALL
+SELECT CASE c.relkind WHEN 'f' THEN 'foreign table' ELSE 'partitioned table' END,
+       n.nspname || '.' || c.relname
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind IN ('f', 'p')
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'
+UNION ALL
+SELECT 'extension', e.extname
+FROM pg_extension e
+WHERE e.extname <> 'plpgsql'
+ORDER BY 1, 2;
+`.trim();
+
+export interface UnfingerprintedObject {
+  kind: string;
+  identity: string;
+}
+
+export function mapUnfingerprintedRows(rows: Array<{ kind: unknown; identity: unknown }>): UnfingerprintedObject[] {
+  return rows.map((r) => ({ kind: String(r.kind), identity: String(r.identity) }));
+}

package/src/cli/security-catalog.ts

@@ -150,6 +150,16 @@ export function catalogFunctionToDescriptor(row: FunctionRow): FunctionDescripto
   };
 }
 
+/**
+ * The FUNCTIONS_SQL row → authz-contract function shape, as one shared map —
+ * every `introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL)` call
+ * site uses this instead of keeping its own copy.
+ */
+export const contractFunctionRow = (row: any): { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean; owner?: string; ownerBypassesRls?: boolean } => {
+  const d = catalogFunctionToDescriptor(row);
+  return { schema: d.schema, name: d.name, securityDefiner: d.securityDefiner, hasSearchPath: d.hasSearchPath, owner: d.owner, ownerBypassesRls: d.ownerBypassesRls };
+};
+
 interface RelationRow {
   schema: string;
   name: string;

package/src/cli/state-apply.ts

@@ -0,0 +1,210 @@
+/**
+ * state-apply — apply db:generate's live-computed diff directly, no tape.
+ *
+ * The state layer's analog of the derived reconciler's apply path: the diff
+ * is computed fresh against the live catalog (it cannot be stale, cannot be
+ * skipped, and has nothing numbered to collide), executed as ONE batch (one
+ * implicit transaction), and recorded in `everystack.schema_log` with the
+ * full SQL text. Held drops and notices are comments by construction and are
+ * never executed — the --allow-drops posture decides what is real DDL long
+ * before this module sees it.
+ *
+ * This retires the drizzle folder as the transport for table changes. The
+ * review discipline the tape file used to provide moves to the printed plan:
+ * the command shows every statement (including what it is NOT running)
+ * before anything executes. Fingerprint pinning (the edge runner) later
+ * upgrades "computed against the database just now" to "verified against a
+ * named state at both ends" — but nothing here needs a folder.
+ */
+
+import { execSync } from 'node:child_process';
+import type { ModelDescriptor } from '@everystack/model';
+import { introspectContract, type AuthzContract, type QueryRunner } from './authz-contract.js';
+import { introspectSchema, type SchemaSnapshot } from './schema-introspect.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog.js';
+import { generateMigrationSql, HELD_DROP_PREFIX } from './migration-generate.js';
+import { fingerprintLive } from './schema-fingerprint.js';
+import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply.js';
+
+const NOTICE_PREFIX = '-- NOTICE';
+
+/** Every line is a comment (or blank) — nothing executable inside. */
+function isPureComment(statement: string): boolean {
+  return statement
+    .split('\n')
+    .every((line) => line.trim() === '' || line.trim().startsWith('--'));
+}
+
+export interface ClassifiedStatements {
+  /** Real DDL (possibly carrying leading -- WARNING lines) — what apply runs. */
+  executable: string[];
+  /** Destructive changes held back as comments (re-run with --allow-drops). */
+  heldDrops: string[];
+  /** Manual follow-ups / rename notices — comments, never executed. */
+  notices: string[];
+}
+
+export function classifyGeneratedStatements(statements: string[]): ClassifiedStatements {
+  const executable: string[] = [];
+  const heldDrops: string[] = [];
+  const notices: string[] = [];
+  for (const statement of statements) {
+    if (statement.startsWith(HELD_DROP_PREFIX)) heldDrops.push(statement);
+    else if (statement.startsWith(NOTICE_PREFIX) || isPureComment(statement)) notices.push(statement);
+    else executable.push(statement);
+  }
+  return { executable, heldDrops, notices };
+}
+
+/** The current git HEAD, for schema_log's intent pointer. Null outside a repo. */
+export function currentGitRef(): string | null {
+  try {
+    return execSync('git rev-parse HEAD', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+export interface StateApplyOptions {
+  actor?: string | null;
+  gitRef?: string | null;
+  planRef?: string | null;
+  /** The live base fingerprint before this apply (schema_log's from-side). */
+  fromFingerprint?: string | null;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+export interface StateApplyResult {
+  /** True when DDL actually executed. */
+  applied: boolean;
+  classified: ClassifiedStatements;
+  /** The batch that was sent (empty when nothing was executable). */
+  batchSql: string;
+  /** schema_log row id for this apply, when one was written. */
+  logId?: number;
+}
+
+/**
+ * Execute the executable subset of a generated diff as one batch and record
+ * it in schema_log. A failed batch rolls back (one implicit transaction),
+ * logs the failure best-effort, and rethrows.
+ */
+export async function applyGeneratedStatements(
+  runner: QueryRunner,
+  statements: string[],
+  options: StateApplyOptions = {},
+): Promise<StateApplyResult> {
+  const classified = classifyGeneratedStatements(statements);
+  if (classified.executable.length === 0) {
+    return { applied: false, classified, batchSql: '' };
+  }
+
+  const now = options.now ?? Date.now;
+  await runner(ENSURE_RECONCILER_SQL.join(';\n'));
+
+  // Semicolon on its own line: a statement whose last line is a comment
+  // cannot swallow the separator.
+  const batchSql = classified.executable.join('\n;\n');
+  const started = now();
+  try {
+    await runner(batchSql);
+  } catch (err: any) {
+    try {
+      await runner(renderSchemaLogInsert({
+        kind: 'state apply', sql: batchSql,
+        outcome: `failed: ${String(err?.message ?? err).slice(0, 500)}`,
+        actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
+        fromFingerprint: options.fromFingerprint,
+        durationMs: now() - started,
+      }));
+    } catch { /* the memoir is best-effort on failure */ }
+    throw err;
+  }
+
+  const logRows = await runner(renderSchemaLogInsert({
+    kind: 'state apply', sql: batchSql, outcome: 'applied',
+    actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
+    fromFingerprint: options.fromFingerprint,
+    durationMs: now() - started,
+  }));
+  const logId = logRows?.[0]?.id !== undefined ? Number(logRows[0].id) : undefined;
+
+  return { applied: true, classified, batchSql, ...(logId !== undefined ? { logId } : {}) };
+}
+
+// ---------------------------------------------------------------------------
+// Apply-and-verify: the full state edge, fingerprinted at both ends.
+// ---------------------------------------------------------------------------
+
+export interface StateSyncOptions extends StateApplyOptions {
+  /** Passed through to the verifying re-diff so held-vs-real matches the plan. */
+  allowDrops?: boolean;
+}
+
+export interface StateSyncOutcome {
+  /** The generated diff, exactly as planned (executable + held + notices). */
+  statements: string[];
+  classified: ClassifiedStatements;
+  /** True when DDL actually executed. */
+  applied: boolean;
+  /** The live base fingerprint before the apply. */
+  fromFingerprint: string;
+  /** The live base fingerprint after (== from when nothing was executable). */
+  toFingerprint: string;
+  /** Executable statements still differing after apply — empty is the bar. */
+  remaining: string[];
+  /** schema_log row id, when DDL ran. */
+  logId?: number;
+  /** Fresh post-apply introspection (the pre-apply one when nothing ran). */
+  after: { snapshot: SchemaSnapshot; contract: AuthzContract };
+}
+
+/**
+ * The state layer's whole move, as one core shared by `db:generate --apply`
+ * and `db:sync`: fingerprint the live base state, execute the executable
+ * subset of an already-generated diff as one transaction, re-introspect,
+ * stamp the schema_log row with both fingerprint endpoints, and VERIFY by
+ * re-diff — done means db:generate is a no-op again, not "statements ran".
+ * With nothing executable it applies nothing and both fingerprints are the
+ * same hash. A failed batch rolls back, is logged best-effort, and rethrows.
+ */
+export async function applyStateAndVerify(
+  runner: QueryRunner,
+  models: ModelDescriptor[],
+  statements: string[],
+  current: SchemaSnapshot,
+  liveAuthz: AuthzContract,
+  options: StateSyncOptions = {},
+): Promise<StateSyncOutcome> {
+  const classified = classifyGeneratedStatements(statements);
+  const fromFingerprint = fingerprintLive(current, liveAuthz).hash;
+
+  if (classified.executable.length === 0) {
+    return {
+      statements, classified, applied: false,
+      fromFingerprint, toFingerprint: fromFingerprint, remaining: [],
+      after: { snapshot: current, contract: liveAuthz },
+    };
+  }
+
+  const result = await applyGeneratedStatements(runner, statements, { ...options, fromFingerprint });
+
+  const snapshot = await introspectSchema(runner);
+  const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  const toFingerprint = fingerprintLive(snapshot, contract).hash;
+  if (result.logId !== undefined) {
+    await runner(renderSchemaLogFingerprintUpdate(result.logId, toFingerprint));
+  }
+
+  const remaining = classifyGeneratedStatements(
+    generateMigrationSql(models, snapshot, { allowDrops: options.allowDrops, liveAuthz: contract }),
+  ).executable;
+
+  return {
+    statements, classified, applied: true,
+    fromFingerprint, toFingerprint, remaining,
+    ...(result.logId !== undefined ? { logId: result.logId } : {}),
+    after: { snapshot, contract },
+  };
+}