@syncular/typegen 0.15.19 → 0.15.21

package/README.md

@@ -9,22 +9,30 @@ overrides it.
 
 ```sh
 syncular generate [--manifest-dir <dir>] [--check] [--watch]
+syncular migrations baseline|check [--manifest-dir <dir>]
 syncular init [--manifest-dir <dir>]
 ```
 
 `generate` reads `<dir>/syncular.json` plus its migrations directory and
-writes the IR JSON and the generated TS module. `--check` regenerates in
-memory and exits 1 unless both files on disk match **byte-exactly** (this is
-the freshness contract; it is unchanged). `--watch` regenerates on any change
-under the manifest dir (Bun's recursive `fs.watch`, debounced; it skips the
-write when outputs are already fresh so it never loops on its own output).
-`--check` and `--watch` are mutually exclusive.
-
-`init` scaffolds a starter `syncular.json` + `migrations/0001_initial/up.sql`
-into an existing project (the "add syncular to my app" path). It refuses to
-overwrite an existing manifest or first migration. New projects usually start
-from the scaffolder instead (`bun create syncular-app my-app`), which emits the
-same shape plus a server + client.
+writes the migration lock, IR JSON, and configured generated modules.
+`--check` regenerates in memory and exits 1 unless every output on disk matches
+**byte-exactly**. `--watch` regenerates on any change under the manifest dir
+(Bun's recursive `fs.watch`, debounced; it skips the write when outputs are
+already fresh so it never loops on its own output). `--check` and `--watch`
+are mutually exclusive.
+
+`migrations baseline` creates the first
+`syncular.migrations.lock.json` and refuses to replace one that already
+exists. `migrations check` is the fast, CI-friendly history check without
+query analysis or output generation. New migrations are appended to the lock
+by ordinary `generate`; locked migrations may never be edited, removed,
+renamed, or reordered.
+
+`init` scaffolds a starter `syncular.json`, first migration, and migration
+lock into an existing project (the "add syncular to my app" path). It refuses
+to overwrite any of them. New projects usually start from the scaffolder
+instead (`bun create syncular-app my-app`), which emits the same shape plus a
+server + client.
 
 When `generate` cannot find the manifest or migrations, the error points at the
 schema guide and suggests `syncular init`.
@@ -99,6 +107,31 @@ final entry's `through` must be the final migration — a migration not
 covered by any version is a hard error (so is a `through` naming a
 missing or out-of-order migration).
 
+### Immutable migration history
+
+`syncular.migrations.lock.json` is the version-controlled deployment baseline.
+Each entry records the migration name, a SHA-256 checksum of its SQL (line
+endings normalized), and a column-layout snapshot used only for diagnostics.
+It contains no SQL, filesystem path, row data, or runtime database state.
+
+For an existing project adopting this contract, review the current history
+once, then run:
+
+```sh
+syncular migrations baseline --manifest-dir .
+git add syncular.migrations.lock.json
+syncular migrations check --manifest-dir .
+```
+
+After that, a deployed migration is immutable. Restore an accidentally edited
+migration and express the repair in a new `NNNN_name/up.sql`; do not delete and
+re-baseline the lock. Existing table layouts are append-only and added columns
+must be nullable so stored payloads and every server backend can upgrade
+safely. `generate` appends a valid new migration to the lock, while
+`generate --check` fails until that updated lock and generated outputs are
+committed. Drift diagnostics name the locked migration and the first affected
+table/column without printing SQL or local paths.
+
 **Every-migrated-table rule.** Every table created by the migrations must
 appear in `tables`. A migrated-but-unlisted table is a hard error, not a
 silent skip; internal/unsynced tables will be a future manifest flag.
@@ -297,8 +330,8 @@ The emitted `*.generated.ts` module:
 
 **Lint/freshness split**: `*.generated.ts` is excluded from biome (see
 `biome.json`) — hand-format rules on machine output only create churn.
-Freshness and integrity are enforced instead by `syncular generate
---check`, which is byte-exact and therefore strictly stronger; the
+Freshness and migration-history integrity are enforced instead by `syncular
+generate --check`, which is byte-exact and refuses locked-history drift; the
 generated fixture is still typechecked by `tsc` and exercised by tests.
 
 ## 5. Native emitter contracts (Swift / Kotlin / Dart)

package/dist/cli.js

