@metaobjectsdev/migrate-ts 0.5.0-rc.1

package/dist/view-ddl-sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-ddl-sqlite.d.ts","sourceRoot":"","sources":["../src/view-ddl-sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAIvE"}

package/dist/view-ddl-sqlite.js

@@ -0,0 +1,7 @@
+export function emitSqliteViewMigration(opts) {
+    if (opts.diffClass === "no-change")
+        return "";
+    // SQLite has no CREATE OR REPLACE VIEW; must drop+create. Wrap in txn.
+    return `BEGIN;\nDROP VIEW IF EXISTS ${opts.viewName};\n${opts.createSql}\nCOMMIT;`;
+}
+//# sourceMappingURL=view-ddl-sqlite.js.map

package/dist/view-ddl-sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-ddl-sqlite.js","sourceRoot":"","sources":["../src/view-ddl-sqlite.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,uBAAuB,CAAC,IAAuB;IAC7D,IAAI,IAAI,CAAC,SAAS,KAAK,WAAW;QAAE,OAAO,EAAE,CAAC;IAC9C,uEAAuE;IACvE,OAAO,+BAA+B,IAAI,CAAC,QAAQ,MAAM,IAAI,CAAC,SAAS,WAAW,CAAC;AACrF,CAAC"}

package/dist/view-diff.d.ts

@@ -0,0 +1,13 @@
+export interface ViewShape {
+    readonly columns: readonly string[];
+    readonly columnTypes?: Readonly<Record<string, string>>;
+}
+export type ViewDiffClass = "no-change" | "safe-append" | "safe-replace" | "breaking";
+export interface ViewMigrationOpts {
+    readonly diffClass: ViewDiffClass;
+    readonly viewName: string;
+    /** Full `CREATE VIEW <name> AS ...;` statement (semicolon included). */
+    readonly createSql: string;
+}
+export declare function classifyViewDiff(prev: ViewShape, next: ViewShape): ViewDiffClass;
+//# sourceMappingURL=view-diff.d.ts.map

package/dist/view-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-diff.d.ts","sourceRoot":"","sources":["../src/view-diff.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACzD;AAED,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,aAAa,GACb,cAAc,GACd,UAAU,CAAC;AAEf,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,aAAa,CAoChF"}

package/dist/view-diff.js

@@ -0,0 +1,42 @@
+export function classifyViewDiff(prev, next) {
+    const prevCols = prev.columns;
+    const nextCols = next.columns;
+    // Dropped column = breaking.
+    for (const c of prevCols) {
+        if (!nextCols.includes(c))
+            return "breaking";
+    }
+    // Type change on existing column = breaking.
+    if (prev.columnTypes && next.columnTypes) {
+        for (const c of prevCols) {
+            const pt = prev.columnTypes[c];
+            const nt = next.columnTypes[c];
+            if (pt && nt && pt !== nt)
+                return "breaking";
+        }
+    }
+    if (prevCols.length === nextCols.length) {
+        // Same length, same set → either identical order or reordered.
+        let identical = true;
+        for (let i = 0; i < prevCols.length; i++) {
+            if (prevCols[i] !== nextCols[i]) {
+                identical = false;
+                break;
+            }
+        }
+        return identical ? "no-change" : "safe-replace";
+    }
+    // Longer next, same prefix? → safe-append.
+    let prefixMatches = true;
+    for (let i = 0; i < prevCols.length; i++) {
+        if (prevCols[i] !== nextCols[i]) {
+            prefixMatches = false;
+            break;
+        }
+    }
+    if (prefixMatches)
+        return "safe-append";
+    // Mixed: reordered + appended → safe-replace (data shape unchanged at column level).
+    return "safe-replace";
+}
+//# sourceMappingURL=view-diff.js.map

