@visorcraft/mongreldb-kit 0.7.0

package/dist/migrate.js

@@ -0,0 +1,1004 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { tableFromIPC } from 'apache-arrow';
+import { table, int, text } from './schema.js';
+import { toCells, pkValueFromRow, parentExists } from './constraints.js';
+import { validateRow } from './validation.js';
+import { KIT_KEY_VERSION, encodedPk, encodeRowGuardKey, encodeUniqueKey } from './keys.js';
+import { KitMigrationError, KitSchemaDriftError, KitForeignKeyError } from './errors.js';
+import { kitSchemaMigrations, kitSchemaCatalog, kitMigrationLocks, kitUniqueKeys, kitRowGuards } from './internalTables.js';
+/**
+ * Schema of the legacy Kit sequence table that existed before engine-native
+ * auto-increment. When present, its rows are used as a one-time fallback to
+ * seed per-table engine counters so upgraded databases do not hand out ids
+ * below a sequence that was already advanced.
+ */
+const legacyKitSequences = table('__kit_sequences', {
+    columns: [
+        text('sequence_name', { primaryKey: true }),
+        int('next_value', { nullable: false })
+    ],
+    primaryKey: ['sequence_name']
+});
+function seedFromLegacyKitSequences(kit) {
+    const db = kit.nativeDb;
+    if (!db.tableNames().includes('__kit_sequences')) {
+        return;
+    }
+    for (const { row } of fullScanRows(db, legacyKitSequences)) {
+        const sequenceName = row.sequence_name;
+        const nextValue = row.next_value;
+        if (!sequenceName || nextValue === null || nextValue <= 1n) {
+            continue;
+        }
+        const tableName = sequenceName.endsWith('_id_seq')
+            ? sequenceName.slice(0, -'_id_seq'.length)
+            : sequenceName;
+        if (!db.tableNames().includes(tableName)) {
+            continue;
+        }
+        // Advance the engine counter until it is at least the legacy next value.
+        // reserveAutoIncSync seeds from max(existing id) on its first call, so this
+        // also covers the case where rows already exist with higher ids.
+        while (true) {
+            const reserved = kit.reserveAutoIncSync(tableName);
+            if (reserved === null)
+                break;
+            if (reserved >= nextValue)
+                break;
+        }
+    }
+}
+const I64_MIN = -9223372036854775808n;
+const I64_MAX = 9223372036854775807n;
+const LOCK_NAME = 'default';
+const LOCK_HOLDER = 'kit';
+const LOCK_TTL_MS = 5 * 60 * 1000;
+function columnId(table, name) {
+    const col = table.columns.find((c) => c.name === name);
+    if (!col) {
+        throw new Error(`Column "${name}" not found in table "${table.name}"`);
+    }
+    return col.id;
+}
+function isoNow() {
+    return new Date().toISOString();
+}
+function toMongrelColumnType(storageType) {
+    switch (storageType) {
+        case 'bool':
+            return 0 /* ColumnType.Bool */;
+        case 'int64':
+        case 'timestamp':
+            return 1 /* ColumnType.Int64 */;
+        case 'float64':
+            return 2 /* ColumnType.Float64 */;
+        case 'date':
+            return 4 /* ColumnType.Date32 */;
+        case 'text':
+        case 'bytes':
+        case 'json':
+            return 5 /* ColumnType.Bytes */;
+        case 'embedding':
+            return 6 /* ColumnType.Embedding */;
+        case 'sparse':
+            return 5 /* ColumnType.Bytes */;
+    }
+}
+function toMongrelColumnSpec(column) {
+    return {
+        id: column.id,
+        name: column.name,
+        ty: toMongrelColumnType(column.storageType),
+        primaryKey: column.primaryKey,
+        nullable: column.nullable,
+        autoIncrement: column.default?.kind === 'sequence',
+        embeddingDim: column.embeddingDim
+    };
+}
+function toMongrelSchema(table) {
+    const indexes = table.indexes.flatMap((idx) => idx.columns.map((colName) => {
+        const col = table.columns.find((c) => c.name === colName);
+        if (!col) {
+            throw new Error(`Index column "${colName}" not found in table "${table.name}"`);
+        }
+        return {
+            name: `${idx.name}_${colName}`,
+            columnId: col.id,
+            kind: 0 /* IndexKindSpec.Bitmap */
+        };
+    }));
+    const indexedColumns = new Set(table.indexes.flatMap((idx) => idx.columns));
+    for (const pk of table.primaryKey) {
+        if (indexedColumns.has(pk))
+            continue;
+        const col = table.columns.find((c) => c.name === pk);
+        if (!col) {
+            throw new Error(`Primary key column "${pk}" not found in table "${table.name}"`);
+        }
+        indexes.push({
+            name: `pk_${pk}`,
+            columnId: col.id,
+            kind: 0 /* IndexKindSpec.Bitmap */
+        });
+        indexedColumns.add(pk);
+    }
+    for (const fk of table.foreignKeys) {
+        for (const colName of fk.columns) {
+            if (indexedColumns.has(colName))
+                continue;
+            const col = table.columns.find((c) => c.name === colName);
+            if (!col) {
+                throw new Error(`Foreign key column "${colName}" not found in table "${table.name}"`);
+            }
+            indexes.push({
+                name: `fk_${fk.name}_${colName}`,
+                columnId: col.id,
+                kind: 0 /* IndexKindSpec.Bitmap */
+            });
+            indexedColumns.add(colName);
+        }
+    }
+    return {
+        columns: table.columns.map(toMongrelColumnSpec),
+        indexes
+    };
+}
+function cellValue(cell) {
+    if (!cell)
+        return null;
+    if (cell.text !== undefined)
+        return cell.text;
+    if (cell.int64 !== undefined)
+        return cell.int64;
+    if (cell.boolean !== undefined)
+        return cell.boolean;
+    if (cell.float64 !== undefined)
+        return cell.float64;
+    if (cell.bytes !== undefined)
+        return cell.bytes;
+    return null;
+}
+function rowFromRowJs(table, rowJs) {
+    const row = {};
+    for (const col of table.columns) {
+        const cell = rowJs.cells.find((c) => c.columnId === col.id);
+        row[col.name] = cellValue(cell);
+    }
+    return row;
+}
+function fullScanCondition(table) {
+    const intColumn = table.columns.find((c) => c.storageType === 'int64' || c.storageType === 'timestamp');
+    if (intColumn) {
+        return {
+            kind: 2 /* ConditionKind.RangeInt */,
+            columnId: intColumn.id,
+            int64Lo: I64_MIN,
+            int64Hi: I64_MAX
+        };
+    }
+    const floatColumn = table.columns.find((c) => c.storageType === 'float64');
+    if (floatColumn) {
+        return {
+            kind: 3 /* ConditionKind.RangeF64 */,
+            columnId: floatColumn.id,
+            float64Lo: -Infinity,
+            float64Hi: Infinity
+        };
+    }
+    throw new KitMigrationError(`Full table scan on "${table.name}" requires an int64, timestamp, or float64 column`);
+}
+function fullScanRows(db, table) {
+    const condition = fullScanCondition(table);
+    return db
+        .table(table.name)
+        .query([condition])
+        .map((rowJs) => ({ rowId: rowJs.rowId, row: rowFromRowJs(table, rowJs) }));
+}
+/**
+ * Canonical, language-neutral serialization of a single migration op. The key
+ * order is fixed and string values use standard JSON escaping (`JSON.stringify`),
+ * so this is byte-for-byte identical to the Rust kit's `canonical_op`
+ * (`crates/mongreldb-kit-core/src/migrations.rs`).
+ */
+function canonicalOp(op) {
+    const s = (value) => JSON.stringify(value);
+    switch (op.kind) {
+        case 'createTable':
+            return `{"op":"create_table","name":${s(op.name)}}`;
+        case 'dropTable':
+            return `{"op":"drop_table","name":${s(op.name)}}`;
+        case 'addColumn':
+            return `{"op":"add_column","table":${s(op.table)},"column":${s(op.column)}}`;
+        case 'dropColumn':
+            return `{"op":"drop_column","table":${s(op.table)},"column":${s(op.column)}}`;
+        case 'alterColumn':
+            return `{"op":"alter_column","table":${s(op.table)},"column":${s(op.column)}}`;
+        case 'addIndex':
+            return `{"op":"add_index","table":${s(op.table)},"index":${s(op.index)}}`;
+        case 'dropIndex':
+            return `{"op":"drop_index","table":${s(op.table)},"index":${s(op.index)}}`;
+        case 'addUnique':
+            return `{"op":"add_unique","table":${s(op.table)},"constraint":${s(op.constraint)}}`;
+        case 'dropUnique':
+            return `{"op":"drop_unique","table":${s(op.table)},"constraint":${s(op.constraint)}}`;
+        case 'addForeignKey':
+            return `{"op":"add_foreign_key","table":${s(op.table)},"constraint":${s(op.constraint)}}`;
+        case 'dropForeignKey':
+            return `{"op":"drop_foreign_key","table":${s(op.table)},"constraint":${s(op.constraint)}}`;
+        case 'addCheck':
+            return `{"op":"add_check","table":${s(op.table)},"constraint":${s(op.constraint)}}`;
+        case 'dropCheck':
+            return `{"op":"drop_check","table":${s(op.table)},"constraint":${s(op.constraint)}}`;
+        case 'rawSql':
+            return `{"op":"raw_sql","sql":${s(op.sql)}}`;
+        default: {
+            const _exhaustive = op;
+            throw new Error(`Unknown migration op: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * The canonical content string a migration's checksum is computed over. Shape:
+ * `{"version":<n>,"name":<json>,"ops":[<op>,...]}` with no insignificant
+ * whitespace, byte-identical to the Rust kit's `canonical_content`.
+ */
+export function migrationContent(migration) {
+    const opsJson = (migration.ops ?? []).map(canonicalOp).join(',');
+    return `{"version":${migration.version},"name":${JSON.stringify(migration.name)},"ops":[${opsJson}]}`;
+}
+/**
+ * Content-aware SHA-256 checksum for a migration. Covers the version, name, and
+ * ordered op list via {@link migrationContent}; the same logical migration
+ * produces the identical checksum in TypeScript, Rust, and Python.
+ */
+export function migrationChecksum(migration) {
+    return createHash('sha256').update(migrationContent(migration)).digest('hex');
+}
+function schemaCatalogJson(schema) {
+    return JSON.stringify(schema.tablesList().map((t) => ({
+        tableId: t.tableId,
+        name: t.name,
+        columns: t.columns.map((c) => ({
+            id: c.id,
+            name: c.name,
+            storageType: c.storageType,
+            applicationType: c.applicationType,
+            nullable: c.nullable,
+            primaryKey: c.primaryKey,
+            enumValues: c.enumValues,
+            min: c.min,
+            max: c.max,
+            minLength: c.minLength,
+            maxLength: c.maxLength,
+            regex: c.regex?.source
+        })),
+        primaryKey: t.primaryKey,
+        indexes: t.indexes,
+        foreignKeys: t.foreignKeys,
+        unique: t.unique,
+        checks: t.checks.map((c) => ({ name: c.name }))
+    })));
+}
+async function runSql(db, sql) {
+    const ipc = await db.sql(sql);
+    const arrowTable = tableFromIPC(ipc);
+    return [...arrowTable].map((row) => ({ ...row }));
+}
+async function acquireLock(kit) {
+    const db = kit.nativeDb;
+    const locks = db.table('__kit_migration_locks');
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
+    const existing = locks.getByPkText(LOCK_NAME);
+    if (existing) {
+        const expiresAtCell = existing.cells.find((c) => c.columnId === columnId(kitMigrationLocks, 'expires_at'));
+        const existingExpires = expiresAtCell?.text;
+        if (existingExpires && new Date(existingExpires) > now) {
+            throw new KitMigrationError('migration lock is already held');
+        }
+        locks.deleteByPkText(LOCK_NAME);
+    }
+    locks.put([
+        { columnId: columnId(kitMigrationLocks, 'lock_name'), text: LOCK_NAME },
+        { columnId: columnId(kitMigrationLocks, 'holder'), text: LOCK_HOLDER },
+        { columnId: columnId(kitMigrationLocks, 'acquired_at'), text: now.toISOString() },
+        { columnId: columnId(kitMigrationLocks, 'expires_at'), text: expiresAt.toISOString() }
+    ]);
+    locks.commit();
+}
+async function releaseLock(kit) {
+    const locks = kit.nativeDb.table('__kit_migration_locks');
+    locks.deleteByPkText(LOCK_NAME);
+    locks.commit();
+}
+async function readAppliedMigrations(kit) {
+    const rows = fullScanRows(kit.nativeDb, kitSchemaMigrations);
+    return rows
+        .map((m) => ({
+        version: m.row.version,
+        name: m.row.name,
+        checksum: m.row.checksum,
+        status: m.row.status
+    }))
+        .sort((a, b) => Number(a.version - b.version));
+}
+async function insertMigrationRecord(kit, migration, status) {
+    const table = kit.nativeDb.table('__kit_schema_migrations');
+    table.put([
+        { columnId: columnId(kitSchemaMigrations, 'version'), int64: BigInt(migration.version) },
+        { columnId: columnId(kitSchemaMigrations, 'name'), text: migration.name },
+        { columnId: columnId(kitSchemaMigrations, 'checksum'), text: migrationChecksum(migration) },
+        { columnId: columnId(kitSchemaMigrations, 'applied_at'), text: isoNow() },
+        { columnId: columnId(kitSchemaMigrations, 'kit_version'), text: kitVersion() },
+        { columnId: columnId(kitSchemaMigrations, 'status'), text: status }
+    ]);
+    table.commit();
+}
+async function updateMigrationStatus(kit, version, status) {
+    const table = kit.nativeDb.table('__kit_schema_migrations');
+    const rowJs = table.getByPkInt64(BigInt(version));
+    if (!rowJs) {
+        throw new KitMigrationError(`migration record ${version} not found`);
+    }
+    const row = rowFromRowJs(kitSchemaMigrations, rowJs);
+    const updated = { ...row, status };
+    table.put(toCells(kitSchemaMigrations, updated));
+    table.commit();
+}
+async function writeSchemaCatalog(kit, schema) {
+    const db = kit.nativeDb;
+    const catalog = db.table('__kit_schema_catalog');
+    const schemaJson = schemaCatalogJson(schema);
+    const checksum = createHash('sha256').update(schemaJson).digest('hex');
+    const now = isoNow();
+    await db.transaction(async (txn) => {
+        txn.put('__kit_schema_catalog', [
+            { columnId: columnId(kitSchemaCatalog, 'schema_version'), int64: 1n },
+            { columnId: columnId(kitSchemaCatalog, 'schema_json'), text: schemaJson },
+            { columnId: columnId(kitSchemaCatalog, 'checksum'), text: checksum },
+            { columnId: columnId(kitSchemaCatalog, 'written_at'), text: now }
+        ]);
+    });
+}
+function kitVersion() {
+    // Keep in sync with package.json. Avoiding a JSON import keeps the ESM bundle simple.
+    return '0.3.0';
+}
+function makeContext(kit) {
+    return {
+        kit,
+        db: kit.nativeDb,
+        ensureTable: (table) => createTable(kit, table),
+        addColumn: (tableName, column) => addColumn(kit, tableName, column),
+        dropColumn: (tableName, columnName) => dropColumn(kit, tableName, columnName),
+        alterColumn: (tableName, columnName, newColumn) => alterColumn(kit, tableName, columnName, newColumn),
+        addIndex: (tableName, index) => addIndex(kit, tableName, index),
+        dropIndex: (tableName, indexName) => dropIndex(kit, tableName, indexName),
+        sql: (sql) => runSql(kit.nativeDb, sql)
+    };
+}
+function acquireLockSync(kit) {
+    const db = kit.nativeDb;
+    const locks = db.table('__kit_migration_locks');
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
+    const existing = locks.getByPkText(LOCK_NAME);
+    if (existing) {
+        const expiresAtCell = existing.cells.find((c) => c.columnId === columnId(kitMigrationLocks, 'expires_at'));
+        const existingExpires = expiresAtCell?.text;
+        if (existingExpires && new Date(existingExpires) > now) {
+            throw new KitMigrationError('migration lock is already held');
+        }
+        locks.deleteByPkText(LOCK_NAME);
+    }
+    locks.put([
+        { columnId: columnId(kitMigrationLocks, 'lock_name'), text: LOCK_NAME },
+        { columnId: columnId(kitMigrationLocks, 'holder'), text: LOCK_HOLDER },
+        { columnId: columnId(kitMigrationLocks, 'acquired_at'), text: now.toISOString() },
+        { columnId: columnId(kitMigrationLocks, 'expires_at'), text: expiresAt.toISOString() }
+    ]);
+    locks.commit();
+}
+function releaseLockSync(kit) {
+    const locks = kit.nativeDb.table('__kit_migration_locks');
+    locks.deleteByPkText(LOCK_NAME);
+    locks.commit();
+}
+function readAppliedMigrationsSync(kit) {
+    const rows = fullScanRows(kit.nativeDb, kitSchemaMigrations);
+    return rows
+        .map((m) => ({
+        version: m.row.version,
+        name: m.row.name,
+        checksum: m.row.checksum,
+        status: m.row.status
+    }))
+        .sort((a, b) => Number(a.version - b.version));
+}
+function insertMigrationRecordSync(kit, migration, status) {
+    const table = kit.nativeDb.table('__kit_schema_migrations');
+    table.put([
+        { columnId: columnId(kitSchemaMigrations, 'version'), int64: BigInt(migration.version) },
+        { columnId: columnId(kitSchemaMigrations, 'name'), text: migration.name },
+        { columnId: columnId(kitSchemaMigrations, 'checksum'), text: migrationChecksum(migration) },
+        { columnId: columnId(kitSchemaMigrations, 'applied_at'), text: isoNow() },
+        { columnId: columnId(kitSchemaMigrations, 'kit_version'), text: kitVersion() },
+        { columnId: columnId(kitSchemaMigrations, 'status'), text: status }
+    ]);
+    table.commit();
+}
+function updateMigrationStatusSync(kit, version, status) {
+    const table = kit.nativeDb.table('__kit_schema_migrations');
+    const rowJs = table.getByPkInt64(BigInt(version));
+    if (!rowJs) {
+        throw new KitMigrationError(`migration record ${version} not found`);
+    }
+    const row = rowFromRowJs(kitSchemaMigrations, rowJs);
+    const updated = { ...row, status };
+    table.put(toCells(kitSchemaMigrations, updated));
+    table.commit();
+}
+function writeSchemaCatalogSync(kit, schema) {
+    const db = kit.nativeDb;
+    const schemaJson = schemaCatalogJson(schema);
+    const checksum = createHash('sha256').update(schemaJson).digest('hex');
+    const now = isoNow();
+    const txn = db.begin();
+    try {
+        txn.put('__kit_schema_catalog', [
+            { columnId: columnId(kitSchemaCatalog, 'schema_version'), int64: 1n },
+            { columnId: columnId(kitSchemaCatalog, 'schema_json'), text: schemaJson },
+            { columnId: columnId(kitSchemaCatalog, 'checksum'), text: checksum },
+            { columnId: columnId(kitSchemaCatalog, 'written_at'), text: now }
+        ]);
+        txn.commit();
+    }
+    catch (err) {
+        txn.rollback();
+        throw err;
+    }
+}
+function makeContextSync(kit) {
+    return {
+        kit,
+        db: kit.nativeDb,
+        ensureTable: (table) => createTableSync(kit, table),
+        addColumn: (tableName, column) => addColumnSync(kit, tableName, column),
+        dropColumn: (tableName, columnName) => dropColumnSync(kit, tableName, columnName),
+        alterColumn: (tableName, columnName, newColumn) => alterColumnSync(kit, tableName, columnName, newColumn),
+        addIndex: (tableName, index) => addIndexSync(kit, tableName, index),
+        dropIndex: (tableName, indexName) => dropIndexSync(kit, tableName, indexName),
+        sql: () => {
+            throw new KitMigrationError('sql() is not available in synchronous migrations');
+        }
+    };
+}
+export function migrateSync(kit, schema, migrations) {
+    acquireLockSync(kit);
+    try {
+        migrations = [...migrations].sort((a, b) => a.version - b.version);
+        const applied = readAppliedMigrationsSync(kit);
+        verifyMigrationChecksums(applied, migrations);
+        const maxApplied = applied.reduce((max, m) => (m.version > max ? m.version : max), 0n);
+        const pending = migrations.filter((m) => BigInt(m.version) > maxApplied);
+        for (const migration of pending) {
+            insertMigrationRecordSync(kit, migration, 'in_progress');
+            const txn = kit.nativeDb.begin();
+            try {
+                const result = migration.up(makeContextSync(kit));
+                if (result && typeof result.then === 'function') {
+                    throw new KitMigrationError('async migration up() cannot be used with migrateSync');
+                }
+                txn.commit();
+                updateMigrationStatusSync(kit, migration.version, 'applied');
+            }
+            catch (cause) {
+                txn.rollback();
+                updateMigrationStatusSync(kit, migration.version, 'failed');
+                const message = cause instanceof Error ? cause.message : String(cause);
+                throw new KitMigrationError(`migration ${migration.version} failed: ${message}`);
+            }
+        }
+        writeSchemaCatalogSync(kit, schema);
+        seedFromLegacyKitSequences(kit);
+    }
+    finally {
+        releaseLockSync(kit);
+    }
+}
+export async function migrate(kit, schema, migrations) {
+    await acquireLock(kit);
+    try {
+        migrations = [...migrations].sort((a, b) => a.version - b.version);
+        const applied = await readAppliedMigrations(kit);
+        verifyMigrationChecksums(applied, migrations);
+        const maxApplied = applied.reduce((max, m) => (m.version > max ? m.version : max), 0n);
+        const pending = migrations.filter((m) => BigInt(m.version) > maxApplied);
+        for (const migration of pending) {
+            await insertMigrationRecord(kit, migration, 'in_progress');
+            try {
+                await kit.nativeDb.transaction(async () => {
+                    await migration.up(makeContext(kit));
+                });
+                await updateMigrationStatus(kit, migration.version, 'applied');
+            }
+            catch (cause) {
+                await updateMigrationStatus(kit, migration.version, 'failed');
+                const message = cause instanceof Error ? cause.message : String(cause);
+                throw new KitMigrationError(`migration ${migration.version} failed: ${message}`);
+            }
+        }
+        await writeSchemaCatalog(kit, schema);
+        seedFromLegacyKitSequences(kit);
+    }
+    finally {
+        await releaseLock(kit);
+    }
+}
+/**
+ * Reject edited or reordered historical migrations by comparing the stored
+ * checksum/name of every applied migration record against the corresponding
+ * migration in the supplied list. Drift here would silently change the meaning
+ * of an already-applied migration and corrupt the schema catalog.
+ */
+function verifyMigrationChecksums(applied, migrations) {
+    const byVersion = new Map(migrations.map((m) => [BigInt(m.version), m]));
+    for (const record of applied) {
+        if (record.status === 'failed') {
+            // Failed migrations are not part of the canonical history; the
+            // caller is expected to repair them before re-running.
+            continue;
+        }
+        const current = byVersion.get(record.version);
+        if (!current) {
+            throw new KitSchemaDriftError(`migration ${record.version} (${record.name}) is recorded as applied but is missing from the supplied migrations list`);
+        }
+        const expected = migrationChecksum(current);
+        if (expected !== record.checksum || current.name !== record.name) {
+            throw new KitSchemaDriftError(`migration ${record.version} (${record.name}) checksum mismatch: stored ${record.checksum}, expected ${expected}`);
+        }
+    }
+}
+function createTableSync(kit, table) {
+    if (kit.nativeDb.tableNames().includes(table.name))
+        return;
+    kit.nativeDb.createTable(table.name, toMongrelSchema(table));
+}
+export async function createTable(kit, table) {
+    createTableSync(kit, table);
+}
+/**
+ * Drop `tableName` and remove every unique-key and row guard it owned. The
+ * application row data and its guards are gone after this; the schema catalog is
+ * re-persisted by the migration runner once all ops complete.
+ */
+export async function dropTable(kit, tableName) {
+    const db = kit.nativeDb;
+    if (!db.tableNames().includes(tableName)) {
+        throw new KitMigrationError(`Table "${tableName}" does not exist`);
+    }
+    db.dropTable(tableName);
+    cleanTableGuards(kit, tableName);
+}
+/** Delete unique-key and row guards owned by a dropped table. */
+function cleanTableGuards(kit, tableName) {
+    const db = kit.nativeDb;
+    const ukHandle = db.table('__kit_unique_keys');
+    const ukGuards = ukHandle.query([
+        {
+            kind: 1 /* ConditionKind.BitmapEq */,
+            columnId: columnId(kitUniqueKeys, 'owner_table'),
+            text: tableName
+        }
+    ]);
+    let ukMutated = false;
+    for (const guard of ukGuards) {
+        const key = guard.cells.find((c) => c.columnId === columnId(kitUniqueKeys, 'encoded_key'))?.text;
+        if (key) {
+            ukHandle.deleteByPkText(key);
+            ukMutated = true;
+        }
+    }
+    if (ukMutated)
+        ukHandle.commit();
+    const rgHandle = db.table('__kit_row_guards');
+    const rgGuards = rgHandle.query([
+        {
+            kind: 1 /* ConditionKind.BitmapEq */,
+            columnId: columnId(kitRowGuards, 'table_name'),
+            text: tableName
+        }
+    ]);
+    let rgMutated = false;
+    for (const guard of rgGuards) {
+        const key = guard.cells.find((c) => c.columnId === columnId(kitRowGuards, 'encoded_guard_key'))?.text;
+        if (key) {
+            rgHandle.deleteByPkText(key);
+            rgMutated = true;
+        }
+    }
+    if (rgMutated)
+        rgHandle.commit();
+}
+function computeDefaultValue(column, kit) {
+    const source = column.default ?? (column.generated === 'uuid' ? { kind: 'uuid' } : column.generated === 'now' ? { kind: 'now' } : null);
+    if (!source)
+        return null;
+    switch (source.kind) {
+        case 'static':
+            return source.value;
+        case 'now':
+            return isoNow();
+        case 'uuid':
+            return randomUUID();
+        case 'sequence':
+            // Sequences are now engine-managed AUTO_INCREMENT, so a freshly
+            // created table with a sequence column migrates fine (the engine
+            // allocates on insert). What is NOT supported is back-filling an
+            // AUTO_INCREMENT value onto existing rows during `addColumn` — each
+            // row would need its own id and re-putting changes identities.
+            throw new KitMigrationError(`AUTO_INCREMENT column "${column.name}" cannot be added with a NOT NULL backfill; add it nullable (or create the table with it)`);
+        case 'custom':
+            return source.fn();
+        default:
+            return null;
+    }
+}
+function addColumnSync(kit, tableName, column) {
+    if (!column.nullable && !column.default && !column.generated) {
+        throw new KitMigrationError(`Column "${column.name}" on "${tableName}" must be nullable or have a default value`);
+    }
+    const db = kit.nativeDb;
+    const table = kit.schema.table(tableName);
+    if (db.tableNames().includes(tableName)) {
+        const dbColumns = db.tableColumns(tableName);
+        if (dbColumns.includes(column.name))
+            return;
+    }
+    const updatedTable = {
+        ...table,
+        columns: [...table.columns, column]
+    };
+    db.addColumn(tableName, toMongrelColumnSpec(column));
+    if (!column.nullable) {
+        const defaultValue = computeDefaultValue(column, kit);
+        const rows = fullScanRows(db, table);
+        for (const { rowId, row } of rows) {
+            const backfilled = { ...row, [column.name]: defaultValue };
+            validateRow(updatedTable, backfilled);
+            db.table(tableName).put(toCells(updatedTable, backfilled));
+        }
+        db.table(tableName).commit();
+    }
+}
+export async function addColumn(kit, tableName, column) {
+    addColumnSync(kit, tableName, column);
+}
+/**
+ * Change the declared type or constraints of an existing column in place.
+ *
+ * Kit keeps application-only changes metadata-local when the old and new
+ * storage types map to the same engine {@link ColumnType}. Native schema
+ * changes (rename, storage type, nullability, primary-key/sequence flags) are
+ * delegated to MongrelDB's native ALTER COLUMN validation.
+ */
+export async function alterColumn(kit, tableName, columnName, newColumn) {
+    alterColumnSync(kit, tableName, columnName, newColumn);
+}
+function alterColumnSync(kit, tableName, columnName, newColumn) {
+    const table = kit.schema.table(tableName);
+    const existingIndex = table.columns.findIndex((c) => c.name === columnName);
+    if (existingIndex === -1) {
+        throw new KitMigrationError(`Column "${columnName}" not found in table "${tableName}"`);
+    }
+    const existing = table.columns[existingIndex];
+    const resolved = { ...newColumn, id: existing.id };
+    if (resolved.name !== existing.name &&
+        table.columns.some((c, idx) => idx !== existingIndex && c.name === resolved.name)) {
+        throw new KitMigrationError(`Column "${resolved.name}" already exists in table "${tableName}"`);
+    }
+    const oldNativeTy = toMongrelColumnType(existing.storageType);
+    const newNativeTy = toMongrelColumnType(resolved.storageType);
+    const nativeChange = resolved.name !== existing.name ||
+        newNativeTy !== oldNativeTy ||
+        resolved.nullable !== existing.nullable ||
+        resolved.primaryKey !== existing.primaryKey ||
+        (resolved.default?.kind === 'sequence') !== (existing.default?.kind === 'sequence');
+    if (nativeChange) {
+        const db = kit.nativeDb;
+        if (typeof db.alterColumn !== 'function') {
+            throw new KitMigrationError(`alterColumn for "${tableName}"."${columnName}" requires a MongrelDB native addon with alterColumn support`);
+        }
+        try {
+            db.alterColumn(tableName, columnName, toMongrelColumnSpec(resolved));
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new KitMigrationError(`alterColumn failed for "${tableName}"."${columnName}": ${message}`);
+        }
+    }
+    table.columns[existingIndex] = resolved;
+    if (resolved.name !== existing.name) {
+        renameColumnReferences(table, existing.name, resolved.name);
+        for (const candidate of kit.schema.tablesList()) {
+            for (const fk of candidate.foreignKeys) {
+                if (fk.referencesTable !== tableName)
+                    continue;
+                fk.referencesColumns = fk.referencesColumns.map((name) => name === existing.name ? resolved.name : name);
+            }
+        }
+    }
+}
+function renameColumnReferences(table, oldName, newName) {
+    table.primaryKey = table.primaryKey.map((name) => (name === oldName ? newName : name));
+    for (const idx of table.indexes) {
+        idx.columns = idx.columns.map((name) => (name === oldName ? newName : name));
+    }
+    for (const constraint of table.unique) {
+        constraint.columns = constraint.columns.map((name) => (name === oldName ? newName : name));
+    }
+    for (const fk of table.foreignKeys) {
+        fk.columns = fk.columns.map((name) => (name === oldName ? newName : name));
+    }
+}
+function rebuildTableSync(kit, table, updatedTable) {
+    const db = kit.nativeDb;
+    const tempName = `__kit_tmp_rebuild_${table.name}_${Date.now()}`;
+    db.createTable(tempName, toMongrelSchema(updatedTable));
+    try {
+        const rows = fullScanRows(db, table);
+        for (const { row } of rows) {
+            db.table(tempName).put(toCells(updatedTable, row));
+        }
+        db.table(tempName).commit();
+        db.dropTable(table.name);
+        db.createTable(table.name, toMongrelSchema(updatedTable));
+        const tempRows = fullScanRows(db, { ...updatedTable, name: tempName });
+        for (const { row } of tempRows) {
+            db.table(table.name).put(toCells(updatedTable, row));
+        }
+        db.table(table.name).commit();
+    }
+    finally {
+        if (db.tableNames().includes(tempName)) {
+            db.dropTable(tempName);
+        }
+    }
+}
+function dropUniqueGuards(kit, tableName, constraintName) {
+    const handle = kit.nativeDb.table('__kit_unique_keys');
+    const guards = handle.query([
+        {
+            kind: 1 /* ConditionKind.BitmapEq */,
+            columnId: columnId(kitUniqueKeys, 'owner_table'),
+            text: tableName
+        }
+    ]);
+    let mutated = false;
+    for (const guard of guards) {
+        const constraint = guard.cells.find((c) => c.columnId === columnId(kitUniqueKeys, 'constraint_name'))?.text;
+        if (constraint !== constraintName)
+            continue;
+        const key = guard.cells.find((c) => c.columnId === columnId(kitUniqueKeys, 'encoded_key'))?.text;
+        if (!key)
+            continue;
+        handle.deleteByPkText(key);
+        mutated = true;
+    }
+    if (mutated)
+        handle.commit();
+}
+function addIndexSync(kit, tableName, index) {
+    const table = kit.schema.table(tableName);
+    if (table.indexes.some((idx) => idx.name === index.name)) {
+        throw new KitMigrationError(`Index "${index.name}" already exists on "${tableName}"`);
+    }
+    const updatedTable = {
+        ...table,
+        indexes: [...table.indexes, index]
+    };
+    const addsUnique = index.unique &&
+        !table.unique.some((constraint) => constraint.columns.join('\0') === index.columns.join('\0'));
+    if (addsUnique) {
+        addUniqueSync(kit, tableName, { name: index.name, columns: [...index.columns] });
+    }
+    try {
+        rebuildTableSync(kit, table, updatedTable);
+    }
+    catch (cause) {
+        if (addsUnique) {
+            table.unique = table.unique.filter((constraint) => constraint.name !== index.name);
+            dropUniqueGuards(kit, tableName, index.name);
+        }
+        throw cause;
+    }
+    table.indexes.push(index);
+}
+export async function addIndex(kit, tableName, index) {
+    addIndexSync(kit, tableName, index);
+}
+function dropIndexSync(kit, tableName, indexName) {
+    const table = kit.schema.table(tableName);
+    const index = table.indexes.find((idx) => idx.name === indexName);
+    if (!index) {
+        throw new KitMigrationError(`Index "${indexName}" does not exist on "${tableName}"`);
+    }
+    const updatedTable = {
+        ...table,
+        indexes: table.indexes.filter((idx) => idx.name !== indexName),
+        unique: index.unique ? table.unique.filter((constraint) => constraint.name !== indexName) : table.unique
+    };
+    rebuildTableSync(kit, table, updatedTable);
+    table.indexes = updatedTable.indexes;
+    if (index.unique) {
+        table.unique = updatedTable.unique;
+        dropUniqueGuards(kit, tableName, indexName);
+    }
+}
+export async function dropIndex(kit, tableName, indexName) {
+    dropIndexSync(kit, tableName, indexName);
+}
+function dropColumnSync(kit, tableName, columnName) {
+    const table = kit.schema.table(tableName);
+    if (!table.columns.some((column) => column.name === columnName)) {
+        throw new KitMigrationError(`Column "${columnName}" does not exist on "${tableName}"`);
+    }
+    if (table.primaryKey.includes(columnName)) {
+        throw new KitMigrationError(`Cannot drop primary-key column "${columnName}" from "${tableName}"`);
+    }
+    for (const candidate of kit.schema.tablesList()) {
+        for (const fk of candidate.foreignKeys) {
+            if (fk.referencesTable === tableName && fk.referencesColumns.includes(columnName)) {
+                throw new KitMigrationError(`Cannot drop "${tableName}"."${columnName}" while foreign key "${fk.name}" references it`);
+            }
+        }
+    }
+    const removedUnique = table.unique
+        .filter((constraint) => constraint.columns.includes(columnName))
+        .map((constraint) => constraint.name);
+    const updatedTable = {
+        ...table,
+        columns: table.columns.filter((column) => column.name !== columnName),
+        indexes: table.indexes.filter((idx) => !idx.columns.includes(columnName)),
+        unique: table.unique.filter((constraint) => !constraint.columns.includes(columnName)),
+        foreignKeys: table.foreignKeys.filter((fk) => !fk.columns.includes(columnName))
+    };
+    rebuildTableSync(kit, table, updatedTable);
+    table.columns = updatedTable.columns;
+    table.indexes = updatedTable.indexes;
+    table.unique = updatedTable.unique;
+    table.foreignKeys = updatedTable.foreignKeys;
+    for (const constraint of removedUnique) {
+        dropUniqueGuards(kit, tableName, constraint);
+    }
+}
+export async function dropColumn(kit, tableName, columnName) {
+    dropColumnSync(kit, tableName, columnName);
+}
+/**
+ * Add a unique constraint and backfill its `__kit_unique_keys` guards for every
+ * existing row (PLAN "Migrations"). Rows whose unique columns are all non-null
+ * reserve a guard; a guard key produced by two different rows means the existing
+ * data already violates the constraint and the migration is rejected. The
+ * constraint is added to the in-memory table so subsequent writes enforce it.
+ */
+function addUniqueSync(kit, tableName, unique) {
+    const db = kit.nativeDb;
+    const table = kit.schema.table(tableName);
+    if (table.unique.some((u) => u.name === unique.name)) {
+        throw new KitMigrationError(`Unique constraint "${unique.name}" already exists on "${tableName}"`);
+    }
+    for (const colName of unique.columns) {
+        if (!table.columns.some((c) => c.name === colName)) {
+            throw new KitMigrationError(`Unique column "${colName}" not found in table "${tableName}"`);
+        }
+    }
+    const ukHandle = db.table('__kit_unique_keys');
+    // Pre-existing guards for this table make the backfill idempotent.
+    const existingKeys = new Set();
+    for (const guard of ukHandle.query([
+        { kind: 1 /* ConditionKind.BitmapEq */, columnId: columnId(kitUniqueKeys, 'owner_table'), text: tableName }
+    ])) {
+        const key = guard.cells.find((c) => c.columnId === columnId(kitUniqueKeys, 'encoded_key'))?.text;
+        if (key)
+            existingKeys.add(key);
+    }
+    const seen = new Map();
+    const now = isoNow();
+    let mutated = false;
+    for (const { row } of fullScanRows(db, table)) {
+        const values = unique.columns.map((colName) => row[colName] === undefined ? null : row[colName]);
+        if (values.some((value) => value === null))
+            continue; // nullable-unique: nulls never collide
+        const encodedKey = encodeUniqueKey(KIT_KEY_VERSION, unique.name, values);
+        const ownerPk = encodedPk(pkValueFromRow(table, row));
+        const prior = seen.get(encodedKey);
+        if (prior !== undefined && prior !== ownerPk) {
+            throw new KitMigrationError(`cannot add unique constraint "${unique.name}" on "${tableName}": existing rows violate it`);
+        }
+        seen.set(encodedKey, ownerPk);
+        if (existingKeys.has(encodedKey))
+            continue;
+        ukHandle.put([
+            { columnId: columnId(kitUniqueKeys, 'encoded_key'), text: encodedKey },
+            { columnId: columnId(kitUniqueKeys, 'constraint_name'), text: unique.name },
+            { columnId: columnId(kitUniqueKeys, 'owner_table'), text: tableName },
+            { columnId: columnId(kitUniqueKeys, 'owner_pk'), text: ownerPk },
+            { columnId: columnId(kitUniqueKeys, 'created_at'), text: now }
+        ]);
+        mutated = true;
+    }
+    if (mutated)
+        ukHandle.commit();
+    table.unique.push(unique);
+}
+export async function addUnique(kit, tableName, unique) {
+    addUniqueSync(kit, tableName, unique);
+}
+/** Build the parent primary-key value referenced by a foreign key. */
+function buildFkParentPk(parent, fkValues) {
+    if (parent.primaryKey.length === 1) {
+        const value = fkValues[0];
+        if (typeof value !== 'string' && typeof value !== 'bigint') {
+            throw new KitMigrationError('Foreign key value must be string or bigint');
+        }
+        return value;
+    }
+    return fkValues.map((value) => {
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value !== 'string' && typeof value !== 'bigint') {
+            throw new KitMigrationError('Foreign key value must be string, bigint, or null');
+        }
+        return value;
+    });
+}
+/**
+ * Add a foreign key and backfill parent `__kit_row_guards` (PLAN "Migrations").
+ * Each existing child row with a non-null FK must reference an existing parent;
+ * a missing parent rejects the migration. The referenced parent's row guard is
+ * touched so a later concurrent parent delete conflicts. The FK is added to the
+ * in-memory table so subsequent writes enforce it.
+ */
+export async function addForeignKey(kit, tableName, fk) {
+    const db = kit.nativeDb;
+    const table = kit.schema.table(tableName);
+    const parent = kit.schema.table(fk.referencesTable);
+    if (table.foreignKeys.some((f) => f.name === fk.name)) {
+        throw new KitMigrationError(`Foreign key "${fk.name}" already exists on "${tableName}"`);
+    }
+    const ckit = { db, schema: kit.schema };
+    const rgHandle = db.table('__kit_row_guards');
+    const touched = new Set();
+    let mutated = false;
+    for (const { row } of fullScanRows(db, table)) {
+        const fkValues = fk.columns.map((colName) => row[colName]);
+        if (fkValues.some((value) => value === null || value === undefined))
+            continue;
+        const parentPk = buildFkParentPk(parent, fkValues);
+        if (!parentExists(ckit, parent.name, parentPk)) {
+            throw new KitForeignKeyError(tableName, fk.name);
+        }
+        const guardKey = encodeRowGuardKey(parent.name, parentPk);
+        if (touched.has(guardKey))
+            continue;
+        touched.add(guardKey);
+        const existing = rgHandle.getByPkText(guardKey);
+        const version = existing
+            ? (existing.cells.find((c) => c.columnId === columnId(kitRowGuards, 'version'))?.int64 ??
+                0n) + 1n
+            : 1n;
+        rgHandle.put([
+            { columnId: columnId(kitRowGuards, 'encoded_guard_key'), text: guardKey },
+            { columnId: columnId(kitRowGuards, 'table_name'), text: parent.name },
+            { columnId: columnId(kitRowGuards, 'primary_key'), text: encodedPk(parentPk) },
+            { columnId: columnId(kitRowGuards, 'version'), int64: version },
+            { columnId: columnId(kitRowGuards, 'updated_at'), text: isoNow() }
+        ]);
+        mutated = true;
+    }
+    if (mutated)
+        rgHandle.commit();
+    table.foreignKeys.push(fk);
+}
+//# sourceMappingURL=migrate.js.map