@@ -18,7 +18,7 @@
 import { existsSync, readFileSync, watch, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { formatSyql } from './fmt.js';
-import { checkOutputs, generate, loadQueries, writeOutputs } from './generate.js';
+import { baselineMigrationHistory, checkMigrationHistory, checkOutputs, generate, loadQueries, writeOutputs, } from './generate.js';
 import { InitError, initProject } from './init.js';
 import { runLspStdio } from './lsp.js';
 import { MANIFEST_FILENAME, parseManifest } from './manifest.js';
@@ -28,6 +28,7 @@ const USAGE = `usage: syncular <command> [options]
 
 commands:
   generate   build the IR + typed module from syncular.json + migrations/
+  migrations baseline or check immutable deployed migration history
   fmt        format .syql query files canonically (one style, no options)
   lsp        run the .syql language server over stdio (editor tooling)
   init       scaffold a starter syncular.json + migrations/0001_initial
@@ -45,6 +46,11 @@ fmt options:
   --manifest-dir <dir>   directory holding syncular.json (default: .)
   --check                fail unless every file is already canonical
 
+migrations options:
+  baseline               create the first immutable history lock; refuses overwrite
+  check                  validate the committed history without generating outputs
+  --manifest-dir <dir>   directory holding syncular.json (default: .)
+
 init options:
   --manifest-dir <dir>   directory to scaffold into (default: .)`;
 function fail(message) {
@@ -304,6 +310,39 @@ function runFmt(argv) {
     if (drifted === 0)
         console.log('all .syql files canonical');
 }
+function runMigrations(argv) {
+    const action = argv[0];
+    if (action !== 'baseline' && action !== 'check') {
+        fail(`migrations requires 'baseline' or 'check'\n${USAGE}`);
+    }
+    const manifestDir = parseManifestDir(argv.slice(1));
+    if (action === 'baseline') {
+        let output;
+        try {
+            output = baselineMigrationHistory(manifestDir);
+        }
+        catch (error) {
+            fail(friendlyGenerateError(error));
+        }
+        if (existsSync(output.path)) {
+            fail(`${output.path} already exists — refusing to replace immutable migration history`);
+        }
+        writeFileSync(output.path, output.content, 'utf8');
+        console.log(`wrote ${output.path}`);
+        console.log('commit this migration baseline before deployment');
+        return;
+    }
+    let drift;
+    try {
+        drift = checkMigrationHistory(manifestDir);
+    }
+    catch (error) {
+        fail(friendlyGenerateError(error));
+    }
+    if (drift.length > 0)
+        fail(drift.join('\n'));
+    console.log('migration history is locked and unchanged');
+}
 export function runCli(argv) {
     const command = argv[0];
     if (command === 'generate') {
@@ -323,6 +362,10 @@ export function runCli(argv) {
         runFmt(argv.slice(1));
         return;
     }
+    if (command === 'migrations') {
+        runMigrations(argv.slice(1));
+        return;
+    }
     if (command === 'lsp') {
         void runLspStdio();
         return;

package/dist/generate.d.ts

@@ -54,6 +54,9 @@ export interface GenerateResult {
     readonly queryHash: string;
     /** Generated TS module source (the exact bytes of the `.ts` output). */
     readonly module: string;
+    /** Immutable application-migration history baseline. */
+    readonly migrationLockJson: string;
+    readonly migrationLockPath: string;
     readonly irPath: string;
     readonly modulePath: string;
     /** Analyzed named queries (empty when no `queries/` files / no query output). */
@@ -62,6 +65,13 @@ export interface GenerateResult {
      * stable order — the single list `writeOutputs`/`checkOutputs` iterate. */
     readonly outputs: readonly GeneratedOutput[];
 }
+/**
+ * Build a first immutable migration baseline. The caller owns the one-time
+ * write so the CLI can refuse replacement before touching the filesystem.
+ */
+export declare function baselineMigrationHistory(manifestDir: string): GeneratedOutput;
+/** Fast CI check for migration history without emitting/query analysis. */
+export declare function checkMigrationHistory(manifestDir: string): string[];
 /** Read `syncular.json` + migrations under `manifestDir`; build outputs. */
 export declare function generate(manifestDir: string): GenerateResult;
 export declare function writeOutputs(result: GenerateResult): void;

package/dist/generate.js

@@ -17,6 +17,7 @@ import { emitSwiftModule } from './emit-swift.js';
 import { TypegenError } from './errors.js';
 import { canonicalizeExtensions, IR_VERSION, irHash, serializeIr, } from './ir.js';
 import { MANIFEST_FILENAME, parseManifest, } from './manifest.js';
+import { buildMigrationLock, MIGRATION_LOCK_FILENAME, readMigrationLock, serializeMigrationLock, validateMigrationLock, } from './migration-lock.js';
 import { buildNamingMap } from './naming.js';
 import { analyzeQueryFile, synthesizeDdl, } from './query.js';
 import { serializeQueryIr } from './query-ir.js';
@@ -322,8 +323,7 @@ export function analyzeQueries(ir, queries, naming, queriesRoot = resolve('/__sy
         close();
     }
 }
-/** Read `syncular.json` + migrations under `manifestDir`; build outputs. */
-export function generate(manifestDir) {
+function loadProjectInputs(manifestDir) {
     const manifestPath = resolve(manifestDir, MANIFEST_FILENAME);
     if (!existsSync(manifestPath)) {
         throw new TypegenError(manifestPath, 'manifest not found');
@@ -337,6 +337,43 @@ export function generate(manifestDir) {
     }
     const manifest = parseManifest(raw);
     const migrations = loadMigrations(resolve(manifestDir, manifest.migrations));
+    return { manifest, migrations };
+}
+/**
+ * Build a first immutable migration baseline. The caller owns the one-time
+ * write so the CLI can refuse replacement before touching the filesystem.
+ */
+export function baselineMigrationHistory(manifestDir) {
+    const { manifest, migrations } = loadProjectInputs(manifestDir);
+    // Baseline only a schema that is valid as a complete generated project.
+    buildIr(manifest, migrations);
+    return {
+        path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
+        content: serializeMigrationLock(buildMigrationLock(migrations)),
+    };
+}
+/** Fast CI check for migration history without emitting/query analysis. */
+export function checkMigrationHistory(manifestDir) {
+    const { manifest, migrations } = loadProjectInputs(manifestDir);
+    const current = buildMigrationLock(migrations);
+    validateMigrationLock(readMigrationLock(manifestDir), current);
+    buildIr(manifest, migrations);
+    const output = {
+        path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
+        content: serializeMigrationLock(current),
+    };
+    if (readFileSync(output.path, 'utf8') !== output.content) {
+        return [
+            `${MIGRATION_LOCK_FILENAME}: new migrations are not locked — run generate and commit the updated lock`,
+        ];
+    }
+    return [];
+}
+/** Read `syncular.json` + migrations under `manifestDir`; build outputs. */
+export function generate(manifestDir) {
+    const { manifest, migrations } = loadProjectInputs(manifestDir);
+    const migrationLock = buildMigrationLock(migrations);
+    validateMigrationLock(readMigrationLock(manifestDir), migrationLock);
     const ir = buildIr(manifest, migrations);
     // §5/§12 naming: the emitter targets this run generates (keyword hazards
     // are only real on targets that exist), and the per-table collision check
@@ -361,9 +398,12 @@ export function generate(manifestDir) {
     const irJson = serializeIr(ir);
     const hash = irHash(irJson);
     const module = emitModule(ir, hash, manifest.naming);
+    const migrationLockJson = serializeMigrationLock(migrationLock);
+    const migrationLockPath = resolve(manifestDir, MIGRATION_LOCK_FILENAME);
     const irPath = resolve(manifestDir, manifest.output.ir);
     const modulePath = resolve(manifestDir, manifest.output.module);
     const outputs = [
+        { path: migrationLockPath, content: migrationLockJson },
         { path: irPath, content: irJson },
         { path: modulePath, content: module },
     ];
@@ -447,6 +487,8 @@ export function generate(manifestDir) {
         queryIrJson,
         queryHash,
         module,
+        migrationLockJson,
+        migrationLockPath,
         irPath,
         modulePath,
         queries: analyzedQueries,

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from './ir.js';
 export * from './lower.js';
 export * from './lsp.js';
 export * from './manifest.js';
+export * from './migration-lock.js';
 export * from './naming.js';
 export * from './query.js';
 export * from './query-ir.js';

package/dist/index.js

@@ -19,6 +19,7 @@ export * from './ir.js';
 export * from './lower.js';
 export * from './lsp.js';
 export * from './manifest.js';
+export * from './migration-lock.js';
 export * from './naming.js';
 export * from './query.js';
 export * from './query-ir.js';

package/dist/init.js

@@ -9,6 +9,7 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { MANIFEST_FILENAME } from './manifest.js';
+import { buildMigrationLock, MIGRATION_LOCK_FILENAME, serializeMigrationLock, } from './migration-lock.js';
 const STARTER_MANIFEST = `{
   "manifestVersion": 1,
   "migrations": "./migrations",
@@ -64,6 +65,7 @@ export function initProject(dir) {
     const manifestPath = join(root, MANIFEST_FILENAME);
     const migrationDir = join(root, 'migrations', '0001_initial');
     const migrationPath = join(migrationDir, 'up.sql');
+    const migrationLockPath = join(root, MIGRATION_LOCK_FILENAME);
     const queriesDir = join(root, 'queries');
     const queryPath = join(queriesDir, 'notes-in-list.sql');
     if (existsSync(manifestPath)) {
@@ -73,6 +75,9 @@ export function initProject(dir) {
     if (existsSync(migrationPath)) {
         throw new InitError(`${migrationPath} already exists — refusing to overwrite.`);
     }
+    if (existsSync(migrationLockPath)) {
+        throw new InitError(`${migrationLockPath} already exists — refusing to overwrite immutable migration history.`);
+    }
     if (existsSync(queryPath)) {
         throw new InitError(`${queryPath} already exists — refusing to overwrite.`);
     }
@@ -80,6 +85,9 @@ export function initProject(dir) {
     mkdirSync(queriesDir, { recursive: true });
     writeFileSync(manifestPath, STARTER_MANIFEST, 'utf8');
     writeFileSync(migrationPath, STARTER_MIGRATION, 'utf8');
+    writeFileSync(migrationLockPath, serializeMigrationLock(buildMigrationLock([{ name: '0001_initial', sql: STARTER_MIGRATION }])), 'utf8');
     writeFileSync(queryPath, STARTER_QUERY, 'utf8');
-    return { written: [manifestPath, migrationPath, queryPath] };
+    return {
+        written: [manifestPath, migrationPath, migrationLockPath, queryPath],
+    };
 }

package/dist/migration-lock.d.ts

@@ -0,0 +1,37 @@
+import type { MigrationInput } from './generate.js';
+import type { IrColumnType } from './ir.js';
+export declare const MIGRATION_LOCK_FILENAME = "syncular.migrations.lock.json";
+export declare const MIGRATION_LOCK_FORMAT_VERSION = 1;
+export interface MigrationLockColumn {
+    readonly name: string;
+    readonly type: IrColumnType;
+    readonly nullable: boolean;
+    readonly crdtType?: string;
+}
+export interface MigrationLockTable {
+    readonly name: string;
+    readonly primaryKey: string;
+    readonly columns: readonly MigrationLockColumn[];
+}
+export interface MigrationLockEntry {
+    readonly name: string;
+    readonly sha256: string;
+    readonly tables: readonly MigrationLockTable[];
+}
+export interface MigrationLock {
+    readonly formatVersion: typeof MIGRATION_LOCK_FORMAT_VERSION;
+    readonly migrations: readonly MigrationLockEntry[];
+}
+/** Build the exact lock document for a complete migration sequence. */
+export declare function buildMigrationLock(migrations: readonly MigrationInput[]): MigrationLock;
+/** Fixed-order, byte-deterministic serialization for clean code review. */
+export declare function serializeMigrationLock(lock: MigrationLock): string;
+/** Parse and structurally validate a committed lock document. */
+export declare function parseMigrationLock(source: string): MigrationLock;
+/** Read the version-controlled baseline without exposing its absolute path. */
+export declare function readMigrationLock(manifestDir: string): MigrationLock;
+/**
+ * Validate the committed history as an exact prefix of the current sequence.
+ * New migrations may be appended; existing names and bytes may never change.
+ */
+export declare function validateMigrationLock(locked: MigrationLock, current: MigrationLock): void;

package/dist/migration-lock.js

@@ -0,0 +1,255 @@
+/**
+ * Immutable application-migration history.
+ *
+ * `syncular.migrations.lock.json` is a version-controlled baseline of every
+ * migration that has been accepted so far. Existing entries are immutable;
+ * generation may only append newly named migrations. The per-migration schema
+ * snapshot exists solely to make checksum drift actionable without retaining
+ * SQL text, row data, or filesystem paths in diagnostics.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { TypegenError } from './errors.js';
+import { applyMigrationSql } from './sql.js';
+export const MIGRATION_LOCK_FILENAME = 'syncular.migrations.lock.json';
+export const MIGRATION_LOCK_FORMAT_VERSION = 1;
+function normalizedSql(sql) {
+    return sql.replace(/\r\n?/g, '\n');
+}
+function checksum(sql) {
+    return createHash('sha256').update(normalizedSql(sql), 'utf8').digest('hex');
+}
+function snapshotColumn(column) {
+    return {
+        name: column.name,
+        type: column.type,
+        nullable: column.nullable,
+        ...(column.crdtType === undefined ? {} : { crdtType: column.crdtType }),
+    };
+}
+function snapshotTables(tables) {
+    return [...tables.values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((table) => ({
+        name: table.name,
+        primaryKey: table.primaryKey,
+        columns: table.columns.map(snapshotColumn),
+    }));
+}
+/** Build the exact lock document for a complete migration sequence. */
+export function buildMigrationLock(migrations) {
+    const tables = new Map();
+    const droppedTables = new Set();
+    const entries = [];
+    for (const migration of migrations) {
+        applyMigrationSql(tables, migration.sql, `${migration.name}/up.sql`, droppedTables);
+        entries.push({
+            name: migration.name,
+            sha256: checksum(migration.sql),
+            tables: snapshotTables(tables),
+        });
+    }
+    return { formatVersion: MIGRATION_LOCK_FORMAT_VERSION, migrations: entries };
+}
+/** Fixed-order, byte-deterministic serialization for clean code review. */
+export function serializeMigrationLock(lock) {
+    return `${JSON.stringify(lock, null, 2)}\n`;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function failLock(message) {
+    throw new TypegenError(MIGRATION_LOCK_FILENAME, message);
+}
+const COLUMN_TYPES = new Set([
+    'string',
+    'integer',
+    'float',
+    'boolean',
+    'json',
+    'bytes',
+    'blob_ref',
+    'crdt',
+]);
+function parseColumn(value, context) {
+    if (!isRecord(value))
+        failLock(`${context} must be an object`);
+    const { name, type, nullable, crdtType } = value;
+    if (typeof name !== 'string' || name.length === 0) {
+        failLock(`${context}.name must be a non-empty string`);
+    }
+    if (typeof type !== 'string' || !COLUMN_TYPES.has(type)) {
+        failLock(`${context}.type is not a supported Syncular column type`);
+    }
+    if (typeof nullable !== 'boolean') {
+        failLock(`${context}.nullable must be boolean`);
+    }
+    if (crdtType !== undefined && typeof crdtType !== 'string') {
+        failLock(`${context}.crdtType must be a string when present`);
+    }
+    return {
+        name,
+        type: type,
+        nullable,
+        ...(crdtType === undefined ? {} : { crdtType }),
+    };
+}
+function parseTable(value, context) {
+    if (!isRecord(value))
+        failLock(`${context} must be an object`);
+    const { name, primaryKey, columns } = value;
+    if (typeof name !== 'string' || name.length === 0) {
+        failLock(`${context}.name must be a non-empty string`);
+    }
+    if (typeof primaryKey !== 'string' || primaryKey.length === 0) {
+        failLock(`${context}.primaryKey must be a non-empty string`);
+    }
+    if (!Array.isArray(columns) || columns.length === 0) {
+        failLock(`${context}.columns must be a non-empty array`);
+    }
+    return {
+        name,
+        primaryKey,
+        columns: columns.map((column, index) => parseColumn(column, `${context}.columns[${index}]`)),
+    };
+}
+function parseEntry(value, index) {
+    const context = `migrations[${index}]`;
+    if (!isRecord(value))
+        failLock(`${context} must be an object`);
+    const { name, sha256, tables } = value;
+    if (typeof name !== 'string' || name.length === 0) {
+        failLock(`${context}.name must be a non-empty string`);
+    }
+    if (typeof sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(sha256)) {
+        failLock(`${context}.sha256 must be a lowercase SHA-256 digest`);
+    }
+    if (!Array.isArray(tables))
+        failLock(`${context}.tables must be an array`);
+    return {
+        name,
+        sha256,
+        tables: tables.map((table, tableIndex) => parseTable(table, `${context}.tables[${tableIndex}]`)),
+    };
+}
+/** Parse and structurally validate a committed lock document. */
+export function parseMigrationLock(source) {
+    let raw;
+    try {
+        raw = JSON.parse(source);
+    }
+    catch {
+        failLock('invalid JSON');
+    }
+    if (!isRecord(raw))
+        failLock('root must be an object');
+    if (raw.formatVersion !== MIGRATION_LOCK_FORMAT_VERSION) {
+        failLock(`formatVersion must be ${MIGRATION_LOCK_FORMAT_VERSION}, got ${JSON.stringify(raw.formatVersion)}`);
+    }
+    if (!Array.isArray(raw.migrations) || raw.migrations.length === 0) {
+        failLock('migrations must be a non-empty array');
+    }
+    const migrations = raw.migrations.map(parseEntry);
+    const names = new Set();
+    for (const migration of migrations) {
+        if (names.has(migration.name)) {
+            failLock(`migration ${JSON.stringify(migration.name)} appears twice`);
+        }
+        names.add(migration.name);
+    }
+    return { formatVersion: MIGRATION_LOCK_FORMAT_VERSION, migrations };
+}
+/** Read the version-controlled baseline without exposing its absolute path. */
+export function readMigrationLock(manifestDir) {
+    const path = resolve(manifestDir, MIGRATION_LOCK_FILENAME);
+    if (!existsSync(path)) {
+        failLock('missing — run `syncular migrations baseline --manifest-dir .` once before deployment, then commit the file');
+    }
+    return parseMigrationLock(readFileSync(path, 'utf8'));
+}
+function describeColumnDifference(tableName, locked, current) {
+    const length = Math.max(locked.length, current.length);
+    for (let index = 0; index < length; index++) {
+        const before = locked[index];
+        const after = current[index];
+        const position = index + 1;
+        if (before === undefined && after !== undefined) {
+            return `table ${JSON.stringify(tableName)}, column ${position} ${JSON.stringify(after.name)} was added (${after.type}, ${after.nullable ? 'nullable' : 'required'})`;
+        }
+        if (before !== undefined && after === undefined) {
+            return `table ${JSON.stringify(tableName)}, column ${position} ${JSON.stringify(before.name)} was removed`;
+        }
+        if (before === undefined || after === undefined)
+            continue;
+        if (before.name !== after.name) {
+            const oldStillPresent = current
+                .slice(index + 1)
+                .some((column) => column.name === before.name);
+            const newWasPresent = locked
+                .slice(index + 1)
+                .some((column) => column.name === after.name);
+            const action = oldStillPresent
+                ? `${JSON.stringify(after.name)} was inserted before locked ${JSON.stringify(before.name)}`
+                : newWasPresent
+                    ? `locked ${JSON.stringify(before.name)} was removed or reordered before ${JSON.stringify(after.name)}`
+                    : `locked ${JSON.stringify(before.name)} became ${JSON.stringify(after.name)}`;
+            return `table ${JSON.stringify(tableName)}, column ${position}: ${action}`;
+        }
+        if (before.type !== after.type) {
+            return `table ${JSON.stringify(tableName)}, column ${JSON.stringify(before.name)} changed type from ${before.type} to ${after.type}`;
+        }
+        if (before.nullable !== after.nullable) {
+            return `table ${JSON.stringify(tableName)}, column ${JSON.stringify(before.name)} changed nullability from ${before.nullable ? 'nullable' : 'required'} to ${after.nullable ? 'nullable' : 'required'}`;
+        }
+        if (before.crdtType !== after.crdtType) {
+            return `table ${JSON.stringify(tableName)}, column ${JSON.stringify(before.name)} changed CRDT type`;
+        }
+    }
+    return undefined;
+}
+function firstSchemaDifference(locked, current) {
+    const length = Math.max(locked.tables.length, current.tables.length);
+    for (let index = 0; index < length; index++) {
+        const before = locked.tables[index];
+        const after = current.tables[index];
+        if (before === undefined && after !== undefined) {
+            return `table ${JSON.stringify(after.name)} was added`;
+        }
+        if (before !== undefined && after === undefined) {
+            return `table ${JSON.stringify(before.name)} was removed`;
+        }
+        if (before === undefined || after === undefined)
+            continue;
+        if (before.name !== after.name) {
+            return `locked table ${JSON.stringify(before.name)} became or moved behind ${JSON.stringify(after.name)}`;
+        }
+        if (before.primaryKey !== after.primaryKey) {
+            return `table ${JSON.stringify(before.name)} changed primary key from ${JSON.stringify(before.primaryKey)} to ${JSON.stringify(after.primaryKey)}`;
+        }
+        const column = describeColumnDifference(before.name, before.columns, after.columns);
+        if (column !== undefined)
+            return column;
+    }
+    return 'schema shape is unchanged; SQL text, defaults, comments, indexes, or another non-column statement changed';
+}
+const REPAIR_HINT = 'deployed migrations are immutable; restore the locked migration and append a new migration (added columns must be nullable)';
+/**
+ * Validate the committed history as an exact prefix of the current sequence.
+ * New migrations may be appended; existing names and bytes may never change.
+ */
+export function validateMigrationLock(locked, current) {
+    for (let index = 0; index < locked.migrations.length; index++) {
+        const before = locked.migrations[index];
+        const after = current.migrations[index];
+        if (after === undefined) {
+            failLock(`history drift at migration ${JSON.stringify(before.name)}: the locked migration is missing; ${REPAIR_HINT}`);
+        }
+        if (before.name !== after.name) {
+            failLock(`history drift at position ${index + 1}: locked ${JSON.stringify(before.name)} but found ${JSON.stringify(after.name)}; migrations cannot be removed, renamed, or reordered; ${REPAIR_HINT}`);
+        }
+        if (before.sha256 !== after.sha256) {
+            failLock(`history drift in migration ${JSON.stringify(before.name)}: checksum changed; first schema difference: ${firstSchemaDifference(before, after)}; ${REPAIR_HINT}`);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.15.19",
+  "version": "0.15.21",
   "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,7 +48,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "devDependencies": {
-    "@syncular/core": "0.15.19",
-    "@syncular/server": "0.15.19"
+    "@syncular/core": "0.15.21",
+    "@syncular/server": "0.15.21"
   }
 }

package/src/cli.ts

@@ -18,7 +18,14 @@
 import { existsSync, readFileSync, watch, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { formatSyql } from './fmt';
-import { checkOutputs, generate, loadQueries, writeOutputs } from './generate';
+import {
+  baselineMigrationHistory,
+  checkMigrationHistory,
+  checkOutputs,
+  generate,
+  loadQueries,
+  writeOutputs,
+} from './generate';
 import { InitError, initProject } from './init';
 import { runLspStdio } from './lsp';
 import { MANIFEST_FILENAME, parseManifest } from './manifest';
@@ -31,6 +38,7 @@ const USAGE = `usage: syncular <command> [options]
 
 commands:
   generate   build the IR + typed module from syncular.json + migrations/
+  migrations baseline or check immutable deployed migration history
   fmt        format .syql query files canonically (one style, no options)
   lsp        run the .syql language server over stdio (editor tooling)
   init       scaffold a starter syncular.json + migrations/0001_initial
@@ -48,6 +56,11 @@ fmt options:
   --manifest-dir <dir>   directory holding syncular.json (default: .)
   --check                fail unless every file is already canonical
 
+migrations options:
+  baseline               create the first immutable history lock; refuses overwrite
+  check                  validate the committed history without generating outputs
+  --manifest-dir <dir>   directory holding syncular.json (default: .)
+
 init options:
   --manifest-dir <dir>   directory to scaffold into (default: .)`;
 
@@ -317,6 +330,40 @@ function runFmt(argv: readonly string[]): void {
   if (drifted === 0) console.log('all .syql files canonical');
 }
 
+function runMigrations(argv: readonly string[]): void {
+  const action = argv[0];
+  if (action !== 'baseline' && action !== 'check') {
+    fail(`migrations requires 'baseline' or 'check'\n${USAGE}`);
+  }
+  const manifestDir = parseManifestDir(argv.slice(1));
+  if (action === 'baseline') {
+    let output: ReturnType<typeof baselineMigrationHistory>;
+    try {
+      output = baselineMigrationHistory(manifestDir);
+    } catch (error) {
+      fail(friendlyGenerateError(error));
+    }
+    if (existsSync(output.path)) {
+      fail(
+        `${output.path} already exists — refusing to replace immutable migration history`,
+      );
+    }
+    writeFileSync(output.path, output.content, 'utf8');
+    console.log(`wrote ${output.path}`);
+    console.log('commit this migration baseline before deployment');
+    return;
+  }
+
+  let drift: string[];
+  try {
+    drift = checkMigrationHistory(manifestDir);
+  } catch (error) {
+    fail(friendlyGenerateError(error));
+  }
+  if (drift.length > 0) fail(drift.join('\n'));
+  console.log('migration history is locked and unchanged');
+}
+
 export function runCli(argv: readonly string[]): void {
   const command = argv[0];
   if (command === 'generate') {
@@ -336,6 +383,10 @@ export function runCli(argv: readonly string[]): void {
     runFmt(argv.slice(1));
     return;
   }
+  if (command === 'migrations') {
+    runMigrations(argv.slice(1));
+    return;
+  }
   if (command === 'lsp') {
     void runLspStdio();
     return;

package/src/generate.ts

@@ -41,6 +41,13 @@ import {
   type ManifestScopeSpec,
   parseManifest,
 } from './manifest';
+import {
+  buildMigrationLock,
+  MIGRATION_LOCK_FILENAME,
+  readMigrationLock,
+  serializeMigrationLock,
+  validateMigrationLock,
+} from './migration-lock';
 import { buildNamingMap, type NamingTarget } from './naming';
 import {
   type AnalyzedQuery,
@@ -521,6 +528,9 @@ export interface GenerateResult {
   readonly queryHash: string;
   /** Generated TS module source (the exact bytes of the `.ts` output). */
   readonly module: string;
+  /** Immutable application-migration history baseline. */
+  readonly migrationLockJson: string;
+  readonly migrationLockPath: string;
   readonly irPath: string;
   readonly modulePath: string;
   /** Analyzed named queries (empty when no `queries/` files / no query output). */
@@ -530,8 +540,12 @@ export interface GenerateResult {
   readonly outputs: readonly GeneratedOutput[];
 }
 
-/** Read `syncular.json` + migrations under `manifestDir`; build outputs. */
-export function generate(manifestDir: string): GenerateResult {
+interface ProjectInputs {
+  readonly manifest: Manifest;
+  readonly migrations: readonly MigrationInput[];
+}
+
+function loadProjectInputs(manifestDir: string): ProjectInputs {
   const manifestPath = resolve(manifestDir, MANIFEST_FILENAME);
   if (!existsSync(manifestPath)) {
     throw new TypegenError(manifestPath, 'manifest not found');
@@ -547,6 +561,46 @@ export function generate(manifestDir: string): GenerateResult {
   }
   const manifest = parseManifest(raw);
   const migrations = loadMigrations(resolve(manifestDir, manifest.migrations));
+  return { manifest, migrations };
+}
+
+/**
+ * Build a first immutable migration baseline. The caller owns the one-time
+ * write so the CLI can refuse replacement before touching the filesystem.
+ */
+export function baselineMigrationHistory(manifestDir: string): GeneratedOutput {
+  const { manifest, migrations } = loadProjectInputs(manifestDir);
+  // Baseline only a schema that is valid as a complete generated project.
+  buildIr(manifest, migrations);
+  return {
+    path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
+    content: serializeMigrationLock(buildMigrationLock(migrations)),
+  };
+}
+
+/** Fast CI check for migration history without emitting/query analysis. */
+export function checkMigrationHistory(manifestDir: string): string[] {
+  const { manifest, migrations } = loadProjectInputs(manifestDir);
+  const current = buildMigrationLock(migrations);
+  validateMigrationLock(readMigrationLock(manifestDir), current);
+  buildIr(manifest, migrations);
+  const output = {
+    path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
+    content: serializeMigrationLock(current),
+  };
+  if (readFileSync(output.path, 'utf8') !== output.content) {
+    return [
+      `${MIGRATION_LOCK_FILENAME}: new migrations are not locked — run generate and commit the updated lock`,
+    ];
+  }
+  return [];
+}
+
+/** Read `syncular.json` + migrations under `manifestDir`; build outputs. */
+export function generate(manifestDir: string): GenerateResult {
+  const { manifest, migrations } = loadProjectInputs(manifestDir);
+  const migrationLock = buildMigrationLock(migrations);
+  validateMigrationLock(readMigrationLock(manifestDir), migrationLock);
   const ir = buildIr(manifest, migrations);
 
   // §5/§12 naming: the emitter targets this run generates (keyword hazards
@@ -575,9 +629,12 @@ export function generate(manifestDir: string): GenerateResult {
   const irJson = serializeIr(ir);
   const hash = irHash(irJson);
   const module = emitModule(ir, hash, manifest.naming);
+  const migrationLockJson = serializeMigrationLock(migrationLock);
+  const migrationLockPath = resolve(manifestDir, MIGRATION_LOCK_FILENAME);
   const irPath = resolve(manifestDir, manifest.output.ir);
   const modulePath = resolve(manifestDir, manifest.output.module);
   const outputs: GeneratedOutput[] = [
+    { path: migrationLockPath, content: migrationLockJson },
     { path: irPath, content: irJson },
     { path: modulePath, content: module },
   ];
@@ -700,6 +757,8 @@ export function generate(manifestDir: string): GenerateResult {
     queryIrJson,
     queryHash,
     module,
+    migrationLockJson,
+    migrationLockPath,
     irPath,
     modulePath,
     queries: analyzedQueries,

package/src/index.ts

@@ -19,6 +19,7 @@ export * from './ir';
 export * from './lower';
 export * from './lsp';
 export * from './manifest';
+export * from './migration-lock';
 export * from './naming';
 export * from './query';
 export * from './query-ir';

package/src/init.ts

@@ -9,6 +9,11 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { MANIFEST_FILENAME } from './manifest';
+import {
+  buildMigrationLock,
+  MIGRATION_LOCK_FILENAME,
+  serializeMigrationLock,
+} from './migration-lock';
 
 const STARTER_MANIFEST = `{
   "manifestVersion": 1,
@@ -73,6 +78,7 @@ export function initProject(dir: string): InitResult {
   const manifestPath = join(root, MANIFEST_FILENAME);
   const migrationDir = join(root, 'migrations', '0001_initial');
   const migrationPath = join(migrationDir, 'up.sql');
+  const migrationLockPath = join(root, MIGRATION_LOCK_FILENAME);
   const queriesDir = join(root, 'queries');
   const queryPath = join(queriesDir, 'notes-in-list.sql');
 
@@ -87,6 +93,11 @@ export function initProject(dir: string): InitResult {
       `${migrationPath} already exists — refusing to overwrite.`,
     );
   }
+  if (existsSync(migrationLockPath)) {
+    throw new InitError(
+      `${migrationLockPath} already exists — refusing to overwrite immutable migration history.`,
+    );
+  }
   if (existsSync(queryPath)) {
     throw new InitError(`${queryPath} already exists — refusing to overwrite.`);
   }
@@ -95,6 +106,15 @@ export function initProject(dir: string): InitResult {
   mkdirSync(queriesDir, { recursive: true });
   writeFileSync(manifestPath, STARTER_MANIFEST, 'utf8');
   writeFileSync(migrationPath, STARTER_MIGRATION, 'utf8');
+  writeFileSync(
+    migrationLockPath,
+    serializeMigrationLock(
+      buildMigrationLock([{ name: '0001_initial', sql: STARTER_MIGRATION }]),
+    ),
+    'utf8',
+  );
   writeFileSync(queryPath, STARTER_QUERY, 'utf8');
-  return { written: [manifestPath, migrationPath, queryPath] };
+  return {
+    written: [manifestPath, migrationPath, migrationLockPath, queryPath],
+  };
 }

package/src/migration-lock.ts

@@ -0,0 +1,329 @@
+/**
+ * Immutable application-migration history.
+ *
+ * `syncular.migrations.lock.json` is a version-controlled baseline of every
+ * migration that has been accepted so far. Existing entries are immutable;
+ * generation may only append newly named migrations. The per-migration schema
+ * snapshot exists solely to make checksum drift actionable without retaining
+ * SQL text, row data, or filesystem paths in diagnostics.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { TypegenError } from './errors';
+import type { MigrationInput } from './generate';
+import type { IrColumn, IrColumnType } from './ir';
+import { applyMigrationSql, type ParsedTable } from './sql';
+
+export const MIGRATION_LOCK_FILENAME = 'syncular.migrations.lock.json';
+export const MIGRATION_LOCK_FORMAT_VERSION = 1;
+
+export interface MigrationLockColumn {
+  readonly name: string;
+  readonly type: IrColumnType;
+  readonly nullable: boolean;
+  readonly crdtType?: string;
+}
+
+export interface MigrationLockTable {
+  readonly name: string;
+  readonly primaryKey: string;
+  readonly columns: readonly MigrationLockColumn[];
+}
+
+export interface MigrationLockEntry {
+  readonly name: string;
+  readonly sha256: string;
+  readonly tables: readonly MigrationLockTable[];
+}
+
+export interface MigrationLock {
+  readonly formatVersion: typeof MIGRATION_LOCK_FORMAT_VERSION;
+  readonly migrations: readonly MigrationLockEntry[];
+}
+
+function normalizedSql(sql: string): string {
+  return sql.replace(/\r\n?/g, '\n');
+}
+
+function checksum(sql: string): string {
+  return createHash('sha256').update(normalizedSql(sql), 'utf8').digest('hex');
+}
+
+function snapshotColumn(column: IrColumn): MigrationLockColumn {
+  return {
+    name: column.name,
+    type: column.type,
+    nullable: column.nullable,
+    ...(column.crdtType === undefined ? {} : { crdtType: column.crdtType }),
+  };
+}
+
+function snapshotTables(
+  tables: ReadonlyMap<string, ParsedTable>,
+): MigrationLockTable[] {
+  return [...tables.values()]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((table) => ({
+      name: table.name,
+      primaryKey: table.primaryKey,
+      columns: table.columns.map(snapshotColumn),
+    }));
+}
+
+/** Build the exact lock document for a complete migration sequence. */
+export function buildMigrationLock(
+  migrations: readonly MigrationInput[],
+): MigrationLock {
+  const tables = new Map<string, ParsedTable>();
+  const droppedTables = new Set<string>();
+  const entries: MigrationLockEntry[] = [];
+  for (const migration of migrations) {
+    applyMigrationSql(
+      tables,
+      migration.sql,
+      `${migration.name}/up.sql`,
+      droppedTables,
+    );
+    entries.push({
+      name: migration.name,
+      sha256: checksum(migration.sql),
+      tables: snapshotTables(tables),
+    });
+  }
+  return { formatVersion: MIGRATION_LOCK_FORMAT_VERSION, migrations: entries };
+}
+
+/** Fixed-order, byte-deterministic serialization for clean code review. */
+export function serializeMigrationLock(lock: MigrationLock): string {
+  return `${JSON.stringify(lock, null, 2)}\n`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function failLock(message: string): never {
+  throw new TypegenError(MIGRATION_LOCK_FILENAME, message);
+}
+
+const COLUMN_TYPES = new Set<IrColumnType>([
+  'string',
+  'integer',
+  'float',
+  'boolean',
+  'json',
+  'bytes',
+  'blob_ref',
+  'crdt',
+]);
+
+function parseColumn(value: unknown, context: string): MigrationLockColumn {
+  if (!isRecord(value)) failLock(`${context} must be an object`);
+  const { name, type, nullable, crdtType } = value;
+  if (typeof name !== 'string' || name.length === 0) {
+    failLock(`${context}.name must be a non-empty string`);
+  }
+  if (typeof type !== 'string' || !COLUMN_TYPES.has(type as IrColumnType)) {
+    failLock(`${context}.type is not a supported Syncular column type`);
+  }
+  if (typeof nullable !== 'boolean') {
+    failLock(`${context}.nullable must be boolean`);
+  }
+  if (crdtType !== undefined && typeof crdtType !== 'string') {
+    failLock(`${context}.crdtType must be a string when present`);
+  }
+  return {
+    name,
+    type: type as IrColumnType,
+    nullable,
+    ...(crdtType === undefined ? {} : { crdtType }),
+  };
+}
+
+function parseTable(value: unknown, context: string): MigrationLockTable {
+  if (!isRecord(value)) failLock(`${context} must be an object`);
+  const { name, primaryKey, columns } = value;
+  if (typeof name !== 'string' || name.length === 0) {
+    failLock(`${context}.name must be a non-empty string`);
+  }
+  if (typeof primaryKey !== 'string' || primaryKey.length === 0) {
+    failLock(`${context}.primaryKey must be a non-empty string`);
+  }
+  if (!Array.isArray(columns) || columns.length === 0) {
+    failLock(`${context}.columns must be a non-empty array`);
+  }
+  return {
+    name,
+    primaryKey,
+    columns: columns.map((column, index) =>
+      parseColumn(column, `${context}.columns[${index}]`),
+    ),
+  };
+}
+
+function parseEntry(value: unknown, index: number): MigrationLockEntry {
+  const context = `migrations[${index}]`;
+  if (!isRecord(value)) failLock(`${context} must be an object`);
+  const { name, sha256, tables } = value;
+  if (typeof name !== 'string' || name.length === 0) {
+    failLock(`${context}.name must be a non-empty string`);
+  }
+  if (typeof sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(sha256)) {
+    failLock(`${context}.sha256 must be a lowercase SHA-256 digest`);
+  }
+  if (!Array.isArray(tables)) failLock(`${context}.tables must be an array`);
+  return {
+    name,
+    sha256,
+    tables: tables.map((table, tableIndex) =>
+      parseTable(table, `${context}.tables[${tableIndex}]`),
+    ),
+  };
+}
+
+/** Parse and structurally validate a committed lock document. */
+export function parseMigrationLock(source: string): MigrationLock {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(source);
+  } catch {
+    failLock('invalid JSON');
+  }
+  if (!isRecord(raw)) failLock('root must be an object');
+  if (raw.formatVersion !== MIGRATION_LOCK_FORMAT_VERSION) {
+    failLock(
+      `formatVersion must be ${MIGRATION_LOCK_FORMAT_VERSION}, got ${JSON.stringify(raw.formatVersion)}`,
+    );
+  }
+  if (!Array.isArray(raw.migrations) || raw.migrations.length === 0) {
+    failLock('migrations must be a non-empty array');
+  }
+  const migrations = raw.migrations.map(parseEntry);
+  const names = new Set<string>();
+  for (const migration of migrations) {
+    if (names.has(migration.name)) {
+      failLock(`migration ${JSON.stringify(migration.name)} appears twice`);
+    }
+    names.add(migration.name);
+  }
+  return { formatVersion: MIGRATION_LOCK_FORMAT_VERSION, migrations };
+}
+
+/** Read the version-controlled baseline without exposing its absolute path. */
+export function readMigrationLock(manifestDir: string): MigrationLock {
+  const path = resolve(manifestDir, MIGRATION_LOCK_FILENAME);
+  if (!existsSync(path)) {
+    failLock(
+      'missing — run `syncular migrations baseline --manifest-dir .` once before deployment, then commit the file',
+    );
+  }
+  return parseMigrationLock(readFileSync(path, 'utf8'));
+}
+
+function describeColumnDifference(
+  tableName: string,
+  locked: readonly MigrationLockColumn[],
+  current: readonly MigrationLockColumn[],
+): string | undefined {
+  const length = Math.max(locked.length, current.length);
+  for (let index = 0; index < length; index++) {
+    const before = locked[index];
+    const after = current[index];
+    const position = index + 1;
+    if (before === undefined && after !== undefined) {
+      return `table ${JSON.stringify(tableName)}, column ${position} ${JSON.stringify(after.name)} was added (${after.type}, ${after.nullable ? 'nullable' : 'required'})`;
+    }
+    if (before !== undefined && after === undefined) {
+      return `table ${JSON.stringify(tableName)}, column ${position} ${JSON.stringify(before.name)} was removed`;
+    }
+    if (before === undefined || after === undefined) continue;
+    if (before.name !== after.name) {
+      const oldStillPresent = current
+        .slice(index + 1)
+        .some((column) => column.name === before.name);
+      const newWasPresent = locked
+        .slice(index + 1)
+        .some((column) => column.name === after.name);
+      const action = oldStillPresent
+        ? `${JSON.stringify(after.name)} was inserted before locked ${JSON.stringify(before.name)}`
+        : newWasPresent
+          ? `locked ${JSON.stringify(before.name)} was removed or reordered before ${JSON.stringify(after.name)}`
+          : `locked ${JSON.stringify(before.name)} became ${JSON.stringify(after.name)}`;
+      return `table ${JSON.stringify(tableName)}, column ${position}: ${action}`;
+    }
+    if (before.type !== after.type) {
+      return `table ${JSON.stringify(tableName)}, column ${JSON.stringify(before.name)} changed type from ${before.type} to ${after.type}`;
+    }
+    if (before.nullable !== after.nullable) {
+      return `table ${JSON.stringify(tableName)}, column ${JSON.stringify(before.name)} changed nullability from ${before.nullable ? 'nullable' : 'required'} to ${after.nullable ? 'nullable' : 'required'}`;
+    }
+    if (before.crdtType !== after.crdtType) {
+      return `table ${JSON.stringify(tableName)}, column ${JSON.stringify(before.name)} changed CRDT type`;
+    }
+  }
+  return undefined;
+}
+
+function firstSchemaDifference(
+  locked: MigrationLockEntry,
+  current: MigrationLockEntry,
+): string {
+  const length = Math.max(locked.tables.length, current.tables.length);
+  for (let index = 0; index < length; index++) {
+    const before = locked.tables[index];
+    const after = current.tables[index];
+    if (before === undefined && after !== undefined) {
+      return `table ${JSON.stringify(after.name)} was added`;
+    }
+    if (before !== undefined && after === undefined) {
+      return `table ${JSON.stringify(before.name)} was removed`;
+    }
+    if (before === undefined || after === undefined) continue;
+    if (before.name !== after.name) {
+      return `locked table ${JSON.stringify(before.name)} became or moved behind ${JSON.stringify(after.name)}`;
+    }
+    if (before.primaryKey !== after.primaryKey) {
+      return `table ${JSON.stringify(before.name)} changed primary key from ${JSON.stringify(before.primaryKey)} to ${JSON.stringify(after.primaryKey)}`;
+    }
+    const column = describeColumnDifference(
+      before.name,
+      before.columns,
+      after.columns,
+    );
+    if (column !== undefined) return column;
+  }
+  return 'schema shape is unchanged; SQL text, defaults, comments, indexes, or another non-column statement changed';
+}
+
+const REPAIR_HINT =
+  'deployed migrations are immutable; restore the locked migration and append a new migration (added columns must be nullable)';
+
+/**
+ * Validate the committed history as an exact prefix of the current sequence.
+ * New migrations may be appended; existing names and bytes may never change.
+ */
+export function validateMigrationLock(
+  locked: MigrationLock,
+  current: MigrationLock,
+): void {
+  for (let index = 0; index < locked.migrations.length; index++) {
+    const before = locked.migrations[index] as MigrationLockEntry;
+    const after = current.migrations[index];
+    if (after === undefined) {
+      failLock(
+        `history drift at migration ${JSON.stringify(before.name)}: the locked migration is missing; ${REPAIR_HINT}`,
+      );
+    }
+    if (before.name !== after.name) {
+      failLock(
+        `history drift at position ${index + 1}: locked ${JSON.stringify(before.name)} but found ${JSON.stringify(after.name)}; migrations cannot be removed, renamed, or reordered; ${REPAIR_HINT}`,
+      );
+    }
+    if (before.sha256 !== after.sha256) {
+      failLock(
+        `history drift in migration ${JSON.stringify(before.name)}: checksum changed; first schema difference: ${firstSchemaDifference(before, after)}; ${REPAIR_HINT}`,
+      );
+    }
+  }
+}