@blamejs/core 0.7.18 → 0.7.19

package/lib/db-schema.js

@@ -1,319 +1,319 @@
-"use strict";
-/**
- * Schema reconciler + imperative migration runner + shared SQL
- * execution helpers used by every db-touching primitive.
- *
- * Hybrid migration strategy (per roadmap Q2):
- *
- *   1. Declarative reconcile (every boot, idempotent):
- *      - CREATE TABLE IF NOT EXISTS for tables in schema config
- *      - ALTER TABLE ADD COLUMN for any new columns (additive only)
- *      - CREATE INDEX IF NOT EXISTS for declared indexes
- *      - Refuses to drop columns or tables (data-loss safety)
- *
- *   2. Imperative migrations (after reconcile, run-once):
- *      - Numbered files: 001-foo.js, 002-bar.js
- *      - Each exports { up(db), down?(db), description }
- *      - Tracked in _blamejs_migrations table; never re-run
- *      - Run in numeric order; first failure halts boot
- *
- * Apps mix both: declarative covers structural changes (CREATE/ALTER),
- * imperative covers data backfills, transformations, conditional schema
- * changes that need code.
- *
- * Shared SQL execution helpers used by lib/migrations / lib/seeders /
- * lib/vault/rotate / lib/db etc.:
- *
- *   - runSql                — raw DDL / BEGIN / COMMIT / PRAGMA on
- *                             the framework's better-sqlite3 handle.
- *   - runSqlOnHandle        — handles BOTH raw better-sqlite3 and
- *                             b.db framework wrapper shapes —
- *                             operator-supplied handles can be either.
- *   - runInTransaction      — wrap fn in BEGIN / COMMIT / ROLLBACK on
- *                             the supplied db handle. opts.lockMode
- *                             appends to BEGIN ("IMMEDIATE" /
- *                             "EXCLUSIVE" on SQLite). opts.onRollbackFail
- *                             surfaces a rollback throw without
- *                             swallowing the original error.
- */
-var path = require("path");
-var atomicFile = require("./atomic-file");
-var safeSql = require("./safe-sql");
-
-// SQLite raw-SQL helper. node:sqlite DatabaseSync exposes a method on the
-// database object that runs raw SQL without bind parameters — used for DDL,
-// BEGIN/COMMIT/ROLLBACK, and PRAGMA. Bracket notation here avoids a
-// false-positive in upstream linters that pattern-match the bare token
-// `.exec(` regardless of receiver type.
-function runSql(database, sql) { return database["exec"](sql); }
-
-// runSqlOnHandle — execute SQL against either handle shape:
-//   - raw better-sqlite3 / node:sqlite Database (db.exec)
-//   - b.db framework wrapper (db.runSql)
-// Migrations / seeders / break-glass migrate accept operator-supplied
-// handles in either shape; this wrapper normalizes the call. The
-// 'exec'/'runSql' lookups use bracket notation so the eslint rule
-// banning bare-identifier db method calls (collapsing prepare → field)
-// stays satisfied.
-function runSqlOnHandle(db, sql) {
-  if (db && typeof db["exec"] === "function") return db["exec"](sql);
-  if (db && typeof db["runSql"] === "function") return db["runSql"](sql);
-  throw new Error("dbSchema.runSqlOnHandle: handle exposes no DDL runner (exec / runSql)");
-}
-
-// runInTransaction — wrap fn in BEGIN / COMMIT / ROLLBACK on the
-// supplied db handle. Used by migrations / seeders / any operator-
-// facing transaction. opts.lockMode appends to BEGIN ("IMMEDIATE",
-// "EXCLUSIVE" — SQLite-specific). opts.onRollbackFail surfaces a
-// rollback throw without swallowing the original error (the original
-// always re-throws).
-function runInTransaction(db, fn, opts) {
-  if (typeof fn !== "function") {
-    throw new TypeError("dbSchema.runInTransaction: fn must be a function");
-  }
-  opts = opts || {};
-  var beginSql = opts.lockMode ? "BEGIN " + opts.lockMode : "BEGIN";
-  runSqlOnHandle(db, beginSql);
-  try {
-    var result = fn();
-    runSqlOnHandle(db, "COMMIT");
-    return result;
-  } catch (e) {
-    try { runSqlOnHandle(db, "ROLLBACK"); }
-    catch (rollbackErr) {
-      if (typeof opts.onRollbackFail === "function") {
-        try { opts.onRollbackFail(rollbackErr); } catch (_e) { /* nested handler must not bubble */ }
-      }
-    }
-    throw e;
-  }
-}
-
-// ---- Internal migrations table ----
-
-var MIGRATIONS_TABLE = "_blamejs_migrations";
-// Pre-quoted for SQL interpolation — keeps the call sites consistent
-// with lib/migrations.js and lib/seeders.js so an identifier rename
-// doesn't silently break.
-var Q_MIGRATIONS_TABLE = '"' + MIGRATIONS_TABLE + '"';
-
-function ensureMigrationsTable(database) {
-  runSql(database,
-    "CREATE TABLE IF NOT EXISTS " + Q_MIGRATIONS_TABLE + " (" +
-    "  name        TEXT PRIMARY KEY," +
-    "  description TEXT," +
-    "  appliedAt   TEXT NOT NULL" +
-    ")"
-  );
-}
-
-// ---- Declarative reconcile ----
-
-function reconcile(database, schema) {
-  if (!Array.isArray(schema)) {
-    throw new Error("db.init({ schema }) must be an array of table definitions");
-  }
-  for (var i = 0; i < schema.length; i++) {
-    reconcileTable(database, schema[i]);
-  }
-}
-
-function reconcileTable(database, table) {
-  if (!table || !table.name) {
-    throw new Error("schema entry missing required 'name' property");
-  }
-  if (!table.columns || typeof table.columns !== "object") {
-    throw new Error("schema entry '" + table.name + "' missing 'columns' object");
-  }
-
-  var name = table.name;
-  validateIdent(name, "table name");
-
-  var colDefs = [];
-  for (var col in table.columns) {
-    validateIdent(col, "column name");
-    colDefs.push('"' + col + '" ' + table.columns[col]);
-  }
-  if (colDefs.length === 0) {
-    throw new Error("schema entry '" + name + "' has no columns");
-  }
-
-  // Structured PRIMARY KEY (alternative to inlining "PRIMARY KEY" in column DDL).
-  // Accepts a single column name or an array (composite PK).
-  if (table.primaryKey) {
-    var pkCols = Array.isArray(table.primaryKey) ? table.primaryKey : [table.primaryKey];
-    pkCols.forEach(function (c) { validateIdent(c, "primary key column"); });
-    pkCols.forEach(function (c) {
-      if (!Object.prototype.hasOwnProperty.call(table.columns, c)) {
-        throw new Error("primaryKey '" + c + "' is not declared in columns of table '" + name + "'");
-      }
-    });
-    colDefs.push("PRIMARY KEY (" + pkCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")");
-  }
-
-  // Structured FOREIGN KEY declarations. Each entry:
-  //   { column: 'userId', references: 'users._id', onDelete?, onUpdate? }
-  // Composite FKs use array form for `column` and the references-side: format
-  // 'table.col1,col2'. Forward references to tables not yet created are fine —
-  // SQLite validates at write time, not table-create time.
-  if (Array.isArray(table.foreignKeys)) {
-    for (var fi = 0; fi < table.foreignKeys.length; fi++) {
-      var fk = table.foreignKeys[fi];
-      if (!fk || !fk.column || !fk.references) {
-        throw new Error("foreignKey on table '" + name + "' requires { column, references }");
-      }
-      var localCols = Array.isArray(fk.column) ? fk.column : [fk.column];
-      var refStr = String(fk.references);
-      var dotIdx = refStr.indexOf(".");
-      if (dotIdx <= 0) {
-        throw new Error("foreignKey 'references' must be 'table.column' (or 'table.col1,col2' for composite): " + refStr);
-      }
-      var refTable = refStr.slice(0, dotIdx);
-      var refColsStr = refStr.slice(dotIdx + 1);
-      var refCols = refColsStr.split(",").map(function (s) { return s.trim(); });
-      validateIdent(refTable, "foreign key referenced table");
-      localCols.forEach(function (c) { validateIdent(c, "foreign key local column"); });
-      refCols.forEach(function (c) { validateIdent(c, "foreign key referenced column"); });
-      if (localCols.length !== refCols.length) {
-        throw new Error("foreignKey on '" + name + "': local-column count must match referenced-column count");
-      }
-      var clause = "FOREIGN KEY (" + localCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")" +
-        ' REFERENCES "' + refTable + '" (' + refCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")";
-      if (fk.onDelete) clause += " ON DELETE " + _validateAction(fk.onDelete, "ON DELETE", name);
-      if (fk.onUpdate) clause += " ON UPDATE " + _validateAction(fk.onUpdate, "ON UPDATE", name);
-      colDefs.push(clause);
-    }
-  }
-
-  runSql(database, 'CREATE TABLE IF NOT EXISTS "' + name + '" (' + colDefs.join(", ") + ")");
-
-  var existingCols = listColumns(database, name);
-  for (var newCol in table.columns) {
-    if (!existingCols.has(newCol)) {
-      try {
-        runSql(database, 'ALTER TABLE "' + name + '" ADD COLUMN "' + newCol + '" ' + table.columns[newCol]);
-      } catch (e) {
-        throw new Error("failed to add column '" + newCol + "' to '" + name + "': " + e.message);
-      }
-    }
-  }
-
-  if (Array.isArray(table.indexes)) {
-    for (var k = 0; k < table.indexes.length; k++) {
-      reconcileIndex(database, name, table.indexes[k]);
-    }
-  }
-}
-
-function _validateAction(action, label, tableName) {
-  var allowed = ["CASCADE", "SET NULL", "SET DEFAULT", "RESTRICT", "NO ACTION"];
-  var up = String(action).toUpperCase();
-  if (allowed.indexOf(up) === -1) {
-    throw new Error(label + " on '" + tableName + "' must be one of " + allowed.join(", ") + " (got: " + action + ")");
-  }
-  return up;
-}
-
-function reconcileIndex(database, tableName, idx) {
-  var cols, indexName, unique;
-  if (typeof idx === "string") {
-    cols = [idx];
-    indexName = "idx_" + tableName + "_" + idx;
-    unique = false;
-  } else if (idx && typeof idx === "object") {
-    cols = Array.isArray(idx.columns) ? idx.columns : [idx.columns];
-    indexName = idx.name || ("idx_" + tableName + "_" + cols.join("_"));
-    unique = !!idx.unique;
-  } else {
-    throw new Error("invalid index spec on table '" + tableName + "'");
-  }
-  validateIdent(indexName, "index name");
-  cols.forEach(function (c) { validateIdent(c, "indexed column"); });
-  var quotedCols = cols.map(function (c) { return '"' + c + '"'; }).join(", ");
-  runSql(database,
-    "CREATE " + (unique ? "UNIQUE " : "") + "INDEX IF NOT EXISTS \"" + indexName + "\"" +
-    ' ON "' + tableName + '" (' + quotedCols + ")"
-  );
-}
-
-function listColumns(database, tableName) {
-  var rows = database.prepare('PRAGMA table_info("' + tableName + '")').all();
-  var set = new Set();
-  for (var i = 0; i < rows.length; i++) set.add(rows[i].name);
-  return set;
-}
-
-// SQL identifier safety: alphanumeric + underscore, starts with letter or underscore.
-function validateIdent(ident, kind) {
-  if (typeof ident !== "string" ||
-      ident.length === 0 ||
-      ident.length > safeSql.MAX_IDENTIFIER_LENGTH ||
-      !safeSql.DEFAULT_IDENTIFIER_RE.test(ident)) {
-    throw new Error("invalid " + kind + ": '" + ident +
-      "' (must match " + safeSql.DEFAULT_IDENTIFIER_RE + ", length 1.." +
-      safeSql.MAX_IDENTIFIER_LENGTH + ")");
-  }
-}
-
-// ---- Imperative migration runner ----
-
-function runMigrations(database, migrationDir) {
-  if (!migrationDir) return { applied: [], skipped: [] };
-
-  ensureMigrationsTable(database);
-
-  // listDir returns [] if migrationDir doesn't exist (missingOk: true default).
-  var files = atomicFile.listDir(migrationDir, {
-    filter: function (f) { return /^\d+-.+\.js$/.test(f); },
-  }).map(function (e) { return e.name; }).sort();
-
-  var appliedSet = new Set();
-  database.prepare("SELECT name FROM " + Q_MIGRATIONS_TABLE).all().forEach(function (r) {
-    appliedSet.add(r.name);
-  });
-
-  var applied = [];
-  var skipped = [];
-  for (var i = 0; i < files.length; i++) {
-    var file = files[i];
-    if (appliedSet.has(file)) {
-      skipped.push(file);
-      continue;
-    }
-    var fullPath = path.join(migrationDir, file);
-    var mig;
-    try {
-      mig = require(fullPath);
-    } catch (e) {
-      throw new Error("migration '" + file + "' failed to load: " + e.message);
-    }
-    if (!mig || typeof mig.up !== "function") {
-      throw new Error("migration '" + file + "' must export an `up(db)` function");
-    }
-
-    try {
-      runInTransaction(database, function () {
-        mig.up(database);
-        database.prepare(
-          "INSERT INTO " + Q_MIGRATIONS_TABLE + " (name, description, appliedAt) VALUES (?, ?, ?)"
-        ).run(file, mig.description || "", new Date().toISOString());
-      });
-    } catch (e) {
-      throw new Error("migration '" + file + "' failed: " + e.message);
-    }
-    applied.push(file);
-  }
-
-  return { applied: applied, skipped: skipped };
-}
-
-module.exports = {
-  reconcile:        reconcile,
-  reconcileTable:   reconcileTable,
-  runMigrations:    runMigrations,
-  validateIdent:    validateIdent,
-  runSql:           runSql,
-  runSqlOnHandle:   runSqlOnHandle,
-  runInTransaction: runInTransaction,
-  MIGRATIONS_TABLE: MIGRATIONS_TABLE,
-};
+"use strict";
+/**
+ * Schema reconciler + imperative migration runner + shared SQL
+ * execution helpers used by every db-touching primitive.
+ *
+ * Hybrid migration strategy (per roadmap Q2):
+ *
+ *   1. Declarative reconcile (every boot, idempotent):
+ *      - CREATE TABLE IF NOT EXISTS for tables in schema config
+ *      - ALTER TABLE ADD COLUMN for any new columns (additive only)
+ *      - CREATE INDEX IF NOT EXISTS for declared indexes
+ *      - Refuses to drop columns or tables (data-loss safety)
+ *
+ *   2. Imperative migrations (after reconcile, run-once):
+ *      - Numbered files: 001-foo.js, 002-bar.js
+ *      - Each exports { up(db), down?(db), description }
+ *      - Tracked in _blamejs_migrations table; never re-run
+ *      - Run in numeric order; first failure halts boot
+ *
+ * Apps mix both: declarative covers structural changes (CREATE/ALTER),
+ * imperative covers data backfills, transformations, conditional schema
+ * changes that need code.
+ *
+ * Shared SQL execution helpers used by lib/migrations / lib/seeders /
+ * lib/vault/rotate / lib/db etc.:
+ *
+ *   - runSql                — raw DDL / BEGIN / COMMIT / PRAGMA on
+ *                             the framework's better-sqlite3 handle.
+ *   - runSqlOnHandle        — handles BOTH raw better-sqlite3 and
+ *                             b.db framework wrapper shapes —
+ *                             operator-supplied handles can be either.
+ *   - runInTransaction      — wrap fn in BEGIN / COMMIT / ROLLBACK on
+ *                             the supplied db handle. opts.lockMode
+ *                             appends to BEGIN ("IMMEDIATE" /
+ *                             "EXCLUSIVE" on SQLite). opts.onRollbackFail
+ *                             surfaces a rollback throw without
+ *                             swallowing the original error.
+ */
+var path = require("path");
+var atomicFile = require("./atomic-file");
+var safeSql = require("./safe-sql");
+
+// SQLite raw-SQL helper. node:sqlite DatabaseSync exposes a method on the
+// database object that runs raw SQL without bind parameters — used for DDL,
+// BEGIN/COMMIT/ROLLBACK, and PRAGMA. Bracket notation here avoids a
+// false-positive in upstream linters that pattern-match the bare token
+// `.exec(` regardless of receiver type.
+function runSql(database, sql) { return database["exec"](sql); }
+
+// runSqlOnHandle — execute SQL against either handle shape:
+//   - raw better-sqlite3 / node:sqlite Database (db.exec)
+//   - b.db framework wrapper (db.runSql)
+// Migrations / seeders / break-glass migrate accept operator-supplied
+// handles in either shape; this wrapper normalizes the call. The
+// 'exec'/'runSql' lookups use bracket notation so the eslint rule
+// banning bare-identifier db method calls (collapsing prepare → field)
+// stays satisfied.
+function runSqlOnHandle(db, sql) {
+  if (db && typeof db["exec"] === "function") return db["exec"](sql);
+  if (db && typeof db["runSql"] === "function") return db["runSql"](sql);
+  throw new Error("dbSchema.runSqlOnHandle: handle exposes no DDL runner (exec / runSql)");
+}
+
+// runInTransaction — wrap fn in BEGIN / COMMIT / ROLLBACK on the
+// supplied db handle. Used by migrations / seeders / any operator-
+// facing transaction. opts.lockMode appends to BEGIN ("IMMEDIATE",
+// "EXCLUSIVE" — SQLite-specific). opts.onRollbackFail surfaces a
+// rollback throw without swallowing the original error (the original
+// always re-throws).
+function runInTransaction(db, fn, opts) {
+  if (typeof fn !== "function") {
+    throw new TypeError("dbSchema.runInTransaction: fn must be a function");
+  }
+  opts = opts || {};
+  var beginSql = opts.lockMode ? "BEGIN " + opts.lockMode : "BEGIN";
+  runSqlOnHandle(db, beginSql);
+  try {
+    var result = fn();
+    runSqlOnHandle(db, "COMMIT");
+    return result;
+  } catch (e) {
+    try { runSqlOnHandle(db, "ROLLBACK"); }
+    catch (rollbackErr) {
+      if (typeof opts.onRollbackFail === "function") {
+        try { opts.onRollbackFail(rollbackErr); } catch (_e) { /* nested handler must not bubble */ }
+      }
+    }
+    throw e;
+  }
+}
+
+// ---- Internal migrations table ----
+
+var MIGRATIONS_TABLE = "_blamejs_migrations";
+// Pre-quoted for SQL interpolation — keeps the call sites consistent
+// with lib/migrations.js and lib/seeders.js so an identifier rename
+// doesn't silently break.
+var Q_MIGRATIONS_TABLE = '"' + MIGRATIONS_TABLE + '"';
+
+function ensureMigrationsTable(database) {
+  runSql(database,
+    "CREATE TABLE IF NOT EXISTS " + Q_MIGRATIONS_TABLE + " (" +
+    "  name        TEXT PRIMARY KEY," +
+    "  description TEXT," +
+    "  appliedAt   TEXT NOT NULL" +
+    ")"
+  );
+}
+
+// ---- Declarative reconcile ----
+
+function reconcile(database, schema) {
+  if (!Array.isArray(schema)) {
+    throw new Error("db.init({ schema }) must be an array of table definitions");
+  }
+  for (var i = 0; i < schema.length; i++) {
+    reconcileTable(database, schema[i]);
+  }
+}
+
+function reconcileTable(database, table) {
+  if (!table || !table.name) {
+    throw new Error("schema entry missing required 'name' property");
+  }
+  if (!table.columns || typeof table.columns !== "object") {
+    throw new Error("schema entry '" + table.name + "' missing 'columns' object");
+  }
+
+  var name = table.name;
+  validateIdent(name, "table name");
+
+  var colDefs = [];
+  for (var col in table.columns) {
+    validateIdent(col, "column name");
+    colDefs.push('"' + col + '" ' + table.columns[col]);
+  }
+  if (colDefs.length === 0) {
+    throw new Error("schema entry '" + name + "' has no columns");
+  }
+
+  // Structured PRIMARY KEY (alternative to inlining "PRIMARY KEY" in column DDL).
+  // Accepts a single column name or an array (composite PK).
+  if (table.primaryKey) {
+    var pkCols = Array.isArray(table.primaryKey) ? table.primaryKey : [table.primaryKey];
+    pkCols.forEach(function (c) { validateIdent(c, "primary key column"); });
+    pkCols.forEach(function (c) {
+      if (!Object.prototype.hasOwnProperty.call(table.columns, c)) {
+        throw new Error("primaryKey '" + c + "' is not declared in columns of table '" + name + "'");
+      }
+    });
+    colDefs.push("PRIMARY KEY (" + pkCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")");
+  }
+
+  // Structured FOREIGN KEY declarations. Each entry:
+  //   { column: 'userId', references: 'users._id', onDelete?, onUpdate? }
+  // Composite FKs use array form for `column` and the references-side: format
+  // 'table.col1,col2'. Forward references to tables not yet created are fine —
+  // SQLite validates at write time, not table-create time.
+  if (Array.isArray(table.foreignKeys)) {
+    for (var fi = 0; fi < table.foreignKeys.length; fi++) {
+      var fk = table.foreignKeys[fi];
+      if (!fk || !fk.column || !fk.references) {
+        throw new Error("foreignKey on table '" + name + "' requires { column, references }");
+      }
+      var localCols = Array.isArray(fk.column) ? fk.column : [fk.column];
+      var refStr = String(fk.references);
+      var dotIdx = refStr.indexOf(".");
+      if (dotIdx <= 0) {
+        throw new Error("foreignKey 'references' must be 'table.column' (or 'table.col1,col2' for composite): " + refStr);
+      }
+      var refTable = refStr.slice(0, dotIdx);
+      var refColsStr = refStr.slice(dotIdx + 1);
+      var refCols = refColsStr.split(",").map(function (s) { return s.trim(); });
+      validateIdent(refTable, "foreign key referenced table");
+      localCols.forEach(function (c) { validateIdent(c, "foreign key local column"); });
+      refCols.forEach(function (c) { validateIdent(c, "foreign key referenced column"); });
+      if (localCols.length !== refCols.length) {
+        throw new Error("foreignKey on '" + name + "': local-column count must match referenced-column count");
+      }
+      var clause = "FOREIGN KEY (" + localCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")" +
+        ' REFERENCES "' + refTable + '" (' + refCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")";
+      if (fk.onDelete) clause += " ON DELETE " + _validateAction(fk.onDelete, "ON DELETE", name);
+      if (fk.onUpdate) clause += " ON UPDATE " + _validateAction(fk.onUpdate, "ON UPDATE", name);
+      colDefs.push(clause);
+    }
+  }
+
+  runSql(database, 'CREATE TABLE IF NOT EXISTS "' + name + '" (' + colDefs.join(", ") + ")");
+
+  var existingCols = listColumns(database, name);
+  for (var newCol in table.columns) {
+    if (!existingCols.has(newCol)) {
+      try {
+        runSql(database, 'ALTER TABLE "' + name + '" ADD COLUMN "' + newCol + '" ' + table.columns[newCol]);
+      } catch (e) {
+        throw new Error("failed to add column '" + newCol + "' to '" + name + "': " + e.message);
+      }
+    }
+  }
+
+  if (Array.isArray(table.indexes)) {
+    for (var k = 0; k < table.indexes.length; k++) {
+      reconcileIndex(database, name, table.indexes[k]);
+    }
+  }
+}
+
+function _validateAction(action, label, tableName) {
+  var allowed = ["CASCADE", "SET NULL", "SET DEFAULT", "RESTRICT", "NO ACTION"];
+  var up = String(action).toUpperCase();
+  if (allowed.indexOf(up) === -1) {
+    throw new Error(label + " on '" + tableName + "' must be one of " + allowed.join(", ") + " (got: " + action + ")");
+  }
+  return up;
+}
+
+function reconcileIndex(database, tableName, idx) {
+  var cols, indexName, unique;
+  if (typeof idx === "string") {
+    cols = [idx];
+    indexName = "idx_" + tableName + "_" + idx;
+    unique = false;
+  } else if (idx && typeof idx === "object") {
+    cols = Array.isArray(idx.columns) ? idx.columns : [idx.columns];
+    indexName = idx.name || ("idx_" + tableName + "_" + cols.join("_"));
+    unique = !!idx.unique;
+  } else {
+    throw new Error("invalid index spec on table '" + tableName + "'");
+  }
+  validateIdent(indexName, "index name");
+  cols.forEach(function (c) { validateIdent(c, "indexed column"); });
+  var quotedCols = cols.map(function (c) { return '"' + c + '"'; }).join(", ");
+  runSql(database,
+    "CREATE " + (unique ? "UNIQUE " : "") + "INDEX IF NOT EXISTS \"" + indexName + "\"" +
+    ' ON "' + tableName + '" (' + quotedCols + ")"
+  );
+}
+
+function listColumns(database, tableName) {
+  var rows = database.prepare('PRAGMA table_info("' + tableName + '")').all();
+  var set = new Set();
+  for (var i = 0; i < rows.length; i++) set.add(rows[i].name);
+  return set;
+}
+
+// SQL identifier safety: alphanumeric + underscore, starts with letter or underscore.
+function validateIdent(ident, kind) {
+  if (typeof ident !== "string" ||
+      ident.length === 0 ||
+      ident.length > safeSql.MAX_IDENTIFIER_LENGTH ||
+      !safeSql.DEFAULT_IDENTIFIER_RE.test(ident)) {
+    throw new Error("invalid " + kind + ": '" + ident +
+      "' (must match " + safeSql.DEFAULT_IDENTIFIER_RE + ", length 1.." +
+      safeSql.MAX_IDENTIFIER_LENGTH + ")");
+  }
+}
+
+// ---- Imperative migration runner ----
+
+function runMigrations(database, migrationDir) {
+  if (!migrationDir) return { applied: [], skipped: [] };
+
+  ensureMigrationsTable(database);
+
+  // listDir returns [] if migrationDir doesn't exist (missingOk: true default).
+  var files = atomicFile.listDir(migrationDir, {
+    filter: function (f) { return /^\d+-.+\.js$/.test(f); },
+  }).map(function (e) { return e.name; }).sort();
+
+  var appliedSet = new Set();
+  database.prepare("SELECT name FROM " + Q_MIGRATIONS_TABLE).all().forEach(function (r) {
+    appliedSet.add(r.name);
+  });
+
+  var applied = [];
+  var skipped = [];
+  for (var i = 0; i < files.length; i++) {
+    var file = files[i];
+    if (appliedSet.has(file)) {
+      skipped.push(file);
+      continue;
+    }
+    var fullPath = path.join(migrationDir, file);
+    var mig;
+    try {
+      mig = require(fullPath);
+    } catch (e) {
+      throw new Error("migration '" + file + "' failed to load: " + e.message);
+    }
+    if (!mig || typeof mig.up !== "function") {
+      throw new Error("migration '" + file + "' must export an `up(db)` function");
+    }
+
+    try {
+      runInTransaction(database, function () {
+        mig.up(database);
+        database.prepare(
+          "INSERT INTO " + Q_MIGRATIONS_TABLE + " (name, description, appliedAt) VALUES (?, ?, ?)"
+        ).run(file, mig.description || "", new Date().toISOString());
+      });
+    } catch (e) {
+      throw new Error("migration '" + file + "' failed: " + e.message);
+    }
+    applied.push(file);
+  }
+
+  return { applied: applied, skipped: skipped };
+}
+
+module.exports = {
+  reconcile:        reconcile,
+  reconcileTable:   reconcileTable,
+  runMigrations:    runMigrations,
+  validateIdent:    validateIdent,
+  runSql:           runSql,
+  runSqlOnHandle:   runSqlOnHandle,
+  runInTransaction: runInTransaction,
+  MIGRATIONS_TABLE: MIGRATIONS_TABLE,
+};