@zincapp/znvault-migrate 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# @zincapp/znvault-migrate
+
+Shared **MySQL** schema-migration library for ZnVault deployer tooling.
+
+Extracts the migration engine (discover `.sql` files → plan pending/reconcile →
+acquire lock → apply scaffolding helpers → run → reconcile → drop scaffolding →
+track in `schema_migrations`) behind an engine-agnostic `EngineAdapter`
+interface, so multiple deployer plugins and the `znvault` CLI can share one
+proven migration runner.
+
+> **Scope: MySQL only.** The `EngineAdapter` interface is engine-agnostic so a
+> PostgreSQL adapter can be added later, but **no PostgreSQL adapter is built
+> here** — `engine: 'postgres'` errors at validation. (PostgreSQL has an
+> unsolved ownership-transfer-on-revoke problem that gets its own design.)
+
+## Install
+
+```bash
+npm install @zincapp/znvault-migrate
+```
+
+## What it provides
+
+- **`runMigrations(ctx, opts, deps)`** — the top-level entrypoint: mints a
+  dynamic-secrets lease, opens a dedicated connection via the engine adapter,
+  runs the migration engine, and revokes the lease (with a settle delay,
+  revoke-retry, and SIGINT/SIGTERM handlers).
+- **`MigrationRunner`** — the engine-agnostic orchestrator (`run()` / `status()`).
+- **`mysqlAdapter`** — the MySQL `EngineAdapter` implementation.
+- **`validateMigrationConfig(cfg)`** / **`MigrationConfig`** — config schema +
+  validation (`engine` is required; `engine: 'postgres'` is rejected).
+
+## Credential model
+
+Credentials come **only** from a ZnVault dynamic-secrets lease (config carries a
+`roleId`; there are no raw connection-string options). Every run mints an
+ephemeral, audited lease and revokes it on exit — preserving the clean-revoke
+posture the scaffolding design depends on.
+
+## MySQL scaffolding (ER-4006)
+
+MySQL's `DROP USER` fails (ER-4006 on 8.4) if the user is the `DEFINER` of any
+stored routine. When a `scaffoldingFile` is configured, the lease user creates
+the helper procedures at phase start and the runner drops every object that user
+defines at phase end — so the ephemeral migrate user owns nothing on revoke and
+`DROP USER` is always clean.
+
+## Development
+
+```bash
+npm install
+npm run build       # tsc
+npm test            # vitest run (real-MySQL e2e self-skips without MYSQL_TEST_HOST)
+npm run typecheck
+npm run lint
+
+# Run the real-MySQL-8.4 e2e + integration tests against a local MySQL:
+MYSQL_TEST_HOST=127.0.0.1 MYSQL_TEST_PORT=33306 MYSQL_TEST_DB=zincdb \
+  MYSQL_TEST_USER=root MYSQL_TEST_PASSWORD=root npm test
+```
+
+## Release
+
+Publishing is handled by GitHub Actions on a version tag (OIDC Trusted
+Publishing — no npm token):
+
+```bash
+npm version patch   # or minor/major
+git push origin main --tags
+```
+
+## License
+
+MIT

package/dist/adapters/engine-adapter.d.ts

