@zincapp/znvault-migrate 1.0.0

package/dist/core/checksum.js

@@ -0,0 +1,30 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+export const CHECKSUM_ALGO = 'sha256-lf-v1';
+/**
+ * Compute the canonical sha256-lf-v1 checksum of a migration file buffer.
+ *
+ * Algorithm (byte-level — never decode to string):
+ *   1. Strip UTF-8 BOM (EF BB BF) at offset 0, if present.
+ *   2. Remove ALL 0x0D bytes (bare CR and CR in CRLF pairs).
+ *   3. SHA-256 the resulting bytes.
+ *   4. Return lowercase hex.
+ *
+ * This matches the Kotlin MigrationChecksummer implementation exactly.
+ */
+export function canonicalChecksum(buf) {
+    let b = buf;
+    // Strip UTF-8 BOM at offset 0
+    if (b.length >= 3 && b[0] === 0xef && b[1] === 0xbb && b[2] === 0xbf) {
+        b = b.subarray(3);
+    }
+    // Drop every 0x0D byte (CR), producing a pure-LF buffer
+    const lf = Buffer.from(b.filter((byte) => byte !== 0x0d));
+    return createHash('sha256').update(lf).digest('hex');
+}
+/**
+ * Read a migration file from disk and return its canonical sha256-lf-v1 checksum.
+ */
+export function canonicalChecksumFile(path) {
+    return canonicalChecksum(readFileSync(path));
+}

package/dist/core/checksum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.js","sourceRoot":"","sources":["../../src/core/checksum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,CAAC,MAAM,aAAa,GAAG,cAAc,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG,GAAG,CAAC;IACZ,8BAA8B;IAC9B,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACrE,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,wDAAwD;IACxD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC;IAC1D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,iBAAiB,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/core/migration-files.d.ts

@@ -0,0 +1,8 @@
+import type { MigrationFile } from './types.js';
+export type { MigrationFile };
+export declare class DuplicatePrefixError extends Error {
+    constructor(prefix: string, files: string[]);
+}
+export declare function parsePrefix(filename: string): string;
+export declare function discover(dir: string): MigrationFile[];
+//# sourceMappingURL=migration-files.d.ts.map

package/dist/core/migration-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-files.d.ts","sourceRoot":"","sources":["../../src/core/migration-files.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD,YAAY,EAAE,aAAa,EAAE,CAAC;AAC9B,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE;CAI5C;AACD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIpD;AACD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE,CASrD"}

package/dist/core/migration-files.js

@@ -0,0 +1,32 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const HELPER_RE = /^(0000)_[^/]*\.sql$/;
+const PREFIX_RE = /^(\d{4}-\d{2}-\d{2}_\d{3})_[^/]*\.sql$/;
+export class DuplicatePrefixError extends Error {
+    constructor(prefix, files) {
+        super(`Duplicate migration prefix '${prefix}': ${files.join(', ')}. Rename to unique monotonic prefixes.`);
+        this.name = 'DuplicatePrefixError';
+    }
+}
+export function parsePrefix(filename) {
+    const h = HELPER_RE.exec(filename);
+    if (h)
+        return h[1];
+    const p = PREFIX_RE.exec(filename);
+    if (p)
+        return p[1];
+    throw new Error(`Migration filename must match 0000_*.sql or YYYY-MM-DD_NNN_*.sql: ${filename}`);
+}
+export function discover(dir) {
+    const files = readdirSync(dir) // shallow — subdirs (baseline/, archive/) not descended
+        .filter((name) => name.endsWith('.sql') && statSync(join(dir, name)).isFile())
+        .map((name) => ({ version: name, prefix: parsePrefix(name), path: join(dir, name) }))
+        .sort((a, b) => (a.prefix < b.prefix ? -1 : a.prefix > b.prefix ? 1 : 0));
+    const byPrefix = new Map();
+    for (const f of files)
+        (byPrefix.get(f.prefix) ?? byPrefix.set(f.prefix, []).get(f.prefix)).push(f.version);
+    for (const [prefix, dups] of byPrefix)
+        if (dups.length > 1)
+            throw new DuplicatePrefixError(prefix, dups);
+    return files;
+}

