@metaobjectsdev/migrate-ts 0.8.1 → 0.9.0-rc.1

package/src/apply/ledger.ts

@@ -0,0 +1,241 @@
+import { type Kysely, sql } from "kysely";
+
+/**
+ * Default migration-history ledger table name. A single source of truth tracked
+ * across postgres + sqlite so `meta migrate --apply` can skip already-applied
+ * files (idempotency from the LEDGER, not from re-diffing).
+ */
+export const MIGRATIONS_TABLE = "_metaobjects_migrations";
+
+/** Default Postgres schema holding the ledger (and, by default, the lock scope). */
+export const DEFAULT_LEDGER_SCHEMA = "public";
+
+/**
+ * Safe SQL identifier pattern for caller-supplied `schema` / `table` names. These
+ * are interpolated as SQL identifiers (one `sql.ref` per part), so they MUST be a
+ * single, unquoted-style identifier — no dots, spaces, or quotes — otherwise
+ * Kysely's `sql.ref` would split a value like `"v1.2_migrations"` on every `.`
+ * into a wrong multi-part name. Validated at resolve time; a violation throws.
+ */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Throw a clear, actionable error if a caller-supplied SQL-identifier option
+ * (`schema` / `table`) is not a single safe identifier. Names the offending
+ * option + value so the caller can fix the misconfiguration directly.
+ */
+function assertSafeIdentifier(option: string, value: string): void {
+  if (!SAFE_IDENTIFIER.test(value)) {
+    throw new Error(
+      `LedgerOptions.${option} must be a single SQL identifier matching ` +
+        `${SAFE_IDENTIFIER.source} (letters, digits, underscore; not starting with a digit). ` +
+        `Got ${JSON.stringify(value)} — a dotted/quoted/spaced value would be mis-parsed as a ` +
+        `multi-part identifier. Use a plain name (e.g. a per-tenant prefix) instead.`,
+    );
+  }
+}
+
+/** The dialect signal threaded through the ledger fns (schema-qualification only applies to pg). */
+export type LedgerDialect = "postgres" | "sqlite";
+
+/**
+ * Multi-tenant ledger configuration. Generalizes the fixed
+ * `public._metaobjects_migrations` ledger so multiple apps/tenants can track
+ * independently in one physical database.
+ *
+ * Defaults preserve the original single-tenant behavior exactly: `schema`
+ * defaults to `public`, `table` to `_metaobjects_migrations`. Postgres uses
+ * `schema`; SQLite has no schemas and ignores it. `lockName` is consumed by the
+ * advisory-lock path (apply/rollback) — see {@link applyPending}.
+ */
+export interface LedgerOptions {
+  /** Postgres schema holding the ledger table. Default `public`. Ignored on SQLite. */
+  schema?: string;
+  /** Ledger table name. Default `_metaobjects_migrations`. */
+  table?: string;
+  /** Advisory-lock name. Default derived from `<schema>.<table>`. Postgres-only. */
+  lockName?: string;
+}
+
+/** A single ledger row. */
+export interface LedgerRow {
+  /** Migration name = the `<timestamp>-<slug>` directory name (sort key + id). */
+  name: string;
+  /** sha-256 of the up.sql contents at apply time (tamper guard). */
+  checksum: string;
+}
+
+/** Resolved ledger location: a dialect + a Kysely raw-SQL identifier reference. */
+interface ResolvedLedger {
+  dialect: LedgerDialect;
+  schema: string;
+  table: string;
+  /**
+   * A qualified-identifier SQL fragment built from SEPARATE `sql.ref` parts —
+   * `"<schema>"."<table>"` on pg, the bare `"<table>"` on sqlite. Built part-wise
+   * (not from a single dotted string) so a `.` inside a name can never be
+   * misread as an identifier separator, independent of the resolve-time
+   * validation.
+   */
+  ref: ReturnType<typeof sql>;
+}
+
+/**
+ * Resolve a {@link LedgerOptions} (+ dialect) to a concrete ledger location.
+ * On Postgres the table is schema-qualified (`"<schema>"."<table>"`); on SQLite
+ * (no schema concept) the schema is ignored and the bare `"<table>"` is used.
+ *
+ * Caller-supplied `schema` / `table` are validated against {@link SAFE_IDENTIFIER}
+ * (a violation throws here, naming the option + value), then assembled from two
+ * separate `sql.ref` parts so identifier quoting stays dialect-portable AND no
+ * `.` can be mis-parsed as a multi-part separator.
+ */
+function resolveLedger(
+  dialect: LedgerDialect,
+  opts: LedgerOptions | undefined,
+): ResolvedLedger {
+  const schema = opts?.schema ?? DEFAULT_LEDGER_SCHEMA;
+  const table = opts?.table ?? MIGRATIONS_TABLE;
+  assertSafeIdentifier("table", table);
+  if (dialect === "postgres") {
+    assertSafeIdentifier("schema", schema);
+  }
+  const ref =
+    dialect === "postgres"
+      ? sql`${sql.ref(schema)}.${sql.ref(table)}`
+      : sql`${sql.ref(table)}`;
+  return { dialect, schema, table, ref };
+}
+
+/**
+ * Create the migration-history table if it does not already exist. Idempotent:
+ * re-running is a no-op and preserves existing rows. Dialect-portable DDL
+ * (TEXT columns work on both sqlite and postgres; `applied_at` is stored as
+ * text so we don't depend on a dialect-specific timestamp type).
+ *
+ * On Postgres a multi-tenant `schema` is created first (`CREATE SCHEMA IF NOT
+ * EXISTS`) so the ledger can live outside `public`.
+ */
+export async function ensureLedger(
+  db: Kysely<Record<string, unknown>>,
+  dialect: LedgerDialect = "sqlite",
+  opts?: LedgerOptions,
+): Promise<void> {
+  const ledger = resolveLedger(dialect, opts);
+  if (ledger.dialect === "postgres") {
+    await sql`CREATE SCHEMA IF NOT EXISTS ${sql.ref(ledger.schema)}`.execute(db);
+  }
+  await sql`
+    CREATE TABLE IF NOT EXISTS ${ledger.ref} (
+      name TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL,
+      checksum TEXT NOT NULL
+    )
+  `.execute(db);
+}
+
+/**
+ * Record a migration as applied. Inserts a row with the current UTC timestamp.
+ * Intended to run inside the SAME transaction that applied the migration SQL.
+ */
+export async function recordApplied(
+  db: Kysely<Record<string, unknown>>,
+  name: string,
+  checksum: string,
+  dialect: LedgerDialect = "sqlite",
+  opts?: LedgerOptions,
+): Promise<void> {
+  const ledger = resolveLedger(dialect, opts);
+  const appliedAt = new Date().toISOString();
+  await sql`
+    INSERT INTO ${ledger.ref} (name, applied_at, checksum)
+    VALUES (${name}, ${appliedAt}, ${checksum})
+  `.execute(db);
+}
+
+/** Delete a migration's ledger row (rollback unrecord). */
+export async function deleteApplied(
+  db: Kysely<Record<string, unknown>>,
+  name: string,
+  dialect: LedgerDialect = "sqlite",
+  opts?: LedgerOptions,
+): Promise<void> {
+  const ledger = resolveLedger(dialect, opts);
+  await sql`
+    DELETE FROM ${ledger.ref} WHERE name = ${name}
+  `.execute(db);
+}
+
+/** Return the set of applied migration names. */
+export async function appliedNames(
+  db: Kysely<Record<string, unknown>>,
+  dialect: LedgerDialect = "sqlite",
+  opts?: LedgerOptions,
+): Promise<Set<string>> {
+  return new Set((await appliedRecords(db, dialect, opts)).keys());
+}
+
+/**
+ * Return a name→checksum map for all applied migrations (tamper-guard input).
+ *
+ * The {@link BASELINE_NAME} marker row is excluded at the SQL level: it is a
+ * marker, NOT a migration, so no migration-listing consumer (e.g. rollback-all,
+ * which derives its work list from these names) should ever see it. The baseline
+ * is read independently via {@link baselineRecord}.
+ */
+export async function appliedRecords(
+  db: Kysely<Record<string, unknown>>,
+  dialect: LedgerDialect = "sqlite",
+  opts?: LedgerOptions,
+): Promise<Map<string, string>> {
+  const ledger = resolveLedger(dialect, opts);
+  // Raw select keeps this dialect-portable and sidesteps typing the dynamic
+  // table name against the untyped Kysely<Record<string, unknown>> schema.
+  const result = await sql<{ name: string; checksum: string }>`
+    SELECT name, checksum FROM ${ledger.ref} WHERE name != ${BASELINE_NAME}
+  `.execute(db);
+  const map = new Map<string, string>();
+  for (const row of result.rows) {
+    map.set(row.name, row.checksum);
+  }
+  return map;
+}
+
+/** Reserved ledger name for the baseline marker (sorts before any timestamped migration). */
+export const BASELINE_NAME = "0000-baseline";
+
+/**
+ * Record (or overwrite) the baseline marker — the snapshot checksum captured when
+ * `migrate baseline` seeded the reference snapshot. Lets a later check detect a
+ * snapshot that was hand-edited out of sync with the migration chain.
+ */
+export async function recordBaseline(
+  db: Kysely<Record<string, unknown>>,
+  dialect: LedgerDialect,
+  checksum: string,
+  opts?: LedgerOptions,
+): Promise<void> {
+  const ledger = resolveLedger(dialect, opts);
+  await ensureLedger(db, dialect, opts);
+  const appliedAt = new Date().toISOString();
+  // Upsert: delete any prior baseline, then insert (portable across sqlite/pg).
+  await sql`DELETE FROM ${ledger.ref} WHERE name = ${BASELINE_NAME}`.execute(db);
+  await sql`
+    INSERT INTO ${ledger.ref} (name, applied_at, checksum)
+    VALUES (${BASELINE_NAME}, ${appliedAt}, ${checksum})
+  `.execute(db);
+}
+
+/** Read the baseline marker, or null if none recorded. */
+export async function baselineRecord(
+  db: Kysely<Record<string, unknown>>,
+  dialect: LedgerDialect = "sqlite",
+  opts?: LedgerOptions,
+): Promise<{ name: string; checksum: string } | null> {
+  const ledger = resolveLedger(dialect, opts);
+  const result = await sql<{ name: string; checksum: string }>`
+    SELECT name, checksum FROM ${ledger.ref} WHERE name = ${BASELINE_NAME}
+  `.execute(db);
+  const row = result.rows[0];
+  return row ? { name: row.name, checksum: row.checksum } : null;
+}