package/dist/view-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-diff.js","sourceRoot":"","sources":["../src/view-diff.ts"],"names":[],"mappings":"AAkBA,MAAM,UAAU,gBAAgB,CAAC,IAAe,EAAE,IAAe;IAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC;IAE9B,6BAA6B;IAC7B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,UAAU,CAAC;IAC/C,CAAC;IAED,6CAA6C;IAC7C,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAC/B,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAC/B,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE;gBAAE,OAAO,UAAU,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxC,+DAA+D;QAC/D,IAAI,SAAS,GAAG,IAAI,CAAC;QACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBAAC,SAAS,GAAG,KAAK,CAAC;gBAAC,MAAM;YAAC,CAAC;QAChE,CAAC;QACD,OAAO,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC;IAClD,CAAC;IAED,2CAA2C;IAC3C,IAAI,aAAa,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YAAC,aAAa,GAAG,KAAK,CAAC;YAAC,MAAM;QAAC,CAAC;IACpE,CAAC;IACD,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IAExC,qFAAqF;IACrF,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/write-migration.d.ts

@@ -0,0 +1,19 @@
+import type { EmitResult } from "./types.js";
+export interface WriteMigrationOptions {
+    /** Migrations root directory (e.g., ".meta/migrations"). Must already exist. */
+    dir: string;
+    /** Human-readable slug; sanitized to lowercase + hyphens. */
+    slug: string;
+    /** Override for the timestamp source (UTC). Defaults to new Date(). */
+    now?: Date;
+}
+export interface WriteMigrationResult {
+    /** Absolute path to the per-migration directory created. */
+    dir: string;
+    /** Path to up.sql. */
+    upPath: string;
+    /** Path to down.sql. */
+    downPath: string;
+}
+export declare function writeMigration(result: Pick<EmitResult, "up" | "down">, opts: WriteMigrationOptions): Promise<WriteMigrationResult>;
+//# sourceMappingURL=write-migration.d.ts.map

package/dist/write-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-migration.d.ts","sourceRoot":"","sources":["../src/write-migration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,CAAC,EACvC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}

package/dist/write-migration.js

@@ -0,0 +1,34 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export async function writeMigration(result, opts) {
+    const ts = formatTimestamp(opts.now ?? new Date());
+    const slug = sanitizeSlug(opts.slug);
+    const migrationDir = join(opts.dir, `${ts}-${slug}`);
+    // Create only the per-migration directory (not the root) — root must exist.
+    await mkdir(migrationDir, { recursive: false });
+    const upPath = join(migrationDir, "up.sql");
+    const downPath = join(migrationDir, "down.sql");
+    await writeFile(upPath, ensureTrailingNewline(result.up), "utf8");
+    await writeFile(downPath, ensureTrailingNewline(result.down), "utf8");
+    return { dir: migrationDir, upPath, downPath };
+}
+function formatTimestamp(d) {
+    const pad = (n) => n.toString().padStart(2, "0");
+    return (d.getUTCFullYear().toString() +
+        pad(d.getUTCMonth() + 1) +
+        pad(d.getUTCDate()) +
+        pad(d.getUTCHours()) +
+        pad(d.getUTCMinutes()) +
+        pad(d.getUTCSeconds()));
+}
+function sanitizeSlug(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .substring(0, 60); // cap length for sane filesystem use
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith("\n") ? s : s + "\n";
+}
+//# sourceMappingURL=write-migration.js.map

package/dist/write-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-migration.js","sourceRoot":"","sources":["../src/write-migration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAqBjC,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAuC,EACvC,IAA2B;IAE3B,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IAErD,4EAA4E;IAC5E,MAAM,KAAK,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAEhD,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAChD,MAAM,SAAS,CAAC,MAAM,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAClE,MAAM,SAAS,CAAC,QAAQ,EAAE,qBAAqB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IAEtE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACjD,CAAC;AAED,SAAS,eAAe,CAAC,CAAO;IAC9B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzD,OAAO,CACL,CAAC,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE;QAC7B,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACxB,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;QACnB,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACpB,GAAG,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;QACtB,GAAG,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CACvB,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG;SACP,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAgB,qCAAqC;AAC3E,CAAC;AAED,SAAS,qBAAqB,CAAC,CAAS;IACtC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;AACzC,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@metaobjectsdev/migrate-ts",
+  "version": "0.5.0-rc.1",
+  "description": "Schema migration tooling for MetaObjects: diff metadata vs DB and emit SQL for Postgres and SQLite.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
+  },
+  "license": "Apache-2.0",
+  "author": "Doug Mealing <doug@dougmealing.com>",
+  "homepage": "https://metaobjects.dev",
+  "bugs": {
+  "url": "https://github.com/metaobjectsdev/metaobjects/issues"
+},
+"repository": {
+  "type": "git",
+  "url": "https://github.com/metaobjectsdev/metaobjects.git",
+  "directory": "server/typescript/packages/migrate-ts"
+},
+"keywords": ["metaobjects", "migrate", "postgres", "sqlite", "schema-diff"],
+"publishConfig": {
+"access": "public"
+},
+"dependencies": {
+  "@metaobjectsdev/metadata": "0.5.0"
+},
+"peerDependencies": {
+  "kysely": ">=0.27.0"
+},
+"devDependencies": {
+  "@libsql/kysely-libsql": "^0.4.1",
+  "@types/pg": "^8.20.0",
+  "bun-types": "latest",
+  "kysely": "^0.27.0",
+  "pg": "^8.20.0",
+  "pg-mem": "^3.0.4",
+  "typescript": "^5.6.0"
+}
+}

