@syncular/typegen 0.15.24 → 0.15.25

package/README.md

@@ -9,7 +9,7 @@ overrides it.
 
 ```sh
 syncular generate [--manifest-dir <dir>] [--check] [--watch]
-syncular migrations baseline|check [--manifest-dir <dir>]
+syncular migrations baseline|check|upgrade-lock [--manifest-dir <dir>]
 syncular init [--manifest-dir <dir>]
 ```
 
@@ -26,7 +26,8 @@ are mutually exclusive.
 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.
+renamed, or reordered. Existing format-1 locks remain valid and keep their
+format until `migrations upgrade-lock` explicitly validates and compacts them.
 
 `init` scaffolds a starter `syncular.json`, first migration, and migration
 lock into an existing project (the "add syncular to my app" path). It refuses
@@ -110,9 +111,11 @@ 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.
+Format 2 records every migration name and SHA-256 checksum (line endings
+normalized), plus one canonical head-schema column snapshot used only for
+diagnostics. It contains no SQL, filesystem path, row data, or runtime database
+state, and grows with migration metadata plus the current schema rather than
+repeating the full cumulative schema after every migration.
 
 For an existing project adopting this contract, review the current history
 once, then run:
@@ -123,6 +126,18 @@ git add syncular.migrations.lock.json
 syncular migrations check --manifest-dir .
 ```
 
+Projects with a committed format-1 lock upgrade deliberately, after first
+checking that immutable history is unchanged:
+
+```sh
+syncular migrations check --manifest-dir .
+syncular migrations upgrade-lock --manifest-dir .
+git add syncular.migrations.lock.json
+```
+
+The upgrade command refuses an already-current lock and ordinary `generate`
+never changes the lock format implicitly.
+
 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

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 { baselineMigrationHistory, checkMigrationHistory, checkOutputs, generate, loadQueries, writeOutputs, } from './generate.js';
+import { baselineMigrationHistory, checkMigrationHistory, checkOutputs, generate, loadQueries, upgradeMigrationHistory, writeOutputs, } from './generate.js';
 import { InitError, initProject } from './init.js';
 import { runLspStdio } from './lsp.js';
 import { MANIFEST_FILENAME, parseManifest } from './manifest.js';
@@ -28,7 +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
+  migrations baseline, check, or upgrade-lock immutable 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
@@ -49,6 +49,7 @@ fmt options:
 migrations options:
   baseline               create the first immutable history lock; refuses overwrite
   check                  validate the committed history without generating outputs
+  upgrade-lock           explicitly compact a validated format-1 lock to format 2
   --manifest-dir <dir>   directory holding syncular.json (default: .)
 
 init options:
@@ -312,8 +313,10 @@ function runFmt(argv) {
 }
 function runMigrations(argv) {
     const action = argv[0];
-    if (action !== 'baseline' && action !== 'check') {
-        fail(`migrations requires 'baseline' or 'check'\n${USAGE}`);
+    if (action !== 'baseline' &&
+        action !== 'check' &&
+        action !== 'upgrade-lock') {
+        fail(`migrations requires 'baseline', 'check', or 'upgrade-lock'\n${USAGE}`);
     }
     const manifestDir = parseManifestDir(argv.slice(1));
     if (action === 'baseline') {
@@ -332,6 +335,19 @@ function runMigrations(argv) {
         console.log('commit this migration baseline before deployment');
         return;
     }
+    if (action === 'upgrade-lock') {
+        let output;
+        try {
+            output = upgradeMigrationHistory(manifestDir);
+        }
+        catch (error) {
+            fail(friendlyGenerateError(error));
+        }
+        writeFileSync(output.path, output.content, 'utf8');
+        console.log(`upgraded ${output.path} to compact format 2`);
+        console.log('review and commit the migration-lock format upgrade');
+        return;
+    }
     let drift;
     try {
         drift = checkMigrationHistory(manifestDir);

package/dist/generate.d.ts

@@ -70,6 +70,12 @@ export interface GenerateResult {
  * write so the CLI can refuse replacement before touching the filesystem.
  */
 export declare function baselineMigrationHistory(manifestDir: string): GeneratedOutput;
+/**
+ * Validate and explicitly compact a version-1 migration lock to version 2.
+ * The caller owns the in-place write so the CLI can make the format transition
+ * visible and reviewable.
+ */
+export declare function upgradeMigrationHistory(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. */

package/dist/generate.js

@@ -17,7 +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 { buildMigrationLock, LEGACY_MIGRATION_LOCK_FORMAT_VERSION, MIGRATION_LOCK_FILENAME, readMigrationLock, serializeMigrationLock, updateMigrationLock, } from './migration-lock.js';
 import { buildNamingMap } from './naming.js';
 import { analyzeQueryFile, synthesizeDdl, } from './query.js';
 import { serializeQueryIr } from './query-ir.js';
@@ -352,11 +352,29 @@ export function baselineMigrationHistory(manifestDir) {
         content: serializeMigrationLock(buildMigrationLock(migrations)),
     };
 }
+/**
+ * Validate and explicitly compact a version-1 migration lock to version 2.
+ * The caller owns the in-place write so the CLI can make the format transition
+ * visible and reviewable.
+ */
+export function upgradeMigrationHistory(manifestDir) {
+    const { manifest, migrations } = loadProjectInputs(manifestDir);
+    const locked = readMigrationLock(manifestDir);
+    if (locked.formatVersion !== LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
+        throw new TypegenError(MIGRATION_LOCK_FILENAME, 'already uses the current compact migration-lock format');
+    }
+    // Validate the immutable prefix before replacing its representation.
+    updateMigrationLock(locked, migrations);
+    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);
+    const current = updateMigrationLock(readMigrationLock(manifestDir), migrations);
     buildIr(manifest, migrations);
     const output = {
         path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
@@ -372,8 +390,7 @@ export function checkMigrationHistory(manifestDir) {
 /** 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 migrationLock = updateMigrationLock(readMigrationLock(manifestDir), migrations);
     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

package/dist/migration-lock.d.ts

@@ -1,7 +1,8 @@
 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 declare const MIGRATION_LOCK_FORMAT_VERSION = 2;
+export declare const LEGACY_MIGRATION_LOCK_FORMAT_VERSION = 1;
 export interface MigrationLockColumn {
     readonly name: string;
     readonly type: IrColumnType;
@@ -16,14 +17,24 @@ export interface MigrationLockTable {
 export interface MigrationLockEntry {
     readonly name: string;
     readonly sha256: string;
+}
+export interface LegacyMigrationLockEntry extends MigrationLockEntry {
     readonly tables: readonly MigrationLockTable[];
 }
-export interface MigrationLock {
+export interface LegacyMigrationLock {
+    readonly formatVersion: typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION;
+    readonly migrations: readonly LegacyMigrationLockEntry[];
+}
+export interface MigrationLockV2 {
     readonly formatVersion: typeof MIGRATION_LOCK_FORMAT_VERSION;
     readonly migrations: readonly MigrationLockEntry[];
+    readonly head: {
+        readonly tables: readonly MigrationLockTable[];
+    };
 }
-/** Build the exact lock document for a complete migration sequence. */
-export declare function buildMigrationLock(migrations: readonly MigrationInput[]): MigrationLock;
+export type MigrationLock = LegacyMigrationLock | MigrationLockV2;
+/** Build a deterministic lock document for a complete migration sequence. */
+export declare function buildMigrationLock(migrations: readonly MigrationInput[], formatVersion?: typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION | typeof MIGRATION_LOCK_FORMAT_VERSION): 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. */
@@ -31,7 +42,10 @@ 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.
+ * Validate a committed lock against migration inputs and build its exact next
+ * document. Ordinary generation preserves the committed format; upgrading a
+ * version-1 lock is always an explicit command.
  */
-export declare function validateMigrationLock(locked: MigrationLock, current: MigrationLock): void;
+export declare function updateMigrationLock(locked: MigrationLock, migrations: readonly MigrationInput[]): MigrationLock;
+/** Validate without changing the committed lock format. */
+export declare function validateMigrationLock(locked: MigrationLock, migrations: readonly MigrationInput[]): void;

package/dist/migration-lock.js

@@ -3,9 +3,10 @@
  *
  * `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.
