@mandujs/core 0.21.0 → 0.22.0

package/src/db/migrations/history-table.ts

@@ -0,0 +1,345 @@
+/**
+ * @mandujs/core/db/migrations/history-table
+ *
+ * History table DDL + row-level query helpers for the migration runtime.
+ *
+ * The `__mandu_migrations` table is Mandu's internal Flyway-style schema
+ * history record. It exists in the user's database alongside their own
+ * tables and is the single source of truth for "which migrations have
+ * already been applied". Every row represents exactly one applied
+ * migration file.
+ *
+ * ## Column contract (stable across dialects)
+ *
+ * | Column         | Type (dialect-mapped)            | Notes                                                  |
+ * |----------------|----------------------------------|--------------------------------------------------------|
+ * | `version`      | `TEXT PRIMARY KEY`               | Zero-padded 4-digit sequence (e.g. `"0001"`).          |
+ * | `filename`     | `TEXT NOT NULL`                  | Migration filename relative to the migrations dir.     |
+ * | `checksum`     | `TEXT NOT NULL`                  | SHA-256 hex lowercase of the file's normalized SQL.    |
+ * | `applied_at`   | `TIMESTAMPTZ` / `DATETIME(6)` / `TEXT` | Dialect's high-precision timestamp.              |
+ * | `execution_ms` | `INTEGER NOT NULL`               | Pure SQL execution time (excludes fetch / checksum).   |
+ * | `success`      | `INTEGER NOT NULL`               | `0` or `1` — stored as int for dialect parity.         |
+ * | `installed_by` | `TEXT`                           | DB user or `MANDU_MIGRATION_USER` env; nullable.       |
+ *
+ * ## Per-dialect DDL
+ *
+ * ### Postgres
+ * ```sql
+ * CREATE TABLE IF NOT EXISTS "__mandu_migrations" (
+ *   "version"      TEXT PRIMARY KEY,
+ *   "filename"     TEXT NOT NULL,
+ *   "checksum"     TEXT NOT NULL,
+ *   "applied_at"   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ *   "execution_ms" INTEGER NOT NULL,
+ *   "success"      INTEGER NOT NULL,
+ *   "installed_by" TEXT
+ * );
+ * ```
+ *
+ * ### MySQL
+ * ```sql
+ * CREATE TABLE IF NOT EXISTS `__mandu_migrations` (
+ *   `version`      VARCHAR(50) NOT NULL,
+ *   `filename`     VARCHAR(255) NOT NULL,
+ *   `checksum`     VARCHAR(64) NOT NULL,
+ *   `applied_at`   DATETIME(6) NOT NULL,
+ *   `execution_ms` INTEGER NOT NULL,
+ *   `success`      INTEGER NOT NULL,
+ *   `installed_by` VARCHAR(255),
+ *   PRIMARY KEY (`version`)
+ * );
+ * ```
+ * (MySQL requires lengths on VARCHAR in primary keys — we pick conservative
+ *  sizes that match Bun.SQL's `TEXT` parse in practice.)
+ *
+ * ### SQLite
+ * ```sql
+ * CREATE TABLE IF NOT EXISTS "__mandu_migrations" (
+ *   "version"      TEXT PRIMARY KEY,
+ *   "filename"     TEXT NOT NULL,
+ *   "checksum"     TEXT NOT NULL,
+ *   "applied_at"   TEXT NOT NULL,
+ *   "execution_ms" INTEGER NOT NULL,
+ *   "success"      INTEGER NOT NULL,
+ *   "installed_by" TEXT
+ * );
+ * ```
+ *
+ * @module db/migrations/history-table
+ */
+
+import type { SqlProvider } from "../../resource/ddl/types";
+import type { Db } from "../index";
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/** Default history-table name. Override via `MigrationRunnerOptions.historyTable`. */
+export const DEFAULT_HISTORY_TABLE = "__mandu_migrations";
+
+/**
+ * Identifier pattern for user-supplied history-table names. Because
+ * Bun.SQL cannot bind identifiers, the table name is interpolated into
+ * DDL/DML directly — we constrain it to `[A-Za-z_][A-Za-z0-9_]*` to
+ * eliminate any SQL-injection surface. Same pattern used by
+ * `filling/session-sqlite.ts:SAFE_IDENT_RE`.
+ */
+export const SAFE_HISTORY_TABLE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// ─── Row shape ──────────────────────────────────────────────────────────────
+
+/**
+ * Row shape for the history table. `success` is stored as an integer
+ * (`0` / `1`) across all three dialects so consumers see a uniform type —
+ * SQLite has no native boolean, and reusing the int form on PG/MySQL
+ * keeps `readAllHistory` producing identically-typed rows.
+ */
+export interface HistoryRow {
+  version: string;
+  filename: string;
+  checksum: string;
+  applied_at: Date;
+  execution_ms: number;
+  success: number; // 0 or 1 — SQLite has no boolean
+  installed_by?: string | null;
+  // Index signature so the row satisfies `Record<string, unknown>` that
+  // Bun.SQL's generic expects. Property types above still win for known keys.
+  [key: string]: unknown;
+}
+
+// ─── Identifier quoting ─────────────────────────────────────────────────────
+
+/**
+ * Quote a validated identifier for the target provider. Postgres/SQLite
+ * use double-quotes; MySQL uses backticks. Callers MUST validate the
+ * identifier against `SAFE_HISTORY_TABLE_RE` before quoting — this
+ * function assumes the input is already safe and does NOT re-escape.
+ */
+function quoteIdent(name: string, provider: SqlProvider): string {
+  if (!SAFE_HISTORY_TABLE_RE.test(name)) {
+    throw new Error(
+      `[@mandujs/core/db/migrations] Invalid identifier ${JSON.stringify(
+        name,
+      )}. Must match ${SAFE_HISTORY_TABLE_RE}.`,
+    );
+  }
+  if (provider === "mysql") return `\`${name}\``;
+  return `"${name}"`;
+}
+
+// ─── DDL ────────────────────────────────────────────────────────────────────
+
+/**
+ * Produce the `CREATE TABLE IF NOT EXISTS` DDL for the history table on
+ * the target provider. Idempotent — callers should execute on every boot;
+ * the `IF NOT EXISTS` clause prevents re-creation once the row exists.
+ *
+ * Column order is fixed across dialects. We choose per-column SQL types
+ * that match the `HistoryRow` contract as closely as each dialect
+ * permits. See the module JSDoc for the full per-dialect rendering.
+ *
+ * @throws when `tableName` fails the safe-identifier check.
+ */
+export function historyTableDdl(tableName: string, provider: SqlProvider): string {
+  const qTable = quoteIdent(tableName, provider);
+
+  switch (provider) {
+    case "postgres": {
+      return [
+        `CREATE TABLE IF NOT EXISTS ${qTable} (`,
+        `  "version"      TEXT PRIMARY KEY,`,
+        `  "filename"     TEXT NOT NULL,`,
+        `  "checksum"     TEXT NOT NULL,`,
+        `  "applied_at"   TIMESTAMPTZ NOT NULL DEFAULT NOW(),`,
+        `  "execution_ms" INTEGER NOT NULL,`,
+        `  "success"      INTEGER NOT NULL,`,
+        `  "installed_by" TEXT`,
+        `)`,
+      ].join("\n");
+    }
+    case "mysql": {
+      // MySQL demands a length on VARCHAR in a PRIMARY KEY. 50 chars is
+      // ample for `NNNN` today and leaves room for longer version schemes.
+      return [
+        `CREATE TABLE IF NOT EXISTS ${qTable} (`,
+        `  \`version\`      VARCHAR(50) NOT NULL,`,
+        `  \`filename\`     VARCHAR(255) NOT NULL,`,
+        `  \`checksum\`     VARCHAR(64) NOT NULL,`,
+        `  \`applied_at\`   DATETIME(6) NOT NULL,`,
+        `  \`execution_ms\` INTEGER NOT NULL,`,
+        `  \`success\`      INTEGER NOT NULL,`,
+        `  \`installed_by\` VARCHAR(255),`,
+        `  PRIMARY KEY (\`version\`)`,
+        `)`,
+      ].join("\n");
+    }
+    case "sqlite": {
+      // SQLite accepts TEXT for timestamps — we insert ISO-8601 strings.
+      return [
+        `CREATE TABLE IF NOT EXISTS ${qTable} (`,
+        `  "version"      TEXT PRIMARY KEY,`,
+        `  "filename"     TEXT NOT NULL,`,
+        `  "checksum"     TEXT NOT NULL,`,
+        `  "applied_at"   TEXT NOT NULL,`,
+        `  "execution_ms" INTEGER NOT NULL,`,
+        `  "success"      INTEGER NOT NULL,`,
+        `  "installed_by" TEXT`,
+        `)`,
+      ].join("\n");
+    }
+  }
+}
+
+// ─── Query helpers ──────────────────────────────────────────────────────────
+//
+// `@mandujs/core/db` exposes a tagged-template API. The SQL we emit here
+// is dynamic in exactly one way (the table name) — SQLite/Postgres/MySQL
+// do not bind identifiers, so we interpolate the (validated) table name
+// into the SQL text and bind only real values through Bun.SQL placeholders.
+//
+// We reuse the same `splitPlaceholders` trick as
+// `filling/session-sqlite.ts` so the query goes through the wrapper's
+// parameter binding path (no string concat of values, ever).
+
+/**
+ * Read every row in the history table, ordered by version. The row
+ * shape is the same across dialects — `applied_at` is coerced to `Date`
+ * when the dialect returns it as a string (SQLite).
+ */
+export async function readAllHistory(
+  db: Db,
+  tableName: string,
+): Promise<HistoryRow[]> {
+  if (!SAFE_HISTORY_TABLE_RE.test(tableName)) {
+    throw new Error(
+      `[@mandujs/core/db/migrations] Invalid history table name ${JSON.stringify(
+        tableName,
+      )}.`,
+    );
+  }
+  const qTable = quoteIdent(tableName, db.provider);
+  const sql = `SELECT version, filename, checksum, applied_at, execution_ms, success, installed_by FROM ${qTable} ORDER BY version ASC`;
+  const rows = await execQuery<Record<string, unknown>>(db, sql, []);
+  return rows.map(coerceHistoryRow);
+}
+
+/**
+ * Insert a single history row. The `applied_at` column is serialized to
+ * ISO-8601 on SQLite (TEXT column) and passed through as-is on PG/MySQL
+ * (native timestamp types).
+ *
+ * Expected to be called inside a transaction by the runner so that a
+ * crash between SQL execution + history write leaves no partial state.
+ */
+export async function insertHistory(
+  db: Db,
+  tableName: string,
+  row: Omit<HistoryRow, "applied_at"> & { applied_at: Date },
+): Promise<void> {
+  if (!SAFE_HISTORY_TABLE_RE.test(tableName)) {
+    throw new Error(
+      `[@mandujs/core/db/migrations] Invalid history table name ${JSON.stringify(
+        tableName,
+      )}.`,
+    );
+  }
+  const qTable = quoteIdent(tableName, db.provider);
+
+  // SQLite stores timestamps as TEXT in our schema; PG/MySQL accept Date.
+  const appliedAtParam =
+    db.provider === "sqlite" ? row.applied_at.toISOString() : row.applied_at;
+
+  const sql = `INSERT INTO ${qTable} (version, filename, checksum, applied_at, execution_ms, success, installed_by) VALUES ($1, $2, $3, $4, $5, $6, $7)`;
+  await execQuery<Record<string, unknown>>(db, sql, [
+    row.version,
+    row.filename,
+    row.checksum,
+    appliedAtParam,
+    row.execution_ms,
+    row.success,
+    row.installed_by ?? null,
+  ]);
+}
+
+// ─── Internals ──────────────────────────────────────────────────────────────
+
+/**
+ * Normalize a raw row read from the DB into the `HistoryRow` contract.
+ * Bun.SQL returns SQLite TEXT timestamps as strings; PG/MySQL drivers
+ * return `Date` already. We unify on `Date`.
+ */
+function coerceHistoryRow(raw: Record<string, unknown>): HistoryRow {
+  const appliedAtValue = raw.applied_at;
+  let appliedAt: Date;
+  if (appliedAtValue instanceof Date) {
+    appliedAt = appliedAtValue;
+  } else if (typeof appliedAtValue === "string") {
+    appliedAt = new Date(appliedAtValue);
+  } else if (typeof appliedAtValue === "number") {
+    appliedAt = new Date(appliedAtValue);
+  } else {
+    // Row with NULL applied_at shouldn't happen (NOT NULL in DDL), but
+    // handle defensively so consumers never crash on a garbage row.
+    appliedAt = new Date(0);
+  }
+
+  return {
+    version: String(raw.version ?? ""),
+    filename: String(raw.filename ?? ""),
+    checksum: String(raw.checksum ?? ""),
+    applied_at: appliedAt,
+    execution_ms: Number(raw.execution_ms ?? 0),
+    success: Number(raw.success ?? 0),
+    installed_by:
+      typeof raw.installed_by === "string" ? raw.installed_by : null,
+  };
+}
+
+/**
+ * Run a SQL string (with `$1, $2, …` placeholders) against the
+ * tagged-template `Db`. We construct a synthetic `TemplateStringsArray`
+ * by splitting on the placeholder markers — the same pattern used by
+ * `filling/session-sqlite.ts:splitPlaceholders`.
+ *
+ * This keeps the value-binding path identical to user-authored tagged
+ * template literals (`db\`SELECT ...\``) — the values are forwarded to
+ * Bun.SQL as bound parameters, never concatenated into the SQL string.
+ */
+async function execQuery<T extends Record<string, unknown>>(
+  db: Db,
+  sql: string,
+  params: unknown[],
+): Promise<T[]> {
+  const parts = splitPlaceholders(sql, params.length);
+  const strings = Object.assign(parts.slice(), {
+    raw: parts.slice(),
+  }) as unknown as TemplateStringsArray;
+  return (await db<T>(strings, ...params)) as T[];
+}
+
+/**
+ * Split a SQL string with `$1`, `$2`, … markers into the string segments
+ * that bracket each placeholder. The resulting array has
+ * `placeholderCount + 1` entries — matches a real
+ * `TemplateStringsArray`'s shape.
+ *
+ * Throws if the detected placeholder count disagrees with the provided
+ * `params.length` — catches mismatched SQL/param pairs at call time
+ * rather than surfacing them as a confusing Bun.SQL error.
+ */
+function splitPlaceholders(sql: string, expected: number): string[] {
+  const parts: string[] = [];
+  let rest = sql;
+  for (let i = 1; i <= expected; i++) {
+    const marker = `$${i}`;
+    const idx = rest.indexOf(marker);
+    if (idx === -1) {
+      throw new Error(
+        `[@mandujs/core/db/migrations] placeholder ${marker} missing in SQL: ${sql}`,
+      );
+    }
+    parts.push(rest.slice(0, idx));
+    rest = rest.slice(idx + marker.length);
+  }
+  parts.push(rest);
+  return parts;
+}