@@ -0,0 +1,91 @@
+import type { MigrationRow } from '../core/types.js';
+/** A live DB connection handle. */
+export interface Conn {
+    /**
+     * Returns result ROWS DIRECTLY (unwrapped) — NOT a driver `[rows, meta]` tuple.
+     *
+     * DELIBERATE DIVERGENCE from dynamic-secrets `DatabaseClient.query()` (which returns a
+     * `[rows, meta]` tuple, `types.ts:35`). ROWS-DIRECTLY is chosen because the existing plugin
+     * runner already assumes it (`migrate/db.ts:85-88` unwraps the mysql2 tuple before returning)
+     * and every core-runner call site expects rows. The adapter MUST unwrap its driver's result
+     * to rows before returning. This exact tuple-vs-rows mismatch caused a real Critical bug before
+     * (`scaffolding.ts:25-34`), so it is pinned. We mirror db-clients' STRUCTURE, NOT its query shape.
+     */
+    query(sql: string, params?: unknown[]): Promise<unknown[]>;
+    end(): Promise<void>;
+}
+export interface SchemaMigrationsRepo {
+    ensureTable(): Promise<void>;
+    all(): Promise<MigrationRow[]>;
+    claim(version: string, checksum: string, appliedBy: string): Promise<void>;
+    markSuccess(version: string, executionMs: number): Promise<void>;
+    seedBaseline(version: string, checksum: string, appliedBy: string): Promise<void>;
+}
+export interface EngineCredentials {
+    host: string;
+    port: number;
+    database: string;
+    user: string;
+    password: string;
+    ssl?: boolean;
+}
+/**
+ * The engine seam. Only 'mysql' is implemented in this project; 'postgres' is a valid literal
+ * so the interface is future-ready, but building a PG adapter is DEFERRED (§11).
+ */
+export interface EngineAdapter {
+    readonly engine: 'mysql' | 'postgres';
+    /** Open a DEDICATED (non-pool) connection — session-scoped locks require it. */
+    openConnection(creds: EngineCredentials): Promise<Conn>;
+    /**
+     * Version check + optionally refuse a read-only/replica target. Engine SQL. Throws on unsafe target.
+     * `requireWritePrimary`: true for a migrate run (reject a read-only replica), false for `status()`
+     * (allow read-only). MUST preserve the existing two-mode behavior — `db.ts:113-115`,
+     * called `preflight(db, true)` for migrate and `preflight(db, false)` for status
+     * (`migration-runner.ts:87-89`). Dropping this flag would make `status()` wrongly reject replicas.
+     */
+    preflight(conn: Conn, requireWritePrimary: boolean): Promise<void>;
+    /** Session-scoped migration lock. acquire throws on busy/timeout. */
+    acquireLock(conn: Conn): Promise<void>;
+    lockHeld(conn: Conn): Promise<boolean>;
+    /**
+     * Release the lock. Returns TRUE if the lock was cleanly held-and-released, FALSE if it was NOT
+     * held at release time (a lost-lock signal). MUST NOT throw. The core runner uses the boolean:
+     * if release returns false AND no primary error occurred, the runner throws
+     * "Lock was not held at release — a concurrent runner may have run" (the lost-lock tripwire —
+     * `migration-lock.ts:70-86`, `migration-runner.ts:218-223`). Returning `Promise<void>` would
+     * erase this concurrency-corruption signal — do NOT simplify it away.
+     */
+    releaseLock(conn: Conn): Promise<boolean>;
+    /** Apply one migration file. mysql: split into statements + execute each. */
+    applyMigrationFile(conn: Conn, sql: string): Promise<void>;
+    /**
+     * Reconcile a file whose tracking row is success=0 (claimed-but-not-confirmed — a crash between
+     * claim and confirm). Takes the file's `version` (derived by the core runner from the path) and
+     * the `SchemaMigrationsRepo` so the adapter can `markSuccess(version, 0)` when the postconditions
+     * pass — this matches the existing `reconcile(path)` at `migration-runner.ts:321-348` which derives
+     * the version and calls `repo.markSuccess(version, 0)`. mysql: re-run only the trailing
+     * `CALL zn_assert_*` postconditions; if they pass, the migration already applied → `markSuccess`
+     * without re-executing.
+     */
+    reconcile(conn: Conn, version: string, fileSql: string, repo: SchemaMigrationsRepo): Promise<void>;
+    schemaMigrationsRepo(conn: Conn): SchemaMigrationsRepo;
+    /**
+     * REQUIRED — the "leave the migrate user droppable" teardown (§2.3). Runs at phase end (in the
+     * finally, if the lock is still held) — but ONLY WHEN SCAFFOLDING IS CONFIGURED (see the runner
+     * contract below; the current runner only drops definer objects inside the scaffolding bracket —
+     * `migration-runner.ts:194-196`, pinned by `test/migrate/migration-runner.scaffolding.test.ts:327-339`).
+     *  - mysql: drop every object the lease user is the DEFINER of (dropDefinerObjects sweep); returns count.
+     *  (A future PG adapter would implement its OWN teardown here — §11 — NOT built in this project.)
+     */
+    dropOwnedObjects(conn: Conn, leaseUser: string): Promise<number>;
+    /**
+     * Read + split the scaffolding file into helper statements, and apply them as the lease user
+     * (MySQL). Takes the RESOLVED scaffolding file path (the core runner resolves `scaffoldingFile`
+     * against `migrationsDir` — the bare-vs-absolute rule — but the READING+SPLITTING is MySQL-specific,
+     * `readScaffoldingSql`/`scaffolding.ts:13-22`, so it lives on the adapter, not core). Absent on a
+     * PG adapter → the scaffolding bracket is a no-op.
+     */
+    applyScaffolding?(conn: Conn, scaffoldingFilePath: string): Promise<void>;
+}
+//# sourceMappingURL=engine-adapter.d.ts.map