package/dist/core/migration-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-files.js","sourceRoot":"","sources":["../../src/core/migration-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,MAAM,SAAS,GAAG,qBAAqB,CAAC;AACxC,MAAM,SAAS,GAAG,wCAAwC,CAAC;AAG3D,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,MAAc,EAAE,KAAe;QACzC,KAAK,CAAC,+BAA+B,MAAM,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;QAC3G,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AACD,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC,CAAE,CAAC;IACxD,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC,CAAE,CAAC;IACxD,MAAM,IAAI,KAAK,CAAC,qEAAqE,QAAQ,EAAE,CAAC,CAAC;AACnG,CAAC;AACD,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAkC,wDAAwD;SACrH,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SAC7E,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;SACpF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC7G,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,QAAQ;QAAE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,oBAAoB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzG,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/planner.d.ts

@@ -0,0 +1,36 @@
+import type { MigrationFile, MigrationRow, MigrationPlan } from './types.js';
+export type { MigrationPlan };
+export declare class ChecksumMismatchError extends Error {
+    constructor(version: string);
+}
+export declare class OrphanTrackedRowError extends Error {
+    constructor(version: string);
+}
+/**
+ * Build a migration plan by comparing discovered files against tracked DB rows.
+ *
+ * Ports MigrationPlanner.kt exactly:
+ *  - 0000_ helpers are skipped (applied unconditionally by the runner before planning).
+ *  - For each tracked row: if no matching file exists on disk → throw OrphanTrackedRowError
+ *    (migration history is immutable — a renamed/deleted file is a fatal integrity violation).
+ *  - For each tracked row: if the file's checksum differs from the stored checksum → throw
+ *    ChecksumMismatchError (migration history is immutable).
+ *  - File without a row → pending.
+ *  - Row with success=1 or baselined=1 → applied.
+ *  - Row with success=0 and baselined=0 → reconcile (crashed mid-run).
+ *
+ * @param files       Migration files for the CURRENT phase's directory (from
+ *                    discover()) — the set that gets classified into apply/reconcile/
+ *                    pending buckets.
+ * @param rows        All rows from schema_migrations (from repo.all()).
+ * @param checksumOf  Checksum function — injectable for unit tests (defaults to canonicalChecksumFile).
+ * @param allTrackedFiles  The UNION of every migration directory that shares this
+ *                    schema_migrations table (pre ∪ post). Used ONLY for the
+ *                    orphan/checksum integrity lookup, so a row applied in a sibling
+ *                    phase's directory is not mistaken for a renamed/deleted file.
+ *                    Defaults to `files` (single-directory configs are byte-identical
+ *                    to the pre-split behavior). Classification still uses `files`
+ *                    alone — the current phase only ever applies its own directory.
+ */
+export declare function plan(files: MigrationFile[], rows: MigrationRow[], checksumOf?: (path: string) => string, allTrackedFiles?: MigrationFile[]): MigrationPlan;
+//# sourceMappingURL=planner.d.ts.map

package/dist/core/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/core/planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG7E,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAM5B;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAM5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,IAAI,CAClB,KAAK,EAAE,aAAa,EAAE,EACtB,IAAI,EAAE,YAAY,EAAE,EACpB,UAAU,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAA8B,EAC5D,eAAe,GAAE,aAAa,EAAU,GACvC,aAAa,CA4Cf"}

package/dist/core/planner.js

