@metaobjectsdev/cli 0.8.1 → 0.9.0

package/src/commands/migrate.ts

@@ -15,15 +15,21 @@ import {
   diff,
   emit,
   writeMigration,
+  baselineFromMetadata,
+  planOffline,
+  snapshotPath,
+  readSnapshot,
+  writeSnapshot,
   BlockedChangesError,
   renderD1,
   applyD1SafetyPass,
   writeMigrationD1,
   introspectD1,
+  applyPending,
+  rollbackTo,
   findWranglerConfig,
   parseWranglerConfig,
   resolveD1Binding,
-  type AllowOptions,
   type AmbiguousChange,
   type AmbiguousResolution,
   type Change,
@@ -40,32 +46,12 @@ import {
   computeProjectionMigrations,
   computeProjectionViewDependencies,
 } from "../lib/projection-migrations.js";
-
-// Map CLI allow tokens → migrate-ts AllowOptions field names
-const ALLOW_TOKEN_MAP: Record<string, keyof AllowOptions> = {
-  "drop-column": "dropColumn",
-  "drop-table": "dropTable",
-  "type-change": "typeChange",
-  "drop-index": "dropIndex",
-  "drop-fk": "dropFk",
-  "nullable-to-not-null": "nullableToNotNull",
-};
+import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
 
 function mapOnAmbiguous(v: "abort" | "rename" | "drop-add"): AmbiguousResolution {
   return v === "drop-add" ? "drop+add" : v;
 }
 
-function tokensToAllowOptions(tokens: string[]): AllowOptions {
-  const opts: AllowOptions = {};
-  for (const tok of tokens) {
-    const field = ALLOW_TOKEN_MAP[tok];
-    if (field !== undefined) {
-      opts[field] = true;
-    }
-  }
-  return opts;
-}
-
 function summarizeChanges(changes: Change[]): Record<string, number> {
   const counts: Record<string, number> = {};
   for (const c of changes) {
@@ -74,25 +60,6 @@ function summarizeChanges(changes: Change[]): Record<string, number> {
   return counts;
 }
 
-function describeChangeForOutput(c: Change): string {
-  switch (c.kind) {
-    case "create-table": return c.table.name;
-    case "drop-table": return c.table;
-    case "rename-table": return `${c.from} → ${c.to}`;
-    case "add-column": return `${c.table}.${c.column.name}`;
-    case "drop-column": return `${c.table}.${c.column}`;
-    case "rename-column": return `${c.table}.${c.from} → ${c.table}.${c.to}`;
-    case "change-column-type": return `${c.table}.${c.column} (${c.from.kind} → ${c.to.kind})`;
-    case "change-column-nullable": return `${c.table}.${c.column} (${c.from ? "NULL" : "NOT NULL"} → ${c.to ? "NULL" : "NOT NULL"})`;
-    case "change-column-default": return `${c.table}.${c.column}`;
-    case "add-index": return `${c.table} idx ${c.index.name}`;
-    case "drop-index": return `${c.table} idx ${c.index}`;
-    case "add-fk": return `${c.table} fk ${c.fk.name}`;
-    case "drop-fk": return `${c.table} fk ${c.fk}`;
-    default: return JSON.stringify(c);
-  }
-}
-
 function allowFlagFor(kind: string): string {
   switch (kind) {
     case "drop-column": return "drop-column";
@@ -108,7 +75,7 @@ function allowFlagFor(kind: string): string {
 function blockedToEntries(err: BlockedChangesError): BlockedEntry[] {
   return err.blocked.map((c) => ({
     kind: c.kind,
-    description: describeChangeForOutput(c),
+    description: describeChange(c),
     allowFlag: allowFlagFor(c.kind),
   }));
 }
@@ -148,18 +115,45 @@ export async function migrateCommand(
   const config = await resolveMigrateConfig(flags, metaRoot);
 
   if (config.dialect === "d1") {
+    if (config.baseline) {
+      log.error(`migrate baseline is not supported for dialect 'd1' (snapshots are a postgres/sqlite concept)`);
+      return 2;
+    }
     if (config.databaseUrl !== undefined) {
       log.error(`migrate: --db / DATABASE_URL is not used for dialect 'd1' — wrangler.toml owns connection`);
       return 2;
     }
+    if (config.rollback !== undefined) {
+      log.error(`migrate: --rollback is not supported for dialect 'd1' (use 'wrangler d1 migrations' tooling)`);
+      return 2;
+    }
     return await runD1Migrate(config, metaRoot, wranglerRunner ?? defaultWranglerRunner);
   }
 
+  // `migrate baseline` — seed the committed reference snapshot, emit no migration.
+  if (config.baseline) {
+    return await runBaseline(config, metaRoot);
+  }
+
+  // Default = offline snapshot generation. The live-introspection path runs only
+  // when explicitly requested via --from-db, when --apply needs a connection, or
+  // for --rollback (which runs hand-authored down.sql against the live DB).
+  if (!config.fromDb && !config.apply && config.rollback === undefined) {
+    return await runOfflineGenerate(config, metaRoot);
+  }
+
   if (config.databaseUrl === undefined) {
     log.error(`migrate: --db <url> required (or set DATABASE_URL, or add migrate.databaseUrl to .metaobjects/config.json)`);
     return 2;
   }
 
+  // --rollback short-circuits the diff/emit pipeline: it runs the down.sql of
+  // every applied migration NEWER than <target> (target retained), in reverse
+  // order, ledger-tracked + advisory-locked. postgres/sqlite only.
+  if (config.rollback !== undefined) {
+    return await runRollback(config, metaRoot);
+  }
+
   // Best-effort load of metaobjects.config.ts to pick up consumer-supplied
   // providers. migrate's postgres/sqlite path also reads the config later
   // for columnNamingStrategy; we load it once here and reuse below.
@@ -196,6 +190,7 @@ export async function migrateCommand(
 
   let exitCode = 0;
   let writtenPaths: string[] = [];
+  let appliedNames: string[] = [];
   let blocked: BlockedEntry[] = [];
   let ambiguous: AmbiguousEntry[] = [];
   let changeCounts: Record<string, number> = {};
@@ -219,6 +214,7 @@ export async function migrateCommand(
       diffResult = await diff({
         expected,
         actual,
+        dialect: kysely.dialect,
         allow: tokensToAllowOptions(config.allow),
         onAmbiguous: async (a) => {
           collectedAmbiguous.push(a);
@@ -367,9 +363,34 @@ export async function migrateCommand(
             { dir: outDir, slug: config.slug },
           );
           writtenPaths = [res.upPath, res.downPath];
+          if (config.fromDb) {
+            log.info(`migrate: --from-db did not advance the committed snapshot; run 'meta migrate baseline --from-db' to re-sync`);
+          }
         }
       }
     }
+
+    // --apply: run pending committed migration files against the DB, tracked by
+    // the migration-history ledger, transactionally. Idempotency comes from the
+    // ledger (skip already-applied), NOT from re-diffing — so this also applies
+    // any previously-written-but-unapplied files in this run. Skipped on dry-run
+    // and when a prior step set a non-zero exit (e.g. blocked changes).
+    if (config.apply && exitCode === 0 && !config.dryRun) {
+      const outDir = resolvePath(metaRoot, config.outDir);
+      try {
+        // applyPending calls ensureLedger internally (idempotent), so no need
+        // to ensure it here. Pass the dialect so postgres gets schema-qualified
+        // ledger DDL + the session advisory lock (sqlite is a no-op there).
+        const result = await applyPending(kysely.db, outDir, {
+          dryRun: false,
+          dialect: kysely.dialect as "sqlite" | "postgres",
+        });
+        appliedNames = [...result.applied];
+      } catch (err) {
+        log.error(`migrate: apply failed: ${(err as Error).message}`);
+        exitCode = 1;
+      }
+    }
   } finally {
     try {
       await kysely.close();
@@ -389,9 +410,223 @@ export async function migrateCommand(
   }, { isTTY: !!process.stdout.isTTY });
 
   log.info(output);
+  if (config.apply && exitCode === 0) {
+    if (appliedNames.length > 0) {
+      log.info(`migrate: applied ${appliedNames.length} migration(s): ${appliedNames.join(", ")}`);
+    } else {
+      log.info(`migrate: no pending migrations to apply`);
+    }
+  }
   return exitCode;
 }
 
+/**
+ * `meta migrate baseline [--from-db]` — seed the committed reference snapshot.
+ * `--from-metadata` (default) derives it from metadata; `--from-db` introspects
+ * an existing database once. Emits no migration.
+ */
+export async function runBaseline(
+  config: ResolvedMigrateConfig,
+  metaRoot: string,
+): Promise<number> {
+  if (config.dialect === undefined) {
+    log.error(`migrate baseline: --dialect required (or set migrate.dialect in .metaobjects/config.json)`);
+    return 2;
+  }
+  const outDir = resolvePath(metaRoot, config.outDir);
+  const path = snapshotPath(outDir, config.dialect);
+
+  let snapshot;
+  if (config.fromDb) {
+    if (config.databaseUrl === undefined) {
+      log.error(`migrate baseline --from-db: --db <url> required`);
+      return 2;
+    }
+    let kysely;
+    try {
+      kysely = await buildKyselyFromUrl(config.databaseUrl, config.dialect);
+    } catch (err) {
+      log.error(`migrate baseline: ${(err as Error).message}`);
+      return 2;
+    }
+    try {
+      snapshot = await introspect(kysely.db, kysely.dialect);
+    } finally {
+      await kysely.close();
+    }
+  } else {
+    let metadata;
+    try {
+      metadata = await loadMemory(metaRoot);
+    } catch (err) {
+      log.error(`migrate baseline: failed to load metadata: ${(err as Error).message}`);
+      return 2;
+    }
+    snapshot = baselineFromMetadata(metadata, config.dialect);
+  }
+
+  if (config.dryRun) {
+    log.info(`migrate baseline (dry-run): would write schema snapshot ${path}`);
+    return 0;
+  }
+
+  await writeSnapshot(path, snapshot);
+  log.info(`migrate: wrote schema snapshot ${path}`);
+  return 0;
+}
+
+/**
+ * Default `meta migrate` generate path — fully offline. Diffs metadata against
+ * the committed snapshot (no DB), writes up/down.sql, and advances the snapshot.
+ * The live-introspection path is used only with --from-db or --apply.
+ *
+ * Scope: table/column/index/FK changes. Projection-view migrations stay on the
+ * introspection path (offline-view parity is a follow-up).
+ */
+export async function runOfflineGenerate(
+  config: ResolvedMigrateConfig,
+  metaRoot: string,
+): Promise<number> {
+  if (config.dialect === undefined) {
+    log.error(`migrate: --dialect required for offline generation (or use --from-db)`);
+    return 2;
+  }
+  let metadata;
+  try {
+    metadata = await loadMemory(metaRoot);
+  } catch (err) {
+    log.error(`migrate: failed to load metadata: ${(err as Error).message}`);
+    return 2;
+  }
+
+  const outDir = resolvePath(metaRoot, config.outDir);
+  const path = snapshotPath(outDir, config.dialect);
+  let snapshot;
+  try {
+    snapshot = await readSnapshot(path);
+  } catch (err) {
+    log.error(`migrate: cannot read schema snapshot at ${path}: ${(err as Error).message}`);
+    return 2;
+  }
+  if (snapshot === null) {
+    log.error(`migrate: no schema snapshot at ${path}; run 'meta migrate baseline' first`);
+    return 2;
+  }
+
+  const collectedAmbiguous: AmbiguousChange[] = [];
+  const onAmbiguousResolution = mapOnAmbiguous(config.onAmbiguous);
+
+  let plan;
+  try {
+    plan = await planOffline({
+      metadata,
+      dialect: config.dialect,
+      snapshot,
+      allow: tokensToAllowOptions(config.allow),
+      onAmbiguous: async (a) => {
+        collectedAmbiguous.push(a);
+        return onAmbiguousResolution;
+      },
+    });
+  } catch (err) {
+    if ((err as Error).message.includes("aborted by onAmbiguous")) {
+      log.error(`migrate: ambiguous rename/drop detected; re-run with --on-ambiguous rename|drop-add`);
+      return 1;
+    }
+    throw err;
+  }
+
+  const { diff: diffResult, nextSnapshot } = plan;
+
+  if (diffResult.blocked.length > 0) {
+    log.error(`migrate: ${diffResult.blocked.length} destructive change(s) blocked; re-run with --allow <tokens>`);
+    return 1;
+  }
+  if (diffResult.changes.length === 0) {
+    log.info(`migrate: no changes`);
+    return 0;
+  }
+  if (config.slug === undefined) {
+    log.error(`migrate: --slug <name> required when there are changes (e.g., --slug add-user-shipping)`);
+    return 2;
+  }
+
+  const emitResult = emit(diffResult.changes, {
+    dialect: config.dialect,
+    expectedSchema: nextSnapshot,
+    ...(snapshot.meta ? { actualMeta: snapshot.meta } : {}),
+  });
+
+  if (config.dryRun) {
+    log.info(`-- UP --\n${emitResult.up}\n\n-- DOWN --\n${emitResult.down}`);
+    return 0;
+  }
+
+  await mkdir(outDir, { recursive: true });
+  const res = await writeMigration(
+    { up: emitResult.up, down: emitResult.down },
+    { dir: outDir, slug: config.slug },
+  );
+  await writeSnapshot(path, nextSnapshot);
+  log.info(`migrate: wrote ${res.upPath}`);
+  return 0;
+}
+
+/**
+ * `meta migrate --rollback <target>` — run the down.sql of every applied
+ * migration newer than <target> (target retained) in reverse order, against the
+ * live DB, ledger-tracked + advisory-locked. postgres/sqlite only.
+ *
+ * Pass `--rollback ""` (empty target) is treated as null → roll back everything.
+ */
+async function runRollback(
+  config: ResolvedMigrateConfig,
+  metaRoot: string,
+): Promise<number> {
+  // databaseUrl is guaranteed defined by the caller's guard above.
+  const databaseUrl = config.databaseUrl as string;
+
+  // Rollback is destructive and runs hand-authored down.sql; there is no
+  // meaningful dry-run plan (no diff to preview), so reject the combination
+  // rather than silently executing.
+  if (config.dryRun) {
+    log.error(`migrate: --dry-run is not supported with --rollback`);
+    return 2;
+  }
+
+  let kysely;
+  try {
+    kysely = await buildKyselyFromUrl(databaseUrl, config.dialect);
+  } catch (err) {
+    log.error(`migrate: ${(err as Error).message}`);
+    return 2;
+  }
+  // kysely.dialect is "sqlite" | "postgres" here — d1 is rejected upstream.
+  const dialect = kysely.dialect as "sqlite" | "postgres";
+  const outDir = resolvePath(metaRoot, config.outDir);
+  // An empty --rollback string means "roll back everything".
+  const target = config.rollback === "" ? null : (config.rollback ?? null);
+
+  try {
+    const result = await rollbackTo(kysely.db, outDir, target, { dialect });
+    if (result.rolledBack.length > 0) {
+      log.info(`migrate: rolled back ${result.rolledBack.length} migration(s): ${result.rolledBack.join(", ")}`);
+    } else {
+      log.info(`migrate: nothing to roll back${target ? ` newer than '${target}'` : ""}`);
+    }
+    return 0;
+  } catch (err) {
+    log.error(`migrate: rollback failed: ${(err as Error).message}`);
+    return 1;
+  } finally {
+    try {
+      await kysely.close();
+    } catch (err) {
+      log.warn(`migrate: failed to close DB cleanly: ${(err as Error).message}`);
+    }
+  }
+}
+
 async function runD1Migrate(
   config: ResolvedMigrateConfig,
   metaRoot: string,

package/src/commands/verify.ts

@@ -13,6 +13,9 @@ import { log } from "../lib/log.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
+import { buildKyselyFromUrl, type Dialect } from "../lib/kysely.js";
+import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
+import { computeDrift, type Change } from "@metaobjectsdev/migrate-ts";
 import { loadMemory } from "@metaobjectsdev/sdk";
 import {
   TYPE_TEMPLATE,
@@ -35,7 +38,7 @@ function attrAsStringArray(attr: unknown): string[] {
 }
 
 export async function verifyCommand(args: string[], cwd: string): Promise<number> {
-  let flags;
+  let flags: ReturnType<typeof parseVerifyArgs>;
   try {
     flags = parseVerifyArgs(args);
   } catch (err) {
@@ -56,7 +59,7 @@ export async function verifyCommand(args: string[], cwd: string): Promise<number
     configProviders = undefined;
   }
 
-  let root;
+  let root: Awaited<ReturnType<typeof loadMemory>>;
   try {
     root = await loadMemory(cwd, {
       ...(configProviders !== undefined ? { providers: configProviders } : {}),
@@ -74,79 +77,187 @@ export async function verifyCommand(args: string[], cwd: string): Promise<number
   const promptsDir = join(cwd, flags.prompts ?? DEFAULT_PROMPTS_DIR);
   const provider = new FileProvider(promptsDir);
 
-  const templates = root.ownChildren().filter((c) => c.type === TYPE_TEMPLATE);
-  if (templates.length === 0) {
-    log.info("meta verify — no template.* nodes found; nothing to check.");
-    return 0;
-  }
+  // Exit-code composition: the overall result is max(templateExit, schemaExit)
+  // so either kind of drift fails CI. The schema path only runs when --db is
+  // present (and not --skip-schema); with no --db it is skipped entirely and
+  // the exit reflects the template path alone (unchanged behavior).
+  const templateExit = runTemplateVerify();
+  const schemaExit = await runSchemaVerify();
+  return Math.max(templateExit, schemaExit);
 
-  let errorCount = 0;
-  let warnCount = 0;
-  let checked = 0;
-
-  for (const tmpl of templates) {
-    const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
-    const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
-    // Absent/typeless required attrs are a loader-schema concern, not verify's.
-    if (typeof textRef !== "string" || typeof payloadRef !== "string") continue;
-
-    // Both subtypes verify that @payloadRef resolves to a loaded object.value.
-    // The render-engine `verify()` would also throw on missing refs, but the
-    // output branch doesn't call it — explicit check keeps the error symmetric.
-    const fieldTree = derivePayloadFieldTree(root, payloadRef);
-    if (fieldTree.length === 0) {
-      log.error(
-        `[${tmpl.name}] (${tmpl.subType}) ${ERR_PARTIAL_UNRESOLVED}: ` +
-          `@payloadRef "${payloadRef}" did not resolve to a loaded object.value`,
-      );
-      errorCount++;
-      continue;
+  // -- template (prompt / output) drift --------------------------------------
+  function runTemplateVerify(): number {
+    const templates = root.ownChildren().filter((c) => c.type === TYPE_TEMPLATE);
+    if (templates.length === 0) {
+      log.info("meta verify — no template.* nodes found; nothing to check.");
+      return 0;
     }
 
-    if (tmpl.subType === TEMPLATE_SUBTYPE_PROMPT) {
-      // Render-engine drift check: template variables ↔ payload field names.
-      const text = provider.resolve(textRef);
-      if (text === undefined) {
+    let errorCount = 0;
+    let warnCount = 0;
+    let checked = 0;
+
+    for (const tmpl of templates) {
+      const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+      const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+      // Absent/typeless required attrs are a loader-schema concern, not verify's.
+      if (typeof textRef !== "string" || typeof payloadRef !== "string") continue;
+
+      // Both subtypes verify that @payloadRef resolves to a loaded object.value.
+      // The render-engine `verify()` would also throw on missing refs, but the
+      // output branch doesn't call it — explicit check keeps the error symmetric.
+      const fieldTree = derivePayloadFieldTree(root, payloadRef);
+      if (fieldTree.length === 0) {
         log.error(
-          `[${tmpl.name}] (prompt) ${ERR_PARTIAL_UNRESOLVED}: @textRef "${textRef}" did not resolve under ${promptsDir}`,
+          `[${tmpl.name}] (${tmpl.subType}) ${ERR_PARTIAL_UNRESOLVED}: ` +
+            `@payloadRef "${payloadRef}" did not resolve to a loaded object.value`,
         );
         errorCount++;
         continue;
       }
 
-      const requiredSlots = attrAsStringArray(tmpl.ownAttr(TEMPLATE_ATTR_REQUIRED_SLOTS));
-      const requiredTags = attrAsStringArray(tmpl.ownAttr(TEMPLATE_ATTR_REQUIRED_TAGS));
-
-      const drift = verify(text, fieldTree, { provider, requiredSlots, requiredTags });
-      checked++;
-      for (const e of drift) {
-        if (e.code === ERR_REQUIRED_SLOT_UNUSED) {
-          log.warn(`[${tmpl.name}] (prompt) ${e.code}: ${e.path}`);
-          warnCount++;
-        } else {
-          log.error(`[${tmpl.name}] (prompt) ${e.code}: ${e.path}`);
+      if (tmpl.subType === TEMPLATE_SUBTYPE_PROMPT) {
+        // Render-engine drift check: template variables ↔ payload field names.
+        const text = provider.resolve(textRef);
+        if (text === undefined) {
+          log.error(
+            `[${tmpl.name}] (prompt) ${ERR_PARTIAL_UNRESOLVED}: @textRef "${textRef}" did not resolve under ${promptsDir}`,
+          );
           errorCount++;
+          continue;
+        }
+
+        const requiredSlots = attrAsStringArray(tmpl.ownAttr(TEMPLATE_ATTR_REQUIRED_SLOTS));
+        const requiredTags = attrAsStringArray(tmpl.ownAttr(TEMPLATE_ATTR_REQUIRED_TAGS));
+
+        const drift = verify(text, fieldTree, { provider, requiredSlots, requiredTags });
+        checked++;
+        for (const e of drift) {
+          if (e.code === ERR_REQUIRED_SLOT_UNUSED) {
+            log.warn(`[${tmpl.name}] (prompt) ${e.code}: ${e.path}`);
+            warnCount++;
+          } else {
+            log.error(`[${tmpl.name}] (prompt) ${e.code}: ${e.path}`);
+            errorCount++;
+          }
         }
+      } else if (tmpl.subType === TEMPLATE_SUBTYPE_OUTPUT) {
+        // Output drift check: re-derive the payload field tree (already done above);
+        // if it resolved, the parser codegen can produce a schema. Field-type
+        // unsupported-by-Zod issues are caught by the codegen itself if/when
+        // `meta gen` runs; verify confines itself to ref-resolution checks.
+        checked++;
+      } else {
+        // Unknown subtype — ignore (loader-schema concern).
       }
-    } else if (tmpl.subType === TEMPLATE_SUBTYPE_OUTPUT) {
-      // Output drift check: re-derive the payload field tree (already done above);
-      // if it resolved, the parser codegen can produce a schema. Field-type
-      // unsupported-by-Zod issues are caught by the codegen itself if/when
-      // `meta gen` runs; verify confines itself to ref-resolution checks.
-      checked++;
-    } else {
-      // Unknown subtype — ignore (loader-schema concern).
     }
-  }
 
-  if (errorCount > 0) {
-    log.error(
-      `meta verify — ${errorCount} drift error(s) across ${templates.length} template(s).`,
+    if (errorCount > 0) {
+      log.error(
+        `meta verify — ${errorCount} drift error(s) across ${templates.length} template(s).`,
+      );
+      return 1;
+    }
+    log.info(
+      `meta verify — ${checked} template(s) clean${warnCount > 0 ? ` (${warnCount} warning(s))` : ""}.`,
     );
-    return 1;
+    return 0;
   }
-  log.info(
-    `meta verify — ${checked} template(s) clean${warnCount > 0 ? ` (${warnCount} warning(s))` : ""}.`,
-  );
-  return 0;
+
+  // -- schema drift (live DB) ------------------------------------------------
+  // Gated on --db. With no --db (or --skip-schema), this is a no-op returning 0
+  // — the DB-free default behavior is unchanged.
+  async function runSchemaVerify(): Promise<number> {
+    if (flags.db === undefined || flags.skipSchema) return 0;
+
+    // d1 has no Kysely-driver introspection path, so the schema-drift gate
+    // can't support it. `buildKyselyFromUrl` already throws for the d1 dialect
+    // ("does not use a URL connection") — the catch below surfaces that as a
+    // clear exit 1, so no separate d1 guard is needed here.
+    let kysely;
+    try {
+      kysely = await buildKyselyFromUrl(flags.db, flags.dialect as Dialect | undefined);
+    } catch (err) {
+      log.error(`verify: ${(err as Error).message}`);
+      return 1;
+    }
+
+    try {
+      const allow = tokensToAllowOptions(flags.allow);
+      let driftResult;
+      try {
+        driftResult = await computeDrift(kysely.db, kysely.dialect, root, { allow });
+      } catch (err) {
+        log.error(`verify: failed to introspect ${kysely.displayUrl}: ${(err as Error).message}`);
+        return 1;
+      }
+
+      // TODO(Unit 3 — migration-history ledger): when the ledger table exists,
+      // a migration that is recorded-as-pending-but-unapplied must also count as
+      // drift here. Until Unit 3 ships the ledger, this MUST no-op — do not query
+      // a table that doesn't exist. `reconcileLedger` returns no extra drift today.
+      const ledgerDrift = await reconcileLedger();
+
+      const changes = driftResult.changes;
+      if (changes.length === 0 && ledgerDrift.length === 0) {
+        log.info(`meta verify — schema in sync with ${kysely.displayUrl}.`);
+        return 0;
+      }
+
+      log.error(`meta verify — schema drift vs ${kysely.displayUrl} (${changes.length} change(s)):`);
+      for (const line of summarizeDrift(changes)) log.error(`  ${line}`);
+      for (const line of ledgerDrift) log.error(`  ${line}`);
+      return 1;
+    } finally {
+      try {
+        await kysely.close();
+      } catch (err) {
+        log.warn(`verify: failed to close DB cleanly: ${(err as Error).message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Migration-history ledger reconciliation hook (Unit 3 — not yet built).
+ *
+ * When the ledger lands, this will read it and report any recorded-but-unapplied
+ * migration as drift. Until then it is a deliberate no-op: returning an empty
+ * array means "no ledger-derived drift", and crucially it does NOT touch any
+ * ledger table (which doesn't exist yet) so a fresh DB never trips on it.
+ */
+async function reconcileLedger(): Promise<string[]> {
+  return [];
+}
+
+// Per-kind glyph (+ add / - drop / ~ change) and noun for the drift summary.
+// The detail string itself comes from the shared `describeChange`.
+const DRIFT_PRESENTATION: Record<Change["kind"], { glyph: string; noun: string }> = {
+  "create-table": { glyph: "+", noun: "table" },
+  "drop-table": { glyph: "-", noun: "table" },
+  "rename-table": { glyph: "~", noun: "table" },
+  "add-column": { glyph: "+", noun: "column" },
+  "drop-column": { glyph: "-", noun: "column" },
+  "rename-column": { glyph: "~", noun: "column" },
+  "change-column-type": { glyph: "~", noun: "column" },
+  "change-column-nullable": { glyph: "~", noun: "column" },
+  "change-column-default": { glyph: "~", noun: "column" },
+  "add-index": { glyph: "+", noun: "index" },
+  "drop-index": { glyph: "-", noun: "index" },
+  "add-fk": { glyph: "+", noun: "fk" },
+  "drop-fk": { glyph: "-", noun: "fk" },
+  "add-check": { glyph: "+", noun: "check" },
+  "drop-check": { glyph: "-", noun: "check" },
+  "create-view": { glyph: "+", noun: "view" },
+  "replace-view": { glyph: "~", noun: "view" },
+  "drop-view": { glyph: "-", noun: "view" },
+};
+
+/** Human-readable one-line-per-change drift summary (table/column/index/fk/view). */
+function summarizeDrift(changes: Change[]): string[] {
+  return changes.map((c) => {
+    const p = DRIFT_PRESENTATION[c.kind];
+    if (p === undefined) return JSON.stringify(c);
+    return `${p.glyph} ${p.noun} ${describeChange(c)}`;
+  });
 }