package/dist/adapters/engine-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/engine-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,mCAAmC;AACnC,MAAM,WAAW,IAAI;IACnB;;;;;;;;;OASG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,GAAG,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CAC7F;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,CAAC;IAEtC,gFAAgF;IAChF,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,qEAAqE;IACrE,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1C,6EAA6E;IAC7E,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;;;;;OAQG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnG,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,oBAAoB,CAAC;IAEvD;;;;;;;OAOG;IACH,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAGjE;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E"}

package/dist/adapters/engine-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/engine-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-adapter.js","sourceRoot":"","sources":["../../src/adapters/engine-adapter.ts"],"names":[],"mappings":""}

package/dist/adapters/mysql/connection.d.ts

@@ -0,0 +1,30 @@
+import type { Conn, EngineCredentials } from '../engine-adapter.js';
+/**
+ * Open a single MySQL connection (NOT a pool — pools can silently reconnect
+ * and would drop the session-scoped GET_LOCK).
+ *
+ * Security / integrity contracts:
+ *  - Asserts that the LIVE session has @@autocommit = 1 (not just a config flag).
+ *  - Captures CONNECTION_ID() and exposes it as db.connectionId so callers can
+ *    verify lock ownership via IS_USED_LOCK.
+ *  - Sets time_zone = '+00:00' so applied_at timestamps are UTC.
+ *  - Redacts the password from any connection error before re-throwing.
+ *  - multipleStatements: false to prevent SQL-injection via DDL concatenation.
+ *
+ * Ported VERBATIM from znvault-plugin-payara/src/migrate/db.ts's `openDb`. The only
+ * change is the input type: `EngineCredentials.ssl` is `boolean | undefined` (vs. the
+ * source `DbConfig.ssl: boolean`) — `undefined` is treated as falsy, same as `ssl: false`.
+ */
+export declare function openConnection(creds: EngineCredentials): Promise<Conn>;
+/**
+ * Pre-migration safety checks against the LIVE connection. Ports
+ * ConnectionFactory.preflight: requires MySQL 8+, and (when requireWritePrimary)
+ * refuses to run against a read-only replica (SELECT @@read_only === 1).
+ *
+ * Call with requireWritePrimary=true for `migrate`, false for `status`.
+ *
+ * Ported VERBATIM from znvault-plugin-payara/src/migrate/db.ts's `preflight`. Only
+ * uses `conn.query`, so it works against the plain engine-agnostic `Conn`.
+ */
+export declare function preflight(conn: Conn, requireWritePrimary: boolean): Promise<void>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/adapters/mysql/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/adapters/mysql/connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGpE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwE5E;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BvF"}

package/dist/adapters/mysql/connection.js