package/src/diff/index.ts

@@ -0,0 +1,294 @@
+import type {
+  SchemaSnapshot, TableDescriptor, ColumnDescriptor, IndexDescriptor, FkDescriptor,
+  Change, ChangeStatus, DiffResult, AllowOptions, AmbiguousCallback,
+} 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 { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+
+export interface DiffArgs {
+  expected: SchemaSnapshot;
+  actual: SchemaSnapshot;
+  allow?: AllowOptions;
+  onAmbiguous?: AmbiguousCallback;
+  /**
+   * Table-name patterns to ignore on both sides of the diff. Tables matching
+   * any pattern are excluded from comparison — neither create-table nor
+   * drop-table changes are emitted for them, and they're omitted from index/
+   * fk passes. Supports exact names and `*` glob wildcards.
+   *
+   * Defaults to [`__drizzle_migrations`] when omitted so the Drizzle migration-
+   * tracking table doesn't surface as a drop. Pass `[]` explicitly to disable
+   * the default. Pass additional patterns to extend.
+   */
+  ignoreTables?: string[];
+}
+
+const ALLOWED: ChangeStatus = { state: "allowed" };
+
+/**
+ * Default ignore-table patterns. Catches migration-tracking and replication
+ * sidecar tables that downstream tools (Drizzle, litestream) create automatically.
+ */
+const DEFAULT_IGNORE_TABLES: string[] = [
+  "__drizzle_migrations",
+  "_litestream_*",
+];
+
+/**
+ * Normalize undefined schema to "public" (Postgres default) for comparison purposes.
+ * Allows snapshots from buildExpectedSchema (often undefined) to compare equal to
+ * snapshots from introspect (always populated for Postgres).
+ *
+ * For SQLite (no schema concept), every table has schema=undefined, so this maps
+ * all tables to the same "public." prefix — harmless and preserves existing behavior.
+ */
+function tableIdentity(table: { name: string; schema?: string }): string {
+  return (table.schema ?? DEFAULT_DB_SCHEMA_POSTGRES) + "." + table.name;
+}
+
+/**
+ * Build the optional-schema spread used when constructing Change records.
+ * Required because `exactOptionalPropertyTypes: true` rejects explicit `undefined`
+ * for an optional field — we either include the key or we don't.
+ */
+function schemaSpread(schema: string | undefined): { schema?: string } {
+  return schema !== undefined ? { schema } : {};
+}
+
+function tableMatchesPattern(name: string, pattern: string): boolean {
+  if (pattern.includes("*")) {
+    const regex = new RegExp(
+      "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$",
+    );
+    return regex.test(name);
+  }
+  return name === pattern;
+}
+
+function shouldIgnoreTable(name: string, patterns: string[]): boolean {
+  return patterns.some((p) => tableMatchesPattern(name, p));
+}
+
+/**
+ * Compares an expected schema (from metadata) against an actual schema (from introspection)
+ * and produces the change list to bring actual → expected. Always returns a Promise.
+ *
+ * Per spec §6.
+ *
+ * Accepts either the full DiffArgs object, or positional (expected, actual[, opts]) for
+ * convenience in tests and simple callers.
+ */
+export async function diff(args: DiffArgs): Promise<DiffResult>;
+export async function diff(expected: SchemaSnapshot, actual: SchemaSnapshot, opts?: Omit<DiffArgs, "expected" | "actual">): Promise<DiffResult>;
+export async function diff(
+  argsOrExpected: DiffArgs | SchemaSnapshot,
+  actualMaybe?: SchemaSnapshot,
+  optsMaybe?: Omit<DiffArgs, "expected" | "actual">,
+): Promise<DiffResult> {
+  // Normalize args.
+  const args: DiffArgs = isDiffArgs(argsOrExpected)
+    ? argsOrExpected
+    : { expected: argsOrExpected, actual: actualMaybe!, ...(optsMaybe ?? {}) };
+
+  const changes: Change[] = [];
+
+  const ignorePatterns = args.ignoreTables ?? DEFAULT_IGNORE_TABLES;
+  // Key tables on (schema, name) identity — same table name in different schemas
+  // are distinct entities. tableIdentity normalizes undefined → "public".
+  const expectedTables = new Map(
+    args.expected.tables
+      .filter((t) => !shouldIgnoreTable(t.name, ignorePatterns))
+      .map((t) => [tableIdentity(t), t] as const),
+  );
+  const actualTables = new Map(
+    args.actual.tables
+      .filter((t) => !shouldIgnoreTable(t.name, ignorePatterns))
+      .map((t) => [tableIdentity(t), t] as const),
+  );
+
+  // Pass 1: tables present in expected but not actual → create-table + add-index + add-fk
+  // Indexes and FKs are separate SQL statements (not part of CREATE TABLE), so they
+  // must be emitted as individual changes even for brand-new tables.
+  for (const [id, table] of expectedTables) {
+    if (!actualTables.has(id)) {
+      changes.push({ kind: "create-table", table, ...schemaSpread(table.schema), status: ALLOWED });
+      for (const index of table.indexes) {
+        changes.push({
+          kind: "add-index", table: table.name, ...schemaSpread(table.schema),
+          index, status: ALLOWED,
+        });
+      }
+      for (const fk of table.foreignKeys) {
+        changes.push({
+          kind: "add-fk", table: table.name, ...schemaSpread(table.schema),
+          fk, status: ALLOWED,
+        });
+      }
+    }
+  }
+  // Pass 1b: tables present in actual but not expected → drop-table
+  // Attach _columns side-channel so detectTableRenames can compare column sets.
+  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,
+      };
+      dropChange._columns = t.columns;
+      changes.push(dropChange);
+    }
+  }
+
+  // Pass 2: tables in both → compare columns/indexes/FKs
+  for (const [id, expectedTable] of expectedTables) {
+    const actualTable = actualTables.get(id);
+    if (!actualTable) continue;
+    diffTableColumns(expectedTable, actualTable, changes);
+    diffTableIndexes(expectedTable, actualTable, changes);
+    diffTableForeignKeys(expectedTable, actualTable, changes);
+  }
+
+  // Pass 3: detect table renames BEFORE column renames — so a renamed table's
+  // columns are not scanned as orphaned drop/add pairs.
+  await detectTableRenames(changes, args.onAmbiguous);
+  await detectColumnRenames(changes, args.onAmbiguous);
+
+  // Strip the rename-detection side-channel fields before status assignment / return.
+  for (const c of changes) {
+    type Aug = Change & { _sqlType?: unknown; _nullable?: unknown; _columns?: unknown };
+    delete (c as Aug)._sqlType;
+    delete (c as Aug)._nullable;
+    delete (c as Aug)._columns;
+  }
+
+  applyStatus(changes, args.allow ?? {});
+  return { changes, blocked: changes.filter((c) => c.status.state === "blocked") };
+}
+
+function isDiffArgs(x: DiffArgs | SchemaSnapshot): x is DiffArgs {
+  return "expected" in x && "actual" in x;
+}
+
+function diffTableColumns(
+  expected: TableDescriptor,
+  actual: TableDescriptor,
+  changes: Change[],
+): void {
+  const table = expected.name;
+  const sx = schemaSpread(expected.schema);
+  const expectedCols = new Map(expected.columns.map((c) => [c.name, c]));
+  const actualCols = new Map(actual.columns.map((c) => [c.name, c]));
+
+  for (const [name, ec] of expectedCols) {
+    const ac = actualCols.get(name);
+    if (!ac) {
+      changes.push({ kind: "add-column", table, ...sx, column: ec, status: ALLOWED });
+      continue;
+    }
+    // Compare type, nullable, default — emit per-aspect change.
+    if (!sqlTypeEquals(ec.sqlType, ac.sqlType)) {
+      changes.push({
+        kind: "change-column-type", table, ...sx, column: name,
+        from: ac.sqlType, to: ec.sqlType, status: ALLOWED,
+      });
+    }
+    if (ec.nullable !== ac.nullable) {
+      changes.push({
+        kind: "change-column-nullable", table, ...sx, column: name,
+        from: ac.nullable, to: ec.nullable, status: ALLOWED,
+      });
+    }
+    if (!columnDefaultsEqual(ec.default, ac.default)) {
+      const change: Change = {
+        kind: "change-column-default", table, ...sx, column: name,
+        status: ALLOWED,
+        ...(ac.default !== undefined ? { from: ac.default } : {}),
+        ...(ec.default !== undefined ? { to: ec.default } : {}),
+      };
+      changes.push(change);
+    }
+  }
+  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,
+      };
+      dropChange._sqlType = ac.sqlType;
+      dropChange._nullable = ac.nullable;
+      changes.push(dropChange);
+    }
+  }
+}
+
+function diffTableIndexes(
+  expected: TableDescriptor,
+  actual: TableDescriptor,
+  changes: Change[],
+): void {
+  const table = expected.name;
+  const sx = schemaSpread(expected.schema);
+  const expectedIdx = new Map(expected.indexes.map((i) => [i.name, i]));
+  const actualIdx = new Map(actual.indexes.map((i) => [i.name, i]));
+  for (const [name, ix] of expectedIdx) {
+    const a = actualIdx.get(name);
+    if (!a) {
+      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 });
+      changes.push({ kind: "add-index", table, ...sx, index: ix, status: ALLOWED });
+    }
+  }
+  for (const [name] of actualIdx) {
+    if (!expectedIdx.has(name)) {
+      changes.push({ kind: "drop-index", table, ...sx, index: name, status: ALLOWED });
+    }
+  }
+}
+
+function diffTableForeignKeys(
+  expected: TableDescriptor,
+  actual: TableDescriptor,
+  changes: Change[],
+): void {
+  const table = expected.name;
+  const sx = schemaSpread(expected.schema);
+  const expectedFk = new Map(expected.foreignKeys.map((f) => [f.name, f]));
+  const actualFk = new Map(actual.foreignKeys.map((f) => [f.name, f]));
+  for (const [name, fk] of expectedFk) {
+    const a = actualFk.get(name);
+    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 });
+      changes.push({ kind: "add-fk", table, ...sx, fk, status: ALLOWED });
+    }
+  }
+  for (const [name] of actualFk) {
+    if (!expectedFk.has(name)) {
+      changes.push({ kind: "drop-fk", table, ...sx, fk: name, status: ALLOWED });
+    }
+  }
+}
+
+function columnDefaultsEqual(a: ColumnDescriptor["default"], b: ColumnDescriptor["default"]): boolean {
+  if (a === undefined && b === undefined) return true;
+  if (a === undefined || b === undefined) return false;
+  return a.kind === b.kind && a.value === b.value;
+}
+
+function indexEquals(a: IndexDescriptor, b: IndexDescriptor): boolean {
+  if (a.unique !== b.unique) return false;
+  if (a.columns.length !== b.columns.length) return false;
+  return a.columns.every((c, i) => c === b.columns[i]);
+}
+
+function fkEquals(a: FkDescriptor, b: FkDescriptor): boolean {
+  if (a.refTable !== b.refTable) return false;
+  if (a.onDelete !== b.onDelete || a.onUpdate !== b.onUpdate) return false;
+  if (a.columns.length !== b.columns.length || a.refColumns.length !== b.refColumns.length) return false;
+  return a.columns.every((c, i) => c === b.columns[i])
+      && a.refColumns.every((c, i) => c === b.refColumns[i]);
+}