turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/cli/migrate.d.ts

@@ -0,0 +1,356 @@
+/**
+ * turbine-orm CLI — Migration system
+ *
+ * SQL-first migrations with UP/DOWN sections, tracked in _turbine_migrations.
+ * Migration files are timestamp-prefixed .sql files.
+ *
+ * File format:
+ *   -- UP
+ *   CREATE TABLE users (...);
+ *
+ *   -- DOWN
+ *   DROP TABLE users;
+ */
+import pg from 'pg';
+import type { DatabaseAdapter } from '../adapters/index.js';
+import { type Dialect } from '../dialect.js';
+import { type DestructiveStatement } from './destructive.js';
+export interface MigrationFile {
+    /** Full filename (e.g. "20260325120000_create_users.sql") */
+    filename: string;
+    /** Absolute path to the file */
+    path: string;
+    /** Extracted name portion (e.g. "20260325120000_create_users") */
+    name: string;
+    /** Timestamp prefix (e.g. "20260325120000") — YYYYMMDDHHMMSS */
+    timestamp: string;
+}
+export interface AppliedMigration {
+    id: number;
+    name: string;
+    applied_at: Date;
+    checksum: string;
+}
+export interface MigrationStatus {
+    file: MigrationFile;
+    applied: boolean;
+    appliedAt?: Date;
+    /** True if the file checksum matches the stored checksum (only set for applied migrations) */
+    checksumValid?: boolean;
+    /** True when the migration was applied but its file is missing from disk. */
+    missingFile?: boolean;
+}
+/** A pending migration whose UP section contains data-destroying statements. */
+export interface DestructiveOffender {
+    file: string;
+    hits: DestructiveStatement[];
+}
+/**
+ * A migration that was applied even though an already-applied migration carries
+ * a newer timestamp prefix, i.e. history was written out of order.
+ */
+export interface OutOfOrderApply {
+    /** The out-of-order migration that was just applied. */
+    applied: string;
+    /** The newest previously-applied migration it landed behind. */
+    newestPrior: string;
+}
+export interface MigrationRunResult {
+    applied: MigrationFile[];
+    errors: Array<{
+        file: MigrationFile;
+        error: string;
+    }>;
+    /**
+     * Destructive statements found in the pending batch. Populated whether or not
+     * the run was allowed to proceed, so a caller (deploy) can print a notice even
+     * when it applies them by design.
+     */
+    destructive: DestructiveOffender[];
+    /** Migrations applied with a timestamp older than an already-applied one. */
+    outOfOrder: OutOfOrderApply[];
+    /**
+     * Migrations applied WITHOUT a transaction (they carried the
+     * `-- turbine:no-transaction` directive). The CLI prints a loud notice for
+     * each: a mid-file failure leaves earlier statements applied and the migration
+     * unrecorded, so every statement in one of these must be idempotent.
+     */
+    noTransaction: MigrationFile[];
+}
+/** Extract the YYYYMMDDHHMMSS timestamp prefix from a migration name, or null. */
+export declare function migrationTimestamp(name: string): string | null;
+/** Scan a set of migration files' UP sections for data-destroying statements. */
+export declare function collectUpDestructive(files: MigrationFile[]): DestructiveOffender[];
+/**
+ * Parse a migration filename into its components.
+ * Expected format: YYYYMMDDHHMMSS_description.sql
+ */
+export declare function parseMigrationFilename(filename: string): MigrationFile | null;
+/**
+ * Sanitize a migration name: lowercase, replace non-alnum with _, collapse duplicates, trim.
+ */
+export declare function sanitizeName(name: string): string;
+/**
+ * Generate a YYYYMMDDHHMMSS timestamp string from a Date.
+ */
+export declare function formatTimestamp(date: Date): string;
+/**
+ * Get pending migration files — those not yet applied.
+ * Returns files sorted by timestamp (ascending).
+ */
+export declare function getPendingMigrations(migrationsDir: string, applied: string[]): MigrationFile[];
+/**
+ * List all migration files in the migrations directory, sorted by name.
+ */
+export declare function listMigrationFiles(migrationsDir: string): MigrationFile[];
+/** The parsed sections of a migration file plus its execution directives. */
+export interface ParsedMigration {
+    up: string;
+    down: string;
+    /** True when the `-- turbine:no-transaction` directive is present in the header. */
+    noTransaction: boolean;
+}
+/**
+ * Parse migration content string into UP and DOWN sections plus directives.
+ * Exported for unit testing.
+ */
+export declare function parseMigrationContent(content: string): ParsedMigration;
+/**
+ * Split a SQL script into individual statements on top-level semicolons.
+ *
+ * A correct tokenizer, not a `split(';')`: a semicolon inside a single-quoted
+ * string (including a backslash-escaping `E'...'` string), a double-quoted
+ * identifier, a dollar-quoted body, a line comment
+ * (`--`), or a block comment (`/* *\/`, which Postgres allows to nest) must NOT
+ * split. This is the one production-destroying failure mode of no-transaction
+ * migrations (a partial statement executed against production), so the behavior
+ * is pinned by exhaustive unit tests.
+ *
+ * Comment-only fragments are dropped; every returned statement is trimmed and
+ * carries no trailing semicolon.
+ */
+export declare function splitSqlStatements(sql: string): string[];
+/**
+ * Parse a migration file into UP and DOWN sections.
+ */
+export declare function parseMigrationSQL(filePath: string): ParsedMigration;
+/**
+ * Can a stored pre-v0.6 checksum be safely upgraded to SHA-256?
+ *
+ * Only when the LEGACY algorithm, run over the file's CURRENT content,
+ * reproduces the stored value: that is what proves the file has not changed
+ * since it was applied. Upgrading without this proof blesses whatever the file
+ * says today and permanently disables drift detection for that migration.
+ *
+ * @internal exported for tests.
+ */
+export declare function canUpgradeLegacyChecksum(stored: string, content: string): boolean;
+/**
+ * Is an applied migration's stored checksum still valid for the file on disk?
+ *
+ * A SHA-256 match is the normal case. A pre-v0.6 row that {@link
+ * canUpgradeLegacyChecksum} would upgrade counts as valid too: `migrate up`
+ * accepts and upgrades it, so reporting it as invalid in `migrate status` would
+ * have the two commands disagree about the same unchanged file. Genuine drift
+ * (a legacy hash the current content no longer reproduces) still reports false.
+ *
+ * @internal exported for tests.
+ */
+export declare function isChecksumValid(stored: string, content: string): boolean;
+/**
+ * A named migration scaffold. `build()` returns the commented-SQL UP/DOWN body
+ * for the recipe; `createMigration({ recipe })` wraps it in the file header.
+ */
+export interface MigrationRecipe {
+    /** One-line description shown in CLI help. */
+    description: string;
+    /** Build the UP/DOWN body (commented scaffold with placeholders). */
+    build(name: string): {
+        up: string;
+        down: string;
+    };
+}
+/**
+ * Registry of migration recipes, keyed by `--recipe <name>`. New recipes slot
+ * in here without touching {@link createMigration} or the CLI handler.
+ */
+export declare const MIGRATION_RECIPES: Record<string, MigrationRecipe>;
+/**
+ * The UP/DOWN body produced by {@link buildDiffMigrationBody}, plus the
+ * destructive statements found in each direction so the CLI can warn loudly.
+ */
+export interface DiffMigrationBody {
+    /** Annotated UP SQL (destructive statements flagged with loud comments). */
+    up: string;
+    /** Annotated DOWN SQL, or an irreversible placeholder when none is derivable. */
+    down: string;
+    /** Destructive statements detected in the UP direction. */
+    destructiveUp: DestructiveStatement[];
+    /** Destructive statements detected in the DOWN direction. */
+    destructiveDown: DestructiveStatement[];
+}
+/**
+ * Build a migration UP/DOWN body from a `schemaDiff()` result.
+ *
+ * - UP is the diff's forward statements. DOWN is the diff's reverse statements
+ *   when derivable, otherwise a clearly-commented "irreversible" placeholder.
+ * - Destructive statements in EITHER direction (a lossy `ALTER COLUMN ... TYPE`
+ *   in UP, a `DROP TABLE`/`DROP COLUMN` reverse in DOWN) are flagged inline and,
+ *   when any exist, a loud file-level banner is prepended to UP.
+ * - Any diff `warnings` (changes the diff refuses to apply automatically, e.g.
+ *   enum value removals) are surfaced as `-- NOTE:` comments in UP.
+ *
+ * Pure and DB-free, so it is unit-testable from a synthesized diff.
+ */
+export declare function buildDiffMigrationBody(diff: {
+    statements: string[];
+    reverseStatements: string[];
+    warnings?: string[];
+}): DiffMigrationBody;
+/**
+ * Create a new migration file.
+ *
+ * - `autoContent`: pre-populate UP/DOWN from a schema diff.
+ * - `options.recipe`: scaffold a named recipe (see {@link MIGRATION_RECIPES}).
+ *   Mutually exclusive with `autoContent`; an unknown recipe throws.
+ * - `options.header`: extra header line(s) injected BEFORE `-- UP` (the only
+ *   place a `-- turbine:no-transaction` directive is honored). Used with
+ *   `autoContent`.
+ */
+export declare function createMigration(migrationsDir: string, name: string, autoContent?: {
+    up: string;
+    down: string;
+}, options?: {
+    recipe?: string;
+    header?: string;
+}): MigrationFile;
+/**
+ * Derive a Postgres advisory lock ID (positive int4) from the database name.
+ *
+ * Uses FNV-1a 32-bit hash — a well-known, stable, non-cryptographic hash with
+ * excellent distribution over short strings (database names are typically <64
+ * chars). Chosen over alternatives because it's:
+ *   - deterministic (same input → same output, across processes/machines)
+ *   - tiny (two lines, no allocations, no imports)
+ *   - well-distributed (low collision rate for typical DB-name distributions)
+ *
+ * The top bit is cleared so the result fits in a positive int4, which is the
+ * range `pg_advisory_lock` expects for the single-argument form. Two databases
+ * in the same Postgres cluster can now run `turbine migrate` concurrently
+ * without contending on a single hardcoded lock ID.
+ */
+export declare function deriveLockId(databaseName: string): number;
+/**
+ * The minimal query surface a transactional migration body needs.
+ * `pg.Client` satisfies it; tests supply a fake.
+ */
+export interface MigrationTxClient {
+    query(sql: string, params?: unknown[]): Promise<unknown>;
+}
+/**
+ * Run one migration body (UP or DOWN) plus its tracking-table write inside a
+ * single transaction. Returns `null` on success, or the error message on
+ * failure, leaving the caller to record it and stop.
+ *
+ * The ROLLBACK is best-effort: if the connection died, ROLLBACK throws too, and
+ * letting that escape would replace the real migration failure with a
+ * connection error. Same guard as `client.ts`, `query/builder.ts`, `dialect.ts`.
+ *
+ * @internal exported for tests; not part of the CLI's public surface.
+ */
+export declare function runMigrationInTransaction(client: MigrationTxClient, body: string, tracking: {
+    sql: string;
+    params: unknown[];
+}): Promise<string | null>;
+export interface ChecksumMismatch {
+    name: string;
+    expected: string;
+    actual: string;
+    /** 'modified' if file changed, 'missing' if file deleted */
+    type: 'modified' | 'missing';
+}
+export interface MigrationDeployPlan {
+    pending: MigrationFile[];
+    mismatches: ChecksumMismatch[];
+}
+/**
+ * Validate that applied migration files have not been modified or deleted since they were run.
+ * Returns an array of mismatched migrations (empty if all are clean).
+ *
+ * @internal exported for tests; not part of the CLI's public surface.
+ */
+export declare function validateChecksums(client: pg.Client, migrationsDir: string, dialect?: Dialect): Promise<ChecksumMismatch[]>;
+export declare function formatChecksumMismatchError(mismatches: ChecksumMismatch[]): string;
+/**
+ * Build a deploy plan from local migration files and applied migration rows.
+ * This is pure file-system planning; callers with a database connection should
+ * use `inspectMigrationDeploy()` to preserve legacy checksum upgrades.
+ */
+export declare function planMigrationDeploy(migrationsDir: string, applied: AppliedMigration[]): MigrationDeployPlan;
+/**
+ * Inspect deploy status without applying migrations.
+ */
+export declare function inspectMigrationDeploy(connectionString: string, migrationsDir: string): Promise<MigrationDeployPlan>;
+/**
+ * Apply all pending migrations (UP).
+ *
+ * Features:
+ * - Idempotent: running twice is safe (already-applied migrations are skipped)
+ * - Advisory lock: prevents concurrent migration runs
+ * - Checksum validation: detects modified migration files (BLOCKING — use
+ *   `allowDrift: true` to bypass when intentionally rewriting history)
+ * - Each migration runs in its own transaction
+ *
+ * Throws `MigrationError` if any applied migration has been modified or deleted
+ * on disk, listing the offending files. Pass `{ allowDrift: true }` to bypass
+ * this check (the CLI exposes this as `--allow-drift`).
+ */
+export declare function migrateUp(connectionString: string, migrationsDir: string, options?: {
+    step?: number;
+    allowDrift?: boolean;
+    force?: boolean /** @deprecated use allowDrift */;
+    /** Run migrations even when they contain data-destroying statements. Default false. */
+    allowDestructive?: boolean;
+    adapter?: DatabaseAdapter;
+    /**
+     * Called right before a `-- turbine:no-transaction` migration runs, so the
+     * CLI can print its loud pre-run notice (a concurrent index build can wait a
+     * long time on other transactions and otherwise looks hung).
+     */
+    onNoTransaction?: (file: MigrationFile) => void;
+}): Promise<MigrationRunResult>;
+/**
+ * Production migration apply. This intentionally applies files as written and
+ * never performs interactive destructive confirmation.
+ */
+export declare function migrateDeploy(connectionString: string, migrationsDir: string, options?: {
+    adapter?: DatabaseAdapter;
+    allowDrift?: boolean;
+}): Promise<MigrationRunResult>;
+/**
+ * Rollback the last N migrations (DOWN).
+ *
+ * Features:
+ * - Advisory lock: prevents concurrent rollback runs
+ * - Each rollback runs in its own transaction
+ * - Properly reverses changes in reverse application order
+ */
+export declare function migrateDown(connectionString: string, migrationsDir: string, options?: {
+    step?: number;
+    allowDestructive?: boolean;
+    adapter?: DatabaseAdapter;
+}): Promise<{
+    rolledBack: MigrationFile[];
+    errors: Array<{
+        file: MigrationFile;
+        error: string;
+    }>;
+}>;
+/**
+ * Get the status of all migrations (applied vs pending).
+ *
+ * Applied rows carry `checksumValid`, decided by {@link isChecksumValid} so an
+ * unchanged pre-v0.6 row reports the same way `migrate up` treats it (valid,
+ * pending an in-place hash upgrade) rather than looking like drift.
+ */
+export declare function migrateStatus(connectionString: string, migrationsDir: string): Promise<MigrationStatus[]>;