@@ -0,0 +1,132 @@
+import mysql from 'mysql2/promise';
+/**
+ * Open a single MySQL connection (NOT a pool — pools can silently reconnect
+ * and would drop the session-scoped GET_LOCK).
+ *
+ * Security / integrity contracts:
+ *  - Asserts that the LIVE session has @@autocommit = 1 (not just a config flag).
+ *  - Captures CONNECTION_ID() and exposes it as db.connectionId so callers can
+ *    verify lock ownership via IS_USED_LOCK.
+ *  - Sets time_zone = '+00:00' so applied_at timestamps are UTC.
+ *  - Redacts the password from any connection error before re-throwing.
+ *  - multipleStatements: false to prevent SQL-injection via DDL concatenation.
+ *
+ * Ported VERBATIM from znvault-plugin-payara/src/migrate/db.ts's `openDb`. The only
+ * change is the input type: `EngineCredentials.ssl` is `boolean | undefined` (vs. the
+ * source `DbConfig.ssl: boolean`) — `undefined` is treated as falsy, same as `ssl: false`.
+ */
+export async function openConnection(creds) {
+    let conn;
+    try {
+        conn = await mysql.createConnection({
+            host: creds.host,
+            port: creds.port,
+            database: creds.database,
+            user: creds.user,
+            password: creds.password,
+            // Kotlin's ConnectionFactory uses sslMode=REQUIRED — encrypt but do NOT verify the
+            // server certificate (REQUIRED ≠ VERIFY_CA). mysql2's `ssl: {}` defaults to
+            // rejectUnauthorized:true (verify against the system CA store), which FAILS against
+            // the prod MySQL's internal CA ("unable to verify the first certificate"). Match
+            // Kotlin: encrypt without cert verification. (Local/e2e uses ssl:false/undefined.)
+            ssl: creds.ssl ? { rejectUnauthorized: false } : undefined,
+            multipleStatements: false,
+            // connector-j 9.x note: on the SSL-disabled path (dev/e2e) allowPublicKeyRetrieval
+            // is needed for caching_sha2_password auth. The mysql2 driver handles this
+            // transparently when ssl is not set.
+            supportBigNumbers: true,
+            bigNumberStrings: false, // BIGINT execution_ms comes back as JS number
+            timezone: 'Z',
+        });
+    }
+    catch (e) {
+        throw redact(e);
+    }
+    try {
+        // 1. Assert LIVE autocommit — a config flag is NOT sufficient; a MySQL Router
+        //    or session carryover could leave it 0.
+        const [acRows] = (await conn.query('SELECT @@autocommit AS ac'));
+        const acValue = acRows[0]?.ac;
+        if (Number(acValue) !== 1) {
+            throw new Error('Target session does not have autocommit=1 — refusing to open a migration connection');
+        }
+        // 2. Set time_zone so TS-written applied_at values match the convention.
+        await conn.query("SET time_zone = '+00:00'");
+        // 3. Capture CONNECTION_ID immediately; expose it for lock ownership checks.
+        const [cidRows] = (await conn.query('SELECT CONNECTION_ID() AS id'));
+        const connectionId = Number(cidRows[0]?.id);
+        const db = {
+            connectionId,
+            // Text protocol — required for the migration DDL path (multipleStatements guard above).
+            query: async (sql, params) => {
+                const [rows] = await conn.query(sql, params);
+                return rows;
+            },
+            // Prepared statement path — used for parameterized metadata queries in repo.
+            // Returns raw tuple [OkPacket|rows, fields] so callers can inspect affectedRows
+            // for DML statements (UPDATE/INSERT) as well as row data for SELECT statements.
+            execute: async (sql, params) => {
+                // Cast to the driver's stricter `ExecuteValues[]` param type — mysql2 3.22.x
+                // narrowed this overload vs. the 3.16.x pinned in the source plugin; the
+                // interface contract here (unknown[]) is intentionally broader, and mysql2
+                // itself just serializes each value at runtime, so this cast changes no
+                // behavior, only satisfies stricter compile-time types.
+                const result = await conn.execute(sql, params);
+                return result;
+            },
+            end: () => conn.end(),
+        };
+        return db;
+    }
+    catch (e) {
+        await conn.end().catch(() => {
+            // best-effort close; swallow error
+        });
+        throw redact(e);
+    }
+}
+/**
+ * Pre-migration safety checks against the LIVE connection. Ports
+ * ConnectionFactory.preflight: requires MySQL 8+, and (when requireWritePrimary)
+ * refuses to run against a read-only replica (SELECT @@read_only === 1).
+ *
+ * Call with requireWritePrimary=true for `migrate`, false for `status`.
+ *
+ * Ported VERBATIM from znvault-plugin-payara/src/migrate/db.ts's `preflight`. Only
+ * uses `conn.query`, so it works against the plain engine-agnostic `Conn`.
+ */
+export async function preflight(conn, requireWritePrimary) {
+    // 1. MySQL >= 8.0.0
+    //    SELECT VERSION() → e.g. "8.4.10" or "8.4.10-mysql": take the part before '-',
+    //    split on '.', compare major/minor/patch as the Kotlin does.
+    const versionRows = await conn.query('SELECT VERSION() AS v');
+    const versionValue = versionRows[0]?.v;
+    const versionStr = String(versionValue).split('-')[0] ?? '';
+    const parts = versionStr.split('.').map((p) => Number(p) || 0);
+    const major = parts[0] ?? 0;
+    const minor = parts[1] ?? 0;
+    const patch = parts[2] ?? 0;
+    // Replicate the Kotlin three-way compare: major>8 || (major==8 && minor>0) || (major==8 && minor==0 && patch>=0)
+    // which simplifies to: major > 8 || major === 8 (i.e. major >= 8).
+    const atLeast8 = major > 8 || (major === 8 && (minor > 0 || (minor === 0 && patch >= 0)));
+    if (!atLeast8) {
+        throw new Error('MySQL 8+ required');
+    }
+    // 2. Refuse to run DDL against a read-only replica.
+    if (requireWritePrimary) {
+        const roRows = await conn.query('SELECT @@read_only AS ro');
+        const roValue = roRows[0]?.ro;
+        if (Number(roValue) === 1) {
+            throw new Error('Target is read-only (not the write primary). Refusing to migrate.');
+        }
+    }
+}
+/**
+ * Redact the password from any error message so it never leaks in logs/traces.
+ */
+function redact(e) {
+    const err = e instanceof Error ? e : new Error(String(e));
+    const safe = new Error(err.message.replace(/password\s*[:=]\s*'[^']*'/gi, "password:'***'"));
+    safe.stack = err.stack?.replace(/password\s*[:=]\s*'[^']*'/gi, "password:'***'");
+    return safe;
+}

package/dist/adapters/mysql/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../src/adapters/mysql/connection.ts"],"names":[],"mappings":"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"}

package/dist/adapters/mysql/lock.d.ts

@@ -0,0 +1,41 @@
+import type { MysqlConn } from './mysql-conn.js';
+export declare const LOCK_KEY = "zincapp_migration";
+export declare class MigrationLockBusyError extends Error {
+    constructor(msg: string);
+}
+export declare class MigrationLockError extends Error {
+    constructor(msg: string);
+}
+/**
+ * Acquire the named session-scoped migration lock via GET_LOCK.
+ *
+ * GET_LOCK return values:
+ *   1    → lock acquired successfully
+ *   0    → timed out waiting (another session holds it) → throws MigrationLockBusyError
+ *   NULL → error (OOM, connection error, etc.)          → throws MigrationLockError
+ *
+ * @param db             An open Db connection.
+ * @param timeoutSeconds How long to wait for the lock (default 30s, matching Kotlin).
+ */
+export declare function acquire(db: MysqlConn, timeoutSeconds?: number): Promise<void>;
+/**
+ * Check whether THIS connection's session still holds the migration lock.
+ *
+ * Uses `IS_USED_LOCK(?) = ?` with the captured CONNECTION_ID so we verify
+ * that the lock is held by THIS specific session — not just by any session.
+ * A MySQL Router / wait_timeout eviction would silently drop the lock server-side
+ * and this function would correctly return false even if the same code path
+ * reconnected with a new session.
+ *
+ * @param db An open Db connection (must be the same connection that called acquire).
+ */
+export declare function isHeld(db: MysqlConn): Promise<boolean>;
+/**
+ * Release the migration lock. NEVER throws — this is designed to run in a
+ * finally block and must not mask any in-flight migration exception.
+ *
+ * @returns true if the lock was cleanly released; false if the lock was not
+ *          held at release time (possible lost session or concurrent runner).
+ */
+export declare function release(db: MysqlConn): Promise<boolean>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/adapters/mysql/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/adapters/mysql/lock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,eAAO,MAAM,QAAQ,sBAAsB,CAAC;AAE5C,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,GAAG,EAAE,MAAM;CAIxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,cAAc,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ5D;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAiB7D"}

package/dist/adapters/mysql/lock.js

@@ -0,0 +1,77 @@
+export const LOCK_KEY = 'zincapp_migration';
+export class MigrationLockBusyError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = 'MigrationLockBusyError';
+    }
+}
+export class MigrationLockError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = 'MigrationLockError';
+    }
+}
+/**
+ * Acquire the named session-scoped migration lock via GET_LOCK.
+ *
+ * GET_LOCK return values:
+ *   1    → lock acquired successfully
+ *   0    → timed out waiting (another session holds it) → throws MigrationLockBusyError
+ *   NULL → error (OOM, connection error, etc.)          → throws MigrationLockError
+ *
+ * @param db             An open Db connection.
+ * @param timeoutSeconds How long to wait for the lock (default 30s, matching Kotlin).
+ */
+export async function acquire(db, timeoutSeconds = 30) {
+    const rows = await db.query('SELECT GET_LOCK(?, ?)', [LOCK_KEY, timeoutSeconds]);
+    // mysql2 returns the result column by its expression text; extract robustly
+    const cell = Object.values(rows[0])[0];
+    if (cell === null || cell === undefined) {
+        throw new MigrationLockError(`GET_LOCK returned NULL (connection/server error)`);
+    }
+    if (Number(cell) !== 1) {
+        throw new MigrationLockBusyError(`Another migration runner holds '${LOCK_KEY}' (GET_LOCK returned 0)`);
+    }
+}
+/**
+ * Check whether THIS connection's session still holds the migration lock.
+ *
+ * Uses `IS_USED_LOCK(?) = ?` with the captured CONNECTION_ID so we verify
+ * that the lock is held by THIS specific session — not just by any session.
+ * A MySQL Router / wait_timeout eviction would silently drop the lock server-side
+ * and this function would correctly return false even if the same code path
+ * reconnected with a new session.
+ *
+ * @param db An open Db connection (must be the same connection that called acquire).
+ */
+export async function isHeld(db) {
+    const rows = await db.query('SELECT IS_USED_LOCK(?) = ? AS held', [LOCK_KEY, db.connectionId]);
+    const cell = rows[0]['held'];
+    if (cell === null || cell === undefined) {
+        // NULL means no session holds the lock at all
+        return false;
+    }
+    return Number(cell) === 1;
+}
+/**
+ * Release the migration lock. NEVER throws — this is designed to run in a
+ * finally block and must not mask any in-flight migration exception.
+ *
+ * @returns true if the lock was cleanly released; false if the lock was not
+ *          held at release time (possible lost session or concurrent runner).
+ */
+export async function release(db) {
+    try {
+        const rows = await db.query('SELECT RELEASE_LOCK(?) AS released', [LOCK_KEY]);
+        const cell = rows[0]['released'];
+        const released = cell !== null && cell !== undefined && Number(cell) === 1;
+        if (!released) {
+            console.warn(`RELEASE_LOCK('${LOCK_KEY}') returned ${String(cell)} — lock was not held at release (lost session / concurrent runner?)`);
+        }
+        return released;
+    }
+    catch (e) {
+        console.warn(`RELEASE_LOCK('${LOCK_KEY}') failed (connection likely dead): ${e instanceof Error ? e.message : String(e)}`);
+        return false;
+    }
+}