package/src/check-expr-compare.ts

@@ -0,0 +1,49 @@
+// src/check-expr-compare.ts
+//
+// CHECK-expression comparison. Postgres rewrites a stored CHECK body so the raw
+// text we generate and the introspected text differ textually but mean the same
+// thing. This reduces both to ONE canonical form for comparison. Reliable here
+// because every check expression we emit is machine-derived with a simple, known
+// shape (comparison / IN / length / regex) — there is no arbitrary author SQL to
+// mis-normalize. The rewrites PG applies (verified against a live server):
+//   - parenthesizes terms:  `col >= 0 AND col <= 100`  →  `(col >= 0) AND (col <= 100)`
+//   - rewrites IN-lists:     `status IN ('A','B')`      →  `status = ANY (ARRAY['A'::text, 'B'::text])`
+//   - appends type casts:    string literals gain `::text`
+// All three are canonicalized below so an enum/range CHECK introspected from PG
+// compares equal to the one we generate (idempotency on the --from-db / verify paths).
+
+/** Canonical form: drop casts/brackets/parens, fold `= ANY (ARRAY[…])` back to `IN`, lower-case, collapse whitespace. */
+export function normalizeCheckExpr(expr: string): string {
+  const stripped = expr
+    .toLowerCase()
+    // Drop `::text` / `::"MyType"` type casts PG adds to literals. The lookbehind
+    // restricts the strip to a cast that immediately follows a CLOSING single
+    // quote (`'open'::text`), so a `::` appearing INSIDE a regex pattern literal
+    // (`slug ~ 'a::foo'`) is preserved — otherwise two distinct regex CHECKs would
+    // normalize equal and a pattern change would be silently missed.
+    .replace(/(?<=')::\s*"?\w+"?/g, "")
+    .replace(/[()[\]]/g, " ")     // drop parens AND square brackets (ARRAY[…])
+    .replace(/\s+/g, " ")
+    .trim();
+  // PG stores `col IN (…)` as `col = ANY (ARRAY[…])`; after the bracket strip above
+  // that reads `col = any array …`. Fold it back to the `col in …` form we emit.
+  return stripped.replace(/=\s*any\s+array/g, "in").replace(/\s+/g, " ").trim();
+}
+
+/** True when two CHECK expressions are equivalent after normalization. */
+export function checkExprEquals(a: string | undefined, b: string | undefined): boolean {
+  if (a === undefined || b === undefined) return false;
+  return normalizeCheckExpr(a) === normalizeCheckExpr(b);
+}
+
+/**
+ * `CHECK (<expr>)` → `<expr>` (balanced outer wrapper); returns input unchanged
+ * if there is no CHECK wrapper. Tolerates a trailing constraint modifier suffix
+ * (`pg_get_constraintdef` can return `CHECK (<expr>) NOT VALID`) so the wrapper
+ * still strips cleanly to the inner expression instead of falling through to the
+ * unchanged-input fallback (which would cause spurious drop+add churn).
+ */
+export function stripCheckWrapper(def: string): string {
+  const m = /^\s*CHECK\s*\((.*)\)(?:\s+NOT\s+VALID)?\s*$/is.exec(def);
+  return m ? m[1]!.trim() : def.trim();
+}

package/src/diff/index.ts

@@ -1,12 +1,14 @@
 import type {
   SchemaSnapshot, TableDescriptor, ColumnDescriptor, IndexDescriptor, FkDescriptor,
   ViewDescriptor,
-  Change, ChangeStatus, DiffResult, AllowOptions, AmbiguousCallback,
+  Change, ChangeStatus, DiffResult, AllowOptions, AmbiguousCallback, Dialect,
 } from "../types.js";
 import type { SqlType } from "../sql-type.js";
 import { sqlTypeEquals } from "../sql-type.js";
 import { applyStatus } from "./status.js";
 import { detectColumnRenames, detectTableRenames } from "./rename-heuristic.js";
+import { viewSqlEquals } from "../view-sql-compare.js";
+import { checkExprEquals } from "../check-expr-compare.js";
 import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
 
 export interface DiffArgs {
@@ -25,6 +27,8 @@ export interface DiffArgs {
    * the default. Pass additional patterns to extend.
    */
   ignoreTables?: string[];
+  /** Dialect; CHECK-constraint evolution on existing tables is emitted for postgres only. */
+  dialect?: Dialect;
 }
 
 const ALLOWED: ChangeStatus = { state: "allowed" };
@@ -128,6 +132,12 @@ export async function diff(
           fk, status: ALLOWED,
         });
       }
+      // CHECK constraints are inlined into the CREATE TABLE DDL at emit time
+      // (both postgres and sqlite support inline CHECK), so they ride on
+      // `create-table.table.checks` rather than as separate add-check changes.
+      // For brand-new tables no add-check is emitted here; existing-table CHECK
+      // evolution (add/drop on tables present on both sides) is handled by
+      // diffTableChecks in Pass 2.
     }
   }
   // Pass 1b: tables present in actual but not expected → drop-table
