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

package/src/emit/postgres.ts

@@ -16,6 +16,7 @@ const STAGE_ORDER: Record<Change["kind"], number> = {
   "rename-column": 3, "rename-table": 3,
   "add-index": 4, "drop-index": 4,
   "add-fk": 5, "drop-fk": 5,
+  "add-check": 5, "drop-check": 5,
   "drop-table": 6,
   "create-view": 7, "replace-view": 7,
 };
@@ -61,6 +62,12 @@ function renderUp(c: Change): string {
     case "drop-index":             return `DROP INDEX ${quoteIndexQualified(c.index, c.schema)};`;
     case "add-fk":                 return renderAddFk(c.table, c.schema, c.fk);
     case "drop-fk":                return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.fk)};`;
+    // add-check / drop-check are declared but NOT yet produced by the diff —
+    // checks are create-time-only (inlined in CREATE TABLE via renderCreateTable).
+    // These arms exist for future existing-table CHECK evolution support, mirroring
+    // the create-view/drop-view "declared, not yet produced" pattern.
+    case "add-check":              return `ALTER TABLE ${quoteQualified(c.table, c.schema)} ADD CONSTRAINT ${quote(c.check.name)} CHECK (${c.check.expression});`;
+    case "drop-check":             return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.check)};`;
     case "create-view":            return renderCreateView(c.view, c.schema, /* orReplace */ false);
     case "drop-view":              return `DROP VIEW ${quoteQualifiedView(c.view, c.schema)};`;
     case "replace-view":           return renderCreateView(c.view, c.schema, /* orReplace */ true);
@@ -70,10 +77,29 @@ function renderUp(c: Change): string {
 function renderDown(c: Change): string {
   switch (c.kind) {
     case "create-table":           return `DROP TABLE ${quoteQualified(c.table.name, c.table.schema)};`;
-    case "drop-table":             return `-- WARNING: down migration cannot restore data\n-- TODO: restore table "${c.table}" structure manually`;
+    case "drop-table": {
+      if (!c.restore) {
+        return `-- WARNING: down migration cannot restore data\n-- TODO: restore table "${c.table}" structure manually`;
+      }
+      // renderCreateTable emits only columns + PK + checks. Indexes and FKs ride
+      // as separate add-index/add-fk changes on the up side, so re-create them
+      // explicitly here or the down silently loses them.
+      const parts = [renderCreateTable(c.restore)];
+      for (const index of c.restore.indexes) {
+        parts.push(renderCreateIndex(c.restore.name, c.restore.schema, index));
+      }
+      for (const fk of c.restore.foreignKeys) {
+        parts.push(renderAddFk(c.restore.name, c.restore.schema, fk));
+      }
+      parts.push("-- NOTE: table data is not restored by this down migration.");
+      return parts.join("\n");
+    }
     case "rename-table":           return `ALTER TABLE ${quoteQualified(c.to, c.schema)} RENAME TO ${quote(c.from)};`;
     case "add-column":             return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP COLUMN ${quote(c.column.name)};`;
-    case "drop-column":            return `-- WARNING: down migration cannot restore data\n-- TODO: re-add dropped column "${c.column}" manually with original type/nullable/default`;
+    case "drop-column":
+      return c.restore
+        ? `ALTER TABLE ${quoteQualified(c.table, c.schema)} ADD COLUMN ${renderColumn(c.restore)};\n-- NOTE: column data is not restored by this down migration.`
+        : `-- WARNING: down migration cannot restore data\n-- TODO: re-add dropped column "${c.column}" manually with original type/nullable/default`;
     case "rename-column":          return `ALTER TABLE ${quoteQualified(c.table, c.schema)} RENAME COLUMN ${quote(c.to)} TO ${quote(c.from)};`;
     case "change-column-type":     return `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} TYPE ${pgType(c.from)};`;
     case "change-column-nullable":
@@ -85,9 +111,22 @@ function renderDown(c: Change): string {
         ? `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} SET DEFAULT ${renderDefault(c.from)};`
         : `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} DROP DEFAULT;`;
     case "add-index":              return `DROP INDEX ${quoteIndexQualified(c.index.name, c.schema)};`;
-    case "drop-index":             return `-- WARNING: down migration cannot restore the original index definition`;
+    case "drop-index":
+      return c.restore
+        ? renderCreateIndex(c.table, c.schema, c.restore)
+        : `-- WARNING: down migration cannot restore the original index definition`;
     case "add-fk":                 return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.fk.name)};`;