+ * generation may only append newly named migrations. Format 2 stores one
+ * canonical head-schema snapshot for actionable diagnostics instead of a
+ * cumulative schema copy after every migration. Format 1 remains readable and
+ * writable until an explicit `migrations upgrade-lock` command replaces it.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
@@ -13,7 +14,8 @@ 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;
+export const MIGRATION_LOCK_FORMAT_VERSION = 2;
+export const LEGACY_MIGRATION_LOCK_FORMAT_VERSION = 1;
 function normalizedSql(sql) {
     return sql.replace(/\r\n?/g, '\n');
 }
@@ -37,8 +39,8 @@ function snapshotTables(tables) {
         columns: table.columns.map(snapshotColumn),
     }));
 }
-/** Build the exact lock document for a complete migration sequence. */
-export function buildMigrationLock(migrations) {
+/** Replay a complete migration sequence with ephemeral diagnostic snapshots. */
+function buildMigrationHistory(migrations) {
     const tables = new Map();
     const droppedTables = new Set();
     const entries = [];
@@ -50,7 +52,31 @@ export function buildMigrationLock(migrations) {
             tables: snapshotTables(tables),
         });
     }
-    return { formatVersion: MIGRATION_LOCK_FORMAT_VERSION, migrations: entries };
+    return { migrations: entries };
+}
+function lockFromHistory(history, formatVersion) {
+    if (history.migrations.length === 0) {
+        failLock('cannot lock an empty migration history');
+    }
+    if (formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
+        return {
+            formatVersion: LEGACY_MIGRATION_LOCK_FORMAT_VERSION,
+            migrations: history.migrations,
+        };
+    }
+    const head = history.migrations.at(-1);
+    return {
+        formatVersion: MIGRATION_LOCK_FORMAT_VERSION,
+        migrations: history.migrations.map(({ name, sha256 }) => ({
+            name,
+            sha256,
+        })),
+        head: { tables: head.tables },
+    };
+}
+/** Build a deterministic lock document for a complete migration sequence. */
+export function buildMigrationLock(migrations, formatVersion = MIGRATION_LOCK_FORMAT_VERSION) {
+    return lockFromHistory(buildMigrationHistory(migrations), formatVersion);
 }
 /** Fixed-order, byte-deterministic serialization for clean code review. */
 export function serializeMigrationLock(lock) {
@@ -118,21 +144,46 @@ function parseEntry(value, index) {
     const context = `migrations[${index}]`;
     if (!isRecord(value))
         failLock(`${context} must be an object`);
-    const { name, sha256, tables } = value;
+    const { name, sha256 } = 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`);
     }
+    return { name, sha256 };
+}
+function parseLegacyEntry(value, index) {
+    const context = `migrations[${index}]`;
+    const entry = parseEntry(value, index);
+    if (!isRecord(value))
+        failLock(`${context} must be an object`);
+    const { tables } = value;
     if (!Array.isArray(tables))
         failLock(`${context}.tables must be an array`);
     return {
-        name,
-        sha256,
+        ...entry,
         tables: tables.map((table, tableIndex) => parseTable(table, `${context}.tables[${tableIndex}]`)),
     };
 }
+function parseHead(value) {
+    if (!isRecord(value))
+        failLock('head must be an object');
+    if (!Array.isArray(value.tables))
+        failLock('head.tables must be an array');
+    return {
+        tables: value.tables.map((table, index) => parseTable(table, `head.tables[${index}]`)),
+    };
+}
+function assertUniqueMigrationNames(migrations) {
+    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);
+    }
+}
 /** Parse and structurally validate a committed lock document. */
 export function parseMigrationLock(source) {
     let raw;
@@ -144,21 +195,28 @@ export function parseMigrationLock(source) {
     }
     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 (raw.formatVersion !== LEGACY_MIGRATION_LOCK_FORMAT_VERSION &&
+        raw.formatVersion !== MIGRATION_LOCK_FORMAT_VERSION) {
+        failLock(`formatVersion must be ${LEGACY_MIGRATION_LOCK_FORMAT_VERSION} or ${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);
+    if (raw.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
+        const migrations = raw.migrations.map(parseLegacyEntry);
+        assertUniqueMigrationNames(migrations);
+        return {
+            formatVersion: LEGACY_MIGRATION_LOCK_FORMAT_VERSION,
+            migrations,
+        };
     }
-    return { formatVersion: MIGRATION_LOCK_FORMAT_VERSION, migrations };
+    const migrations = raw.migrations.map(parseEntry);
+    assertUniqueMigrationNames(migrations);
+    return {
+        formatVersion: MIGRATION_LOCK_FORMAT_VERSION,
+        migrations,
+        head: parseHead(raw.head),
+    };
 }
 /** Read the version-controlled baseline without exposing its absolute path. */
 export function readMigrationLock(manifestDir) {
@@ -238,7 +296,7 @@ const REPAIR_HINT = 'deployed migrations are immutable; restore the locked migra
  * 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) {
+function validateMigrationHistory(locked, current) {
     for (let index = 0; index < locked.migrations.length; index++) {
         const before = locked.migrations[index];
         const after = current.migrations[index];
@@ -249,7 +307,33 @@ export function validateMigrationLock(locked, current) {
             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}`);
+            const diagnosticBefore = locked.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION
+                ? locked.migrations[index]
+                : {
+                    ...before,
+                    tables: locked.head.tables,
+                };
+            // Format 2 keeps one schema snapshot after the complete locked prefix.
+            // Compare it with the current schema at that same boundary, excluding
+            // valid newly appended migrations from the diagnostic.
+            const diagnosticAfter = locked.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION
+                ? after
+                : (current.migrations[locked.migrations.length - 1] ?? after);
+            failLock(`history drift in migration ${JSON.stringify(before.name)}: checksum changed; first schema difference: ${firstSchemaDifference(diagnosticBefore, diagnosticAfter)}; ${REPAIR_HINT}`);
         }
     }
 }
+/**
+ * Validate a committed lock against migration inputs and build its exact next
+ * document. Ordinary generation preserves the committed format; upgrading a
+ * version-1 lock is always an explicit command.
+ */
+export function updateMigrationLock(locked, migrations) {
+    const current = buildMigrationHistory(migrations);
+    validateMigrationHistory(locked, current);
+    return lockFromHistory(current, locked.formatVersion);
+}
+/** Validate without changing the committed lock format. */
+export function validateMigrationLock(locked, migrations) {
+    validateMigrationHistory(locked, buildMigrationHistory(migrations));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.15.24",
+  "version": "0.15.25",
   "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.24",
-    "@syncular/server": "0.15.24"
+    "@syncular/core": "0.15.25",
+    "@syncular/server": "0.15.25"
   }
 }

package/src/cli.ts

@@ -24,6 +24,7 @@ import {
   checkOutputs,
   generate,
   loadQueries,
+  upgradeMigrationHistory,
   writeOutputs,
 } from './generate';
 import { InitError, initProject } from './init';
@@ -38,7 +39,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
+  migrations baseline, check, or upgrade-lock immutable 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
@@ -59,6 +60,7 @@ fmt options:
 migrations options:
   baseline               create the first immutable history lock; refuses overwrite
   check                  validate the committed history without generating outputs
+  upgrade-lock           explicitly compact a validated format-1 lock to format 2
   --manifest-dir <dir>   directory holding syncular.json (default: .)
 
 init options:
@@ -332,8 +334,14 @@ function runFmt(argv: readonly string[]): void {
 
 function runMigrations(argv: readonly string[]): void {
   const action = argv[0];
-  if (action !== 'baseline' && action !== 'check') {
-    fail(`migrations requires 'baseline' or 'check'\n${USAGE}`);
+  if (
+    action !== 'baseline' &&
+    action !== 'check' &&
+    action !== 'upgrade-lock'
+  ) {
+    fail(
+      `migrations requires 'baseline', 'check', or 'upgrade-lock'\n${USAGE}`,
+    );
   }
   const manifestDir = parseManifestDir(argv.slice(1));
   if (action === 'baseline') {
@@ -354,6 +362,19 @@ function runMigrations(argv: readonly string[]): void {
     return;
   }
 
+  if (action === 'upgrade-lock') {
+    let output: ReturnType<typeof upgradeMigrationHistory>;
+    try {
+      output = upgradeMigrationHistory(manifestDir);
+    } catch (error) {
+      fail(friendlyGenerateError(error));
+    }
+    writeFileSync(output.path, output.content, 'utf8');
+    console.log(`upgraded ${output.path} to compact format 2`);
+    console.log('review and commit the migration-lock format upgrade');
+    return;
+  }
+
   let drift: string[];
   try {
     drift = checkMigrationHistory(manifestDir);

package/src/generate.ts

@@ -43,10 +43,11 @@ import {
 } from './manifest';
 import {
   buildMigrationLock,
+  LEGACY_MIGRATION_LOCK_FORMAT_VERSION,
   MIGRATION_LOCK_FILENAME,
   readMigrationLock,
   serializeMigrationLock,
-  validateMigrationLock,
+  updateMigrationLock,
 } from './migration-lock';
 import { buildNamingMap, type NamingTarget } from './naming';
 import {
@@ -578,11 +579,36 @@ export function baselineMigrationHistory(manifestDir: string): GeneratedOutput {
   };
 }
 
+/**
+ * Validate and explicitly compact a version-1 migration lock to version 2.
+ * The caller owns the in-place write so the CLI can make the format transition
+ * visible and reviewable.
+ */
+export function upgradeMigrationHistory(manifestDir: string): GeneratedOutput {
+  const { manifest, migrations } = loadProjectInputs(manifestDir);
+  const locked = readMigrationLock(manifestDir);
+  if (locked.formatVersion !== LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
+    throw new TypegenError(
+      MIGRATION_LOCK_FILENAME,
+      'already uses the current compact migration-lock format',
+    );
+  }
+  // Validate the immutable prefix before replacing its representation.
+  updateMigrationLock(locked, migrations);
+  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);
+  const current = updateMigrationLock(
+    readMigrationLock(manifestDir),
+    migrations,
+  );
   buildIr(manifest, migrations);
   const output = {
     path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
@@ -599,8 +625,10 @@ export function checkMigrationHistory(manifestDir: string): string[] {
 /** 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 migrationLock = updateMigrationLock(
+    readMigrationLock(manifestDir),
+    migrations,
+  );
   const ir = buildIr(manifest, migrations);
 
   // §5/§12 naming: the emitter targets this run generates (keyword hazards

package/src/migration-lock.ts

@@ -3,9 +3,10 @@
  *
  * `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.
+ * generation may only append newly named migrations. Format 2 stores one
+ * canonical head-schema snapshot for actionable diagnostics instead of a
+ * cumulative schema copy after every migration. Format 1 remains readable and
+ * writable until an explicit `migrations upgrade-lock` command replaces it.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
@@ -16,7 +17,8 @@ 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 const MIGRATION_LOCK_FORMAT_VERSION = 2;
+export const LEGACY_MIGRATION_LOCK_FORMAT_VERSION = 1;
 
 export interface MigrationLockColumn {
   readonly name: string;
@@ -34,12 +36,29 @@ export interface MigrationLockTable {
 export interface MigrationLockEntry {
   readonly name: string;
   readonly sha256: string;
+}
+
+export interface LegacyMigrationLockEntry extends MigrationLockEntry {
   readonly tables: readonly MigrationLockTable[];
 }
 
-export interface MigrationLock {
+export interface LegacyMigrationLock {
+  readonly formatVersion: typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION;
+  readonly migrations: readonly LegacyMigrationLockEntry[];
+}
+
+export interface MigrationLockV2 {
   readonly formatVersion: typeof MIGRATION_LOCK_FORMAT_VERSION;
   readonly migrations: readonly MigrationLockEntry[];
+  readonly head: {
+    readonly tables: readonly MigrationLockTable[];
+  };
+}
+
+export type MigrationLock = LegacyMigrationLock | MigrationLockV2;
+
+interface CurrentMigrationHistory {
+  readonly migrations: readonly LegacyMigrationLockEntry[];
 }
 
 function normalizedSql(sql: string): string {
@@ -71,13 +90,13 @@ function snapshotTables(
     }));
 }
 
-/** Build the exact lock document for a complete migration sequence. */
-export function buildMigrationLock(
+/** Replay a complete migration sequence with ephemeral diagnostic snapshots. */
+function buildMigrationHistory(
   migrations: readonly MigrationInput[],
-): MigrationLock {
+): CurrentMigrationHistory {
   const tables = new Map<string, ParsedTable>();
   const droppedTables = new Set<string>();
-  const entries: MigrationLockEntry[] = [];
+  const entries: LegacyMigrationLockEntry[] = [];
   for (const migration of migrations) {
     applyMigrationSql(
       tables,
@@ -91,7 +110,43 @@ export function buildMigrationLock(
       tables: snapshotTables(tables),
     });
   }
-  return { formatVersion: MIGRATION_LOCK_FORMAT_VERSION, migrations: entries };
+  return { migrations: entries };
+}
+
+function lockFromHistory(
+  history: CurrentMigrationHistory,
+  formatVersion:
+    | typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION
+    | typeof MIGRATION_LOCK_FORMAT_VERSION,
+): MigrationLock {
+  if (history.migrations.length === 0) {
+    failLock('cannot lock an empty migration history');
+  }
+  if (formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
+    return {
+      formatVersion: LEGACY_MIGRATION_LOCK_FORMAT_VERSION,
+      migrations: history.migrations,
+    };
+  }
+  const head = history.migrations.at(-1) as LegacyMigrationLockEntry;
+  return {
+    formatVersion: MIGRATION_LOCK_FORMAT_VERSION,
+    migrations: history.migrations.map(({ name, sha256 }) => ({
+      name,
+      sha256,
+    })),
+    head: { tables: head.tables },
+  };
+}
+
+/** Build a deterministic lock document for a complete migration sequence. */
+export function buildMigrationLock(
+  migrations: readonly MigrationInput[],
+  formatVersion:
+    | typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION
+    | typeof MIGRATION_LOCK_FORMAT_VERSION = MIGRATION_LOCK_FORMAT_VERSION,
+): MigrationLock {
+  return lockFromHistory(buildMigrationHistory(migrations), formatVersion);
 }
 
 /** Fixed-order, byte-deterministic serialization for clean code review. */
@@ -165,23 +220,55 @@ function parseTable(value: unknown, context: string): MigrationLockTable {
 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;
+  const { name, sha256 } = 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`);
   }
+  return { name, sha256 };
+}
+
+function parseLegacyEntry(
+  value: unknown,
+  index: number,
+): LegacyMigrationLockEntry {
+  const context = `migrations[${index}]`;
+  const entry = parseEntry(value, index);
+  if (!isRecord(value)) failLock(`${context} must be an object`);
+  const { tables } = value;
   if (!Array.isArray(tables)) failLock(`${context}.tables must be an array`);
   return {
-    name,
-    sha256,
+    ...entry,
     tables: tables.map((table, tableIndex) =>
       parseTable(table, `${context}.tables[${tableIndex}]`),
     ),
   };
 }
 
+function parseHead(value: unknown): MigrationLockV2['head'] {
+  if (!isRecord(value)) failLock('head must be an object');
+  if (!Array.isArray(value.tables)) failLock('head.tables must be an array');
+  return {
+    tables: value.tables.map((table, index) =>
+      parseTable(table, `head.tables[${index}]`),
+    ),
+  };
+}
+
+function assertUniqueMigrationNames(
+  migrations: readonly MigrationLockEntry[],
+): void {
+  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);
+  }
+}
+
 /** Parse and structurally validate a committed lock document. */
 export function parseMigrationLock(source: string): MigrationLock {
   let raw: unknown;
@@ -191,23 +278,32 @@ export function parseMigrationLock(source: string): MigrationLock {
     failLock('invalid JSON');
   }
   if (!isRecord(raw)) failLock('root must be an object');
-  if (raw.formatVersion !== MIGRATION_LOCK_FORMAT_VERSION) {
+  if (
+    raw.formatVersion !== LEGACY_MIGRATION_LOCK_FORMAT_VERSION &&
+    raw.formatVersion !== MIGRATION_LOCK_FORMAT_VERSION
+  ) {
     failLock(
-      `formatVersion must be ${MIGRATION_LOCK_FORMAT_VERSION}, got ${JSON.stringify(raw.formatVersion)}`,
+      `formatVersion must be ${LEGACY_MIGRATION_LOCK_FORMAT_VERSION} or ${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);
+  if (raw.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
+    const migrations = raw.migrations.map(parseLegacyEntry);
+    assertUniqueMigrationNames(migrations);
+    return {
+      formatVersion: LEGACY_MIGRATION_LOCK_FORMAT_VERSION,
+      migrations,
+    };
   }
-  return { formatVersion: MIGRATION_LOCK_FORMAT_VERSION, migrations };
+  const migrations = raw.migrations.map(parseEntry);
+  assertUniqueMigrationNames(migrations);
+  return {
+    formatVersion: MIGRATION_LOCK_FORMAT_VERSION,
+    migrations,
+    head: parseHead(raw.head),
+  };
 }
 
 /** Read the version-controlled baseline without exposing its absolute path. */
@@ -266,8 +362,8 @@ function describeColumnDifference(
 }
 
 function firstSchemaDifference(
-  locked: MigrationLockEntry,
-  current: MigrationLockEntry,
+  locked: LegacyMigrationLockEntry,
+  current: LegacyMigrationLockEntry,
 ): string {
   const length = Math.max(locked.tables.length, current.tables.length);
   for (let index = 0; index < length; index++) {
@@ -303,9 +399,9 @@ const REPAIR_HINT =
  * 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(
+function validateMigrationHistory(
   locked: MigrationLock,
-  current: MigrationLock,
+  current: CurrentMigrationHistory,
 ): void {
   for (let index = 0; index < locked.migrations.length; index++) {
     const before = locked.migrations[index] as MigrationLockEntry;
@@ -321,9 +417,45 @@ export function validateMigrationLock(
       );
     }
     if (before.sha256 !== after.sha256) {
+      const diagnosticBefore: LegacyMigrationLockEntry =
+        locked.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION
+          ? (locked.migrations[index] as LegacyMigrationLockEntry)
+          : {
+              ...before,
+              tables: locked.head.tables,
+            };
+      // Format 2 keeps one schema snapshot after the complete locked prefix.
+      // Compare it with the current schema at that same boundary, excluding
+      // valid newly appended migrations from the diagnostic.
+      const diagnosticAfter =
+        locked.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION
+          ? after
+          : (current.migrations[locked.migrations.length - 1] ?? after);
       failLock(
-        `history drift in migration ${JSON.stringify(before.name)}: checksum changed; first schema difference: ${firstSchemaDifference(before, after)}; ${REPAIR_HINT}`,
+        `history drift in migration ${JSON.stringify(before.name)}: checksum changed; first schema difference: ${firstSchemaDifference(diagnosticBefore, diagnosticAfter)}; ${REPAIR_HINT}`,
       );
     }
   }
 }
+
+/**
+ * Validate a committed lock against migration inputs and build its exact next
+ * document. Ordinary generation preserves the committed format; upgrading a
+ * version-1 lock is always an explicit command.
+ */
+export function updateMigrationLock(
+  locked: MigrationLock,
+  migrations: readonly MigrationInput[],
+): MigrationLock {
+  const current = buildMigrationHistory(migrations);
+  validateMigrationHistory(locked, current);
+  return lockFromHistory(current, locked.formatVersion);
+}
+
+/** Validate without changing the committed lock format. */
+export function validateMigrationLock(
+  locked: MigrationLock,
+  migrations: readonly MigrationInput[],
+): void {
+  validateMigrationHistory(locked, buildMigrationHistory(migrations));
+}