package/src/db/migrations/lock.ts

@@ -0,0 +1,269 @@
+/**
+ * @mandujs/core/db/migrations/lock
+ *
+ * Per-dialect serialization for the migration apply loop. Prevents two
+ * concurrent `MigrationRunner.apply()` calls — in the same process or
+ * (for PG/MySQL) across processes — from stepping on each other.
+ *
+ * ## Strategy matrix
+ *
+ * | Provider  | Strategy              | Mechanism                                                        |
+ * |-----------|-----------------------|------------------------------------------------------------------|
+ * | postgres  | `pg_advisory_lock`    | `pg_advisory_lock($1)` — lockId = `hashtext('mandu:migrations')` |
+ * | mysql     | `mysql_get_lock`      | `GET_LOCK('mandu:migrations', 60)` — blocks up to 60 s           |
+ * | sqlite    | `sqlite_immediate`    | `BEGIN IMMEDIATE` on a dedicated connection                      |
+ * | (any)     | `none`                | No-op (tests / non-concurrent scenarios)                         |
+ *
+ * All strategies wrap the same conceptual lock — the lockId string
+ * (`"mandu:migrations"` by default) is stable across runs, so two
+ * processes agreeing on the same string will serialise. If callers pass
+ * a custom `lockId`, every participant MUST use the same value.
+ *
+ * ## Release semantics
+ *
+ * `acquireMigrationLock(...)` returns a `MigrationLock` whose
+ * `release()` is idempotent. Callers should invoke it in a `finally`
+ * block — the `MigrationRunner.apply()` implementation does exactly
+ * this. SQLite's `sqlite_immediate` releases by committing the wrapper
+ * transaction; the other strategies issue an explicit unlock statement.
+ *
+ * @module db/migrations/lock
+ */
+
+import type { LockStrategy } from "../../resource/ddl/types";
+import type { Db } from "../index";
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/** A held migration lock. Calling `release()` twice is a no-op. */
+export interface MigrationLock {
+  release(): Promise<void>;
+}
+
+/**
+ * Default lockId — a stable string shared by every participant. For
+ * `pg_advisory_lock` we hash this to a bigint via `hashtext()`; the
+ * other dialects use the raw string.
+ */
+export const DEFAULT_LOCK_ID = "mandu:migrations";
+
+/** MySQL `GET_LOCK` default timeout in seconds. */
+const MYSQL_LOCK_TIMEOUT_SECONDS = 60;
+
+/**
+ * Acquire the migration lock for the configured dialect.
+ *
+ * - `pg_advisory_lock` blocks the connection until the lock is granted.
+ * - `mysql_get_lock` blocks up to {@link MYSQL_LOCK_TIMEOUT_SECONDS}; on
+ *   timeout we throw a descriptive error.
+ * - `sqlite_immediate` enters a BEGIN IMMEDIATE transaction on a
+ *   dedicated connection; if another writer holds the database lock,
+ *   Bun.SQL surfaces `SQLITE_BUSY` which we rethrow.
+ * - `none` is a no-op — useful for tests and single-shot CLI runs.
+ *
+ * @throws on MySQL lock timeout (`GET_LOCK` returns `0`), on explicit
+ *   `GET_LOCK` error (returns `null`), or on provider/strategy mismatch
+ *   (e.g. requesting `pg_advisory_lock` while `db.provider === "sqlite"`).
+ */
+export async function acquireMigrationLock(
+  db: Db,
+  strategy: LockStrategy,
+  lockId: string = DEFAULT_LOCK_ID,
+): Promise<MigrationLock> {
+  switch (strategy) {
+    case "pg_advisory_lock":
+      assertProvider(db, "postgres", strategy);
+      return await acquirePgAdvisoryLock(db, lockId);
+    case "mysql_get_lock":
+      assertProvider(db, "mysql", strategy);
+      return await acquireMysqlLock(db, lockId);
+    case "sqlite_immediate":
+      assertProvider(db, "sqlite", strategy);
+      return await acquireSqliteImmediate(db, lockId);
+    case "none":
+      return makeNoopLock();
+  }
+}
+
+// ─── Strategy impls ─────────────────────────────────────────────────────────
+
+async function acquirePgAdvisoryLock(
+  db: Db,
+  lockId: string,
+): Promise<MigrationLock> {
+  // Postgres advisory locks take a bigint. We derive it from the lockId
+  // string via `hashtext()::bigint` so the value is deterministic for
+  // the same input across instances. `hashtext` returns int4; cast to
+  // bigint for compatibility with `pg_advisory_lock(bigint)`.
+  //
+  // `SELECT pg_advisory_lock(hashtext($1)::bigint)` is safer than
+  // computing the hash client-side because it keeps every participant
+  // in the same database agreeing on the value without language-specific
+  // hash-function reproduction.
+  await db`SELECT pg_advisory_lock(hashtext(${lockId})::bigint)`;
+
+  let released = false;
+  return {
+    async release(): Promise<void> {
+      if (released) return;
+      released = true;
+      try {
+        await db`SELECT pg_advisory_unlock(hashtext(${lockId})::bigint)`;
+      } catch (err) {
+        // Best-effort release — if the connection has already died or
+        // the lock is no longer held, we don't want to mask the caller's
+        // unwind path. Surface the error name for diagnostics.
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(
+          `[@mandujs/core/db/migrations] pg_advisory_unlock failed: ${msg}`,
+        );
+      }
+    },
+  };
+}
+
+async function acquireMysqlLock(
+  db: Db,
+  lockId: string,
+): Promise<MigrationLock> {
+  // `GET_LOCK` returns:
+  //   1 — lock granted
+  //   0 — timeout (still blocked after the timeout)
+  //   NULL — error (aborted, killed, etc.)
+  //
+  // Bun.SQL returns the single row as `[{ acquired: 1 }]`; we destructure
+  // defensively to handle any driver-side aliasing.
+  const timeoutSec = MYSQL_LOCK_TIMEOUT_SECONDS;
+  const rows = await db<{ acquired: number | bigint | null }>`
+    SELECT GET_LOCK(${lockId}, ${timeoutSec}) AS acquired
+  `;
+  const first = rows[0];
+  const value = first ? Number(first.acquired) : NaN;
+  if (value !== 1) {
+    throw new Error(
+      `[@mandujs/core/db/migrations] GET_LOCK(${JSON.stringify(lockId)}, ${timeoutSec}) ` +
+        `returned ${value === 0 ? "0 (timeout)" : "NULL (error)"}; ` +
+        `another migration runner may be holding the lock.`,
+    );
+  }
+
+  let released = false;
+  return {
+    async release(): Promise<void> {
+      if (released) return;
+      released = true;
+      try {
+        await db`SELECT RELEASE_LOCK(${lockId})`;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(
+          `[@mandujs/core/db/migrations] RELEASE_LOCK failed: ${msg}`,
+        );
+      }
+    },
+  };
+}
+
+/**
+ * Per-process mutex queues keyed by lockId. SQLite is single-writer at
+ * the engine level, so cross-process writes already serialise — the
+ * remaining failure mode is two `apply()` calls in the SAME process
+ * interleaving their `db.transaction(...)` calls. A process-local
+ * promise chain is the simplest correct coordinator.
+ *
+ * This is stored on `globalThis` rather than module scope so that
+ * multiple copies of the module (e.g. reloads under watch mode) still
+ * agree on the same queue.
+ */
+const SQLITE_LOCK_REGISTRY_SYMBOL = Symbol.for(
+  "@mandujs/core/db/migrations/sqlite-locks",
+);
+interface SqliteLockRegistry {
+  /** Most-recent promise in each lockId's queue. */
+  chains: Map<string, Promise<void>>;
+}
+function getSqliteLockRegistry(): SqliteLockRegistry {
+  const g = globalThis as unknown as Record<symbol, unknown>;
+  let reg = g[SQLITE_LOCK_REGISTRY_SYMBOL] as SqliteLockRegistry | undefined;
+  if (!reg) {
+    reg = { chains: new Map() };
+    g[SQLITE_LOCK_REGISTRY_SYMBOL] = reg;
+  }
+  return reg;
+}
+
+async function acquireSqliteImmediate(
+  db: Db,
+  lockId: string,
+): Promise<MigrationLock> {
+  // Why an in-process mutex instead of `BEGIN IMMEDIATE`:
+  //
+  //   - `BEGIN IMMEDIATE` at the handle level conflicts with the
+  //     `db.transaction()` calls we issue per-migration — SQLite
+  //     errors with "cannot start a transaction within a transaction".
+  //   - SQLite is already single-writer at the engine level, so
+  //     cross-process writes queue via the OS file lock; the only
+  //     race we need to close is two concurrent `apply()` calls in
+  //     the SAME process interleaving their statements.
+  //   - A promise-chain mutex is the minimal correct mechanism for
+  //     in-process serialisation. Every apply() awaits the previous
+  //     holder's release before entering the critical section.
+  //
+  // Cross-process migration coordination is v2 per RFC 0001 §8.
+  //
+  // Sanity probe: executing a trivial statement on the handle at
+  // acquire time catches "pool closed" / handle validity issues
+  // before the caller commits resources to the apply loop.
+  await db`SELECT 1`;
+
+  const registry = getSqliteLockRegistry();
+  const previous = registry.chains.get(lockId) ?? Promise.resolve();
+
+  let release!: () => void;
+  const nextPromise = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const tail = previous.then(() => nextPromise);
+  registry.chains.set(lockId, tail);
+
+  // Wait for the previous holder to release.
+  await previous;
+
+  let released = false;
+  return {
+    async release(): Promise<void> {
+      if (released) return;
+      released = true;
+      release();
+      // If no one queued behind us, drop the entry so the registry
+      // doesn't grow unbounded across many apply() cycles.
+      if (registry.chains.get(lockId) === tail) {
+        registry.chains.delete(lockId);
+      }
+    },
+  };
+}
+
+function makeNoopLock(): MigrationLock {
+  let released = false;
+  return {
+    async release(): Promise<void> {
+      released = true;
+    },
+  };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function assertProvider(
+  db: Db,
+  expected: Db["provider"],
+  strategy: LockStrategy,
+): void {
+  if (db.provider !== expected) {
+    throw new Error(
+      `[@mandujs/core/db/migrations] Lock strategy ${JSON.stringify(strategy)} requires ` +
+        `provider ${JSON.stringify(expected)}, but db.provider is ${JSON.stringify(db.provider)}.`,
+    );
+  }
+}