package/dist/adapters/mysql/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/adapters/mysql/lock.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,QAAQ,GAAG,mBAAmB,CAAC;AAE5C,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,GAAW;QACrB,KAAK,CAAC,GAAG,CAAC,CAAC;QACX,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,GAAW;QACrB,KAAK,CAAC,GAAG,CAAC,CAAC;QACX,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,EAAa,EAAE,cAAc,GAAG,EAAE;IAC9D,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,uBAAuB,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC;IACjF,4EAA4E;IAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAA4B,CAAC,CAAC,CAAC,CAAC,CAAC;IAClE,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,IAAI,kBAAkB,CAAC,kDAAkD,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,sBAAsB,CAAC,mCAAmC,QAAQ,yBAAyB,CAAC,CAAC;IACzG,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,EAAa;IACxC,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,oCAAoC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAI,IAAI,CAAC,CAAC,CAA6B,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxC,8CAA8C;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,EAAa;IACzC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,oCAAoC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC9E,MAAM,IAAI,GAAI,IAAI,CAAC,CAAC,CAA6B,CAAC,UAAU,CAAC,CAAC;QAC9D,MAAM,QAAQ,GAAG,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3E,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CACV,iBAAiB,QAAQ,eAAe,MAAM,CAAC,IAAI,CAAC,qEAAqE,CAC1H,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CACV,iBAAiB,QAAQ,uCAAuC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAC7G,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/adapters/mysql/mysql-adapter.d.ts