-    case "drop-fk":                return `-- WARNING: down migration cannot restore the original FK definition`;
+    case "drop-fk":
+      return c.restore
+        ? renderAddFk(c.table, c.schema, c.restore)
+        : `-- WARNING: down migration cannot restore the original FK definition`;
+    // add-check / drop-check down arms: declared but not yet produced by the diff
+    // (checks are create-time-only; see renderUp note).
+    case "add-check":              return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.check.name)};`;
+    case "drop-check":
+      return c.restore
+        ? `ALTER TABLE ${quoteQualified(c.table, c.schema)} ADD CONSTRAINT ${quote(c.restore.name)} CHECK (${c.restore.expression});`
+        : `-- WARNING: down migration cannot restore the original CHECK definition`;
     case "create-view":            return `DROP VIEW ${quoteQualifiedView(c.view.name, c.schema)};`;
     case "drop-view":              return `-- WARNING: down migration cannot restore the original view definition`;
     case "replace-view":           return `-- WARNING: down migration cannot restore the original view definition`;
@@ -99,6 +138,9 @@ function renderCreateTable(t: TableDescriptor): string {
   if (t.primaryKey.length > 0) {
     colDefs.push(`  CONSTRAINT ${quote(t.name + "_pkey")} PRIMARY KEY (${t.primaryKey.map(quote).join(", ")})`);
   }
+  for (const chk of t.checks ?? []) {
+    colDefs.push(`  CONSTRAINT ${quote(chk.name)} CHECK (${chk.expression})`);
+  }
   const create = `CREATE TABLE ${quoteQualified(t.name, t.schema)} (\n${colDefs.join(",\n")}\n);`;
   const comments = renderTableComments(t);
   return comments.length === 0 ? create : `${create}\n${comments.join("\n")}`;
@@ -156,6 +198,7 @@ function pgType(t: SqlType): string {
     case "boolean":   return "BOOLEAN";
     case "timestamp": return t.withTimezone ? "TIMESTAMPTZ" : "TIMESTAMP";
     case "date":      return "DATE";
+    case "time":      return "TIME";
     case "json":      return "JSONB";
     case "blob":      return "BYTEA";
     case "uuid":      return "UUID";

package/src/emit/sqlite.ts

@@ -13,6 +13,7 @@ const STAGE_ORDER: Record<Change["kind"], number> = {
   "rename-column": 3, "rename-table": 3,
   "add-index": 4, "drop-index": 4,
   "add-fk": 5, "drop-fk": 5,
+  "add-check": 5, "drop-check": 5,
   "drop-table": 6,
   "create-view": 99, "drop-view": 99, "replace-view": 99,
 };
@@ -110,6 +111,8 @@ function changeTable(c: Change): string | undefined {
     case "drop-index":
     case "add-fk":
     case "drop-fk":
+    case "add-check":
+    case "drop-check":
       return c.table;
     default:
       return undefined;
@@ -188,6 +191,12 @@ function renderUpNative(c: Change): string {
     case "rename-column":  return `ALTER TABLE ${quote(c.table)} RENAME COLUMN ${quote(c.from)} TO ${quote(c.to)};`;
     case "add-index":      return renderCreateIndex(c.table, c.index);
     case "drop-index":     return `DROP INDEX ${quote(c.index)};`;
+    case "add-check":
+    case "drop-check":
+      // Declared for future existing-table support; the diff does not yet produce
+      // these (checks are create-time-only, inlined in CREATE TABLE). Unreachable
+      // today — throw rather than silently mis-emit if one ever arrives here.
+      throw new Error("CHECK migration not implemented for sqlite (recreate path pending)");
     case "change-column-type":
     case "change-column-nullable":
     case "change-column-default":
@@ -212,6 +221,12 @@ function renderDownNative(c: Change): string {
     case "rename-column":  return `ALTER TABLE ${quote(c.table)} RENAME COLUMN ${quote(c.to)} TO ${quote(c.from)};`;
     case "add-index":      return `DROP INDEX ${quote(c.index.name)};`;
     case "drop-index":     return `-- WARNING: down migration cannot restore the original index definition`;
+    case "add-check":
+    case "drop-check":
+      // Declared for future existing-table support; the diff does not yet produce
+      // these (checks are create-time-only, inlined in CREATE TABLE). Unreachable
+      // today — throw rather than silently mis-emit if one ever arrives here.
+      throw new Error("CHECK migration not implemented for sqlite (recreate path pending)");
     case "change-column-type":
     case "change-column-nullable":
     case "change-column-default":
@@ -243,6 +258,12 @@ function renderCreateTable(t: TableDescriptor): string {
     if (fk.onUpdate) clause += ` ON UPDATE ${renderFkAction(fk.onUpdate)}`;
     colDefs.push(clause);
   }
+  // CHECK constraints are inlined into the CREATE TABLE DDL (SQLite supports
+  // inline named CHECK). Checks are create-time-only; the diff never produces
+  // add-check / drop-check, so this is the sole place SQLite emits a CHECK.
+  for (const chk of t.checks ?? []) {
+    colDefs.push(`  CONSTRAINT ${quote(chk.name)} CHECK (${chk.expression})`);
+  }
   return `CREATE TABLE ${quote(t.name)} (\n${colDefs.join(",\n")}\n);`;
 }
 
@@ -286,6 +307,7 @@ function sqliteType(t: SqlType, identity: ColumnDescriptor["identity"]): string
     case "boolean":   return "BOOLEAN";        // SQLite stores as 0/1 but preserves declared type for round-trip
     case "timestamp": return "TIMESTAMP";
     case "date":      return "DATE";
+    case "time":      return "TIME";
     case "json":      return "TEXT";          // SQLite has JSON1 but stores as text
     case "blob":      return "BLOB";
     case "uuid":      return "TEXT";

package/src/errors.ts

@@ -65,6 +65,10 @@ function changeLocator(c: Change): string {
       return `${c.table}.${c.fk.name}`;
     case "drop-fk":
       return `${c.table}.${c.fk}`;
+    case "add-check":
+      return `${c.table}.${c.check.name}`;
+    case "drop-check":
+      return `${c.table}.${c.check}`;
     case "create-view":
     case "replace-view":
       return c.view.name;

package/src/expected-schema.ts

@@ -1,11 +1,15 @@
-import type { ColumnNamingStrategy, MetaData, MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import type { ColumnNamingStrategy, MetaData, MetaObject, MetaRoot, MetaValidator } from "@metaobjectsdev/metadata";
 import {
+  VALIDATOR_SUBTYPE_NUMERIC, VALIDATOR_SUBTYPE_LENGTH, VALIDATOR_SUBTYPE_REGEX,
+  VALIDATOR_ATTR_PATTERN,
   TYPE_OBJECT,
   MetaSource,
   IDENTITY_ATTR_GENERATION,
   IDENTITY_ATTR_UNIQUE,
   FIELD_ATTR_DEFAULT,
   FIELD_ATTR_MAX_LENGTH,
+  FIELD_ATTR_PRECISION,
+  FIELD_ATTR_SCALE,
   FIELD_ATTR_UNIQUE,
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_INT,
@@ -22,8 +26,15 @@ import {
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_CLASS,
+  FIELD_SUBTYPE_UUID,
+  FIELD_SUBTYPE_ENUM,
+  FIELD_ATTR_VALUES,
   FIELD_ATTR_OBJECT_REF,
   FIELD_ATTR_STORAGE,
+  FIELD_ATTR_DB_COLUMN_TYPE,
+  DB_COLUMN_TYPE_UUID,
+  DB_COLUMN_TYPE_JSONB,
+  DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ,
   STORAGE_FLATTENED,
   DOC_ATTR_DESCRIPTION,
   applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY,
@@ -32,6 +43,7 @@ import {
 import type { SqlType } from "./sql-type.js";
 import type {
   Dialect, SchemaSnapshot, TableDescriptor, ColumnDescriptor, IndexDescriptor, FkDescriptor,
+  CheckDescriptor,
 } from "./types.js";
 import { buildExpectedViews } from "./expected-views.js";
 import {
@@ -97,7 +109,7 @@ export function buildExpectedSchema(
   // Schema is resolved here (not stored in Pass 1) to avoid exactOptionalPropertyTypes
   // issues with `string | undefined` vs `schema?: string`.
   const tables: TableDescriptor[] = entities.map(({ entity, tableName }) => {
-    const t = buildTable(entity, tableName, resolveTargetTable, root as MetaRoot, strategy);
+    const t = buildTable(entity, tableName, resolveTargetTable, root as MetaRoot, strategy, dialect);
     const schema = resolveTableSchema(entity);
     if (schema !== undefined) t.schema = schema;
     return t;
@@ -142,6 +154,7 @@ function normalizeForSqlite(sqlType: SqlType): SqlType {
       return { kind: "integer", bits: 64 };
     case "timestamp":
     case "date":
+    case "time":
       return { kind: "text" };
     case "integer":
       // SQLite stores every INTEGER as a 64-bit value and Drizzle's int() emits
@@ -155,6 +168,12 @@ function normalizeForSqlite(sqlType: SqlType): SqlType {
       // what the SQLite introspector produces, preventing a phantom
       // change-column-type diff on every field.float column.
       return { kind: "real" };
+    case "uuid":
+      // SQLite has no native uuid type; uuid values are stored as TEXT (the
+      // conformance corpus is Postgres-only, but TS supports a sqlite dialect).
+      // Collapse uuid → text so the expected snapshot matches what the SQLite
+      // introspector produces, preventing a phantom change-column-type diff.
+      return { kind: "text" };
     default:
       return sqlType;
   }
@@ -166,6 +185,7 @@ function buildTable(
   resolveTargetTable: (entityName: string) => string | undefined,
   root: MetaRoot,
   strategy: ColumnNamingStrategy,
+  dialect: Dialect | undefined,
 ): TableDescriptor {
   // Use effective accessors so inherited fields/identities (from `extends:` /
   // abstract bases like BaseEntity) are included.
@@ -201,6 +221,7 @@ function buildTable(
     columns,
     indexes: buildSecondaryIndexes(entity, tableName, strategy),
     foreignKeys: buildForeignKeys(entity, tableName, resolveTargetTable, root, strategy),
+    checks: buildChecks(entity, tableName, strategy, dialect),
     primaryKey,
   };
   const entityDesc = readDescription(entity);
@@ -258,6 +279,80 @@ function buildSecondaryIndexes(
   return indexes;
 }
 
+/**
+ * Derive a CHECK constraint per `field.enum` field: `CHECK (<col> IN ('A', 'B'))`,
+ * constraining the column to the declared `@values` members. The constraint name
+ * is `<table>_<column>_chk`, mirroring the FK/index naming conventions.
+ *
+ * `@values` is read effective (`field.attr`) so a concrete field that extends an
+ * abstract `field.enum` super inherits its members. The loader rejects a
+ * `field.enum` without `@values` (ERR_MISSING_REQUIRED_ATTR), so a present enum
+ * field always yields a non-empty member set; a defensive guard skips any edge
+ * case where the array is absent rather than emitting `IN ()`.
+ */
+/**
+ * Map a single declared validator to a DB CHECK descriptor, or null when it has
+ * no SQL-expressible form on this dialect. The constraint name is
+ * `<table>_<col>_<validator>_chk`. The expression references the resolved physical
+ * column name verbatim (matching the enum-check convention).
+ */
+function validatorCheck(
+  v: MetaValidator, col: string, tableName: string, dialect: Dialect | undefined,
+): CheckDescriptor | null {
+  switch (v.subType) {
+    case VALIDATOR_SUBTYPE_NUMERIC: {
+      const parts: string[] = [];
+      if (v.min !== undefined) parts.push(`${col} >= ${v.min}`);
+      if (v.max !== undefined) parts.push(`${col} <= ${v.max}`);
+      if (parts.length === 0) return null;
+      return { name: `${tableName}_${col}_numeric_chk`, expression: parts.join(" AND ") };
+    }
+    case VALIDATOR_SUBTYPE_LENGTH: {
+      const parts: string[] = [];
+      if (v.min !== undefined) parts.push(`length(${col}) >= ${v.min}`);
+      if (v.max !== undefined) parts.push(`length(${col}) <= ${v.max}`);
+      if (parts.length === 0) return null;
+      return { name: `${tableName}_${col}_length_chk`, expression: parts.join(" AND ") };
+    }
+    case VALIDATOR_SUBTYPE_REGEX: {
+      // Postgres-only: SQLite has no native regex operator.
+      if (dialect === "sqlite" || dialect === "d1") return null;
+      const pattern = v.ownAttr(VALIDATOR_ATTR_PATTERN);
+      if (typeof pattern !== "string" || pattern.length === 0) return null;
+      return {
+        name: `${tableName}_${col}_regex_chk`,
+        expression: `${col} ~ '${pattern.replace(/'/g, "''")}'`,
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+function buildChecks(
+  entity: MetaObject, tableName: string, strategy: ColumnNamingStrategy, dialect: Dialect | undefined,
+): CheckDescriptor[] {
+  const checks: CheckDescriptor[] = [];
+  for (const field of entity.fields()) {
+    const col = resolveColumnName(field, strategy);
+    // Enum membership check (unchanged).
+    if (field.subType === FIELD_SUBTYPE_ENUM) {
+      const raw = field.attr(FIELD_ATTR_VALUES);
+      if (Array.isArray(raw) && raw.length > 0) {
+        const values = raw.map((v) => String(v));
+        const expression = `${col} IN (${values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ")})`;
+        checks.push({ name: `${tableName}_${col}_chk`, expression });
+      }
+    }
+    // Validator-derived checks.
+    for (const v of field.validators()) {
+      const check = validatorCheck(v, col, tableName, dialect);
+      if (check) checks.push(check);
+    }
+  }
+  return checks;
+}
+
 function buildForeignKeys(
   entity: MetaObject,
   tableName: string,
@@ -375,6 +470,18 @@ function buildColumn(
 }
 
 function subtypeToSqlType(field: MetaData): SqlType {
+  // R6 Plan 2b: a physical @dbColumnType override selects the DB column type
+  // instead of the subtype default (the loader has already validated the
+  // (subtype × value) pairing, so an unrecognized value never reaches here).
+  const dbColumnType = field.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
+  if (typeof dbColumnType === "string") {
+    switch (dbColumnType) {
+      case DB_COLUMN_TYPE_UUID:              return { kind: "uuid" };
+      case DB_COLUMN_TYPE_JSONB:             return { kind: "json" };
+      case DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ: return { kind: "timestamp", withTimezone: true };
+    }
+  }
+
   const subType = field.subType;
   switch (subType) {
     case FIELD_SUBTYPE_STRING:    {
@@ -389,13 +496,26 @@ function subtypeToSqlType(field: MetaData): SqlType {
     case FIELD_SUBTYPE_CURRENCY:  return { kind: "integer", bits: 64 };
     case FIELD_SUBTYPE_DOUBLE:    return { kind: "real" };
     case FIELD_SUBTYPE_FLOAT:     return { kind: "real4" };
-    case FIELD_SUBTYPE_DECIMAL:   return { kind: "numeric" };
+    case FIELD_SUBTYPE_DECIMAL:   {
+      // @precision/@scale are declared as ATTR_SUBTYPE_INT so the loader coerces them
+      // to numbers. Both present → NUMERIC(p,s); absent → bare NUMERIC (back-compat).
+      const precision = field.ownAttr(FIELD_ATTR_PRECISION);
+      const scale = field.ownAttr(FIELD_ATTR_SCALE);
+      if (typeof precision === "number" && typeof scale === "number") {
+        return { kind: "numeric", precision, scale };
+      }
+      if (typeof precision === "number") {
+        return { kind: "numeric", precision };
+      }
+      return { kind: "numeric" };
+    }
     case FIELD_SUBTYPE_BOOLEAN:   return { kind: "boolean" };
     case FIELD_SUBTYPE_DATE:      return { kind: "date" };
-    case FIELD_SUBTYPE_TIME:      return { kind: "text" }; // SQL TIME rare; coerce to text
+    case FIELD_SUBTYPE_TIME:      return { kind: "time" }; // Postgres native TIME (whole-second wire form)
     case FIELD_SUBTYPE_TIMESTAMP: return { kind: "timestamp", withTimezone: false };
     case FIELD_SUBTYPE_OBJECT:
     case FIELD_SUBTYPE_CLASS:     return { kind: "json" };
+    case FIELD_SUBTYPE_UUID:      return { kind: "uuid" }; // R6 Plan 2a — Postgres native uuid
     default:                      return { kind: "text" }; // unknown → text fallback
   }
 }

package/src/index.ts

@@ -11,10 +11,24 @@
 export { buildExpectedSchema } from "./expected-schema.js";
 export { introspect, introspectPostgres, introspectSqlite } from "./introspect/index.js";
 export { diff } from "./diff/index.js";
+export { computeDrift, type ComputeDriftOptions } from "./drift/drift.js";
+export { classifyDrift, driftAgainstSnapshot } from "./drift/classify.js";
+export type { DriftClassification } from "./drift/classify.js";
 export { emit } from "./emit/index.js";
 export { writeMigration } from "./write-migration.js";
 export { writeMigrationD1 } from "./write-migration-d1.js";
 
+// Reference-snapshot generation (offline, deterministic).
+export {
+  serializeSnapshot,
+  parseSnapshot,
+  SNAPSHOT_FORMAT_VERSION,
+} from "./snapshot/serialize.js";
+export { snapshotChecksum } from "./snapshot/checksum.js";
+export { snapshotPath, readSnapshot, writeSnapshot } from "./snapshot/store.js";
+export { planOffline, baselineFromMetadata } from "./snapshot/plan.js";
+export type { PlanOfflineArgs, PlanOfflineResult } from "./snapshot/plan.js";
+
 // Errors
 export { BlockedChangesError, SetNullNotNullableError } from "./errors.js";
 
@@ -37,6 +51,7 @@ export type { WriteMigrationOptions, WriteMigrationResult } from "./write-migrat
 export type { WriteMigrationD1Options, WriteMigrationD1Result } from "./write-migration-d1.js";
 
 // View diff + dialect emitters
+export { normalizeViewSql, viewSqlEquals } from "./view-sql-compare.js";
 export { classifyViewDiff } from "./view-diff.js";
 export type { ViewShape, ViewDiffClass, ViewMigrationOpts } from "./view-diff.js";
 export { emitPostgresViewMigration } from "./view-ddl-postgres.js";
@@ -60,6 +75,35 @@ export {
 // D1 introspection
 export { introspectD1, type D1Runner, type IntrospectD1Options } from "./introspect/d1.js";
 
+// Migration-history ledger + ordered transactional apply (postgres/sqlite)
+export {
+  ensureLedger,
+  recordApplied,
+  deleteApplied,
+  appliedNames,
+  appliedRecords,
+  recordBaseline,
+  baselineRecord,
+  BASELINE_NAME,
+  MIGRATIONS_TABLE,
+  DEFAULT_LEDGER_SCHEMA,
+  type LedgerRow,
+  type LedgerOptions,
+  type LedgerDialect,
+} from "./apply/ledger.js";
+export {
+  applyPending,
+  rollbackTo,
+  type ApplyPendingOptions,
+  type ApplyPendingResult,
+  type RollbackToOptions,
+  type RollbackToResult,
+} from "./apply/apply.js";
+
+// Snapshot-integrity: replay migrations and assert == committed snapshot.
+export { verifyReplay } from "./verify/replay.js";
+export type { VerifyReplayArgs, VerifyReplayResult } from "./verify/replay.js";
+
 // Wrangler config helpers
 export {
   findWranglerConfig,

package/src/introspect/d1.ts

@@ -71,6 +71,7 @@ export async function introspectD1(opts: IntrospectD1Options): Promise<SchemaSna
       columns: cols,
       indexes: await readIndexes(exec, name),
       foreignKeys: await readForeignKeys(exec, name),
+      checks: [], // CHECK introspection is out of scope; expected-side derives them
       primaryKey: pk,
     });
   }

package/src/introspect/postgres.ts

@@ -28,8 +28,10 @@
  */
 import type { Kysely } from "kysely";
 import { sql } from "kysely";
-import type { SchemaSnapshot, TableDescriptor, ColumnDescriptor, ColumnDefault, IndexDescriptor, FkDescriptor, FkAction, ViewDescriptor } from "../types.js";
+import type { SchemaSnapshot, TableDescriptor, ColumnDescriptor, ColumnDefault, IndexDescriptor, FkDescriptor, FkAction, ViewDescriptor, CheckDescriptor } from "../types.js";
 import type { SqlType } from "../sql-type.js";
+import { MIGRATIONS_TABLE } from "../apply/ledger.js";
+import { stripCheckWrapper } from "../check-expr-compare.js";
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -51,6 +53,7 @@ export async function introspectPostgres(db: Kysely<Record<string, unknown>>): P
       columns,
       indexes: await readPgIndexes(k, schema, name),
       foreignKeys: await readPgForeignKeys(k, schema, name),
+      checks: await readPgChecks(k, schema, name),
       primaryKey,
     });
   }
