@noego/proper 0.1.0 → 0.2.1

package/bin/cli.mjs

@@ -121,7 +121,7 @@ var init_MigrationFilter = __esm({
 });
 
 // framework/errors.ts
-var MigrationError, ConfigurationError, DatabaseConnectionError, MigrationExecutionError, CLIError;
+var MigrationError, ConfigurationError, DatabaseConnectionError, MigrationExecutionError, PatchError, PatchValidationError, PatchIntegrityError, PatchConflictError, PatchExecutionError, CLIError;
 var init_errors = __esm({
   "framework/errors.ts"() {
     MigrationError = class _MigrationError extends Error {
@@ -236,6 +236,54 @@ ${originalError.message}`;
         return new _MigrationExecutionError(message);
       }
     };
+    PatchError = class _PatchError extends MigrationError {
+      constructor(message, patchFile, patchKey) {
+        super(`Patch Error: ${message}`);
+        this.patchFile = patchFile;
+        this.patchKey = patchKey;
+        this.name = "PatchError";
+        Object.setPrototypeOf(this, _PatchError.prototype);
+      }
+    };
+    PatchValidationError = class _PatchValidationError extends PatchError {
+      constructor(message, patchFile, patchKey) {
+        super(message, patchFile, patchKey);
+        this.name = "PatchValidationError";
+        Object.setPrototypeOf(this, _PatchValidationError.prototype);
+      }
+    };
+    PatchIntegrityError = class _PatchIntegrityError extends PatchError {
+      constructor(message, patchFile, patchKey, expectedChecksum, actualChecksum) {
+        super(message, patchFile, patchKey);
+        this.expectedChecksum = expectedChecksum;
+        this.actualChecksum = actualChecksum;
+        this.name = "PatchIntegrityError";
+        Object.setPrototypeOf(this, _PatchIntegrityError.prototype);
+      }
+    };
+    PatchConflictError = class _PatchConflictError extends PatchError {
+      constructor(message, patchFile, patchKey, operationIndex, operationVerb, migrationKeys, observedRowCounts) {
+        super(message, patchFile, patchKey);
+        this.operationIndex = operationIndex;
+        this.operationVerb = operationVerb;
+        this.migrationKeys = migrationKeys;
+        this.observedRowCounts = observedRowCounts;
+        this.name = "PatchConflictError";
+        Object.setPrototypeOf(this, _PatchConflictError.prototype);
+      }
+    };
+    PatchExecutionError = class _PatchExecutionError extends PatchError {
+      constructor(message, patchFile, patchKey, operationIndex, operationVerb, originalError) {
+        super(originalError ? `${message}
+Original Error:
+${originalError.message}` : message, patchFile, patchKey);
+        this.operationIndex = operationIndex;
+        this.operationVerb = operationVerb;
+        this.originalError = originalError;
+        this.name = "PatchExecutionError";
+        Object.setPrototypeOf(this, _PatchExecutionError.prototype);
+      }
+    };
     CLIError = class _CLIError extends MigrationError {
       constructor(message) {
         super(`CLI Error: ${message}`);
@@ -412,13 +460,52 @@ var init_SqlMigrationBuilder = __esm({
   }
 });
 
-// framework/MigrationDirectoryReader.ts
+// framework/MigrationManifest.ts
 import fs from "fs";
 import path from "path";
+function isMigrationFile(fileName) {
+  return MIGRATION_FILE_REGEX.test(fileName);
+}
+function canonicalMigrationKey(value) {
+  return value.replace(MIGRATION_FILE_REGEX, "").toLowerCase();
+}
+function resolveMigrationFile(directory, baseName, direction, dialect) {
+  const dialectExt = dialect === "sql" ? "mysql" : dialect;
+  const dialectFile = path.join(directory, `${baseName}.${dialectExt}.${direction}.sql`);
+  if (fs.existsSync(dialectFile)) return dialectFile;
+  const genericFile = path.join(directory, `${baseName}.${direction}.sql`);
+  if (fs.existsSync(genericFile)) return genericFile;
+  return null;
+}
+function loadMigrationManifest(directory, dialect) {
+  const manifest = /* @__PURE__ */ new Map();
+  if (!fs.existsSync(directory)) return manifest;
+  const files = fs.readdirSync(directory, { withFileTypes: true }).filter((f) => f.isFile()).map((f) => f.name).filter(isMigrationFile);
+  const uniqueKeys = /* @__PURE__ */ new Set();
+  files.forEach((file) => uniqueKeys.add(canonicalMigrationKey(file)));
+  uniqueKeys.forEach((key) => {
+    manifest.set(key, {
+      key,
+      upFile: resolveMigrationFile(directory, key, "up", dialect),
+      downFile: resolveMigrationFile(directory, key, "down", dialect)
+    });
+  });
+  return manifest;
+}
+var MIGRATION_FILE_REGEX;
+var init_MigrationManifest = __esm({
+  "framework/MigrationManifest.ts"() {
+    MIGRATION_FILE_REGEX = /(?:\.(mysql|sqlite|pg))?\.(up|down)\.(sql|js)$/i;
+  }
+});
+
+// framework/MigrationDirectoryReader.ts
+import fs2 from "fs";
 var MigrationDirectoryReader;
 var init_MigrationDirectoryReader = __esm({
   "framework/MigrationDirectoryReader.ts"() {
     init_SqlMigrationBuilder();
+    init_MigrationManifest();
     MigrationDirectoryReader = class {
       constructor(directory, read_strategy, sqlrunner, dialect = "sql") {
         this.directory = directory;
@@ -432,12 +519,7 @@ var init_MigrationDirectoryReader = __esm({
        * File extensions: `.mysql.up.sql`, `.sqlite.up.sql`, `.pg.up.sql`.
        */
       resolveFile(baseName, direction) {
-        const dialectExt = this.dialect === "sql" ? "mysql" : this.dialect;
-        const dialectFile = path.join(this.directory, `${baseName}.${dialectExt}.${direction}.sql`);
-        if (fs.existsSync(dialectFile)) return dialectFile;
-        const genericFile = path.join(this.directory, `${baseName}.${direction}.sql`);
-        if (fs.existsSync(genericFile)) return genericFile;
-        return null;
+        return resolveMigrationFile(this.directory, baseName, direction, this.dialect);
       }
       /**
        * Checks if a file path is dialect-specific (contains .mysql. or .sqlite. in the name)
@@ -446,11 +528,11 @@ var init_MigrationDirectoryReader = __esm({
         return /\.(mysql|sqlite|pg)\.(up|down)\.sql$/i.test(filePath);
       }
       loadMigrations(table, connection) {
-        fs.existsSync(this.directory) || fs.mkdirSync(this.directory);
-        const dir_content = fs.readdirSync(this.directory, { withFileTypes: true }).filter((file) => file.isFile()).map((file) => file.name);
+        fs2.existsSync(this.directory) || fs2.mkdirSync(this.directory);
+        const dir_content = fs2.readdirSync(this.directory, { withFileTypes: true }).filter((file) => file.isFile()).map((file) => file.name).filter(isMigrationFile);
         const uniqueKeys = /* @__PURE__ */ new Set();
         dir_content.forEach((file) => {
-          const key = file.replace(/(?:\.(mysql|sqlite|pg))?\.(up|down)\.(sql|js)/i, "").toLowerCase();
+          const key = canonicalMigrationKey(file);
           uniqueKeys.add(key);
         });
         const migration_sorter = {};
@@ -490,14 +572,14 @@ var init_MigrationDirectoryReader = __esm({
         return builder;
       }
       sql_up(file) {
-        let content = fs.readFileSync(file).toString();
+        let content = fs2.readFileSync(file).toString();
         if (!this.isDialectSpecific(file)) {
           content = this.read_strategy(content);
         }
         return content.trim();
       }
       sql_down(file) {
-        let content = fs.readFileSync(file).toString();
+        let content = fs2.readFileSync(file).toString();
         if (!this.isDialectSpecific(file)) {
           content = this.read_strategy(content);
         }
@@ -507,11 +589,31 @@ var init_MigrationDirectoryReader = __esm({
   }
 });
 
+// framework/PatchTypes.ts
+import path2 from "path";
+function resolvePatchFolder(config) {
+  if (config.patch_folder) return config.patch_folder;
+  const dir = path2.dirname(config.migration_folder);
+  return dir === "." && !config.migration_folder.includes(path2.sep) && !config.migration_folder.includes("/") ? "patches" : path2.join(dir, "patches");
+}
+function resolvePatchTable(config) {
+  return config.patch_table || DEFAULT_PATCH_TABLE;
+}
+var PATCH_FORMAT_VERSION, DEFAULT_PATCH_TABLE, PATCH_FILENAME_REGEX;
+var init_PatchTypes = __esm({
+  "framework/PatchTypes.ts"() {
+    PATCH_FORMAT_VERSION = 1;
+    DEFAULT_PATCH_TABLE = "proper_patches";
+    PATCH_FILENAME_REGEX = new RegExp("^(?<stamp>[0-9]{13})_(?<name>[a-z0-9][a-z0-9_-]{0,119})\\.yaml$");
+  }
+});
+
 // framework/MigrationSetup.ts
-import fs2 from "fs";
+import fs3 from "fs";
 var MigrationSetup;
 var init_MigrationSetup = __esm({
   "framework/MigrationSetup.ts"() {
+    init_PatchTypes();
     MigrationSetup = class {
       constructor(sqlrunner, config) {
         this.sqlrunner = sqlrunner;
@@ -519,7 +621,7 @@ var init_MigrationSetup = __esm({
       }
       setup() {
         return __async(this, null, function* () {
-          fs2.existsSync(this.config.migration_folder) || fs2.mkdirSync(this.config.migration_folder);
+          fs3.existsSync(this.config.migration_folder) || fs3.mkdirSync(this.config.migration_folder);
           const tableName = this.config.migration_table;
           const createTableSql = this.config.database === "sqlite" ? `CREATE TABLE IF NOT EXISTS ${tableName} (
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -541,11 +643,39 @@ var init_MigrationSetup = __esm({
                 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
             )`;
           yield this.sqlrunner.query(createTableSql);
+          const patchTable = resolvePatchTable(this.config);
+          const createPatchTableSql = this.config.database === "sqlite" ? `CREATE TABLE IF NOT EXISTS ${patchTable} (
+                migration_table TEXT NOT NULL,
+                patch_key TEXT NOT NULL,
+                checksum TEXT NOT NULL,
+                format_version INTEGER NOT NULL,
+                description TEXT NOT NULL,
+                applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (migration_table, patch_key)
+            )` : this.config.database === "pg" ? `CREATE TABLE IF NOT EXISTS ${patchTable} (
+                migration_table TEXT NOT NULL,
+                patch_key TEXT NOT NULL,
+                checksum TEXT NOT NULL,
+                format_version INTEGER NOT NULL,
+                description TEXT NOT NULL,
+                applied_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+                PRIMARY KEY (migration_table, patch_key)
+            )` : `CREATE TABLE IF NOT EXISTS ${patchTable} (
+                migration_table VARCHAR(255) NOT NULL,
+                patch_key VARCHAR(255) NOT NULL,
+                checksum CHAR(64) NOT NULL,
+                format_version INT NOT NULL,
+                description TEXT NOT NULL,
+                applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (migration_table, patch_key)
+            )`;
+          yield this.sqlrunner.query(createPatchTableSql);
         });
       }
       teardown() {
         return __async(this, null, function* () {
           yield this.sqlrunner.execute(`DROP TABLE ${this.config.migration_table}`);
+          yield this.sqlrunner.execute(`DROP TABLE IF EXISTS ${resolvePatchTable(this.config)}`);
         });
       }
     };
@@ -614,6 +744,703 @@ var init_MigrationDialectParser = __esm({
   }
 });
 
+// framework/PatchValidator.ts
+import Ajv from "ajv";
+import { parseDocument } from "yaml";
+function fail(message, file, patchKey) {
+  throw new PatchValidationError(message, file, patchKey);
+}
+function checkMigrationKey(value, context, file, patchKey) {
+  if (value !== value.trim()) fail(`${context}: migration key has leading/trailing whitespace`, file, patchKey);
+  if (/[/\\]/.test(value)) fail(`${context}: migration key contains a path separator`, file, patchKey);
+  if (/[\x00-\x1f\x7f]/.test(value)) fail(`${context}: migration key contains control characters`, file, patchKey);
+  if (value.length === 0 || value.length > MAX_MIGRATION_KEY_LENGTH) {
+    fail(`${context}: migration key length out of bounds`, file, patchKey);
+  }
+  return canonicalMigrationKey(value);
+}
+function assertStrictYaml(doc, file, patchKey) {
+  if (doc.errors.length > 0) {
+    fail(`YAML parse error: ${doc.errors[0].message}`, file, patchKey);
+  }
+  if (doc.warnings.length > 0) {
+    fail(`YAML warning treated as error: ${doc.warnings[0].message}`, file, patchKey);
+  }
+  const visit = (node) => {
+    var _a, _b;
+    if (node == null || typeof node !== "object") return;
+    if ("source" in node && ((_a = node.constructor) == null ? void 0 : _a.name) === "Alias") {
+      fail("YAML aliases are not permitted in patch files", file, patchKey);
+    }
+    if (node.anchor) {
+      fail("YAML anchors are not permitted in patch files", file, patchKey);
+    }
+    if (node.tag && ![
+      "tag:yaml.org,2002:str",
+      "tag:yaml.org,2002:int",
+      "tag:yaml.org,2002:bool",
+      "tag:yaml.org,2002:null",
+      "tag:yaml.org,2002:map",
+      "tag:yaml.org,2002:seq"
+    ].includes(node.tag)) {
+      fail(`YAML tag '${node.tag}' is not permitted in patch files`, file, patchKey);
+    }
+    if (Array.isArray(node.items)) {
+      for (const item of node.items) {
+        if (item && typeof item === "object" && "key" in item) {
+          const keyValue = (_b = item.key) == null ? void 0 : _b.value;
+          if (keyValue === "<<") fail("YAML merge keys are not permitted in patch files", file, patchKey);
+          visit(item.key);
+          visit(item.value);
+        } else {
+          visit(item);
+        }
+      }
+    }
+  };
+  visit(doc.contents);
+}
+function parsePatchContent(content, fileName, patchKey) {
+  var _a;
+  const doc = parseDocument(content, {
+    uniqueKeys: true,
+    // duplicate mapping keys become errors
+    merge: false,
+    schema: "core",
+    version: "1.2"
+  });
+  assertStrictYaml(doc, fileName, patchKey);
+  const raw = doc.toJS({ mapAsMap: false });
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    fail("Patch document must be a YAML mapping", fileName, patchKey);
+  }
+  if (!validateSchema(raw)) {
+    const detail = ((_a = validateSchema.errors) != null ? _a : []).map((e) => `${e.instancePath || "/"} ${e.message}`).join("; ");
+    const anyRaw = raw;
+    if (typeof anyRaw.version === "number" && anyRaw.version !== PATCH_FORMAT_VERSION) {
+      fail(`Unknown patch format version: ${anyRaw.version} (supported: ${PATCH_FORMAT_VERSION})`, fileName, patchKey);
+    }
+    fail(`Schema validation failed: ${detail}`, fileName, patchKey);
+  }
+  const parsed = raw;
+  if (parsed.version !== PATCH_FORMAT_VERSION) {
+    fail(`Unknown patch format version: ${parsed.version} (supported: ${PATCH_FORMAT_VERSION})`, fileName, patchKey);
+  }
+  const description = parsed.description.trim();
+  if (description.length === 0) fail("description must be non-empty", fileName, patchKey);
+  if (description.length > MAX_DESCRIPTION_LENGTH) {
+    fail(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters`, fileName, patchKey);
+  }
+  const operations = parsed.operations.map((op, index) => {
+    const verbs = Object.keys(op);
+    const verb = verbs[0];
+    const context = `operation ${index} (${verb})`;
+    switch (verb) {
+      case "rename_migration": {
+        const from = checkMigrationKey(op.rename_migration.from, context, fileName, patchKey);
+        const to = checkMigrationKey(op.rename_migration.to, context, fileName, patchKey);
+        if (from === to) {
+          fail(`${context}: 'from' and 'to' are identical after canonicalization ('${from}')`, fileName, patchKey);
+        }
+        return { verb: "rename_migration", from, to };
+      }
+      case "mark_applied":
+        return { verb: "mark_applied", key: checkMigrationKey(op.mark_applied.key, context, fileName, patchKey) };
+      case "unmark_applied":
+        return { verb: "unmark_applied", key: checkMigrationKey(op.unmark_applied.key, context, fileName, patchKey) };
+      default:
+        fail(`operation ${index}: unknown verb '${verb}'`, fileName, patchKey);
+    }
+  });
+  return { version: parsed.version, description, operations };
+}
+function validatePatchPlan(patches, manifest) {
+  const renames = [];
+  for (const patch of patches) {
+    patch.operations.forEach((op, index) => {
+      if (op.verb === "rename_migration") {
+        renames.push({ from: op.from, to: op.to, file: patch.fileName });
+      } else if (op.verb === "mark_applied") {
+        if (!manifest.has(op.key)) {
+          throw new PatchValidationError(
+            `operation ${index} (mark_applied): key '${op.key}' is not present in the current migration manifest`,
+            patch.fileName,
+            patch.patchKey
+          );
+        }
+      }
+    });
+  }
+  if (renames.length === 0) return;
+  const mentioned = /* @__PURE__ */ new Set();
+  renames.forEach((r) => {
+    mentioned.add(r.from);
+    mentioned.add(r.to);
+  });
+  const finalKey = (start) => {
+    let current = start;
+    for (const r of renames) {
+      if (current === r.from) current = r.to;
+    }
+    return current;
+  };
+  for (const key of mentioned) {
+    const finish = finalKey(key);
+    if (manifest.has(key)) {
+      if (finish !== key) {
+        throw new PatchValidationError(
+          `rename plan moves current migration '${key}' to '${finish}', which would make its file incorrectly pending`
+        );
+      }
+    } else {
+      if (!manifest.has(finish)) {
+        throw new PatchValidationError(
+          `rename plan leaves historical key '${key}' at '${finish}', which is not present in the current migration manifest`
+        );
+      }
+    }
+  }
+}
+var MAX_DESCRIPTION_LENGTH, MAX_MIGRATION_KEY_LENGTH, migrationKeySchema, patchSchema, ajv, validateSchema;
+var init_PatchValidator = __esm({
+  "framework/PatchValidator.ts"() {
+    init_errors();
+    init_MigrationManifest();
+    init_PatchTypes();
+    MAX_DESCRIPTION_LENGTH = 500;
+    MAX_MIGRATION_KEY_LENGTH = 255;
+    migrationKeySchema = {
+      type: "string",
+      minLength: 1,
+      maxLength: MAX_MIGRATION_KEY_LENGTH
+    };
+    patchSchema = {
+      type: "object",
+      additionalProperties: false,
+      required: ["version", "description", "operations"],
+      properties: {
+        version: { type: "integer" },
+        description: { type: "string" },
+        operations: {
+          type: "array",
+          minItems: 1,
+          items: {
+            type: "object",
+            additionalProperties: false,
+            minProperties: 1,
+            maxProperties: 1,
+            properties: {
+              rename_migration: {
+                type: "object",
+                additionalProperties: false,
+                required: ["from", "to"],
+                properties: { from: migrationKeySchema, to: migrationKeySchema }
+              },
+              mark_applied: {
+                type: "object",
+                additionalProperties: false,
+                required: ["key"],
+                properties: { key: migrationKeySchema }
+              },
+              unmark_applied: {
+                type: "object",
+                additionalProperties: false,
+                required: ["key"],
+                properties: { key: migrationKeySchema }
+              }
+            }
+          }
+        }
+      }
+    };
+    ajv = new Ajv({ allErrors: true, strict: true });
+    validateSchema = ajv.compile(patchSchema);
+  }
+});
+
+// framework/PatchDirectoryReader.ts
+import crypto from "crypto";
+import fs4 from "fs";
+import path3 from "path";
+var PatchDirectoryReader;
+var init_PatchDirectoryReader = __esm({
+  "framework/PatchDirectoryReader.ts"() {
+    init_errors();
+    init_PatchValidator();
+    init_PatchTypes();
+    PatchDirectoryReader = class {
+      constructor(directory) {
+        this.directory = directory;
+      }
+      loadPatches() {
+        if (!fs4.existsSync(this.directory)) return [];
+        const entries = fs4.readdirSync(this.directory, { withFileTypes: true });
+        const patchFiles = [];
+        for (const entry of entries) {
+          if (!entry.name.endsWith(".yaml")) continue;
+          if (!entry.isFile() || entry.isSymbolicLink()) {
+            if (entry.isSymbolicLink()) {
+              throw new PatchValidationError(`patch file must be a regular file, not a symlink`, entry.name);
+            }
+            continue;
+          }
+          patchFiles.push(entry.name);
+        }
+        patchFiles.sort((a, b) => {
+          const stampA = parseInt(a.slice(0, 13), 10);
+          const stampB = parseInt(b.slice(0, 13), 10);
+          if (!Number.isNaN(stampA) && !Number.isNaN(stampB) && stampA !== stampB) {
+            return stampA - stampB;
+          }
+          return a < b ? -1 : a > b ? 1 : 0;
+        });
+        return patchFiles.map((fileName) => {
+          const match = PATCH_FILENAME_REGEX.exec(fileName);
+          if (!match) {
+            throw new PatchValidationError(
+              `invalid patch filename (expected <13-digit-stamp>_<name>.yaml with name matching [a-z0-9][a-z0-9_-]{0,119})`,
+              fileName
+            );
+          }
+          const patchKey = fileName.slice(0, -".yaml".length);
+          const filePath = path3.join(this.directory, fileName);
+          const bytes = fs4.readFileSync(filePath);
+          const checksum = crypto.createHash("sha256").update(bytes).digest("hex");
+          const content = bytes.toString("utf8");
+          const { version, description, operations } = parsePatchContent(content, fileName, patchKey);
+          return { patchKey, fileName, filePath, checksum, version, description, operations };
+        });
+      }
+    };
+  }
+});
+
+// framework/PatchRunner.ts
+function toError(error) {
+  if (error instanceof Error) return error;
+  return new Error(String(error));
+}
+function extractRows(result) {
+  if (!Array.isArray(result)) return [];
+  if (Array.isArray(result[0])) return result[0];
+  if (result.length === 2 && result[0] && typeof result[0] === "object" && result[1] && typeof result[1] === "object" && !("rows" in result[1])) {
+    return result;
+  }
+  if (result[0] == null) return [];
+  return [result[0]];
+}
+var PatchRunner;
+var init_PatchRunner = __esm({
+  "framework/PatchRunner.ts"() {
+    init_PatchDirectoryReader();
+    init_PatchValidator();
+    init_MigrationManifest();
+    init_PatchTypes();
+    init_errors();
+    PatchRunner = class {
+      constructor(sqlrunner, config) {
+        this.sqlrunner = sqlrunner;
+        this.config = config;
+        this.patchTable = resolvePatchTable(config);
+        this.migrationTable = config.migration_table;
+        this.dialect = config.database;
+      }
+      /**
+       * Discovers, validates, and applies every unapplied patch in order.
+       * Each unapplied patch is its own transaction; earlier committed patches
+       * remain committed if a later patch fails.
+       */
+      applyPending() {
+        return __async(this, null, function* () {
+          const reader = new PatchDirectoryReader(resolvePatchFolder(this.config));
+          const patches = reader.loadPatches();
+          const history = yield this.loadHistory();
+          if (patches.length === 0 && history.length === 0) {
+            return [];
+          }
+          const byKey = new Map(patches.map((p) => [p.patchKey, p]));
+          for (const row of history) {
+            const file = byKey.get(row.patch_key);
+            if (!file) {
+              throw new PatchIntegrityError(
+                `applied patch '${row.patch_key}' has no corresponding file in the patch folder; patch files are permanent and must never be renamed or deleted`,
+                void 0,
+                row.patch_key
+              );
+            }
+            if (file.checksum !== row.checksum) {
+              throw new PatchIntegrityError(
+                `applied patch '${row.patch_key}' content changed after application; patch files are immutable once recorded`,
+                file.fileName,
+                row.patch_key,
+                row.checksum,
+                file.checksum
+              );
+            }
+          }
+          const manifest = loadMigrationManifest(this.config.migration_folder, this.dialect);
+          validatePatchPlan(patches, manifest);
+          const appliedKeys = new Set(history.map((r) => r.patch_key));
+          const results = [];
+          for (const patch of patches) {
+            if (appliedKeys.has(patch.patchKey)) {
+              results.push({
+                patchKey: patch.patchKey,
+                fileName: patch.fileName,
+                status: "already_applied",
+                operations: []
+              });
+              continue;
+            }
+            results.push(yield this.applyOne(patch, manifest));
+          }
+          return results;
+        });
+      }
+      loadHistory() {
+        return __async(this, null, function* () {
+          try {
+            const result = yield this.sqlrunner.query(
+              `SELECT patch_key, checksum FROM ${this.patchTable} WHERE migration_table = ?`,
+              [this.migrationTable]
+            );
+            return extractRows(result);
+          } catch (error) {
+            throw new PatchExecutionError(
+              `failed to read patch history from '${this.patchTable}'`,
+              void 0,
+              void 0,
+              void 0,
+              void 0,
+              toError(error)
+            );
+          }
+        });
+      }
+      beginSql() {
+        switch (this.dialect) {
+          case "sqlite":
+            return "BEGIN IMMEDIATE";
+          case "pg":
+            return "BEGIN";
+          default:
+            return "START TRANSACTION";
+        }
+      }
+      begin(patch) {
+        return __async(this, null, function* () {
+          const deadline = Date.now() + 1e4;
+          while (true) {
+            try {
+              yield this.sqlrunner.execute(this.beginSql());
+              return;
+            } catch (error) {
+              const message = toError(error).message;
+              if (/SQLITE_BUSY|database is locked/i.test(message) && Date.now() < deadline) {
+                yield new Promise((resolve) => setTimeout(resolve, 50));
+                continue;
+              }
+              throw new PatchExecutionError(
+                "failed to start patch transaction",
+                patch.fileName,
+                patch.patchKey,
+                void 0,
+                void 0,
+                toError(error)
+              );
+            }
+          }
+        });
+      }
+      rollbackQuietly() {
+        return __async(this, null, function* () {
+          try {
+            yield this.sqlrunner.execute("ROLLBACK");
+          } catch (e) {
+          }
+        });
+      }
+      applyOne(patch, manifest) {
+        return __async(this, null, function* () {
+          yield this.begin(patch);
+          try {
+            yield this.sqlrunner.execute(
+              `INSERT INTO ${this.patchTable} (migration_table, patch_key, checksum, format_version, description)
+                 VALUES (?, ?, ?, ?, ?)`,
+              [this.migrationTable, patch.patchKey, patch.checksum, patch.version, patch.description]
+            );
+          } catch (claimError) {
+            yield this.rollbackQuietly();
+            const committed = yield this.findCommittedRow(patch.patchKey);
+            if (committed) {
+              if (committed.checksum === patch.checksum) {
+                return {
+                  patchKey: patch.patchKey,
+                  fileName: patch.fileName,
+                  status: "already_applied",
+                  operations: []
+                };
+              }
+              throw new PatchIntegrityError(
+                `patch '${patch.patchKey}' was applied elsewhere with a different checksum`,
+                patch.fileName,
+                patch.patchKey,
+                committed.checksum,
+                patch.checksum
+              );
+            }
+            throw new PatchExecutionError(
+              "failed to claim patch-history row",
+              patch.fileName,
+              patch.patchKey,
+              void 0,
+              void 0,
+              toError(claimError)
+            );
+          }
+          const operationResults = [];
+          try {
+            for (let index = 0; index < patch.operations.length; index++) {
+              operationResults.push(
+                yield this.applyOperation(patch, patch.operations[index], index, manifest)
+              );
+            }
+            yield this.sqlrunner.execute("COMMIT");
+          } catch (error) {
+            yield this.rollbackQuietly();
+            if (error instanceof PatchConflictError || error instanceof PatchExecutionError || error instanceof PatchIntegrityError) {
+              throw error;
+            }
+            throw new PatchExecutionError(
+              "patch application failed",
+              patch.fileName,
+              patch.patchKey,
+              void 0,
+              void 0,
+              toError(error)
+            );
+          }
+          return {
+            patchKey: patch.patchKey,
+            fileName: patch.fileName,
+            status: "applied",
+            operations: operationResults
+          };
+        });
+      }
+      findCommittedRow(patchKey) {
+        return __async(this, null, function* () {
+          const result = yield this.sqlrunner.query(
+            `SELECT patch_key, checksum FROM ${this.patchTable} WHERE migration_table = ? AND patch_key = ?`,
+            [this.migrationTable, patchKey]
+          );
+          const list = extractRows(result);
+          return list.length > 0 ? list[0] : null;
+        });
+      }
+      countRows(key) {
+        return __async(this, null, function* () {
+          var _a, _b, _c;
+          const result = yield this.sqlrunner.query(
+            `SELECT COUNT(*) AS row_count FROM ${this.migrationTable} WHERE migration_key = ?`,
+            [key]
+          );
+          const rows = extractRows(result);
+          const value = (_c = (_a = rows[0]) == null ? void 0 : _a.row_count) != null ? _c : Object.values((_b = rows[0]) != null ? _b : {})[0];
+          return Number(value != null ? value : 0);
+        });
+      }
+      conflict(patch, index, verb, message, keys, counts) {
+        throw new PatchConflictError(
+          `operation ${index} (${verb}): ${message}`,
+          patch.fileName,
+          patch.patchKey,
+          index,
+          verb,
+          keys,
+          counts
+        );
+      }
+      applyOperation(patch, op, index, manifest) {
+        return __async(this, null, function* () {
+          var _a, _b, _c, _d;
+          try {
+            switch (op.verb) {
+              case "rename_migration": {
+                const fromCount = yield this.countRows(op.from);
+                const toCount = yield this.countRows(op.to);
+                const counts = { [op.from]: fromCount, [op.to]: toCount };
+                if (fromCount > 1 || toCount > 1) {
+                  this.conflict(
+                    patch,
+                    index,
+                    op.verb,
+                    `ledger corruption: duplicate rows for a migration key`,
+                    [op.from, op.to],
+                    counts
+                  );
+                }
+                if (fromCount === 1 && toCount === 1) {
+                  this.conflict(
+                    patch,
+                    index,
+                    op.verb,
+                    `both '${op.from}' and '${op.to}' exist in the ledger`,
+                    [op.from, op.to],
+                    counts
+                  );
+                }
+                if (fromCount === 0) {
+                  return { verb: op.verb, changed: false };
+                }
+                const target = manifest.get(op.to);
+                if (target) {
+                  yield this.sqlrunner.execute(
+                    `UPDATE ${this.migrationTable} SET migration_key = ?, up = ?, down = ? WHERE migration_key = ?`,
+                    [op.to, (_a = target.upFile) != null ? _a : "", (_b = target.downFile) != null ? _b : "", op.from]
+                  );
+                } else {
+                  yield this.sqlrunner.execute(
+                    `UPDATE ${this.migrationTable} SET migration_key = ? WHERE migration_key = ?`,
+                    [op.to, op.from]
+                  );
+                }
+                return { verb: op.verb, changed: true };
+              }
+              case "mark_applied": {
+                const count = yield this.countRows(op.key);
+                if (count > 1) {
+                  this.conflict(
+                    patch,
+                    index,
+                    op.verb,
+                    `ledger corruption: duplicate rows for '${op.key}'`,
+                    [op.key],
+                    { [op.key]: count }
+                  );
+                }
+                if (count === 1) {
+                  return { verb: op.verb, changed: false };
+                }
+                const entry = manifest.get(op.key);
+                yield this.sqlrunner.execute(
+                  `INSERT INTO ${this.migrationTable} (migration_key, up, down) VALUES (?, ?, ?)`,
+                  [op.key, (_c = entry == null ? void 0 : entry.upFile) != null ? _c : "", (_d = entry == null ? void 0 : entry.downFile) != null ? _d : ""]
+                );
+                return { verb: op.verb, changed: true };
+              }
+              case "unmark_applied": {
+                const count = yield this.countRows(op.key);
+                if (count > 1) {
+                  this.conflict(
+                    patch,
+                    index,
+                    op.verb,
+                    `ledger corruption: duplicate rows for '${op.key}'`,
+                    [op.key],
+                    { [op.key]: count }
+                  );
+                }
+                if (count === 0) {
+                  return { verb: op.verb, changed: false };
+                }
+                yield this.sqlrunner.execute(
+                  `DELETE FROM ${this.migrationTable} WHERE migration_key = ?`,
+                  [op.key]
+                );
+                return { verb: op.verb, changed: true };
+              }
+            }
+          } catch (error) {
+            if (error instanceof PatchConflictError) throw error;
+            throw new PatchExecutionError(
+              `operation failed`,
+              patch.fileName,
+              patch.patchKey,
+              index,
+              op.verb,
+              toError(error)
+            );
+          }
+        });
+      }
+    };
+  }
+});
+
+// framework/PatchCreator.ts
+import fs5 from "fs";
+import path4 from "path";
+var MAX_NAME_LENGTH, SCAFFOLD, PatchCreator;
+var init_PatchCreator = __esm({
+  "framework/PatchCreator.ts"() {
+    init_errors();
+    MAX_NAME_LENGTH = 120;
+    SCAFFOLD = `version: 1
+description: TODO
+operations: []
+`;
+    PatchCreator = class _PatchCreator {
+      constructor(patchFolder) {
+        this.patchFolder = patchFolder;
+      }
+      /**
+       * Normalizes a patch name: trim, whitespace runs -> `_`, lowercase.
+       * Rejects empty results, path separators, `..`, control characters,
+       * characters outside [a-z0-9_-], and names longer than 120 characters.
+       */
+      static normalizeName(name) {
+        const normalized = (name != null ? name : "").trim().replace(/\s+/g, "_").toLowerCase();
+        if (normalized.length === 0) {
+          throw new CLIError("Patch name is required");
+        }
+        if (normalized.includes("/") || normalized.includes("\\")) {
+          throw new CLIError("Patch name must not contain path separators");
+        }
+        if (normalized.includes("..")) {
+          throw new CLIError("Patch name must not contain '..'");
+        }
+        if (/[\x00-\x1f\x7f]/.test(normalized)) {
+          throw new CLIError("Patch name must not contain control characters");
+        }
+        if (!/^[a-z0-9_-]+$/.test(normalized)) {
+          throw new CLIError("Patch name may only contain characters [a-z0-9_-]");
+        }
+        if (normalized.length > MAX_NAME_LENGTH) {
+          throw new CLIError(`Patch name exceeds ${MAX_NAME_LENGTH} characters after normalization`);
+        }
+        return normalized;
+      }
+      /**
+       * Creates `<patch_folder>/<stamp>_<normalized_name>.yaml` with exclusive
+       * file creation. On a millisecond-stamp collision, mints a later stamp
+       * and retries. Returns the created path.
+       */
+      create(name) {
+        const normalized = _PatchCreator.normalizeName(name);
+        if (!fs5.existsSync(this.patchFolder)) {
+          fs5.mkdirSync(this.patchFolder, { recursive: true });
+        }
+        let stamp = Date.now();
+        for (let attempt = 0; attempt < 1e3; attempt++) {
+          const filePath = path4.join(this.patchFolder, `${stamp}_${normalized}.yaml`);
+          try {
+            fs5.writeFileSync(filePath, SCAFFOLD, { flag: "wx" });
+            return filePath;
+          } catch (error) {
+            if (error && error.code === "EEXIST") {
+              stamp += 1;
+              continue;
+            }
+            throw error;
+          }
+        }
+        throw new CLIError("Unable to create patch file: too many filename collisions");
+      }
+    };
+  }
+});
+
 // framework/SQLRunner.ts
 function isPromiseLike(value) {
   return !!value && typeof value.then === "function";
@@ -933,8 +1760,8 @@ ${sql}
 });
 
 // framework/MigrationRunner.ts
-import fs3 from "fs";
-function toError(error) {
+import fs6 from "fs";
+function toError2(error) {
   if (error instanceof Error) return error;
   return new Error(String(error));
 }
@@ -957,6 +1784,9 @@ var init_MigrationRunner = __esm({
     init_MigrationSetup();
     init_MigrationFilter();
     init_MigrationDialectParser();
+    init_PatchRunner();
+    init_PatchCreator();
+    init_PatchTypes();
     init_SQLRunner();
     init_errors();
     MigrationRunnerFactory = class _MigrationRunnerFactory {
@@ -967,10 +1797,12 @@ var init_MigrationRunner = __esm({
         return __async(this, null, function* () {
           const configReader = new FileMigrationConfigReader(configFile);
           const config = configReader.loadFile();
+          let factoryOwnsConnection = false;
           if (!conn) {
             conn = yield this.createConnection(config);
+            factoryOwnsConnection = true;
           }
-          return new _MigrationRunnerFactory().create(config, conn);
+          return new _MigrationRunnerFactory().create(config, conn, factoryOwnsConnection);
         });
       }
       static createConnection(config) {
@@ -990,7 +1822,7 @@ var init_MigrationRunner = __esm({
                 conn = yield ((_b = (_a = mysql.default) == null ? void 0 : _a.createConnection) != null ? _b : mysql.createConnection)(settings);
                 return conn;
               } catch (error) {
-                throw DatabaseConnectionError.connectionFailed("sql", toError(error).message);
+                throw DatabaseConnectionError.connectionFailed("sql", toError2(error).message);
               }
             case "sqlite":
               if (!config.sqlite) {
@@ -1005,7 +1837,7 @@ var init_MigrationRunner = __esm({
                 });
                 return conn;
               } catch (error) {
-                throw DatabaseConnectionError.connectionFailed("sqlite", toError(error).message);
+                throw DatabaseConnectionError.connectionFailed("sqlite", toError2(error).message);
               }
             case "pg":
               if (!config.pg && !process.env.DATABASE_URL) {
@@ -1021,7 +1853,7 @@ var init_MigrationRunner = __esm({
                 yield conn.connect();
                 return conn;
               } catch (error) {
-                throw DatabaseConnectionError.connectionFailed("pg", toError(error).message);
+                throw DatabaseConnectionError.connectionFailed("pg", toError2(error).message);
               }
             default:
               throw ConfigurationError.unknownDatabaseType(config.database);
@@ -1035,7 +1867,7 @@ var init_MigrationRunner = __esm({
           return new _MigrationRunnerFactory().createEmpty(config);
         });
       }
-      create(config, conn) {
+      create(config, conn, factoryOwnsConnection = false) {
         return __async(this, null, function* () {
           let sqlrunner;
           let driverConnection = conn;
@@ -1048,8 +1880,19 @@ var init_MigrationRunner = __esm({
           const setup = new MigrationSetup(sqlrunner, config);
           const read_strategy = this.getReadStategy(config);
           const migration_files = new MigrationDirectoryReader(config.migration_folder, read_strategy, sqlrunner, config.database);
-          yield setup.setup();
-          return new MySQLMigrationRunner(config, migration_files, setup, sqlrunner, driverConnection);
+          const runner = new MySQLMigrationRunner(config, migration_files, setup, sqlrunner, driverConnection);
+          try {
+            yield runner.setup();
+          } catch (error) {
+            if (factoryOwnsConnection) {
+              try {
+                yield sqlrunner.end();
+              } catch (e) {
+              }
+            }
+            throw error;
+          }
+          return runner;
         });
       }
       createEmpty(config) {
@@ -1059,7 +1902,7 @@ var init_MigrationRunner = __esm({
           const setup = new MigrationSetup(sqlrunner, config);
           const read_strategy = this.getReadStategy(config);
           const migration_files = new MigrationDirectoryReader(config.migration_folder, read_strategy, sqlrunner, config.database);
-          return new MySQLMigrationRunner(config, migration_files, setup, sqlrunner, conn);
+          return new MySQLMigrationRunner(config, migration_files, setup, sqlrunner, conn, false);
         });
       }
       getReadStategy(config) {
@@ -1076,33 +1919,77 @@ var init_MigrationRunner = __esm({
       }
     };
     MySQLMigrationRunner = class {
-      constructor(config, directory, setupRunner, sqlrunner, connection) {
+      constructor(config, directory, setupRunner, sqlrunner, connection, preflightEnabled = true) {
         this.config = config;
         this.directory = directory;
         this.setupRunner = setupRunner;
         this.sqlrunner = sqlrunner;
         this.connection = connection;
+        this.preflightEnabled = preflightEnabled;
+        /**
+         * Memoized in-flight preflight promise. Simultaneous or repeated calls
+         * to setup() on one runner execute the preflight (migration table setup
+         * + patch application) exactly once. Cleared after rejection so a caller
+         * may retry after fixing the cause.
+         */
+        this.preflightPromise = null;
+        this.lastPatchResults = [];
       }
       setup() {
+        return __async(this, null, function* () {
+          if (!this.preflightEnabled) {
+            return;
+          }
+          if (!this.preflightPromise) {
+            this.preflightPromise = this.runPreflight();
+            this.preflightPromise.catch(() => {
+              this.preflightPromise = null;
+            });
+          }
+          return this.preflightPromise;
+        });
+      }
+      runPreflight() {
         return __async(this, null, function* () {
           try {
             yield this.setupRunner.setup();
           } catch (error) {
-            throw new MigrationExecutionError("Failed to set up migration database", void 0, void 0, toError(error));
+            throw new MigrationExecutionError("Failed to set up migration database", void 0, void 0, toError2(error));
           }
+          const patchRunner = new PatchRunner(this.sqlrunner, this.config);
+          this.lastPatchResults = yield patchRunner.applyPending();
+        });
+      }
+      /**
+       * Delegates to the same idempotent preflight; returns the results of the
+       * patch pass that ran (or is running) for this runner.
+       */
+      applyPendingPatches() {
+        return __async(this, null, function* () {
+          yield this.setup();
+          return this.lastPatchResults;
         });
       }
+      /**
+       * Scaffolds a new ledger patch file and returns the created path.
+       * Never connects to a database.
+       */
+      createPatch(name) {
+        const creator = new PatchCreator(resolvePatchFolder(this.config));
+        return creator.create(name);
+      }
       terminate() {
         return __async(this, null, function* () {
           try {
             yield this.setupRunner.teardown();
           } catch (error) {
-            throw new MigrationExecutionError("Failed to tear down migration database", void 0, void 0, toError(error));
+            throw new MigrationExecutionError("Failed to tear down migration database", void 0, void 0, toError2(error));
           }
         });
       }
       getMigrationsHistory() {
         return __async(this, null, function* () {
+          yield this.setup();
           try {
             const results = yield this.sqlrunner.query(`
                 select * 
@@ -1110,16 +1997,17 @@ var init_MigrationRunner = __esm({
             `);
             return results[0];
           } catch (error) {
-            throw new MigrationExecutionError("Failed to get migration history", void 0, void 0, toError(error));
+            throw new MigrationExecutionError("Failed to get migration history", void 0, void 0, toError2(error));
           }
         });
       }
       getMigrations() {
         return __async(this, null, function* () {
+          yield this.setup();
           try {
             return this.directory.loadMigrations(this.config.migration_table, this.connection);
           } catch (error) {
-            throw new MigrationExecutionError("Failed to load migrations", void 0, void 0, toError(error));
+            throw new MigrationExecutionError("Failed to load migrations", void 0, void 0, toError2(error));
           }
         });
       }
@@ -1132,7 +2020,7 @@ var init_MigrationRunner = __esm({
             if (error instanceof MigrationExecutionError) {
               throw error;
             }
-            throw new MigrationExecutionError("Failed to get pending migrations", void 0, void 0, toError(error));
+            throw new MigrationExecutionError("Failed to get pending migrations", void 0, void 0, toError2(error));
           }
         });
       }
@@ -1145,12 +2033,13 @@ var init_MigrationRunner = __esm({
             if (error instanceof MigrationExecutionError) {
               throw error;
             }
-            throw new MigrationExecutionError("Failed to get completed migrations", void 0, void 0, toError(error));
+            throw new MigrationExecutionError("Failed to get completed migrations", void 0, void 0, toError2(error));
           }
         });
       }
       migrate(migrationNodes, forward) {
         return __async(this, null, function* () {
+          yield this.setup();
           for (let node of migrationNodes) {
             try {
               if (forward) {
@@ -1163,7 +2052,7 @@ var init_MigrationRunner = __esm({
                 `Failed to ${forward ? "apply" : "rollback"} migration`,
                 node.name || String(node),
                 forward ? node.up_sql() : node.down_sql(),
-                toError(error)
+                toError2(error)
               );
             }
           }
@@ -1171,6 +2060,7 @@ var init_MigrationRunner = __esm({
       }
       reset() {
         return __async(this, null, function* () {
+          yield this.setup();
           try {
             let migrations = yield this.getMigrations();
             const rollback = yield migration_filter(migrations, true);
@@ -1182,7 +2072,7 @@ var init_MigrationRunner = __esm({
             if (error instanceof MigrationExecutionError) {
               throw error;
             }
-            throw new MigrationExecutionError("Failed to reset migrations", void 0, void 0, toError(error));
+            throw new MigrationExecutionError("Failed to reset migrations", void 0, void 0, toError2(error));
           }
         });
       }
@@ -1191,7 +2081,7 @@ var init_MigrationRunner = __esm({
           const creator = new MigrationCreator(this.config);
           creator.create(name);
         } catch (error) {
-          throw new MigrationExecutionError(`Failed to create migration: ${name}`, void 0, void 0, toError(error));
+          throw new MigrationExecutionError(`Failed to create migration: ${name}`, void 0, void 0, toError2(error));
         }
       }
       close() {
@@ -1200,7 +2090,7 @@ var init_MigrationRunner = __esm({
             try {
               yield this.sqlrunner.end();
             } catch (error) {
-              throw new DatabaseConnectionError(`Failed to close database connection: ${toError(error).message}`);
+              throw new DatabaseConnectionError(`Failed to close database connection: ${toError2(error).message}`);
             }
           }
         });
@@ -1214,7 +2104,7 @@ var init_MigrationRunner = __esm({
         return __async(this, null, function* () {
           try {
             console.log(`Checking for ${config_file}`);
-            const config_exist = fs3.existsSync(config_file);
+            const config_exist = fs6.existsSync(config_file);
             if (!config_exist) {
               console.log(`Creating ${config_file}`);
               const default_config = {
@@ -1228,11 +2118,11 @@ var init_MigrationRunner = __esm({
                   "password": ""
                 }
               };
-              fs3.writeFileSync(config_file, JSON.stringify(default_config, null, 2));
+              fs6.writeFileSync(config_file, JSON.stringify(default_config, null, 2));
               console.log(`Created ${config_file}`);
             }
           } catch (error) {
-            throw new ConfigurationError(`Failed to initialize config file: ${toError(error).message}`);
+            throw new ConfigurationError(`Failed to initialize config file: ${toError2(error).message}`);
           }
         });
       }
@@ -1243,7 +2133,7 @@ var init_MigrationRunner = __esm({
       }
       loadFile() {
         try {
-          const fileContent = fs3.readFileSync(this.configFile);
+          const fileContent = fs6.readFileSync(this.configFile);
           const config = JSON.parse(fileContent.toString());
           if (!config.migration_folder) {
             throw ConfigurationError.missingRequiredProperty("migration_folder");
@@ -1267,7 +2157,7 @@ var init_MigrationRunner = __esm({
           if (error instanceof ConfigurationError) {
             throw error;
           }
-          const err = toError(error);
+          const err = toError2(error);
           if (err.message.includes("ENOENT")) {
             throw new ConfigurationError(`Config file not found: ${this.configFile}`);
           }
@@ -1284,16 +2174,16 @@ var init_MigrationRunner = __esm({
           throw new CLIError("Migration name is required");
         }
         try {
-          if (!fs3.existsSync(this.config.migration_folder)) {
-            fs3.mkdirSync(this.config.migration_folder, { recursive: true });
+          if (!fs6.existsSync(this.config.migration_folder)) {
+            fs6.mkdirSync(this.config.migration_folder, { recursive: true });
           }
           const now_timestamp = Date.now();
           const filename_up = `${now_timestamp}_${name}.up.sql`;
           const filename_down = `${now_timestamp}_${name}.down.sql`;
-          fs3.writeFileSync(`${this.config.migration_folder}/${filename_up}`, `
+          fs6.writeFileSync(`${this.config.migration_folder}/${filename_up}`, `
 -- Write your up migration here
             `.trim());
-          fs3.writeFileSync(`${this.config.migration_folder}/${filename_down}`, `
+          fs6.writeFileSync(`${this.config.migration_folder}/${filename_down}`, `
 -- Write your down migration here
             `.trim());
           console.log(`Created migration files:`);
@@ -1303,7 +2193,7 @@ var init_MigrationRunner = __esm({
           if (error instanceof CLIError) {
             throw error;
           }
-          throw new MigrationExecutionError(`Failed to create migration files: ${toError(error).message}`);
+          throw new MigrationExecutionError(`Failed to create migration files: ${toError2(error).message}`);
         }
       }
     };
@@ -1311,10 +2201,10 @@ var init_MigrationRunner = __esm({
 });
 
 // framework/SeedRunner.ts
-import fs4 from "fs";
-import path2 from "path";
+import fs7 from "fs";
+import path5 from "path";
 import { pathToFileURL } from "url";
-import Ajv from "ajv";
+import Ajv2 from "ajv";
 import addFormats from "ajv-formats";
 import { tsImport } from "tsx/esm/api";
 function resolveAlias(name, aliasMap) {
@@ -1323,10 +2213,10 @@ function resolveAlias(name, aliasMap) {
   return (_a = aliasMap[name]) != null ? _a : name;
 }
 function walkForFile(rootDir, fileName) {
-  if (!fs4.existsSync(rootDir)) return null;
-  const entries = fs4.readdirSync(rootDir, { withFileTypes: true });
+  if (!fs7.existsSync(rootDir)) return null;
+  const entries = fs7.readdirSync(rootDir, { withFileTypes: true });
   for (const entry of entries) {
-    const full = path2.join(rootDir, entry.name);
+    const full = path5.join(rootDir, entry.name);
     if (entry.isDirectory()) {
       const found = walkForFile(full, fileName);
       if (found) return found;
@@ -1420,39 +2310,39 @@ function resolveSeed(name, migrationConfig, options) {
 }
 function loadJson(filePath) {
   return __async(this, null, function* () {
-    const content = yield fs4.promises.readFile(filePath, "utf8");
+    const content = yield fs7.promises.readFile(filePath, "utf8");
     return JSON.parse(content);
   });
 }
 function createValidator() {
-  const ajv = new Ajv({ allErrors: true, strict: false });
-  addFormats(ajv);
-  return ajv;
+  const ajv2 = new Ajv2({ allErrors: true, strict: false });
+  addFormats(ajv2);
+  return ajv2;
 }
 function validateData(schemaPath, data, validate, log) {
   return __async(this, null, function* () {
     if (!validate || !schemaPath) return;
-    const content = yield fs4.promises.readFile(schemaPath, "utf8");
+    const content = yield fs7.promises.readFile(schemaPath, "utf8");
     const schema = JSON.parse(content);
-    const ajv = createValidator();
-    const validateFn = ajv.compile(schema);
+    const ajv2 = createValidator();
+    const validateFn = ajv2.compile(schema);
     const ok = validateFn(data);
     if (!ok) {
       log == null ? void 0 : log(`Validation failed for seed data (${schemaPath})`);
-      throw new Error(`Seed data validation failed: ${ajv.errorsText(validateFn.errors || [])}`);
+      throw new Error(`Seed data validation failed: ${ajv2.errorsText(validateFn.errors || [])}`);
     }
   });
 }
 function runSqlSeed(runner, resolved, direction) {
   return __async(this, null, function* () {
     const sqlPath = direction === "up" ? resolved.upPath : resolved.downPath;
-    const sql = yield fs4.promises.readFile(sqlPath, "utf8");
+    const sql = yield fs7.promises.readFile(sqlPath, "utf8");
     yield runner.query(sql);
   });
 }
 function loadSeedModule(modulePath) {
   return __async(this, null, function* () {
-    const resolved = path2.resolve(modulePath);
+    const resolved = path5.resolve(modulePath);
     if (resolved.endsWith(".ts")) {
       const fileUrl = pathToFileURL(resolved).href;
       return tsImport(fileUrl, fileUrl);
@@ -1567,7 +2457,7 @@ var require_cli = __commonJS({
     }
     var commands = args.commands;
     var command = commands[0];
-    var load_database = !["init", "create", "help"].includes(command.toLowerCase());
+    var load_database = !["init", "create", "help", "patch"].includes(command.toLowerCase());
     var config_file = args.flags.config || "proper.json";
     if (command.toLowerCase() === "help") {
       printUsage();
@@ -1576,9 +2466,17 @@ var require_cli = __commonJS({
     console.log(`Loading database: ${load_database}`);
     var pending_runner = load_database ? MigrationRunnerFactory.create(config_file) : MigrationRunnerFactory.createEmpty(config_file);
     pending_runner.then((runner) => __async(null, null, function* () {
+      let failed = false;
       try {
         if (load_database) {
-          yield runner.setup();
+          const patch_results = yield runner.applyPendingPatches();
+          for (const patch of patch_results) {
+            if (patch.status === "applied") {
+              const changed = patch.operations.filter((op) => op.changed).length;
+              const noop = patch.operations.length - changed;
+              console.log(`Applied patch ${patch.fileName}: ${changed} changed, ${noop} no-op operation(s)`);
+            }
+          }
         }
         switch (command.toLowerCase()) {
           case "up":
@@ -1598,7 +2496,6 @@ var require_cli = __commonJS({
             } else {
               console.log("No pending migrations");
             }
-            yield runner.close();
             break;
           case "down":
             const migrations_rollback = yield runner.getMigrations();
@@ -1619,13 +2516,11 @@ var require_cli = __commonJS({
             } else {
               console.log("No migrations to roll back");
             }
-            yield runner.close();
             break;
           case "reset":
             console.log("Resetting all migrations...");
             yield runner.reset();
             console.log("Reset completed successfully");
-            yield runner.close();
             break;
           case "create":
             let filename = args.flags.name || commands[1];
@@ -1634,11 +2529,22 @@ var require_cli = __commonJS({
             }
             filename = filename.replace(/\s/g, "_");
             runner.createMigration(filename);
-            runner.close();
             break;
+          case "patch": {
+            const patch_name = args.flags.name || commands[1];
+            if (!patch_name) {
+              throw new CLIError("Patch name is required. Usage: proper patch <name>");
+            }
+            const created_path = runner.createPatch(patch_name);
+            console.log(`Created patch file:`);
+            console.log(`  ${created_path}`);
+            console.log("");
+            console.log("Complete this file before running another database-backed");
+            console.log("Proper command: 'operations: []' is intentionally not runnable.");
+            break;
+          }
           case "init":
             yield runner.init(config_file);
-            runner.close();
             break;
           case "status":
             const { printTable } = __require("console-table-printer");
@@ -1652,7 +2558,6 @@ var require_cli = __commonJS({
               };
             }));
             printTable(yield Promise.all(table));
-            runner.close();
             break;
           case "query":
             const sql_query = args.flags.query || commands[1];
@@ -1696,7 +2601,6 @@ Returned ${results.length} row(s)`);
             } catch (error) {
               throw new CLIError(`Query execution failed: ${error.message}`);
             }
-            yield runner.close();
             break;
           case "seed": {
             const subCommands = commands.slice(1);
@@ -1729,7 +2633,6 @@ Returned ${results.length} row(s)`);
             const reader = new FileMigrationConfigReader(config_file);
             const migrationConfig = reader.loadFile();
             yield runSeedsWithRunner(runner, migrationConfig, action, seedOptions);
-            yield runner.close();
             break;
           }
           default:
@@ -1740,9 +2643,25 @@ Returned ${results.length} row(s)`);
         if (error.stack && process.env.DEBUG) {
           console.error(error.stack);
         }
+        failed = true;
+      } finally {
+        try {
+          yield runner.close();
+        } catch (closeError) {
+          console.error(`Error closing connection: ${closeError.message}`);
+          failed = true;
+        }
+      }
+      if (failed) {
         process.exit(1);
       }
-    }));
+    })).catch((error) => {
+      console.error(`Error: ${error.message}`);
+      if (error.stack && process.env.DEBUG) {
+        console.error(error.stack);
+      }
+      process.exit(1);
+    });
     function printUsage() {
       console.log(`
 SQL Proper - Database migration tool
@@ -1755,6 +2674,7 @@ Commands:
   down     Roll back completed migrations
   reset    Roll back all migrations and reapply them
   create   Create a new migration
+  patch    Create a new ledger patch file (repairs migration history; no database access)
   init     Initialize a new config file
   status   Show migration status
   query    Execute a SQL query and display results
@@ -1773,6 +2693,7 @@ Examples:
   proper down --increment 3                    Roll back the last 3 applied migrations
   proper down --all                            Roll back all completed migrations
   proper create my_migration                   Create a new migration named "my_migration"
+  proper patch fix_renamed_keys                Scaffold a ledger patch file in the patch folder
   proper init                                  Create a new config file
   proper status                                Show the status of all migrations
   proper query "select * from users"           Execute a SQL query