@iterativeflow/mysql 2.0.0-alpha.10

package/README.md

@@ -0,0 +1,28 @@
+# @iterativeflow/mysql
+
+A MySQL backend for [iterativeflow](https://github.com/ahmedrowaihi/iterativeflow) — the four ports
+(Store / Queue / Timer / Wakeup) over one InnoDB database. State and dispatch share the database, so
+the transactional outbox commits in one `BEGIN…COMMIT`, and `claim` uses `FOR UPDATE SKIP LOCKED` for
+contention-free batch dispatch. Passes the same conformance suites as the Postgres, SQLite, DynamoDB,
+and Redis backends. Requires MySQL 8+ (for `SKIP LOCKED`).
+
+```ts
+import { createPool } from "mysql2/promise";
+import { createMysqlBackend, applySchema, mysqlPool } from "@iterativeflow/mysql";
+import { createEngine } from "@iterativeflow/core";
+
+const sql = mysqlPool(createPool(process.env.MYSQL_URL));
+await applySchema(sql);
+const engine = createEngine(createMysqlBackend(sql), [
+  /* your flows */
+]);
+```
+
+## Notes
+
+- **`mysql2` is a peer dependency.**
+- **Wakeup is in-process** (like SQLite/DynamoDB/Redis).
+- **No `RETURNING`**: first-writer-wins reads `affectedRows` (`INSERT IGNORE`), and `claim` does
+  `SELECT … FOR UPDATE SKIP LOCKED` then `UPDATE` — the semantics are identical to the Postgres
+  backend, just expressed without `RETURNING`.
+- Timestamps are BIGINT epoch ms; JSON columns are LONGTEXT. Run `applySchema(sql, prefix?)` once.

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+import { Backend, IdGen } from "@iterativeflow/core/backend";
+import { Pool } from "mysql2/promise";
+//#region src/sql.d.ts
+/** What a write reports — MySQL has no `RETURNING`, so first-writer-wins reads `affectedRows`. */
+interface WriteResult {
+  affectedRows: number;
+  insertId: number;
+}
+/**
+ * The minimal SQL surface the backend needs: positional-`?` `query` for reads, `exec` for writes
+ * (returning `affectedRows`, since MySQL has no `RETURNING`), and a `tx` that runs a unit of work on
+ * one connection in a transaction. Abstracting it keeps the backend driver-agnostic and runs every
+ * outbox side-effect on the SAME connection. Tables are InnoDB, so `SELECT … FOR UPDATE SKIP LOCKED`
+ * gives contention-free batch claims.
+ */
+interface Sql {
+  query<R = Record<string, unknown>>(text: string, params?: readonly unknown[]): Promise<R[]>;
+  exec(text: string, params?: readonly unknown[]): Promise<WriteResult>;
+  tx<T>(fn: (t: Sql) => Promise<T>): Promise<T>;
+}
+/** Adapt a `mysql2/promise` {@link Pool} to {@link Sql}. `tx` checks out one connection for the unit. */
+declare const mysqlPool: (pool: Pool) => Sql;
+//#endregion
+//#region src/backend.d.ts
+interface MysqlBackendOpts {
+  /** Table-name prefix, for running multiple engines in one database. Default none. */
+  prefix?: string;
+  /** Id generator for runs, signals, and lease tokens. Defaults to {@link newId} (RFC-4122 v4). */
+  id?: IdGen;
+}
+/**
+ * The MySQL {@link Backend}: the four ports over one {@link Sql} connection (an InnoDB database).
+ * Store/Queue/Timer share the database, so an outbox commits in one transaction; `claim` uses
+ * `FOR UPDATE SKIP LOCKED`. Wakeup is in-process. Run {@link applySchema} once before use.
+ */
+declare const createMysqlBackend: (sql: Sql, opts?: MysqlBackendOpts) => Backend;
+//#endregion
+//#region src/schema.d.ts
+/**
+ * DDL for the MySQL backend (InnoDB). `run` carries durable state; `step` is the exactly-once memo
+ * (PK `(run_id, cursor_key)`); `job` is the lease queue; `timer` the durable-deadline set. Timestamps
+ * are BIGINT epoch ms; JSON columns are LONGTEXT; `seq` is AUTO_INCREMENT (insertion order, since
+ * MySQL has no implicit rowid). Indexed string columns are `VARCHAR(191)` to stay under the utf8mb4
+ * index-key limit. The idempotency/signal-dedup UNIQUE KEYs need no partial `WHERE`: MySQL treats
+ * NULLs as distinct, so unkeyed rows never collide.
+ */
+declare const ddl: (prefix?: string) => string[];
+/** Apply the schema DDL (idempotent). Run once before use. */
+declare const applySchema: (sql: Sql, prefix?: string) => Promise<void>;
+//#endregion
+//#region src/tx.d.ts
+/**
+ * Run `fn` inside one MySQL transaction, handing it a {@link Backend} bound to that
+ * transaction plus the raw {@link Sql} for the caller's own writes. Every `submit` /
+ * `startRun` / `enqueue` on that backend commits ATOMICALLY with the caller's writes on
+ * `tx` — the transactional-enqueue guarantee: business work and workflow dispatch land
+ * together or not at all. A throw rolls back both, so a failed request never leaves an
+ * orphan run or a dangling job.
+ *
+ * @example
+ * await inTx(pool, async (backend, tx) => {
+ *   await tx.query("INSERT INTO orders (id) VALUES (?)", [orderId]);
+ *   await submit(backend, fulfilOrder, { orderId }); // enqueued iff the order commits
+ * });
+ */
+declare const inTx: <T>(pool: Pool, fn: (backend: Backend, tx: Sql) => Promise<T>, opts?: MysqlBackendOpts) => Promise<T>;
+//#endregion
+export { type MysqlBackendOpts, type Sql, applySchema, createMysqlBackend, ddl, inTx, mysqlPool };

package/dist/index.mjs

@@ -0,0 +1,656 @@
+import { NON_SUCCESS_TERMINAL_STATUSES, RECONCILABLE_STATUSES, TERMINAL_STATUSES, assertSqlIdentifier, createLocalWakeup, newId, orphanedRunsSql, queueDepthOf, statusList, zeroRunStats } from "@iterativeflow/core/backend";
+//#region src/queue.ts
+/** @internal */
+const createMysqlQueue = (sql, t, id) => {
+	const ms = (d) => (d ?? /* @__PURE__ */ new Date()).getTime();
+	return {
+		async enqueue(runId, opts) {
+			await sql.exec(`INSERT INTO ${t.job} (run_id, run_at, priority, version) VALUES (?, ?, ?, 1)
+         ON DUPLICATE KEY UPDATE run_at = VALUES(run_at), priority = VALUES(priority), version = version + 1`, [
+				runId,
+				opts?.runAt ? opts.runAt.getTime() : 0,
+				opts?.priority ?? 0
+			]);
+		},
+		async claim({ limit, leaseMs, now, names }) {
+			if (names && names.length === 0) return [];
+			const at = ms(now);
+			const expiresAt = new Date(at + leaseMs);
+			return sql.tx(async (tx) => {
+				const namePredicate = names ? ` AND r.name IN (${names.map(() => "?").join(",")})` : "";
+				const params = names ? [
+					at,
+					at,
+					...names,
+					limit
+				] : [
+					at,
+					at,
+					limit
+				];
+				const due = await tx.query(`SELECT j.run_id AS run_id, j.version AS version
+             FROM ${t.job} j LEFT JOIN ${t.run} r ON r.id = j.run_id
+             WHERE j.run_at <= ? AND (j.lease_expires IS NULL OR j.lease_expires <= ?)${namePredicate}
+             ORDER BY j.priority, j.run_at LIMIT ? FOR UPDATE OF j SKIP LOCKED`, params);
+				const leases = [];
+				for (const row of due) {
+					const token = `${id()}:${row.run_id}`;
+					await tx.exec(`UPDATE ${t.job} SET lease_token = ?, lease_expires = ? WHERE run_id = ?`, [
+						token,
+						at + leaseMs,
+						row.run_id
+					]);
+					leases.push({
+						runId: row.run_id,
+						token,
+						expiresAt,
+						version: Number(row.version)
+					});
+				}
+				return leases;
+			});
+		},
+		async heartbeat(lease, { leaseMs, now }) {
+			const at = ms(now);
+			const { affectedRows } = await sql.exec(`UPDATE ${t.job} SET lease_expires = ?
+         WHERE run_id = ? AND lease_token = ? AND lease_expires > ?`, [
+				at + leaseMs,
+				lease.runId,
+				lease.token,
+				at
+			]);
+			if (affectedRows === 0) throw new Error(`heartbeat: lease for ${lease.runId} is no longer held`);
+			return {
+				...lease,
+				expiresAt: new Date(at + leaseMs)
+			};
+		},
+		async ack(lease, opts) {
+			const params = [
+				lease.runId,
+				lease.token,
+				ms(opts?.now),
+				lease.version
+			];
+			await sql.exec(`DELETE FROM ${t.job}
+         WHERE run_id = ? AND lease_token = ? AND lease_expires > ? AND version = ?`, params);
+			await sql.exec(`UPDATE ${t.job} SET lease_token = NULL, lease_expires = NULL, run_at = 0
+         WHERE run_id = ? AND lease_token = ? AND lease_expires > ? AND version <> ?`, params);
+		},
+		async depth(now) {
+			return queueDepthOf((await sql.query(`SELECT run_at, lease_expires FROM ${t.job}`)).map((r) => ({
+				runAt: Number(r.run_at),
+				leaseExpires: r.lease_expires == null ? void 0 : Number(r.lease_expires)
+			})), now.getTime());
+		}
+	};
+};
+//#endregion
+//#region src/schema.ts
+/** @internal */
+const tables = (prefix) => {
+	assertSqlIdentifier(prefix);
+	return {
+		run: `\`${prefix}run\``,
+		step: `\`${prefix}step\``,
+		job: `\`${prefix}job\``,
+		timer: `\`${prefix}timer\``,
+		signal: `\`${prefix}signal\``,
+		cron: `\`${prefix}cron\``
+	};
+};
+/**
+* DDL for the MySQL backend (InnoDB). `run` carries durable state; `step` is the exactly-once memo
+* (PK `(run_id, cursor_key)`); `job` is the lease queue; `timer` the durable-deadline set. Timestamps
+* are BIGINT epoch ms; JSON columns are LONGTEXT; `seq` is AUTO_INCREMENT (insertion order, since
+* MySQL has no implicit rowid). Indexed string columns are `VARCHAR(191)` to stay under the utf8mb4
+* index-key limit. The idempotency/signal-dedup UNIQUE KEYs need no partial `WHERE`: MySQL treats
+* NULLs as distinct, so unkeyed rows never collide.
+*/
+const ddl = (prefix = "") => {
+	const t = tables(prefix);
+	return [
+		`CREATE TABLE IF NOT EXISTS ${t.run} (
+      id                VARCHAR(191) PRIMARY KEY,
+      seq               BIGINT AUTO_INCREMENT UNIQUE,
+      name              VARCHAR(191) NOT NULL,
+      version           INT NOT NULL,
+      status            VARCHAR(32) NOT NULL,
+      input             LONGTEXT,
+      output            LONGTEXT,
+      error             LONGTEXT,
+      attempts          INT NOT NULL DEFAULT 0,
+      idempotency_key   VARCHAR(191),
+      tags              LONGTEXT,
+      parent_run_id     VARCHAR(191),
+      parent_cursor_key VARCHAR(191),
+      depth             INT NOT NULL DEFAULT 0,
+      join_remaining    INT NOT NULL DEFAULT 0,
+      created_at        BIGINT NOT NULL,
+      UNIQUE KEY run_idem (name, version, idempotency_key),
+      KEY run_created (created_at),
+      KEY run_parent (parent_run_id),
+      KEY run_status (status)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
+		`CREATE TABLE IF NOT EXISTS ${t.step} (
+      run_id     VARCHAR(191) NOT NULL,
+      cursor_key VARCHAR(191) NOT NULL,
+      status     VARCHAR(32) NOT NULL,
+      result     LONGTEXT,
+      error      LONGTEXT,
+      attempts   INT NOT NULL,
+      shape      VARCHAR(191),
+      PRIMARY KEY (run_id, cursor_key)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
+		`CREATE TABLE IF NOT EXISTS ${t.job} (
+      run_id        VARCHAR(191) PRIMARY KEY,
+      run_at        BIGINT NOT NULL,
+      priority      INT NOT NULL DEFAULT 0,
+      version       BIGINT NOT NULL DEFAULT 0,
+      lease_token   VARCHAR(191),
+      lease_expires BIGINT,
+      KEY job_claimable (priority, run_at)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
+		`CREATE TABLE IF NOT EXISTS ${t.timer} (
+      run_id  VARCHAR(191) PRIMARY KEY,
+      fire_at BIGINT NOT NULL,
+      KEY timer_due (fire_at)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
+		`CREATE TABLE IF NOT EXISTS ${t.signal} (
+      id       VARCHAR(191) PRIMARY KEY,
+      seq      BIGINT AUTO_INCREMENT UNIQUE,
+      run_id   VARCHAR(191) NOT NULL,
+      name     VARCHAR(191) NOT NULL,
+      payload  LONGTEXT,
+      idem_key VARCHAR(191),
+      KEY signal_inbox (run_id, seq),
+      UNIQUE KEY signal_idem (run_id, idem_key)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
+		`CREATE TABLE IF NOT EXISTS ${t.cron} (
+      name         VARCHAR(191) PRIMARY KEY,
+      schedule     VARCHAR(255) NOT NULL,
+      flow_name    VARCHAR(191) NOT NULL,
+      flow_version INT NOT NULL,
+      input        LONGTEXT,
+      overlap      VARCHAR(16) NOT NULL DEFAULT 'allow',
+      next_run_at  BIGINT NOT NULL,
+      last_run_at  BIGINT,
+      KEY cron_due (next_run_at)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`
+	];
+};
+/** Apply the schema DDL (idempotent). Run once before use. */
+const applySchema = async (sql, prefix = "") => {
+	for (const stmt of ddl(prefix)) await sql.query(stmt);
+};
+//#endregion
+//#region src/codec.ts
+/** @internal */
+const j = (value) => value === void 0 ? null : JSON.stringify(value);
+const p = (text) => text === null ? void 0 : JSON.parse(text);
+const orUndef = (v) => v === null ? void 0 : v;
+const at = (v) => new Date(Number(v));
+const mapRun = (r) => ({
+	id: r.id,
+	name: r.name,
+	version: r.version,
+	status: r.status,
+	input: p(r.input),
+	attempts: r.attempts,
+	output: p(r.output),
+	error: p(r.error),
+	idempotencyKey: orUndef(r.idempotency_key),
+	tags: p(r.tags),
+	parentRunId: orUndef(r.parent_run_id),
+	parentCursorKey: orUndef(r.parent_cursor_key),
+	depth: r.depth,
+	createdAt: at(r.created_at)
+});
+const mapStep = (r) => ({
+	status: r.status,
+	result: p(r.result),
+	error: p(r.error),
+	attempts: r.attempts,
+	shape: orUndef(r.shape ?? null)
+});
+const mapSignal = (r) => ({
+	id: r.id,
+	name: r.name,
+	payload: p(r.payload)
+});
+const mapCron = (r) => ({
+	name: r.name,
+	schedule: r.schedule,
+	flowName: r.flow_name,
+	flowVersion: r.flow_version,
+	input: p(r.input),
+	overlap: r.overlap,
+	nextRunAt: at(r.next_run_at),
+	lastRunAt: r.last_run_at === null ? void 0 : at(r.last_run_at)
+});
+//#endregion
+//#region src/statements.ts
+const inList$1 = (n) => `(${Array.from({ length: n }, () => "?").join(",")})`;
+/** @internal */
+const enqueueStmt = (sql, t, runId, opts) => sql.exec(`INSERT INTO ${t.job} (run_id, run_at, priority, version) VALUES (?, ?, ?, 1)
+     ON DUPLICATE KEY UPDATE run_at = VALUES(run_at), priority = VALUES(priority), version = version + 1`, [
+	runId,
+	opts?.runAt ? opts.runAt.getTime() : 0,
+	opts?.priority ?? 0
+]);
+/** @internal */
+const scheduleStmt = (sql, t, runId, fireAt) => sql.exec(`INSERT INTO ${t.timer} (run_id, fire_at) VALUES (?, ?)
+     ON DUPLICATE KEY UPDATE fire_at = VALUES(fire_at)`, [runId, fireAt.getTime()]);
+/** @internal */
+const applyOutbox = async (sql, t, fx) => {
+	for (const s of fx.spawn ?? []) {
+		await sql.exec(`INSERT IGNORE INTO ${t.run}
+         (id, name, version, status, input, idempotency_key, tags, parent_run_id, parent_cursor_key, depth, created_at)
+       VALUES (?, ?, ?, 'pending', ?, ?, ?, ?, ?, ?, ?)`, [
+			s.runId,
+			s.spec.name,
+			s.spec.version,
+			j(s.spec.input),
+			s.spec.idempotencyKey ?? null,
+			j(s.spec.tags),
+			s.spec.parentRunId ?? null,
+			s.spec.parentCursorKey ?? null,
+			s.spec.depth ?? 0,
+			(s.spec.createdAt ?? /* @__PURE__ */ new Date()).getTime()
+		]);
+		await enqueueStmt(sql, t, s.runId, s.enqueue);
+	}
+	for (const e of fx.enqueue ?? []) await enqueueStmt(sql, t, e.runId, e.opts);
+	for (const tm of fx.timers ?? []) await scheduleStmt(sql, t, tm.runId, tm.fireAt);
+	if (fx.cancelTimers?.length) await sql.exec(`DELETE FROM ${t.timer} WHERE run_id IN ${inList$1(fx.cancelTimers.length)}`, fx.cancelTimers);
+	if (fx.consumeSignals?.length) await sql.exec(`DELETE FROM ${t.signal} WHERE id IN ${inList$1(fx.consumeSignals.length)}`, fx.consumeSignals);
+	if (fx.joinTarget) await sql.exec(`UPDATE ${t.run} SET join_remaining = ? WHERE id = ?`, [fx.joinTarget.count, fx.joinTarget.runId]);
+};
+//#endregion
+//#region src/store.ts
+const sqlTuple = (statuses) => `(${statuses.map((s) => `'${s}'`).join(",")})`;
+const TERMINAL = sqlTuple(TERMINAL_STATUSES);
+const RECONCILABLE = sqlTuple(RECONCILABLE_STATUSES);
+const NON_SUCCESS_TERMINAL = sqlTuple(NON_SUCCESS_TERMINAL_STATUSES);
+const inList = (n) => `(${Array.from({ length: n }, () => "?").join(",")})`;
+/** @internal */
+const createMysqlStore = (sql, t, id) => {
+	const loadStep = async (exec, runId, cursorKey) => {
+		const row = (await exec.query(`SELECT status, result, error, attempts, shape FROM ${t.step} WHERE run_id = ? AND cursor_key = ?`, [runId, cursorKey]))[0];
+		if (!row) throw new Error(`checkpointStep: step ${runId}/${cursorKey} vanished after write`);
+		return mapStep(row);
+	};
+	const startOne = async (exec, spec) => {
+		const runId = id();
+		if (spec.idempotencyKey) {
+			if ((await exec.exec(`INSERT IGNORE INTO ${t.run}
+           (id, name, version, status, input, idempotency_key, tags, parent_run_id, parent_cursor_key, depth, created_at)
+         VALUES (?, ?, ?, 'pending', ?, ?, ?, ?, ?, ?, ?)`, [
+				runId,
+				spec.name,
+				spec.version,
+				j(spec.input),
+				spec.idempotencyKey,
+				j(spec.tags),
+				spec.parentRunId ?? null,
+				spec.parentCursorKey ?? null,
+				spec.depth ?? 0,
+				(spec.createdAt ?? /* @__PURE__ */ new Date()).getTime()
+			])).affectedRows === 1) return {
+				runId,
+				created: true,
+				status: "pending"
+			};
+			const hit = await exec.query(`SELECT id, status FROM ${t.run} WHERE name = ? AND version = ? AND idempotency_key = ?`, [
+				spec.name,
+				spec.version,
+				spec.idempotencyKey
+			]);
+			return {
+				runId: hit[0].id,
+				created: false,
+				status: hit[0].status
+			};
+		}
+		await exec.exec(`INSERT INTO ${t.run}
+         (id, name, version, status, input, tags, parent_run_id, parent_cursor_key, depth, created_at)
+       VALUES (?, ?, ?, 'pending', ?, ?, ?, ?, ?, ?)`, [
+			runId,
+			spec.name,
+			spec.version,
+			j(spec.input),
+			j(spec.tags),
+			spec.parentRunId ?? null,
+			spec.parentCursorKey ?? null,
+			spec.depth ?? 0,
+			(spec.createdAt ?? /* @__PURE__ */ new Date()).getTime()
+		]);
+		return {
+			runId,
+			created: true,
+			status: "pending"
+		};
+	};
+	return {
+		startRun(spec) {
+			return startOne(sql, spec);
+		},
+		startManyRuns(specs) {
+			return sql.tx(async (tx) => {
+				const out = [];
+				for (const s of specs) out.push(await startOne(tx, s));
+				return out;
+			});
+		},
+		async loadRun(runId) {
+			const [runRows, stepRows, sigRows] = await Promise.all([
+				sql.query(`SELECT * FROM ${t.run} WHERE id = ?`, [runId]),
+				sql.query(`SELECT cursor_key, status, result, error, attempts, shape FROM ${t.step} WHERE run_id = ?`, [runId]),
+				sql.query(`SELECT id, name, payload FROM ${t.signal} WHERE run_id = ? ORDER BY seq`, [runId])
+			]);
+			const runRow = runRows[0];
+			if (!runRow) return void 0;
+			return {
+				run: mapRun(runRow),
+				steps: new Map(stepRows.map((r) => [r.cursor_key, mapStep(r)])),
+				signals: sigRows.map(mapSignal)
+			};
+		},
+		async loadRunRow(runId) {
+			const rows = await sql.query(`SELECT * FROM ${t.run} WHERE id = ?`, [runId]);
+			return rows[0] ? mapRun(rows[0]) : void 0;
+		},
+		async loadRunRows(runIds) {
+			if (runIds.length === 0) return [];
+			const rows = await sql.query(`SELECT * FROM ${t.run} WHERE id IN ${inList(runIds.length)}`, runIds);
+			const byId = new Map(rows.map((r) => [r.id, mapRun(r)]));
+			return runIds.map((runId) => byId.get(runId));
+		},
+		arriveAtJoin(parentRunId) {
+			return sql.tx(async (tx) => {
+				if ((await tx.exec(`UPDATE ${t.run} SET join_remaining = join_remaining - 1 WHERE id = ?`, [parentRunId])).affectedRows === 0) return void 0;
+				const rows = await tx.query(`SELECT join_remaining FROM ${t.run} WHERE id = ?`, [parentRunId]);
+				return rows[0] ? Number(rows[0].join_remaining) : void 0;
+			});
+		},
+		async postSignal(runId, name, payload, opts) {
+			return sql.tx(async (tx) => {
+				if ((await tx.exec(`INSERT IGNORE INTO ${t.signal} (id, run_id, name, payload, idem_key) VALUES (?, ?, ?, ?, ?)`, [
+					id(),
+					runId,
+					name,
+					j(payload),
+					opts?.idempotencyKey ?? null
+				])).affectedRows === 0) return { delivered: false };
+				await enqueueStmt(tx, t, runId);
+				return { delivered: true };
+			});
+		},
+		markRunning(runId) {
+			return sql.tx(async (tx) => {
+				const cur = await tx.query(`SELECT status, attempts FROM ${t.run} WHERE id = ? FOR UPDATE`, [runId]);
+				if (!cur[0]) throw new Error(`markRunning: run ${runId} not found`);
+				const attempts = Number(cur[0].attempts);
+				if (TERMINAL_STATUSES.includes(cur[0].status)) return attempts;
+				await tx.exec(`UPDATE ${t.run} SET status = 'running', attempts = attempts + 1 WHERE id = ?`, [runId]);
+				return attempts + 1;
+			});
+		},
+		checkpointStep(c, fx) {
+			return sql.tx(async (tx) => {
+				if (!(await tx.query(`SELECT 1 AS ok FROM ${t.run} WHERE id = ?`, [c.runId]))[0]) throw new Error(`checkpointStep: run ${c.runId} not found`);
+				if (fx?.requireVersion !== void 0) {
+					if ((await tx.query(`SELECT 1 AS ok FROM ${t.step} WHERE run_id = ? AND cursor_key = ?`, [c.runId, c.cursorKey])).length === 0) {
+						const job = await tx.query(`SELECT version FROM ${t.job} WHERE run_id = ? FOR UPDATE`, [c.runId]);
+						if (!job[0] || Number(job[0].version) !== fx.requireVersion) return {
+							status: c.status,
+							attempts: c.attempts,
+							committed: false
+						};
+					}
+				}
+				if ((await tx.exec(`INSERT IGNORE INTO ${t.step} (run_id, cursor_key, status, result, error, attempts, shape)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+					c.runId,
+					c.cursorKey,
+					c.status,
+					j(c.result),
+					j(c.error),
+					c.attempts,
+					c.shape ?? null
+				])).affectedRows === 1 && fx) await applyOutbox(tx, t, fx);
+				return loadStep(tx, c.runId, c.cursorKey);
+			});
+		},
+		suspendRun(runId, status, fx) {
+			return sql.tx(async (tx) => {
+				const reset = status !== "retrying" ? ", attempts = 0" : "";
+				if ((await tx.exec(`UPDATE ${t.run} SET status = ?${reset} WHERE id = ? AND status NOT IN ${TERMINAL}`, [status, runId])).affectedRows > 0 && fx) await applyOutbox(tx, t, fx);
+			});
+		},
+		markTerminal(runId, outcome, fx) {
+			return sql.tx(async (tx) => {
+				const output = outcome.status === "done" ? outcome.output : void 0;
+				const error = outcome.status === "done" ? void 0 : outcome.error;
+				if ((await tx.exec(`UPDATE ${t.run} SET status = ?, output = ?, error = ?
+           WHERE id = ? AND status <> 'canceled'`, [
+					outcome.status,
+					j(output),
+					j(error),
+					runId
+				])).affectedRows > 0 && fx) await applyOutbox(tx, t, fx);
+			});
+		},
+		async listRuns(filter, page) {
+			const statuses = statusList(filter.status);
+			const where = [];
+			const params = [];
+			if (statuses) {
+				where.push(`status IN ${inList(statuses.length)}`);
+				params.push(...statuses);
+			}
+			if (filter.name) {
+				where.push(`name = ?`);
+				params.push(filter.name);
+			}
+			if (filter.tag) {
+				where.push(`JSON_CONTAINS(tags, JSON_QUOTE(?))`);
+				params.push(filter.tag);
+			}
+			if (page.cursor) {
+				where.push(`seq < ?`);
+				params.push(Number(page.cursor));
+			}
+			params.push(page.limit);
+			const clause = where.length ? `WHERE ${where.join(" AND ")}` : "";
+			const rows = await sql.query(`SELECT * FROM ${t.run} ${clause} ORDER BY seq DESC LIMIT ?`, params);
+			const last = rows[rows.length - 1];
+			const cursor = rows.length === page.limit && last ? String(last.seq) : void 0;
+			return {
+				runs: rows.map((r) => mapRun(r)),
+				cursor
+			};
+		},
+		async childrenOf(runId) {
+			return (await sql.query(`SELECT * FROM ${t.run} WHERE parent_run_id = ?`, [runId])).map((r) => mapRun(r));
+		},
+		async runStats() {
+			const rows = await sql.query(`SELECT status, count(*) AS n FROM ${t.run} GROUP BY status`);
+			const stats = zeroRunStats();
+			for (const r of rows) stats[r.status] = Number(r.n);
+			return stats;
+		},
+		async orphanedRuns(limit) {
+			return (await sql.query(orphanedRunsSql({
+				run: t.run,
+				job: t.job,
+				timer: t.timer,
+				reconcilable: RECONCILABLE,
+				terminal: TERMINAL,
+				nonSuccessTerminal: NON_SUCCESS_TERMINAL,
+				order: "r.seq",
+				limit: "?"
+			}), [limit])).map((r) => r.id);
+		},
+		deleteRunsOlderThan(before, limit) {
+			return sql.tx(async (tx) => {
+				const ids = (await tx.query(`SELECT id FROM ${t.run}
+             WHERE status IN ${TERMINAL} AND created_at < ?
+             ORDER BY seq LIMIT ?`, [before.getTime(), limit])).map((r) => r.id);
+				if (ids.length === 0) return 0;
+				const inIds = inList(ids.length);
+				await tx.exec(`DELETE FROM ${t.step} WHERE run_id IN ${inIds}`, ids);
+				await tx.exec(`DELETE FROM ${t.signal} WHERE run_id IN ${inIds}`, ids);
+				await tx.exec(`DELETE FROM ${t.job} WHERE run_id IN ${inIds}`, ids);
+				await tx.exec(`DELETE FROM ${t.timer} WHERE run_id IN ${inIds}`, ids);
+				await tx.exec(`DELETE FROM ${t.run} WHERE id IN ${inIds}`, ids);
+				return ids.length;
+			});
+		},
+		retryRun(runId) {
+			return sql.tx(async (tx) => {
+				if ((await tx.exec(`UPDATE ${t.run} SET status = 'pending', error = NULL WHERE id = ? AND status = 'failed'`, [runId])).affectedRows !== 1) return { retried: false };
+				await enqueueStmt(tx, t, runId);
+				return { retried: true };
+			});
+		},
+		async upsertCron(spec) {
+			await sql.exec(`INSERT INTO ${t.cron}
+           (name, schedule, flow_name, flow_version, input, overlap, next_run_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE
+           schedule = VALUES(schedule),
+           flow_name = VALUES(flow_name),
+           flow_version = VALUES(flow_version),
+           input = VALUES(input),
+           overlap = VALUES(overlap)`, [
+				spec.name,
+				spec.schedule,
+				spec.flowName,
+				spec.flowVersion,
+				j(spec.input),
+				spec.overlap ?? "allow",
+				spec.nextRunAt.getTime()
+			]);
+		},
+		async dueCrons(now, limit) {
+			return (await sql.query(`SELECT * FROM ${t.cron} WHERE next_run_at <= ? ORDER BY next_run_at LIMIT ?`, [now.getTime(), limit])).map(mapCron);
+		},
+		async advanceCron(name, expectedNextRunAt, nextRunAt, lastRunAt) {
+			return (await sql.exec(`UPDATE ${t.cron} SET next_run_at = ?, last_run_at = ?
+         WHERE name = ? AND next_run_at = ?`, [
+				nextRunAt.getTime(),
+				lastRunAt.getTime(),
+				name,
+				expectedNextRunAt.getTime()
+			])).affectedRows === 1;
+		}
+	};
+};
+//#endregion
+//#region src/timer.ts
+/** @internal */
+const createMysqlTimer = (sql, t) => {
+	return {
+		async schedule(runId, fireAt) {
+			await sql.exec(`INSERT INTO ${t.timer} (run_id, fire_at) VALUES (?, ?)
+         ON DUPLICATE KEY UPDATE fire_at = VALUES(fire_at)`, [runId, fireAt.getTime()]);
+		},
+		async dueBatch({ now, limit }) {
+			const at = (now ?? /* @__PURE__ */ new Date()).getTime();
+			return sql.tx(async (tx) => {
+				const due = await tx.query(`SELECT run_id FROM ${t.timer} WHERE fire_at <= ? ORDER BY fire_at LIMIT ? FOR UPDATE SKIP LOCKED`, [at, limit]);
+				if (!due.length) return [];
+				const ids = due.map((r) => r.run_id);
+				const holes = ids.map(() => "?").join(", ");
+				await tx.exec(`DELETE FROM ${t.timer} WHERE run_id IN (${holes})`, ids);
+				return ids;
+			});
+		},
+		async cancel(runId) {
+			await sql.exec(`DELETE FROM ${t.timer} WHERE run_id = ?`, [runId]);
+		},
+		async nextDueAt(now) {
+			const at = (await sql.query(`SELECT min(fire_at) AS fire_at FROM ${t.timer} WHERE fire_at > ?`, [now.getTime()]))[0]?.fire_at;
+			return at == null ? null : new Date(Number(at));
+		}
+	};
+};
+//#endregion
+//#region src/backend.ts
+/**
+* The MySQL {@link Backend}: the four ports over one {@link Sql} connection (an InnoDB database).
+* Store/Queue/Timer share the database, so an outbox commits in one transaction; `claim` uses
+* `FOR UPDATE SKIP LOCKED`. Wakeup is in-process. Run {@link applySchema} once before use.
+*/
+const createMysqlBackend = (sql, opts = {}) => {
+	const t = tables(opts.prefix ?? "");
+	const id = opts.id ?? newId;
+	return {
+		store: createMysqlStore(sql, t, id),
+		queue: createMysqlQueue(sql, t, id),
+		timer: createMysqlTimer(sql, t),
+		wakeup: createLocalWakeup()
+	};
+};
+//#endregion
+//#region src/sql.ts
+const write = (r) => {
+	const h = r[0];
+	return {
+		affectedRows: h.affectedRows,
+		insertId: h.insertId
+	};
+};
+const bind = (q) => ({
+	query: (text, params) => q.query(text, params).then((r) => r[0]),
+	exec: (text, params) => q.query(text, params).then(write)
+});
+const onConn = (c) => ({
+	...bind(c),
+	tx: (fn) => fn(onConn(c))
+});
+/** Adapt a `mysql2/promise` {@link Pool} to {@link Sql}. `tx` checks out one connection for the unit. */
+const mysqlPool = (pool) => {
+	const configured = /* @__PURE__ */ new WeakSet();
+	return {
+		...bind(pool),
+		async tx(fn) {
+			const c = await pool.getConnection();
+			try {
+				if (!configured.has(c)) {
+					await c.query("SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED");
+					configured.add(c);
+				}
+				await c.beginTransaction();
+				const out = await fn(onConn(c));
+				await c.commit();
+				return out;
+			} catch (e) {
+				await c.rollback().catch(() => void 0);
+				throw e;
+			} finally {
+				c.release();
+			}
+		}
+	};
+};
+//#endregion
+//#region src/tx.ts
+/**
+* Run `fn` inside one MySQL transaction, handing it a {@link Backend} bound to that
+* transaction plus the raw {@link Sql} for the caller's own writes. Every `submit` /
+* `startRun` / `enqueue` on that backend commits ATOMICALLY with the caller's writes on
+* `tx` — the transactional-enqueue guarantee: business work and workflow dispatch land
+* together or not at all. A throw rolls back both, so a failed request never leaves an
+* orphan run or a dangling job.
+*
+* @example
+* await inTx(pool, async (backend, tx) => {
+*   await tx.query("INSERT INTO orders (id) VALUES (?)", [orderId]);
+*   await submit(backend, fulfilOrder, { orderId }); // enqueued iff the order commits
+* });
+*/
+const inTx = (pool, fn, opts) => mysqlPool(pool).tx((tx) => fn(createMysqlBackend(tx, opts), tx));
+//#endregion
+export { applySchema, createMysqlBackend, ddl, inTx, mysqlPool };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@iterativeflow/mysql",
+  "version": "2.0.0-alpha.10",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahmedrowaihi/iterativeflow.git",
+    "directory": "v2/packages/mysql"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "imports": {
+    "#*": "./src/*.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "@iterativeflow/core": "2.0.0-alpha.10"
+  },
+  "peerDependencies": {
+    "mysql2": ">=3.0.0"
+  }
+}