@@ -121,6 +124,7 @@ export function pgTypeToSqlType(dataType: string, maxLength?: number | null): Sq
 
   // Date + time
   if (dt === "date") return { kind: "date" };
+  if (dt === "time" || dt === "time without time zone") return { kind: "time" };
   if (dt === "timestamp" || dt === "timestamp without time zone") {
     return { kind: "timestamp", withTimezone: false };
   }
@@ -207,6 +211,7 @@ async function readTableNames(k: Kysely<any>): Promise<SchemaTableRef[]> {
     WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
       AND table_schema NOT LIKE 'pg_%'
       AND table_type = 'BASE TABLE'
+      AND table_name <> ${MIGRATIONS_TABLE}
     ORDER BY table_schema, table_name
   `.execute(k);
   return rows.rows.map((r) => ({ schema: r.table_schema, name: r.table_name }));
@@ -217,13 +222,20 @@ async function readPgViews(k: RawKysely): Promise<ViewDescriptor[]> {
   // "relation views does not exist". We catch and return [] so other tests
   // still pass on pg-mem. Real PG (Postgres 16) handles this correctly.
   try {
-    const rows = await sql<{ table_name: string; table_schema: string }>`
-      SELECT table_name, table_schema FROM information_schema.views
+    // information_schema.views.view_definition is the SELECT body (not the
+    // full CREATE VIEW statement). We carry it through on the descriptor so the
+    // diff can detect view-body drift (not just name presence).
+    const rows = await sql<{ table_name: string; table_schema: string; view_definition: string | null }>`
+      SELECT table_name, table_schema, view_definition FROM information_schema.views
       WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
         AND table_schema NOT LIKE 'pg_%'
       ORDER BY table_schema, table_name
     `.execute(k);
-    return rows.rows.map((r) => ({ name: r.table_name, schema: r.table_schema }));
+    return rows.rows.map((r) => {
+      const view: ViewDescriptor = { name: r.table_name, schema: r.table_schema };
+      if (r.view_definition) view.sql = r.view_definition;
+      return view;
+    });
   } catch {
     // pg-mem: information_schema.views not supported — return empty view list.
     return [];
@@ -426,3 +438,25 @@ function pgRuleToAction(rule: string): FkAction {
   if (r === "RESTRICT") return "restrict";
   return "no-action";
 }
+
+/**
+ * Read CHECK constraints for a table from pg_constraint. pg-mem does not support
+ * pg_constraint, so this catches and returns [] there (same accepted gap as
+ * readPgForeignKeys/readPgIndexes); real-DB coverage is the MIGRATE_TS_PG_URL-gated
+ * integration test. `pg_get_constraintdef` returns `CHECK (<expr>)`; the wrapper is
+ * stripped to the expression, compared via normalizeCheckExpr at diff time.
+ */
+async function readPgChecks(k: RawKysely, schema: string, table: string): Promise<CheckDescriptor[]> {
+  try {
+    const rows = await sql<{ name: string; def: string }>`
+      SELECT con.conname AS name, pg_get_constraintdef(con.oid) AS def
+      FROM pg_constraint con
+      JOIN pg_class rel ON rel.oid = con.conrelid
+      JOIN pg_namespace ns ON ns.oid = rel.relnamespace
+      WHERE con.contype = 'c' AND rel.relname = ${table} AND ns.nspname = ${schema}
+    `.execute(k);
+    return rows.rows.map((r) => ({ name: r.name, expression: stripCheckWrapper(r.def) }));
+  } catch {
+    return []; // pg-mem: pg_constraint unsupported
+  }
+}

package/src/introspect/sqlite.ts

@@ -5,6 +5,7 @@ import type {
   IndexDescriptor, FkDescriptor, FkAction, ViewDescriptor,
 } from "../types.js";
 import { parseSqliteDefault, sqliteTypeToSqlType, sqliteRuleToAction } from "./sqlite-shared.js";
+import { MIGRATIONS_TABLE } from "../apply/ledger.js";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type RawKysely = Kysely<any>;
@@ -18,6 +19,7 @@ export async function introspectSqlite(db: Kysely<Record<string, unknown>>): Pro
   const tableNamesRows = await sql<{ name: string; sql: string | null }>`
     SELECT name, sql FROM sqlite_master
     WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__new_%'
+      AND name <> ${MIGRATIONS_TABLE}
     ORDER BY name
   `.execute(k);
 
@@ -36,6 +38,7 @@ export async function introspectSqlite(db: Kysely<Record<string, unknown>>): Pro
       columns: cols,
       indexes: await readSqliteIndexes(k, t.name),
       foreignKeys: await readSqliteForeignKeys(k, t.name),
+      checks: [], // CHECK introspection is out of scope; expected-side derives them
       primaryKey: pk,
     });
   }