@@ -0,0 +1,81 @@
+import { canonicalChecksumFile } from './checksum.js';
+export class ChecksumMismatchError extends Error {
+    constructor(version) {
+        super(`Checksum mismatch for already-applied migration '${version}' (immutable history)`);
+        this.name = 'ChecksumMismatchError';
+    }
+}
+export class OrphanTrackedRowError extends Error {
+    constructor(version) {
+        super(`Tracked migration '${version}' has no file on disk (renamed/deleted?). Refusing to proceed.`);
+        this.name = 'OrphanTrackedRowError';
+    }
+}
+/**
+ * Build a migration plan by comparing discovered files against tracked DB rows.
+ *
+ * Ports MigrationPlanner.kt exactly:
+ *  - 0000_ helpers are skipped (applied unconditionally by the runner before planning).
+ *  - For each tracked row: if no matching file exists on disk → throw OrphanTrackedRowError
+ *    (migration history is immutable — a renamed/deleted file is a fatal integrity violation).
+ *  - For each tracked row: if the file's checksum differs from the stored checksum → throw
+ *    ChecksumMismatchError (migration history is immutable).
+ *  - File without a row → pending.
+ *  - Row with success=1 or baselined=1 → applied.
+ *  - Row with success=0 and baselined=0 → reconcile (crashed mid-run).
+ *
+ * @param files       Migration files for the CURRENT phase's directory (from
+ *                    discover()) — the set that gets classified into apply/reconcile/
+ *                    pending buckets.
+ * @param rows        All rows from schema_migrations (from repo.all()).
+ * @param checksumOf  Checksum function — injectable for unit tests (defaults to canonicalChecksumFile).
+ * @param allTrackedFiles  The UNION of every migration directory that shares this
+ *                    schema_migrations table (pre ∪ post). Used ONLY for the
+ *                    orphan/checksum integrity lookup, so a row applied in a sibling
+ *                    phase's directory is not mistaken for a renamed/deleted file.
+ *                    Defaults to `files` (single-directory configs are byte-identical
+ *                    to the pre-split behavior). Classification still uses `files`
+ *                    alone — the current phase only ever applies its own directory.
+ */
+export function plan(files, rows, checksumOf = canonicalChecksumFile, allTrackedFiles = files) {
+    // Integrity lookup spans the UNION of all phase dirs that share the history table.
+    // A shared schema_migrations table (pre/ then post/ against one DB) means the
+    // post phase legitimately sees rows for pre/ migrations whose files live in the
+    // sibling directory — those must NOT be flagged as orphans.
+    const integrityByVersion = new Map(allTrackedFiles.filter((f) => !f.version.startsWith('0000_')).map((f) => [f.version, f]));
+    // Integrity pass (matches Kotlin MigrationPlanner.plan exactly, now union-scoped):
+    // Iterate every tracked row (non-0000_); throw on the first orphan or mismatch.
+    // This runs BEFORE bucket classification so no partially-classified plan is returned.
+    for (const row of rows) {
+        if (row.version.startsWith('0000_'))
+            continue; // helpers are never tracked
+        const f = integrityByVersion.get(row.version);
+        if (!f) {
+            throw new OrphanTrackedRowError(row.version);
+        }
+        if (checksumOf(f.path) !== row.checksum) {
+            throw new ChecksumMismatchError(row.version);
+        }
+    }
+    // Bucket classification — now safe: all tracked rows have a matching file.
+    const rowByVersion = new Map(rows.map((r) => [r.version, r]));
+    const applied = [];
+    const reconcile = [];
+    const pending = [];
+    for (const f of files) {
+        // 0000_ helpers are re-applied every run and are never tracked/planned.
+        if (f.version.startsWith('0000_'))
+            continue;
+        const row = rowByVersion.get(f.version);
+        if (!row) {
+            pending.push(f);
+        }
+        else if (row.success || row.baselined) {
+            applied.push(f);
+        }
+        else {
+            reconcile.push(f);
+        }
+    }
+    return { applied, reconcile, pending };
+}

package/dist/core/planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.js","sourceRoot":"","sources":["../../src/core/planner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAItD,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CACH,oDAAoD,OAAO,uBAAuB,CACnF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CACH,sBAAsB,OAAO,gEAAgE,CAC9F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,IAAI,CAClB,KAAsB,EACtB,IAAoB,EACpB,aAAuC,qBAAqB,EAC5D,kBAAmC,KAAK;IAExC,mFAAmF;IACnF,8EAA8E;IAC9E,gFAAgF;IAChF,4DAA4D;IAC5D,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAChC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CACzF,CAAC;IAEF,mFAAmF;IACnF,gFAAgF;IAChF,sFAAsF;IACtF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS,CAAC,4BAA4B;QAC3E,MAAM,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,IAAI,qBAAqB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,QAAQ,EAAE,CAAC;YACxC,MAAM,IAAI,qBAAqB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,MAAM,SAAS,GAAoB,EAAE,CAAC;IACtC,MAAM,OAAO,GAAoB,EAAE,CAAC;IAEpC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,wEAAwE;QACxE,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS;QAE5C,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;aAAM,IAAI,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AACzC,CAAC"}

package/dist/core/runner.d.ts