@@ -0,0 +1,11 @@
+import type { EngineAdapter } from '../engine-adapter.js';
+/**
+ * The concrete MySQL EngineAdapter. Wires the already-ported leaf modules
+ * (lock, sql-splitter, scaffolding, schema-migrations-repo) and this file's
+ * connection.ts into the engine-agnostic `EngineAdapter` interface consumed by
+ * `core/runner.ts`. No new logic beyond delegation — the split-execute apply
+ * logic and the asserts-first reconcile logic are relocated verbatim from the
+ * source `migration-runner.ts` (`executeStatements` / `reconcile`).
+ */
+export declare const mysqlAdapter: EngineAdapter;
+//# sourceMappingURL=mysql-adapter.d.ts.map

package/dist/adapters/mysql/mysql-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/mysql/mysql-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,aAAa,EAAoE,MAAM,sBAAsB,CAAC;AAiBlI;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,aA+H1B,CAAC"}

package/dist/adapters/mysql/mysql-adapter.js

@@ -0,0 +1,130 @@
+import { openConnection, preflight } from './connection.js';
+import * as lock from './lock.js';
+import { splitStatements } from './sql-splitter.js';
+import { readScaffoldingSql, dropDefinerObjects } from './scaffolding.js';
+import { SchemaMigrationsRepo } from './schema-migrations-repo.js';
+/**
+ * True when a statement is a postcondition assertion call (zn_assert_* proc).
+ * MySQL-convention detection, relocated verbatim from
+ * znvault-plugin-payara/src/migrate/migration-runner.ts's private `isPostcondition`.
+ */
+function isPostcondition(stmt) {
+    return /^\s*CALL\s+zn_assert_/i.test(stmt);
+}
+/**
+ * The concrete MySQL EngineAdapter. Wires the already-ported leaf modules
+ * (lock, sql-splitter, scaffolding, schema-migrations-repo) and this file's
+ * connection.ts into the engine-agnostic `EngineAdapter` interface consumed by
+ * `core/runner.ts`. No new logic beyond delegation — the split-execute apply
+ * logic and the asserts-first reconcile logic are relocated verbatim from the
+ * source `migration-runner.ts` (`executeStatements` / `reconcile`).
+ */
+export const mysqlAdapter = {
+    engine: 'mysql',
+    openConnection(creds) {
+        return openConnection(creds);
+    },
+    preflight(conn, requireWritePrimary) {
+        return preflight(conn, requireWritePrimary);
+    },
+    acquireLock(conn) {
+        return lock.acquire(conn);
+    },
+    lockHeld(conn) {
+        return lock.isHeld(conn);
+    },
+    releaseLock(conn) {
+        return lock.release(conn);
+    },
+    /**
+     * Relocated verbatim from migration-runner.ts's private `executeStatements`:
+     * split the file's SQL into individual statements and execute each in order
+     * over the text protocol.
+     */
+    async applyMigrationFile(conn, sql) {
+        for (const stmt of splitStatements(sql)) {
+            await conn.query(stmt);
+        }
+    },
+    /**
+     * Relocated verbatim from migration-runner.ts's private `reconcile(path)`:
+     * asserts-first — run the file's trailing `CALL zn_assert_*` postconditions
+     * first; if they all pass, the migration is already applied (markSuccess
+     * without re-running the idempotent body). If there are no asserts, or any
+     * assert throws, re-run the entire body, then markSuccess.
+     *
+     * FIDELITY NOTE (documented per task brief): the source's `reconcile(path)`
+     * called `this.requireLockHeld()` a SECOND time here, immediately before
+     * `repo.markSuccess(version, 0)` (a guard against a session kill happening
+     * during the (possibly long) body re-execution). That per-reconcile guard is
+     * intentionally OMITTED here — the interface's `reconcile` signature has no
+     * lock hook, and lock-liveness semantics are owned by the core runner, not
+     * this adapter. The core runner (`core/runner.ts`, reconcile loop) already
+     * calls `await this.requireLockHeld()` immediately BEFORE invoking
+     * `adapter.reconcile(...)` for each file, so the PRE-reconcile guard is
+     * preserved. What's dropped is only the narrower POST-body-re-execution,
+     * pre-markSuccess check. This is a minimal, deliberate fidelity relocation,
+     * not an oversight — flagged here per the task brief's instruction to
+     * document rather than silently decide.
+     */
+    async reconcile(conn, version, fileSql, repo) {
+        const stmts = splitStatements(fileSql);
+        const asserts = stmts.filter((s) => isPostcondition(s));
+        let satisfied = false;
+        if (asserts.length > 0) {
+            try {
+                for (const a of asserts) {
+                    await conn.query(a);
+                }
+                satisfied = true; // all asserts passed
+            }
+            catch {
+                satisfied = false; // at least one assert failed → re-run body
+            }
+        }
+        // satisfied = false also when asserts.length === 0 (no-asserts → always re-run)
+        if (!satisfied) {
+            // Re-run entire body — must be idempotent (spec requirement).
+            // A genuinely failed CALL zn_assert_* will throw and propagate.
+            for (const s of stmts) {
+                await conn.query(s);
+            }
+        }
+        await repo.markSuccess(version, 0);
+    },
+    schemaMigrationsRepo(conn) {
+        return new SchemaMigrationsRepo(conn);
+    },
+    dropOwnedObjects(conn, leaseUser) {
+        return dropDefinerObjects(conn, leaseUser);
+    },
+    /**
+     * Read + split the scaffolding file (already resolved to an absolute path by
+     * the core runner) and apply its statements over the text protocol. The core
+     * runner passes an already-resolved absolute path in `scaffoldingFilePath`;
+     * `readScaffoldingSql`'s `isAbsolute(filename) ? filename : join(migrationsDir,
+     * filename)` short-circuits on an absolute filename, so the `migrationsDir`
+     * argument is irrelevant here and passed as ''.
+     *
+     * FIDELITY NOTE: the source runner's scaffolding-apply loop
+     * (`migration-runner.ts`) called `this.requireLockHeld()` before EACH
+     * statement — a per-statement guard against a killed session / proxy
+     * reconnect silently dropping the GET_LOCK server-side mid-apply. That
+     * per-statement check is restored HERE, in the adapter, because both the
+     * scaffolding split/apply logic and the lock module are MySQL-specific
+     * concerns; `core/runner.ts` calls this method as a single unit and stays
+     * engine-SQL-free.
+     */
+    async applyScaffolding(conn, scaffoldingFilePath) {
+        const { statements } = readScaffoldingSql('', scaffoldingFilePath);
+        for (const stmt of statements) {
+            // Per-statement lock-liveness guard (faithful port of the source runner's
+            // scaffolding loop): a killed session / proxy reconnect silently drops the
+            // GET_LOCK server-side; abort before running further DDL on a lock-less session.
+            if (!(await lock.isHeld(conn))) {
+                throw new Error('Lost the migration lock mid-run (session killed or reconnected). Aborting to avoid concurrent DDL.');
+            }
+            await conn.query(stmt);
+        }
+    },
+};