@@ -45,11 +48,18 @@ export async function introspectSqlite(db: Kysely<Record<string, unknown>>): Pro
 }
 
 async function readSqliteViews(k: RawKysely): Promise<ViewDescriptor[]> {
-  const rows = await sql<{ name: string }>`
-    SELECT name FROM sqlite_master WHERE type='view' AND name NOT LIKE 'sqlite_%'
+  // sqlite_master.sql holds the full `CREATE VIEW <name> AS <body>` statement.
+  // We carry it through on the descriptor so the diff can detect view-body
+  // drift (not just name presence).
+  const rows = await sql<{ name: string; sql: string | null }>`
+    SELECT name, sql FROM sqlite_master WHERE type='view' AND name NOT LIKE 'sqlite_%'
     ORDER BY name
   `.execute(k);
-  return rows.rows.map((r) => ({ name: r.name }));
+  return rows.rows.map((r) => {
+    const view: ViewDescriptor = { name: r.name };
+    if (r.sql) view.sql = r.sql;
+    return view;
+  });
 }
 
 async function readSqliteColumns(k: RawKysely, table: string): Promise<ColumnDescriptor[]> {

package/src/snapshot/checksum.ts

@@ -0,0 +1,15 @@
+// src/snapshot/checksum.ts
+import { createHash } from "node:crypto";
+import type { SchemaSnapshot } from "../types.js";
+import { serializeSnapshot } from "./serialize.js";
+
+/**
+ * Deterministic sha256 of a schema snapshot. Reuses the canonical
+ * (order-stable, byte-identical) serializer, so the hash is independent of
+ * table/column ordering and depends only on the schema's content. Used to make
+ * the committed snapshot tamper-evident (record the hash; a later hand-edit
+ * changes it) and as the baseline marker's payload.
+ */
+export function snapshotChecksum(snapshot: SchemaSnapshot): string {
+  return createHash("sha256").update(serializeSnapshot(snapshot), "utf8").digest("hex");
+}

package/src/snapshot/plan.ts

@@ -0,0 +1,53 @@
+// src/snapshot/plan.ts
+import type { ColumnNamingStrategy, MetaData } from "@metaobjectsdev/metadata";
+import { buildExpectedSchema } from "../expected-schema.js";
+import { diff, type DiffArgs } from "../diff/index.js";
+import type { Dialect, DiffResult, SchemaSnapshot } from "../types.js";
+
+export interface PlanOfflineArgs extends Pick<DiffArgs, "allow" | "onAmbiguous" | "ignoreTables"> {
+  metadata: MetaData;
+  dialect: Dialect;
+  /** The stored reference snapshot (the "from" side). Use `{ tables: [], views: [] }` for a fresh project. */
+  snapshot: SchemaSnapshot;
+  columnNamingStrategy?: ColumnNamingStrategy;
+}
+
+export interface PlanOfflineResult {
+  /** The change set to emit, from diffing metadata-expected against the snapshot. */
+  diff: DiffResult;
+  /** The schema the migration brings us to — write this back as the new snapshot on accept. */
+  nextSnapshot: SchemaSnapshot;
+}
+
+/**
+ * Plan a migration offline: build the expected schema from metadata and diff it
+ * against the stored snapshot. No database. The caller emits `diff` and, on
+ * accept, persists `nextSnapshot` via writeSnapshot.
+ */
+export async function planOffline(args: PlanOfflineArgs): Promise<PlanOfflineResult> {
+  const nextSnapshot = buildExpectedSchema(args.metadata, {
+    dialect: args.dialect,
+    ...(args.columnNamingStrategy ? { columnNamingStrategy: args.columnNamingStrategy } : {}),
+  });
+  const result = await diff({
+    expected: nextSnapshot,
+    actual: args.snapshot,
+    dialect: args.dialect,
+    ...(args.allow ? { allow: args.allow } : {}),
+    ...(args.onAmbiguous ? { onAmbiguous: args.onAmbiguous } : {}),
+    ...(args.ignoreTables ? { ignoreTables: args.ignoreTables } : {}),
+  });
+  return { diff: result, nextSnapshot };
+}
+
+/** Seed an initial reference snapshot from metadata (greenfield baseline). */
+export function baselineFromMetadata(
+  metadata: MetaData,
+  dialect: Dialect,
+  columnNamingStrategy?: ColumnNamingStrategy,
+): SchemaSnapshot {
+  return buildExpectedSchema(metadata, {
+    dialect,
+    ...(columnNamingStrategy ? { columnNamingStrategy } : {}),
+  });
+}