@@ -135,7 +145,7 @@ export async function diff(
   for (const [id, t] of actualTables) {
     if (!expectedTables.has(id)) {
       const dropChange: Change & { _columns?: ColumnDescriptor[] } = {
-        kind: "drop-table", table: t.name, ...schemaSpread(t.schema), status: ALLOWED,
+        kind: "drop-table", table: t.name, ...schemaSpread(t.schema), restore: t, status: ALLOWED,
       };
       dropChange._columns = t.columns;
       changes.push(dropChange);
@@ -149,13 +159,15 @@ export async function diff(
     diffTableColumns(expectedTable, actualTable, changes);
     diffTableIndexes(expectedTable, actualTable, changes);
     diffTableForeignKeys(expectedTable, actualTable, changes);
+    // CHECK constraints on existing tables are evolved for postgres only (SQLite
+    // evolves checks via table recreate, not ALTER). Gated on `actual.checks`
+    // being populated — by the snapshot offline, or pg_constraint introspection.
+    if (args.dialect === "postgres") diffTableChecks(expectedTable, actualTable, changes);
   }
 
-  // Pass 2b: views. Identity is (schema, name). Body comparison isn't
-  // implemented — introspect doesn't read view bodies today, so a name match
-  // is no-change regardless of how the user's projection metadata has evolved.
-  // Users who change a view body without renaming need to manually drop+recreate
-  // or do a full bootstrap until replace-view-from-body-diff lands.
+  // Pass 2b: views. Identity is (schema, name). A name present on both sides
+  // with a divergent body (whitespace-/wrapper-normalized) emits replace-view;
+  // introspect now reads the actual body so view-body drift is visible.
   diffViews(args.expected.views, args.actual.views, changes);
 
   // Pass 3: detect table renames BEFORE column renames — so a renamed table's
@@ -221,7 +233,7 @@ function diffTableColumns(
   for (const [name, ac] of actualCols) {
     if (!expectedCols.has(name)) {
       const dropChange: Change & { _sqlType?: SqlType; _nullable?: boolean } = {
-        kind: "drop-column", table, ...sx, column: name, status: ALLOWED,
+        kind: "drop-column", table, ...sx, column: name, restore: ac, status: ALLOWED,
       };
       dropChange._sqlType = ac.sqlType;
       dropChange._nullable = ac.nullable;
@@ -245,13 +257,14 @@ function diffTableIndexes(
       changes.push({ kind: "add-index", table, ...sx, index: ix, status: ALLOWED });
     } else if (!indexEquals(ix, a)) {
       // Index shape changed: drop + add (atomic from caller's perspective).
-      changes.push({ kind: "drop-index", table, ...sx, index: name, status: ALLOWED });
+      // restore = the ACTUAL shape so the down re-creates the original index.
+      changes.push({ kind: "drop-index", table, ...sx, index: name, restore: a, status: ALLOWED });
       changes.push({ kind: "add-index", table, ...sx, index: ix, status: ALLOWED });
     }
   }
-  for (const [name] of actualIdx) {
+  for (const [name, ai] of actualIdx) {
     if (!expectedIdx.has(name)) {
-      changes.push({ kind: "drop-index", table, ...sx, index: name, status: ALLOWED });
+      changes.push({ kind: "drop-index", table, ...sx, index: name, restore: ai, status: ALLOWED });
     }
   }
 }
@@ -270,13 +283,35 @@ function diffTableForeignKeys(
     if (!a) {
       changes.push({ kind: "add-fk", table, ...sx, fk, status: ALLOWED });
     } else if (!fkEquals(fk, a)) {
-      changes.push({ kind: "drop-fk", table, ...sx, fk: name, status: ALLOWED });
+      // FK shape changed: drop + add. restore = the ACTUAL shape so the down
+      // re-creates the original FK.
+      changes.push({ kind: "drop-fk", table, ...sx, fk: name, restore: a, status: ALLOWED });
       changes.push({ kind: "add-fk", table, ...sx, fk, status: ALLOWED });
     }
   }
-  for (const [name] of actualFk) {
+  for (const [name, af] of actualFk) {
     if (!expectedFk.has(name)) {
-      changes.push({ kind: "drop-fk", table, ...sx, fk: name, status: ALLOWED });
+      changes.push({ kind: "drop-fk", table, ...sx, fk: name, restore: af, status: ALLOWED });
+    }
+  }
+}
+
+function diffTableChecks(expected: TableDescriptor, actual: TableDescriptor, changes: Change[]): void {
+  const sx = schemaSpread(expected.schema);
+  const expectedChk = new Map(expected.checks.map((c) => [c.name, c]));
+  const actualChk = new Map(actual.checks.map((c) => [c.name, c]));
+  for (const [name, ec] of expectedChk) {
+    const ac = actualChk.get(name);
+    if (!ac) {
+      changes.push({ kind: "add-check", table: expected.name, ...sx, check: ec, status: ALLOWED });
+    } else if (!checkExprEquals(ec.expression, ac.expression)) {
+      changes.push({ kind: "drop-check", table: expected.name, ...sx, check: name, restore: ac, status: ALLOWED });
+      changes.push({ kind: "add-check", table: expected.name, ...sx, check: ec, status: ALLOWED });
+    }
+  }
+  for (const [name, ac] of actualChk) {
+    if (!expectedChk.has(name)) {
+      changes.push({ kind: "drop-check", table: expected.name, ...sx, check: name, restore: ac, status: ALLOWED });
     }
   }
 }
@@ -291,8 +326,17 @@ function diffViews(
   const exp = new Map(expected.map((v) => [viewIdentity(v), v] as const));
   const act = new Map(actual.map((v) => [viewIdentity(v), v] as const));
   for (const [id, v] of exp) {
-    if (!act.has(id)) {
+    const a = act.get(id);
+    if (a === undefined) {
       changes.push({ kind: "create-view", view: v, ...schemaSpread(v.schema), status: ALLOWED });
+    } else if (
+      // Both bodies known and divergent → replace-view. When either body is
+      // absent (e.g. expected projection unresolvable, or an introspector that
+      // couldn't read the body) we cannot prove a change, so we leave it alone
+      // rather than emit a spurious replace.
+      v.sql !== undefined && a.sql !== undefined && !viewSqlEquals(v.sql, a.sql)
+    ) {
+      changes.push({ kind: "replace-view", view: v, ...schemaSpread(v.schema), status: ALLOWED });
     }
   }
   for (const [id, v] of act) {

package/src/diff/status.ts

@@ -27,6 +27,8 @@ function blockedReasonFor(c: Change, allow: AllowOptions): string | null {
       return allow.dropIndex ? null : "destructive: drop-index not allowed (pass allow.dropIndex)";
     case "drop-fk":
       return allow.dropFk ? null : "destructive: drop-fk not allowed (pass allow.dropFk)";
+    case "drop-check":
+      return allow.dropCheck ? null : "destructive: drop-check not allowed (pass allow.dropCheck)";
 
     case "change-column-type":
       if (isWidening(c.from, c.to)) return null;     // widening always allowed
@@ -47,6 +49,7 @@ function blockedReasonFor(c: Change, allow: AllowOptions): string | null {
     case "change-column-default":
     case "add-index":
     case "add-fk":
+    case "add-check":
     case "create-view":
     case "drop-view":
     case "replace-view":

package/src/drift/classify.ts

@@ -0,0 +1,56 @@
+// src/drift/classify.ts
+import { diff } from "../diff/index.js";
+import type { Change, Dialect, DiffResult, SchemaSnapshot } from "../types.js";
+
+/**
+ * Change kinds that represent an object present in the live DB but absent from
+ * the snapshot. When the snapshot is the `expected` side of a diff, these are
+ * the DB's *unmanaged* objects — hand-authored, not modeled — and must never be
+ * treated as actionable drift or auto-dropped.
+ */
+const UNMANAGED_KINDS = new Set<string>([
+  "drop-table",
+  "drop-column",
+  "drop-index",
+  "drop-fk",
+  "drop-view",
+  // A CHECK present in the DB but not the snapshot is a DB-only object, same as
+  // a hand-authored index/fk/view — never actionable drift, never auto-dropped.
+  "drop-check",
+]);
+
+export interface DriftClassification {
+  /** Modeled objects the DB is missing or has differently — actionable; fails the gate. */
+  drift: Change[];
+  /** Objects present in the DB but not the snapshot — informational; never dropped. */
+  unmanaged: Change[];
+}
+
+export function classifyDrift(changes: Change[]): DriftClassification {
+  const drift: Change[] = [];
+  const unmanaged: Change[] = [];
+  for (const c of changes) {
+    if (UNMANAGED_KINDS.has(c.kind)) unmanaged.push(c);
+    else drift.push(c);
+  }
+  return { drift, unmanaged };
+}
+
+/**
+ * Drift of a live DB (introspected into `actual`) against the committed snapshot.
+ * Diffs with `expected = snapshot` so that objects only in the DB surface as
+ * `drop-*` → classified `unmanaged`; objects the snapshot has but the DB lacks or
+ * differs surface as create/add/change → classified `drift`.
+ */
+export async function driftAgainstSnapshot(
+  snapshot: SchemaSnapshot,
+  actual: SchemaSnapshot,
+  dialect?: Dialect,
+): Promise<DriftClassification> {
+  const result: DiffResult = await diff({
+    expected: snapshot,
+    actual,
+    ...(dialect !== undefined ? { dialect } : {}),
+  });
+  return classifyDrift(result.changes);
+}

package/src/drift/drift.ts

@@ -0,0 +1,66 @@
+// computeDrift — structural + view-body drift of a live DB vs the metadata-
+// declared schema. Thin composition over the existing pipeline:
+//   buildExpectedSchema(metadata) + introspect(db, dialect) → diff(...)
+//
+// Used by the `meta verify --db` schema-drift gate: a non-empty `changes` list
+// means the live DB has diverged from what the metadata describes (a missing
+// column, a changed view body, an extra table, etc.). Unlike `meta migrate`,
+// drift detection never emits SQL or asks about ambiguous renames — it just
+// reports the divergence so CI can fail loud.
+
+import type { Kysely } from "kysely";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import type { ColumnNamingStrategy } from "@metaobjectsdev/metadata";
+import { buildExpectedSchema } from "../expected-schema.js";
+import { introspect } from "../introspect/index.js";
+import { diff } from "../diff/index.js";
+import type { AllowOptions, Dialect, DiffResult } from "../types.js";
+
+export interface ComputeDriftOptions {
+  /**
+   * Destructive-change permissions. Mirrors `diff`'s `allow` — a drift that is
+   * "allowed" still appears in `changes` (it's still drift), so the gate fails
+   * on it. `allow` only affects `blocked`. Defaults to `{}`.
+   */
+  allow?: AllowOptions;
+  /**
+   * Column-naming strategy for fields with no `@column` override. Must match
+   * the runtime's strategy or the expected schema's columns won't line up with
+   * what introspection sees. Defaults to `buildExpectedSchema`'s default.
+   */
+  columnNamingStrategy?: ColumnNamingStrategy;
+  /**
+   * Table-name patterns to ignore on both sides (passed through to `diff`).
+   * Omit to keep `diff`'s default (migration-tracking sidecar tables).
+   */
+  ignoreTables?: string[];
+}
+
+/**
+ * Compute the drift between a live DB and the metadata-declared schema.
+ *
+ * Returns a `DiffResult` whose `changes` is empty iff the DB matches the
+ * metadata. The caller decides exit behavior (the schema-drift gate fails when
+ * `changes` is non-empty).
+ */
+export async function computeDrift(
+  db: Kysely<Record<string, unknown>>,
+  dialect: Dialect,
+  metadata: MetaRoot,
+  opts?: ComputeDriftOptions,
+): Promise<DiffResult> {
+  const expected = buildExpectedSchema(metadata, {
+    dialect,
+    ...(opts?.columnNamingStrategy !== undefined
+      ? { columnNamingStrategy: opts.columnNamingStrategy }
+      : {}),
+  });
+  const actual = await introspect(db, dialect);
+  return diff({
+    expected,
+    actual,
+    dialect,
+    allow: opts?.allow ?? {},
+    ...(opts?.ignoreTables !== undefined ? { ignoreTables: opts.ignoreTables } : {}),
+  });
+}

package/src/emit/d1-safety-pass.ts

@@ -1,3 +1,5 @@
+import { splitSqlStatements } from "../sql/split-statements.js";
+
 const MAX_STATEMENT_BYTES = 1 * 1024 * 1024; // 1 MB — D1 batch API per-statement limit (path used by `wrangler d1 migrations apply --file`).
 
 export class D1UnsupportedStatementError extends Error {
@@ -22,73 +24,42 @@ export function applyD1SafetyPass(sql: string, opts?: { collectWarnings?: boolea
     return collect ? { sql: "", warnings } : "";
   }
 
-  const statements = splitStatements(sql);
+  // splitSqlStatements already returns trimmed, non-empty statements.
+  const statements = splitSqlStatements(sql);
   const kept: string[] = [];
 
   for (const stmt of statements) {
-    const trimmed = stmt.trim();
-    if (trimmed.length === 0) continue;
-
     // Reject hard failures up front.
-    if (/^\s*(ATTACH|DETACH)\b/i.test(trimmed)) {
-      throw new D1UnsupportedStatementError(trimmed, "ATTACH/DETACH DATABASE");
+    if (/^\s*(ATTACH|DETACH)\b/i.test(stmt)) {
+      throw new D1UnsupportedStatementError(stmt, "ATTACH/DETACH DATABASE");
     }
-    if (/^\s*VACUUM\b/i.test(trimmed)) {
-      throw new D1UnsupportedStatementError(trimmed, "VACUUM");
+    if (/^\s*VACUUM\b/i.test(stmt)) {
+      throw new D1UnsupportedStatementError(stmt, "VACUUM");
     }
 
     // Strip explicit transaction control + savepoints.
-    if (/^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)\b/i.test(trimmed)) {
+    if (/^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)\b/i.test(stmt)) {
       continue;
     }
 
-    const byteLen = byteLength(trimmed);
+    const byteLen = byteLength(stmt);
     if (byteLen > MAX_STATEMENT_BYTES) {
       warnings.push(
         `statement exceeds D1's 1 MB per-statement limit (${byteLen} bytes); ` +
-        `may be rejected by D1 at apply time: ${trimmed.slice(0, 80)}...`,
+        `may be rejected by D1 at apply time: ${stmt.slice(0, 80)}...`,
       );
     }
 
-    kept.push(trimmed);
+    kept.push(stmt);
   }
 
-  // Re-join: each statement on its own line, blank line between top-level
-  // DDL statements (matches sqlite emit's output style).
-  const out = kept.join("\n\n");
+  // Re-join: each statement on its own line, blank line between top-level DDL
+  // statements (matches sqlite emit's output style). splitSqlStatements strips
+  // the `;` separators, so re-add exactly one terminator per kept statement.
+  const out = kept.map((s) => `${s};`).join("\n\n");
   return collect ? { sql: out, warnings } : out;
 }
 
-/**
- * Split SQL on `;` boundaries, respecting single-quoted strings (SQL uses
- * '' to escape a single quote inside a literal — two consecutive quotes toggle
- * inString twice, net zero, which is exactly what we want).
- * Sufficient for our DDL output; we don't generate dollar-quoted blocks or
- * other exotic SQLite literals.
- */
-function splitStatements(sql: string): string[] {
-  const out: string[] = [];
-  let buf = "";
-  let inString = false;
-  for (let i = 0; i < sql.length; i++) {
-    const c = sql[i]!;
-    if (c === "'") {
-      buf += c;
-      inString = !inString;
-      continue;
-    }
-    if (c === ";" && !inString) {
-      buf += ";";
-      out.push(buf);
-      buf = "";
-      continue;
-    }
-    buf += c;
-  }
-  if (buf.trim().length > 0) out.push(buf);
-  return out;
-}
-
 function byteLength(s: string): number {
   return new TextEncoder().encode(s).length;
 }