package/dist/cjs/cli/migrate.js

@@ -27,9 +27,13 @@ exports.listMigrationFiles = listMigrationFiles;
 exports.parseMigrationContent = parseMigrationContent;
 exports.splitSqlStatements = splitSqlStatements;
 exports.parseMigrationSQL = parseMigrationSQL;
+exports.canUpgradeLegacyChecksum = canUpgradeLegacyChecksum;
+exports.isChecksumValid = isChecksumValid;
 exports.buildDiffMigrationBody = buildDiffMigrationBody;
 exports.createMigration = createMigration;
 exports.deriveLockId = deriveLockId;
+exports.runMigrationInTransaction = runMigrationInTransaction;
+exports.validateChecksums = validateChecksums;
 exports.formatChecksumMismatchError = formatChecksumMismatchError;
 exports.planMigrationDeploy = planMigrationDeploy;
 exports.inspectMigrationDeploy = inspectMigrationDeploy;
@@ -67,6 +71,20 @@ function collectUpDestructive(files) {
 // Tracking table management
 // ---------------------------------------------------------------------------
 const TRACKING_TABLE = '_turbine_migrations';
+/**
+ * The dialect the migration runner speaks.
+ *
+ * The runner connects with `pg.Client`, so Postgres (and the Postgres-compatible
+ * engines behind `adapters/`) is the only thing it can actually reach. The
+ * dialect is still threaded through every tracking-table statement, so making
+ * migrations dialect-aware is a matter of teaching this layer to build the
+ * engine's own client. Until then there is deliberately NO caller-supplied
+ * dialect option: accepting one would advertise sqlite/mysql/mssql migrations
+ * that silently run their SQL against Postgres.
+ */
+function migrationDialect() {
+    return dialect_js_1.postgresDialect;
+}
 function quotedTrackingTable(dialect) {
     return dialect.quoteIdentifier(TRACKING_TABLE);
 }
@@ -368,9 +386,53 @@ function parseMigrationSQL(filePath) {
 function checksum(content) {
     return (0, node_crypto_1.createHash)('sha256').update(content, 'utf-8').digest('hex');
 }
-/** Detect legacy djb2 checksums (short alphanumeric strings, pre-v0.6) */
+/**
+ * The pre-v0.6 checksum algorithm (a 32-bit rolling hash rendered as base36).
+ * Kept verbatim so a legacy stored value can be RE-DERIVED from the current
+ * file content before we upgrade the row to SHA-256. Never used for new rows.
+ */
+function legacyChecksum(content) {
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        const chr = content.charCodeAt(i);
+        hash = ((hash << 5) - hash + chr) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Detect legacy checksums (short alphanumeric strings, pre-v0.6).
+ * An EMPTY checksum is never legacy: blessing it would silently disarm drift
+ * detection for a row whose stored hash was lost or never written.
+ */
 function isLegacyChecksum(hash) {
-    return hash.length < 64;
+    return hash.length > 0 && hash.length < 64;
+}
+/**
+ * Can a stored pre-v0.6 checksum be safely upgraded to SHA-256?
+ *
+ * Only when the LEGACY algorithm, run over the file's CURRENT content,
+ * reproduces the stored value: that is what proves the file has not changed
+ * since it was applied. Upgrading without this proof blesses whatever the file
+ * says today and permanently disables drift detection for that migration.
+ *
+ * @internal exported for tests.
+ */
+function canUpgradeLegacyChecksum(stored, content) {
+    return isLegacyChecksum(stored) && legacyChecksum(content) === stored;
+}
+/**
+ * Is an applied migration's stored checksum still valid for the file on disk?
+ *
+ * A SHA-256 match is the normal case. A pre-v0.6 row that {@link
+ * canUpgradeLegacyChecksum} would upgrade counts as valid too: `migrate up`
+ * accepts and upgrades it, so reporting it as invalid in `migrate status` would
+ * have the two commands disagree about the same unchanged file. Genuine drift
+ * (a legacy hash the current content no longer reproduces) still reports false.
+ *
+ * @internal exported for tests.
+ */
+function isChecksumValid(stored, content) {
+    return checksum(content) === stored || canUpgradeLegacyChecksum(stored, content);
 }
 /** The sanctioned two-phase (add nullable, batched backfill, swap) recipe. */
 function buildBackfillRecipe() {
@@ -618,9 +680,40 @@ async function releaseLock(client, lockId, adapter) {
     const a = adapter ?? index_js_1.postgresql;
     await a.releaseLock(client, lockId);
 }
+/**
+ * Run one migration body (UP or DOWN) plus its tracking-table write inside a
+ * single transaction. Returns `null` on success, or the error message on
+ * failure, leaving the caller to record it and stop.
+ *
+ * The ROLLBACK is best-effort: if the connection died, ROLLBACK throws too, and
+ * letting that escape would replace the real migration failure with a
+ * connection error. Same guard as `client.ts`, `query/builder.ts`, `dialect.ts`.
+ *
+ * @internal exported for tests; not part of the CLI's public surface.
+ */
+async function runMigrationInTransaction(client, body, tracking) {
+    try {
+        await client.query('BEGIN');
+        await client.query(body);
+        await client.query(tracking.sql, tracking.params);
+        await client.query('COMMIT');
+        return null;
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            // Best effort: the original error below is what the user needs to see.
+        }
+        return err instanceof Error ? err.message : String(err);
+    }
+}
 /**
  * Validate that applied migration files have not been modified or deleted since they were run.
  * Returns an array of mismatched migrations (empty if all are clean).
+ *
+ * @internal exported for tests; not part of the CLI's public surface.
  */
 async function validateChecksums(client, migrationsDir, dialect = dialect_js_1.postgresDialect) {
     const applied = await getAppliedMigrations(client, dialect);
@@ -641,8 +734,11 @@ async function validateChecksums(client, migrationsDir, dialect = dialect_js_1.p
         const content = (0, node_fs_1.readFileSync)(file.path, 'utf-8');
         const currentHash = checksum(content);
         if (currentHash !== migration.checksum) {
-            // Auto-upgrade legacy djb2 checksums to SHA-256 without flagging as modified
-            if (isLegacyChecksum(migration.checksum)) {
+            // Auto-upgrade a pre-v0.6 checksum to SHA-256 without flagging it as
+            // modified, but ONLY when the legacy hash of the current content still
+            // matches what was stored. A legacy row whose file HAS changed falls
+            // through to the mismatch path below (bypassable with --allow-drift).
+            if (canUpgradeLegacyChecksum(migration.checksum, content)) {
                 await client.query(dialect.buildMigrationUpdateChecksum(quotedTrackingTable(dialect)), [
                     currentHash,
                     migration.name,
@@ -709,8 +805,11 @@ function planMigrationDeploy(migrationsDir, applied) {
             });
             continue;
         }
-        const currentHash = checksum((0, node_fs_1.readFileSync)(file.path, 'utf-8'));
-        if (currentHash !== migration.checksum && !isLegacyChecksum(migration.checksum)) {
+        const content = (0, node_fs_1.readFileSync)(file.path, 'utf-8');
+        const currentHash = checksum(content);
+        // A pre-v0.6 checksum is only forgiven when the legacy algorithm over the
+        // current content still reproduces it: otherwise the file really has drifted.
+        if (currentHash !== migration.checksum && !canUpgradeLegacyChecksum(migration.checksum, content)) {
             mismatches.push({
                 name: migration.name,
                 expected: migration.checksum,
@@ -727,10 +826,10 @@ function planMigrationDeploy(migrationsDir, applied) {
 /**
  * Inspect deploy status without applying migrations.
  */
-async function inspectMigrationDeploy(connectionString, migrationsDir, options) {
+async function inspectMigrationDeploy(connectionString, migrationsDir) {
     const client = new pg_1.default.Client({ connectionString });
     await client.connect();
-    const dialect = options?.dialect ?? dialect_js_1.postgresDialect;
+    const dialect = migrationDialect();
     try {
         await ensureTrackingTable(client, dialect);
         const mismatches = await validateChecksums(client, migrationsDir, dialect);
@@ -764,7 +863,7 @@ async function migrateUp(connectionString, migrationsDir, options) {
     await client.connect();
     // Treat `force` as an alias for `allowDrift` for backwards compatibility.
     const allowDrift = options?.allowDrift === true || options?.force === true;
-    const dialect = options?.dialect ?? dialect_js_1.postgresDialect;
+    const dialect = migrationDialect();
     try {
         // Derive an advisory lock ID per-database so concurrent migrations in
         // sibling databases on the same Postgres cluster do not contend.
@@ -871,21 +970,17 @@ async function migrateUp(connectionString, migrationsDir, options) {
                     }
                     continue;
                 }
-                try {
-                    await client.query('BEGIN');
-                    await client.query(up);
-                    await client.query(insertApplied, [file.name, hash]);
-                    await client.query('COMMIT');
-                    results.push(file);
-                    flagOutOfOrder(file);
-                }
-                catch (err) {
-                    await client.query('ROLLBACK');
-                    const msg = err instanceof Error ? err.message : String(err);
-                    errors.push({ file, error: msg });
+                const failure = await runMigrationInTransaction(client, up, {
+                    sql: insertApplied,
+                    params: [file.name, hash],
+                });
+                if (failure !== null) {
+                    errors.push({ file, error: failure });
                     // Stop on first error
                     break;
                 }
+                results.push(file);
+                flagOutOfOrder(file);
             }
             return { applied: results, errors, destructive, outOfOrder, noTransaction: noTransactionApplied };
         }
@@ -908,7 +1003,6 @@ async function migrateDeploy(connectionString, migrationsDir, options) {
         allowDrift: options?.allowDrift === true,
         allowDestructive: true,
         adapter: options?.adapter,
-        dialect: options?.dialect,
     });
 }
 /**
@@ -922,7 +1016,7 @@ async function migrateDeploy(connectionString, migrationsDir, options) {
 async function migrateDown(connectionString, migrationsDir, options) {
     const client = new pg_1.default.Client({ connectionString });
     await client.connect();
-    const dialect = options?.dialect ?? dialect_js_1.postgresDialect;
+    const dialect = migrationDialect();
     try {
         // Derive a per-database advisory lock ID so concurrent migrations in
         // sibling databases on the same cluster do not contend.
@@ -1008,19 +1102,15 @@ async function migrateDown(connectionString, migrationsDir, options) {
                     }
                     continue;
                 }
-                try {
-                    await client.query('BEGIN');
-                    await client.query(down);
-                    await client.query(deleteApplied, [migration.name]);
-                    await client.query('COMMIT');
-                    results.push(file);
-                }
-                catch (err) {
-                    await client.query('ROLLBACK');
-                    const msg = err instanceof Error ? err.message : String(err);
-                    errors.push({ file, error: msg });
+                const failure = await runMigrationInTransaction(client, down, {
+                    sql: deleteApplied,
+                    params: [migration.name],
+                });
+                if (failure !== null) {
+                    errors.push({ file, error: failure });
                     break;
                 }
+                results.push(file);
             }
             return { rolledBack: results, errors };
         }
@@ -1034,12 +1124,15 @@ async function migrateDown(connectionString, migrationsDir, options) {
 }
 /**
  * Get the status of all migrations (applied vs pending).
- * Includes checksum validation for applied migrations.
+ *
+ * Applied rows carry `checksumValid`, decided by {@link isChecksumValid} so an
+ * unchanged pre-v0.6 row reports the same way `migrate up` treats it (valid,
+ * pending an in-place hash upgrade) rather than looking like drift.
  */
-async function migrateStatus(connectionString, migrationsDir, options) {
+async function migrateStatus(connectionString, migrationsDir) {
     const client = new pg_1.default.Client({ connectionString });
     await client.connect();
-    const dialect = options?.dialect ?? dialect_js_1.postgresDialect;
+    const dialect = migrationDialect();
     try {
         await ensureTrackingTable(client, dialect);
         const applied = await getAppliedMigrations(client, dialect);
@@ -1050,9 +1143,7 @@ async function migrateStatus(connectionString, migrationsDir, options) {
             const record = appliedMap.get(file.name);
             let checksumValid;
             if (record) {
-                const content = (0, node_fs_1.readFileSync)(file.path, 'utf-8');
-                const currentHash = checksum(content);
-                checksumValid = currentHash === record.checksum;
+                checksumValid = isChecksumValid(record.checksum, (0, node_fs_1.readFileSync)(file.path, 'utf-8'));
             }
             return {
                 file,

package/dist/cjs/cli/observe-ui.d.ts

@@ -0,0 +1 @@
+export declare const OBSERVE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n  <meta name=\"color-scheme\" content=\"dark\" />\n  <title>Turbine Observe</title>\n  <style>\n    :root {\n      --bg: #0a0a0b;\n      --bg-elev: #111113;\n      --bg-hover: #1a1a1d;\n      --border: #26262b;\n      --text: #e6e6ea;\n      --text-dim: #8a8a93;\n      --accent: #60a5fa;\n      --green: #4ade80;\n      --red: #f87171;\n      --orange: #fb923c;\n      --purple: #a78bfa;\n      --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n      --sans: system-ui, -apple-system, sans-serif;\n      --radius: 6px;\n    }\n    * { margin: 0; padding: 0; box-sizing: border-box; }\n    body { background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; padding: 24px; }\n    h1 { font-size: 20px; margin-bottom: 4px; }\n    .subtitle { color: var(--text-dim); margin-bottom: 24px; }\n    .controls { display: flex; gap: 8px; margin-bottom: 24px; }\n    .controls button {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      color: var(--text); padding: 6px 12px; cursor: pointer; font-size: 13px;\n    }\n    .controls button.active { border-color: var(--accent); color: var(--accent); }\n    .card {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      padding: 16px; margin-bottom: 16px;\n    }\n    .card h2 { font-size: 14px; color: var(--text-dim); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.5px; }\n    table { width: 100%; border-collapse: collapse; font-family: var(--mono); font-size: 12px; }\n    th { text-align: left; padding: 6px 8px; color: var(--text-dim); border-bottom: 1px solid var(--border); }\n    td { padding: 6px 8px; border-bottom: 1px solid var(--border); }\n    .num { text-align: right; }\n    .error-rate { color: var(--red); }\n    .low-error { color: var(--green); }\n    svg { width: 100%; height: 200px; }\n    .chart-line { fill: none; stroke-width: 1.5; }\n    .line-avg { stroke: var(--accent); }\n    .line-p95 { stroke: var(--orange); }\n    .line-p99 { stroke: var(--red); }\n    .legend { display: flex; gap: 16px; margin-top: 8px; font-size: 12px; color: var(--text-dim); }\n    .legend span::before { content: ''; display: inline-block; width: 12px; height: 2px; margin-right: 4px; vertical-align: middle; }\n    .legend .l-avg::before { background: var(--accent); }\n    .legend .l-p95::before { background: var(--orange); }\n    .legend .l-p99::before { background: var(--red); }\n    .empty { color: var(--text-dim); text-align: center; padding: 40px; }\n  </style>\n</head>\n<body>\n  <h1>Turbine Observe</h1>\n  <p class=\"subtitle\">Query performance metrics</p>\n  <div class=\"controls\">\n    <button data-range=\"1h\" class=\"active\">1h</button>\n    <button data-range=\"6h\">6h</button>\n    <button data-range=\"24h\">24h</button>\n    <button data-range=\"7d\">7d</button>\n  </div>\n  <div class=\"card\" id=\"latency-card\">\n    <h2>Latency over time</h2>\n    <div id=\"chart\"></div>\n    <div class=\"legend\">\n      <span class=\"l-avg\">avg</span>\n      <span class=\"l-p95\">p95</span>\n      <span class=\"l-p99\">p99</span>\n    </div>\n  </div>\n  <div class=\"card\" id=\"models-card\">\n    <h2>Top models</h2>\n    <div id=\"models-table\"></div>\n  </div>\n  <div class=\"card\" id=\"errors-card\">\n    <h2>Error rates</h2>\n    <div id=\"errors-table\"></div>\n  </div>\n  <script nonce=\"__CSP_NONCE__\">\n    let currentRange = '1h';\n    // Anchored on a cookie boundary so a decoy cookie whose name ends with this\n    // one cannot shadow the real token.\n    const token = document.cookie.match(/(?:^|;\\s*)turbine_observe_token=([a-f0-9]+)/)?.[1] || '';\n    const headers = { 'x-turbine-token': token };\n\n    document.querySelector('.controls').addEventListener('click', e => {\n      if (e.target.tagName !== 'BUTTON') return;\n      document.querySelectorAll('.controls button').forEach(b => b.classList.remove('active'));\n      e.target.classList.add('active');\n      currentRange = e.target.dataset.range;\n      refresh();\n    });\n\n    async function fetchJson(path) {\n      const res = await fetch(path, { headers });\n      if (!res.ok) return null;\n      return res.json();\n    }\n\n    function buildSvgPath(points, width, height, maxY) {\n      if (points.length === 0) return '';\n      const xStep = width / Math.max(points.length - 1, 1);\n      return points.map((y, i) => {\n        const px = i * xStep;\n        const py = height - (y / maxY) * height;\n        return (i === 0 ? 'M' : 'L') + px.toFixed(1) + ',' + py.toFixed(1);\n      }).join(' ');\n    }\n\n    function renderChart(data) {\n      const el = document.getElementById('chart');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      const width = 800; const height = 180;\n      const allVals = data.flatMap(d => [d.avg_ms, d.p95_ms, d.p99_ms]);\n      const maxY = Math.max(...allVals, 1) * 1.1;\n      const avgPath = buildSvgPath(data.map(d => d.avg_ms), width, height, maxY);\n      const p95Path = buildSvgPath(data.map(d => d.p95_ms), width, height, maxY);\n      const p99Path = buildSvgPath(data.map(d => d.p99_ms), width, height, maxY);\n      el.innerHTML = '<svg viewBox=\"0 0 ' + width + ' ' + height + '\" preserveAspectRatio=\"none\">'\n        + '<path class=\"chart-line line-avg\" d=\"' + avgPath + '\"/>'\n        + '<path class=\"chart-line line-p95\" d=\"' + p95Path + '\"/>'\n        + '<path class=\"chart-line line-p99\" d=\"' + p99Path + '\"/>'\n        + '</svg>';\n    }\n\n    function escapeHtml(s) {\n      if (s == null) return '';\n      return String(s)\n        .replace(/&/g, '&amp;')\n        .replace(/</g, '&lt;')\n        .replace(/>/g, '&gt;')\n        .replace(/\"/g, '&quot;')\n        .replace(/'/g, '&#39;');\n    }\n\n    // Numeric sink: counts are integer aggregates, but they are still values\n    // arriving over the wire, so coerce rather than interpolating them raw.\n    function num(v) {\n      const n = Number(v);\n      return Number.isFinite(n) ? String(n) : '0';\n    }\n\n    function renderModels(data) {\n      const el = document.getElementById('models-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Count</th><th class=\"num\">Avg (ms)</th><th class=\"num\">P95 (ms)</th><th class=\"num\">P99 (ms)</th></tr></thead><tbody>';\n      for (const row of data) {\n        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'\n          + '<td class=\"num\">' + num(row.count) + '</td>'\n          + '<td class=\"num\">' + row.avg_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p95_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p99_ms.toFixed(1) + '</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    function renderErrors(data) {\n      const el = document.getElementById('errors-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No errors</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Total</th><th class=\"num\">Errors</th><th class=\"num\">Rate</th></tr></thead><tbody>';\n      for (const row of data) {\n        const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';\n        const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';\n        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'\n          + '<td class=\"num\">' + num(row.count) + '</td>'\n          + '<td class=\"num\">' + num(row.error_count) + '</td>'\n          + '<td class=\"num ' + cls + '\">' + rate + '%</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    async function refresh() {\n      const [latency, models] = await Promise.all([\n        fetchJson('/api/latency?range=' + currentRange),\n        fetchJson('/api/models?range=' + currentRange),\n      ]);\n      renderChart(latency);\n      renderModels(models);\n      // Derive errors from models data\n      const withErrors = (models || []).filter(m => m.error_count > 0);\n      renderErrors(withErrors);\n    }\n\n    refresh();\n    setInterval(refresh, 60000);\n  </script>\n</body>\n</html>";