package/dist/adapters/mysql/mysql-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql-adapter.js","sourceRoot":"","sources":["../../../src/adapters/mysql/mysql-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;;;GAIG;AACH,SAAS,eAAe,CAAC,IAAY;IACnC,OAAO,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAkB;IACzC,MAAM,EAAE,OAAO;IAEf,cAAc,CAAC,KAAwB;QACrC,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,SAAS,CAAC,IAAU,EAAE,mBAA4B;QAChD,OAAO,SAAS,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;IAC9C,CAAC;IAED,WAAW,CAAC,IAAU;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAiB,CAAC,CAAC;IACzC,CAAC;IAED,QAAQ,CAAC,IAAU;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAiB,CAAC,CAAC;IACxC,CAAC;IAED,WAAW,CAAC,IAAU;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAiB,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,kBAAkB,CAAC,IAAU,EAAE,GAAW;QAC9C,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,SAAS,CACb,IAAU,EACV,OAAe,EACf,OAAe,EACf,IAA2B;QAE3B,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;QAExD,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC;gBACH,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;oBACxB,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBACtB,CAAC;gBACD,SAAS,GAAG,IAAI,CAAC,CAAC,qBAAqB;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS,GAAG,KAAK,CAAC,CAAC,2CAA2C;YAChE,CAAC;QACH,CAAC;QACD,gFAAgF;QAEhF,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,8DAA8D;YAC9D,gEAAgE;YAChE,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QAED,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,oBAAoB,CAAC,IAAU;QAC7B,OAAO,IAAI,oBAAoB,CAAC,IAAiB,CAAC,CAAC;IACrD,CAAC;IAED,gBAAgB,CAAC,IAAU,EAAE,SAAiB;QAC5C,OAAO,kBAAkB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,gBAAgB,CAAC,IAAU,EAAE,mBAA2B;QAC5D,MAAM,EAAE,UAAU,EAAE,GAAG,kBAAkB,CAAC,EAAE,EAAE,mBAAmB,CAAC,CAAC;QACnE,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,0EAA0E;YAC1E,2EAA2E;YAC3E,iFAAiF;YACjF,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAiB,CAAC,CAAC,EAAE,CAAC;gBAC5C,MAAM,IAAI,KAAK,CACb,oGAAoG,CACrG,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;CACF,CAAC"}