@@ -0,0 +1,159 @@
+import type { EngineAdapter, Conn } from '../adapters/engine-adapter.js';
+import type { RunResult } from './types.js';
+export type { RunResult };
+/**
+ * Orchestrates migration discovery, planning, locking, and execution.
+ *
+ * Ports MigrationRunner.kt + MigrateMain.kt orchestration EXACTLY:
+ *  - status(): read-only — ensureTable + plan; preflight(version-check only).
+ *  - run(): write path — preflight(requireWritePrimary=true) → ensureTable (before lock,
+ *    Kotlin parity) → acquire → seedIfVirgin → plan → reconcile → pending → release.
+ *
+ * `zn_*` helper procedures (0000_ files) are NOT created by this engine — see the
+ * doc comment on run() for details.
+ *
+ * Engine-agnostic core: the six MySQL-specific collaborators (preflight, lock
+ * acquire/isHeld/release, migration-file apply, reconcile, definer-object cleanup,
+ * schema_migrations repo) are delegated to an injected `EngineAdapter` operating
+ * on a live `Conn`. The runner's own control flow — ordering, guards, error
+ * strings — is unchanged from the MySQL-only source.
+ */
+export declare class MigrationRunner {
+    private readonly adapter;
+    private readonly conn;
+    private readonly migrationsDir;
+    private readonly appliedBy;
+    private readonly integrityDirs;
+    private readonly scaffolding?;
+    private repo;
+    /**
+     * @param adapter        The engine adapter — implements the six MySQL-specific
+     *                       collaborators (preflight, lock, migration-file apply,
+     *                       reconcile, definer-object cleanup, schema_migrations repo).
+     * @param conn           The live connection the adapter's methods operate on.
+     * @param migrationsDir  The CURRENT phase's migrations directory — the one whose
+     *                       files are classified and applied.
+     * @param appliedBy      The applied-by identity recorded on each row.
+     * @param integrityDirs  Additional directories that share this DB's
+     *                       schema_migrations history (the OTHER migration phase's dir,
+     *                       e.g. the pre/ dir when this runner is running post/). Used
+     *                       only to widen the orphan/checksum integrity lookup so a row
+     *                       applied by a sibling phase is not mistaken for a
+     *                       renamed/deleted file. Defaults to none (single-dir configs).
+     * @param scaffolding    Optional migration-helper scaffolding config for THIS phase.
+     *                       When set, `run()` applies `<migrationsDir>/<filename>` at the
+     *                       start of the phase (after discover(), before seeding/reconcile/
+     *                       pending) and, unconditionally, drops every object the given
+     *                       `leaseUser` defined once the reconcile+pending work concludes
+     *                       (success or failure) — see the ordering note on run(). Undefined
+     *                       (the default) means no scaffolding: byte-identical to the
+     *                       pre-scaffolding runner.
+     */
+    constructor(adapter: EngineAdapter, conn: Conn, migrationsDir: string, appliedBy: string, integrityDirs?: string[], scaffolding?: {
+        filename: string;
+        leaseUser: string;
+    } | undefined);
+    /**
+     * Build the union of migration files across this phase's dir and any sibling
+     * integrity dirs (pre ∪ post), for the planner's integrity lookup. Missing dirs
+     * are skipped defensively (discover() throws on a non-existent path). If two dirs
+     * ever declare the same version prefix, the current phase's file wins the lookup.
+     */
+    private allTrackedFiles;
+    /**
+     * Read-only status: how many migrations are in each state.
+     * Does NOT acquire the lock or apply any helpers.
+     * Mirrors MigrateMain: preflight(requireWritePrimary=false) for 'status'.
+     */
+    status(): Promise<{
+        applied: number;
+        reconcile: number;
+        pending: number;
+    }>;
+    /**
+     * Apply all pending and reconcile migrations.
+     *
+     * Order (load-bearing — matches Kotlin MigrationRunner.run() exactly):
+     *  1. preflight(requireWritePrimary=true) — refuse read-only replicas.
+     *  2. ensureTable() BEFORE the lock (the only pre-lock mutation, per Kotlin parity).
+     *  3. acquire(db) — GET_LOCK.
+     *  3a. scaffolding (if configured) — apply THIS phase's helper objects (migration_utils.sql
+     *      or equivalent) before any seeding/reconcile/pending work touches the DB.
+     *  4. seedBaselineIfVirgin — seed baselined rows when schema_migrations is empty.
+     *  5. plan() — classify remaining files.
+     *  6. reconcile — asserts-first; re-run body only when unmet or no asserts.
+     *  7. pending — claim(success=0) → exec → markSuccess(success=1).
+     *  7a. finally (nested, scoped to 6+7): scaffolding cleanup — if configured and the
+     *      lock is still held, drop every object the lease user defined
+     *      (dropDefinerObjects), unconditionally — runs whether 6/7 succeeded or threw.
+     *      A cleanup failure is logged, never rethrown (must not mask a primary error).
+     *      The lock-held check itself (lockHeld()) is also non-throwing — a dead
+     *      connection can make the underlying IS_USED_LOCK query reject rather than
+     *      resolve false, and this guard must not mask a primary error either.
+     *  8. finally: release lock; if release was not clean and no primary error, throw tripwire.
+     *
+     * The `zn_*` helper procedures (0000_ files) are NO LONGER created here. They are
+     * now provisioned ahead of the migration phase by vault's routines-apply step,
+     * owned by a persistent routines DB account — see the vault-side dynsec-routines-
+     * provisioning feature (docs/superpowers/specs/2026-07-01-dynsec-routines-
+     * provisioning-design.md). Root cause: DROP+CREATE'ing them here made the
+     * ephemeral migrate user their DEFINER, and MySQL 8.4 refuses `DROP USER` for an
+     * account referenced as a stored-routine DEFINER (ER 4006) — which broke lease
+     * revocation on every migration run. Migrations now only `CALL zn_*`; they never
+     * (re)create the procedures themselves.
+     */
+    run(): Promise<RunResult>;
+    /**
+     * Abort immediately if this session no longer holds the GET_LOCK.
+     * A killed session or proxy reconnect would silently drop the lock server-side.
+     */
+    private requireLockHeld;
+    /**
+     * Non-throwing counterpart to requireLockHeld() — used by cleanup paths (e.g.
+     * scaffolding's finally block) that must NOT touch the DB once the lock is lost,
+     * but also must not themselves throw while already unwinding another error.
+     *
+     * `lock.isHeld()` runs `SELECT IS_USED_LOCK(...)`, which can itself REJECT on a
+     * dead connection (killed session / proxy reconnect — exactly the scenario this
+     * guard exists for), not just resolve to false. Since callers await this from a
+     * `finally` block, an unswallowed rejection here would replace/mask whatever
+     * primary error is already in flight (a throwing `finally` overrides the pending
+     * exception). Treat any error the same as "lock not held": skip the guarded
+     * cleanup rather than risk touching a possibly-dead connection or masking the
+     * real error.
+     */
+    private lockHeld;
+    /**
+     * Execute every SQL statement in a file (text protocol, one at a time).
+     * A failed CALL zn_assert_* signals SIGNAL '45000', which propagates as an
+     * Error and leaves any pending claim row at success=0.
+     *
+     * The split+per-statement-execute logic lives on the adapter (`applyMigrationFile`)
+     * — core only reads the file and hands the SQL text over.
+     */
+    private executeStatements;
+    /**
+     * Reconcile a success=0 row per spec step 7a.
+     *
+     * Run the file's trailing CALL zn_assert_* postconditions FIRST:
+     *  - If they exist and all pass → the migration is already fully applied;
+     *    markSuccess WITHOUT re-running the body (avoids double-apply hazard for
+     *    non-idempotent bodies).
+     *  - If there are no asserts, OR any assert throws → re-run the ENTIRE
+     *    (idempotent) body, then markSuccess.
+     *
+     * The asserts-first logic (and the requireLockHeld() guard before markSuccess)
+     * lives on the adapter (`reconcile`) — core only reads the file, derives the
+     * version, and delegates.
+     */
+    private reconcile;
+    /**
+     * Seed baselined rows for a virgin DB (schema_migrations has no rows yet).
+     *
+     * Reads the BASELINE_MARKER from baseline/00-baseline-schema.sql and seeds
+     * a baselined row for every non-0000_ file whose prefix <= the marker.
+     * Returns the number of rows seeded.
+     */
+    private seedBaselineIfVirgin;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/core/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/core/runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAwB,MAAM,+BAA+B,CAAC;AAK/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IA2BxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IA/B/B,OAAO,CAAC,IAAI,CAAuB;IAEnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBAEgB,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAM,EAAO,EAC5B,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,YAAA;IAKxE;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAWvB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAQhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,GAAG,IAAI,OAAO,CAAC,SAAS,CAAC;IAoG/B;;;OAGG;YACW,eAAe;IAQ7B;;;;;;;;;;;;;OAaG;YACW,QAAQ;IAatB;;;;;;;OAOG;YACW,iBAAiB;IAK/B;;;;;;;;;;;;;OAaG;YACW,SAAS;IAMvB;;;;;;OAMG;YACW,oBAAoB;CAcnC"}