mundane-sdk 0.0.1

package/README.md

@@ -0,0 +1,29 @@
+# mundane-sdk (TypeScript)
+
+See [`../SPEC.md`](../SPEC.md) for the cross-runtime contract.
+
+```ts
+import { run } from "mundane-sdk";
+
+await run("task.db", async (ctx) => {
+  const user = await ctx.step("fetch", async () => ({ name: "alice" }));
+  await ctx.sleep("cool-off", "100ms");
+  await ctx.step("notify", async () => `hi ${user.name}`);
+});
+```
+
+## Implementation notes
+
+- **Locking.** The runtime opens the SQLite file and takes
+  `flock(LOCK_EX | LOCK_NB)` on its fd via the `fs-ext` native binding —
+  no subprocess. It is the same `flock(2)` the bash, Go, and Python
+  runtimes use, so a lock held by one is visible to the rest, and the
+  kernel drops it automatically if the process dies.
+- **No redundant SQLite locking.** The DB is opened with the `unix-none`
+  VFS (`file:…?vfs=unix-none`), which turns off SQLite's own file locking.
+  Our `flock` already guarantees a single writer for the whole run, so
+  SQLite's locking is redundant — and on platforms where SQLite locks via
+  `flock(2)` (e.g. macOS) it would collide with ours on the same file and
+  deadlock. `unix-none` leaves our flock as the sole authority.
+- **DB binding.** Built on `node-sqlite3`, wrapped in a thin promise layer
+  (see `src/db.ts`).

package/dist/src/db.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Thin promise wrapper over node-sqlite3.
+ *
+ * The database is opened with the `unix-none` VFS, which disables SQLite's own
+ * file locking. We don't need it: mundane already holds an exclusive
+ * `flock(LOCK_EX)` on the file for the whole run (see lock.ts), so single-writer
+ * is guaranteed externally and visible across all runtimes. Leaving SQLite's
+ * locking on would be redundant — and on platforms where SQLite locks via
+ * `flock(2)` (e.g. macOS), it would collide with our own flock on the same file
+ * and deadlock ("database is locked"). `unix-none` sidesteps that entirely.
+ */
+export interface Db {
+    run(sql: string, params?: unknown[]): Promise<void>;
+    get<T>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    all<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function openDb(path: string, opts?: {
+    readonly?: boolean;
+}): Promise<Db>;

package/dist/src/db.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Thin promise wrapper over node-sqlite3.
+ *
+ * The database is opened with the `unix-none` VFS, which disables SQLite's own
+ * file locking. We don't need it: mundane already holds an exclusive
+ * `flock(LOCK_EX)` on the file for the whole run (see lock.ts), so single-writer
+ * is guaranteed externally and visible across all runtimes. Leaving SQLite's
+ * locking on would be redundant — and on platforms where SQLite locks via
+ * `flock(2)` (e.g. macOS), it would collide with our own flock on the same file
+ * and deadlock ("database is locked"). `unix-none` sidesteps that entirely.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openDb = openDb;
+const node_url_1 = require("node:url");
+const sqlite3 = __importStar(require("sqlite3"));
+function openDb(path, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const url = (0, node_url_1.pathToFileURL)(path);
+        url.searchParams.set("vfs", "unix-none");
+        const mode = (opts.readonly ? sqlite3.OPEN_READONLY : sqlite3.OPEN_READWRITE | sqlite3.OPEN_CREATE) |
+            sqlite3.OPEN_URI;
+        const raw = new sqlite3.Database(url.href, mode, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve(wrap(raw));
+        });
+    });
+}
+function wrap(raw) {
+    return {
+        run: (sql, params = []) => new Promise((resolve, reject) => raw.run(sql, params, (err) => (err ? reject(err) : resolve()))),
+        get: (sql, params = []) => new Promise((resolve, reject) => raw.get(sql, params, (err, row) => (err ? reject(err) : resolve(row)))),
+        all: (sql, params = []) => new Promise((resolve, reject) => raw.all(sql, params, (err, rows) => (err ? reject(err) : resolve(rows)))),
+        exec: (sql) => new Promise((resolve, reject) => raw.exec(sql, (err) => (err ? reject(err) : resolve()))),
+        close: () => new Promise((resolve, reject) => raw.close((err) => (err ? reject(err) : resolve()))),
+    };
+}

package/dist/src/duration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse duration strings like "30s", "5m", "2h", "1d", "500ms".
+ *
+ * Returns the number of milliseconds. Throws on unparseable input.
+ */
+export declare function parseDurationMs(input: string | number): number;

package/dist/src/duration.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Parse duration strings like "30s", "5m", "2h", "1d", "500ms".
+ *
+ * Returns the number of milliseconds. Throws on unparseable input.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDurationMs = parseDurationMs;
+const UNIT_MS = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+const RE = /^\s*(\d+(?:\.\d+)?)(ms|s|m|h|d)\s*$/i;
+function parseDurationMs(input) {
+    if (typeof input === "number") {
+        if (!Number.isFinite(input))
+            throw new TypeError("duration: non-finite number");
+        return Math.trunc(input);
+    }
+    const m = RE.exec(input);
+    if (!m) {
+        throw new Error(`invalid duration ${JSON.stringify(input)}: expected e.g. "500ms", "30s", "5m", "2h", "1d"`);
+    }
+    const magnitude = Number(m[1]);
+    const unit = m[2].toLowerCase();
+    return Math.round(magnitude * UNIT_MS[unit]);
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Custom error classes thrown by mundane.
+ *
+ * - MundaneLockedError: another live process holds the file lock.
+ * - MundaneSerializationError: a step's return value doesn't survive a
+ *   JSON round-trip (Date, undefined, BigInt, Map, Set, function, circular).
+ * - MundaneSchemaError: file exists but meta.schema_version != "1".
+ * - MundaneStepFailedError: a step body threw; wraps the underlying error.
+ */
+export declare class MundaneLockedError extends Error {
+    readonly code = "EMUNDANELOCKED";
+    constructor(message: string);
+}
+export declare class MundaneSerializationError extends Error {
+    readonly code = "EMUNDANESERIALIZATION";
+    readonly path?: string;
+    constructor(message: string, path?: string);
+}
+export declare class MundaneSchemaError extends Error {
+    readonly code = "EMUNDANESCHEMA";
+    constructor(message: string);
+}
+export declare class MundaneDuplicateStepError extends Error {
+    readonly code = "EMUNDANEDUPLICATE";
+    readonly stepName: string;
+    constructor(stepName: string);
+}
+export declare class MundaneStepFailedError extends Error {
+    readonly code = "EMUNDANESTEPFAILED";
+    readonly stepName: string;
+    readonly original: unknown;
+    constructor(stepName: string, original: unknown);
+}

package/dist/src/errors.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Custom error classes thrown by mundane.
+ *
+ * - MundaneLockedError: another live process holds the file lock.
+ * - MundaneSerializationError: a step's return value doesn't survive a
+ *   JSON round-trip (Date, undefined, BigInt, Map, Set, function, circular).
+ * - MundaneSchemaError: file exists but meta.schema_version != "1".
+ * - MundaneStepFailedError: a step body threw; wraps the underlying error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MundaneStepFailedError = exports.MundaneDuplicateStepError = exports.MundaneSchemaError = exports.MundaneSerializationError = exports.MundaneLockedError = void 0;
+class MundaneLockedError extends Error {
+    code = "EMUNDANELOCKED";
+    constructor(message) {
+        super(message);
+        this.name = "MundaneLockedError";
+    }
+}
+exports.MundaneLockedError = MundaneLockedError;
+class MundaneSerializationError extends Error {
+    code = "EMUNDANESERIALIZATION";
+    path;
+    constructor(message, path) {
+        super(message);
+        this.name = "MundaneSerializationError";
+        this.path = path;
+    }
+}
+exports.MundaneSerializationError = MundaneSerializationError;
+class MundaneSchemaError extends Error {
+    code = "EMUNDANESCHEMA";
+    constructor(message) {
+        super(message);
+        this.name = "MundaneSchemaError";
+    }
+}
+exports.MundaneSchemaError = MundaneSchemaError;
+class MundaneDuplicateStepError extends Error {
+    code = "EMUNDANEDUPLICATE";
+    stepName;
+    constructor(stepName) {
+        super(`duplicate step name: ${stepName}`);
+        this.name = "MundaneDuplicateStepError";
+        this.stepName = stepName;
+    }
+}
+exports.MundaneDuplicateStepError = MundaneDuplicateStepError;
+class MundaneStepFailedError extends Error {
+    code = "EMUNDANESTEPFAILED";
+    stepName;
+    original;
+    constructor(stepName, original) {
+        const msg = original instanceof Error
+            ? `step ${JSON.stringify(stepName)} failed: ${original.message}`
+            : `step ${JSON.stringify(stepName)} failed: ${String(original)}`;
+        super(msg);
+        this.name = "MundaneStepFailedError";
+        this.stepName = stepName;
+        this.original = original;
+        if (original instanceof Error && original.stack) {
+            this.stack = `${this.stack}\nCaused by: ${original.stack}`;
+        }
+    }
+}
+exports.MundaneStepFailedError = MundaneStepFailedError;

package/dist/src/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * mundane-sdk — tiny durable-execution library.
+ *
+ * Public API:
+ *   run(path, async (ctx) => { ... })
+ *   ctx.step(name, async () => json-able)
+ *   ctx.sleep(name, "5m" | 5_000)
+ *
+ * See ../../../SPEC.md (project root) for the full contract.
+ */
+import { MundaneDuplicateStepError, MundaneLockedError, MundaneSchemaError, MundaneSerializationError, MundaneStepFailedError } from "./errors";
+export { MundaneDuplicateStepError, MundaneLockedError, MundaneSchemaError, MundaneSerializationError, MundaneStepFailedError, };
+export type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+export interface Context {
+    step<T = unknown>(name: string, fn: () => Promise<T> | T): Promise<T>;
+    sleep(name: string, duration: string | number): Promise<void>;
+}
+export declare function run<T>(path: string, fn: (ctx: Context) => Promise<T> | T): Promise<T>;

package/dist/src/index.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * mundane-sdk — tiny durable-execution library.
+ *
+ * Public API:
+ *   run(path, async (ctx) => { ... })
+ *   ctx.step(name, async () => json-able)
+ *   ctx.sleep(name, "5m" | 5_000)
+ *
+ * See ../../../SPEC.md (project root) for the full contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MundaneStepFailedError = exports.MundaneSerializationError = exports.MundaneSchemaError = exports.MundaneLockedError = exports.MundaneDuplicateStepError = void 0;
+exports.run = run;
+const db_1 = require("./db");
+const duration_1 = require("./duration");
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "MundaneDuplicateStepError", { enumerable: true, get: function () { return errors_1.MundaneDuplicateStepError; } });
+Object.defineProperty(exports, "MundaneLockedError", { enumerable: true, get: function () { return errors_1.MundaneLockedError; } });
+Object.defineProperty(exports, "MundaneSchemaError", { enumerable: true, get: function () { return errors_1.MundaneSchemaError; } });
+Object.defineProperty(exports, "MundaneSerializationError", { enumerable: true, get: function () { return errors_1.MundaneSerializationError; } });
+Object.defineProperty(exports, "MundaneStepFailedError", { enumerable: true, get: function () { return errors_1.MundaneStepFailedError; } });
+const lock_1 = require("./lock");
+const names_1 = require("./names");
+const schema_1 = require("./schema");
+function checkJsonRoundtrip(value) {
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch (e) {
+        throw new errors_1.MundaneSerializationError(`value is not JSON-serializable: ${e.message}`);
+    }
+    if (text === undefined) {
+        // JSON.stringify returns undefined for top-level undefined/function/symbol
+        throw new errors_1.MundaneSerializationError("value is not JSON-serializable (undefined / function / symbol at top level)");
+    }
+    const decoded = JSON.parse(text);
+    const mismatch = deepDiff(value, decoded, "");
+    if (mismatch !== null) {
+        throw new errors_1.MundaneSerializationError(`value does not round-trip through JSON at ${JSON.stringify(mismatch)}`, mismatch);
+    }
+    return text;
+}
+function deepDiff(a, b, path) {
+    if (a === b)
+        return null;
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+        // Special-case: NaN/Infinity get encoded as null by JSON, mismatch.
+        return path || "(root)";
+    }
+    if (Array.isArray(a) !== Array.isArray(b))
+        return path || "(root)";
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return path || "(root)";
+        for (let i = 0; i < a.length; i++) {
+            const d = deepDiff(a[i], b[i], `${path}[${i}]`);
+            if (d)
+                return d;
+        }
+        return null;
+    }
+    // Plain objects: keys must match exactly (catches `undefined` values
+    // disappearing, Date/Map/Set turning into "{}", and class instances).
+    const aProto = Object.getPrototypeOf(a);
+    if (aProto !== Object.prototype && aProto !== null) {
+        return path || "(root)";
+    }
+    const aKeys = Object.keys(a).sort();
+    const bKeys = Object.keys(b).sort();
+    if (aKeys.length !== bKeys.length)
+        return path || "(root)";
+    for (let i = 0; i < aKeys.length; i++) {
+        if (aKeys[i] !== bKeys[i])
+            return path || "(root)";
+        const d = deepDiff(a[aKeys[i]], b[aKeys[i]], `${path}.${aKeys[i]}`);
+        if (d)
+            return d;
+    }
+    return null;
+}
+function decodeResult(row) {
+    if (row.result === null)
+        return null;
+    // node-sqlite3 returns BLOB as Buffer, TEXT as string.
+    switch (row.encoding) {
+        case "json": {
+            const text = typeof row.result === "string" ? row.result : row.result.toString("utf8");
+            return JSON.parse(text);
+        }
+        case "bytes":
+            return typeof row.result === "string" ? Buffer.from(row.result, "utf8") : row.result;
+        default:
+            throw new Error(`unknown encoding: ${row.encoding}`);
+    }
+}
+class TaskState {
+    db;
+    cache = new Map();
+    seen = new Set();
+    constructor(db) {
+        this.db = db;
+    }
+    static async create(db) {
+        const task = new TaskState(db);
+        await task.loadCache();
+        return task;
+    }
+    checkSeen(name) {
+        if (this.seen.has(name)) {
+            throw new errors_1.MundaneDuplicateStepError(name);
+        }
+        this.seen.add(name);
+    }
+    async loadCache() {
+        const rows = await this.db.all("SELECT id, name, kind, encoding, result, status, error FROM mundane_steps ORDER BY id");
+        for (const row of rows)
+            this.cache.set(row.name, row);
+    }
+    async ensurePendingRow(name, kind, encoding) {
+        const existing = this.cache.get(name);
+        if (existing) {
+            // Re-running a leftover pending/failed row (never 'done' on this path):
+            // reset it to pending so the on-disk state reflects the retry (SPEC §2).
+            await this.db.run("UPDATE mundane_steps SET kind=?, encoding=?, status='pending', result=NULL, error=NULL, finished_at=NULL " +
+                "WHERE name=?", [kind, encoding, name]);
+            existing.kind = kind;
+            existing.encoding = encoding;
+            existing.status = "pending";
+            existing.result = null;
+            existing.error = null;
+            return existing;
+        }
+        const now = new Date().toISOString();
+        await this.db.run("INSERT INTO mundane_steps (name, kind, encoding, result, status, started_at) " +
+            "VALUES (?, ?, ?, NULL, 'pending', ?)", [name, kind, encoding, now]);
+        const row = (await this.db.get("SELECT id, name, kind, encoding, result, status, error FROM mundane_steps WHERE name = ?", [name]));
+        this.cache.set(name, row);
+        return row;
+    }
+    async commitDone(name, encoding, result) {
+        const finished = new Date().toISOString();
+        await this.db.run("UPDATE mundane_steps SET status='done', encoding=?, result=?, finished_at=?, error=NULL " +
+            "WHERE name=?", [encoding, result, finished, name]);
+        const row = this.cache.get(name);
+        row.status = "done";
+        row.encoding = encoding;
+        row.result = result;
+    }
+    async commitFailed(name, errMsg) {
+        const finished = new Date().toISOString();
+        await this.db.run("UPDATE mundane_steps SET status='failed', error=?, finished_at=? WHERE name=?", [errMsg, finished, name]);
+        const row = this.cache.get(name);
+        row.status = "failed";
+        row.error = errMsg;
+    }
+}
+class ContextImpl {
+    task;
+    constructor(task) {
+        this.task = task;
+    }
+    async step(name, fn) {
+        (0, names_1.validateName)(name);
+        this.task.checkSeen(name);
+        const cached = this.task.cache.get(name);
+        if (cached && cached.status === "done") {
+            return decodeResult(cached);
+        }
+        await this.task.ensurePendingRow(name, "step", "json");
+        let value;
+        try {
+            value = await fn();
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            await this.task.commitFailed(name, msg);
+            throw new errors_1.MundaneStepFailedError(name, e);
+        }
+        const text = checkJsonRoundtrip(value);
+        await this.task.commitDone(name, "json", text);
+        // Return the round-tripped value so first run and resume agree exactly.
+        return JSON.parse(text);
+    }
+    async sleep(name, duration) {
+        (0, names_1.validateName)(name);
+        this.task.checkSeen(name);
+        const cached = this.task.cache.get(name);
+        let wakeAt;
+        if (cached && cached.status === "done") {
+            // Resume: the duration arg is ignored (SPEC §6), so don't parse it — a
+            // now-invalid duration string must not fail an otherwise-no-op resume.
+            wakeAt = Number(decodeResult(cached));
+        }
+        else {
+            wakeAt = Date.now() + (0, duration_1.parseDurationMs)(duration);
+            await this.task.ensurePendingRow(name, "sleep", "json");
+            await this.task.commitDone(name, "json", String(wakeAt));
+        }
+        const remaining = wakeAt - Date.now();
+        if (remaining > 0) {
+            await new Promise((resolve) => setTimeout(resolve, remaining));
+        }
+    }
+}
+async function run(path, fn) {
+    let lock;
+    try {
+        lock = await (0, lock_1.acquireLock)(path);
+    }
+    catch (e) {
+        if (e instanceof errors_1.MundaneLockedError)
+            throw e;
+        throw e;
+    }
+    let db = null;
+    try {
+        db = await (0, db_1.openDb)(path);
+        await (0, schema_1.bootstrap)(db);
+        const task = await TaskState.create(db);
+        const ctx = new ContextImpl(task);
+        return await fn(ctx);
+    }
+    finally {
+        if (db) {
+            try {
+                await db.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        await lock.release();
+    }
+}

package/dist/src/lock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cross-process exclusive lock interoperable with flock(2).
+ *
+ * We open the SQLite file and take flock(LOCK_EX | LOCK_NB) on its fd via the
+ * `fs-ext` native binding — no subprocess. This is the same flock(2) that the
+ * bash (`flock`), Go (`unix.Flock`), and Python (`fcntl.flock`) runtimes use,
+ * so a lock held by any one is visible to all. The kernel drops it
+ * automatically if the process dies, so there is nothing to clean up on crash.
+ *
+ * We hold a raw integer fd (not a `FileHandle`) on purpose: a `FileHandle` has
+ * a GC finalizer that would close the fd — and release the lock — if it were
+ * collected mid-run. A raw fd stays open until we close it (or the process
+ * exits).
+ */
+export interface AcquiredLock {
+    release(): Promise<void>;
+}
+export declare function acquireLock(path: string): Promise<AcquiredLock>;

package/dist/src/lock.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Cross-process exclusive lock interoperable with flock(2).
+ *
+ * We open the SQLite file and take flock(LOCK_EX | LOCK_NB) on its fd via the
+ * `fs-ext` native binding — no subprocess. This is the same flock(2) that the
+ * bash (`flock`), Go (`unix.Flock`), and Python (`fcntl.flock`) runtimes use,
+ * so a lock held by any one is visible to all. The kernel drops it
+ * automatically if the process dies, so there is nothing to clean up on crash.
+ *
+ * We hold a raw integer fd (not a `FileHandle`) on purpose: a `FileHandle` has
+ * a GC finalizer that would close the fd — and release the lock — if it were
+ * collected mid-run. A raw fd stays open until we close it (or the process
+ * exits).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireLock = acquireLock;
+const node_fs_1 = require("node:fs");
+const fs_ext_1 = require("fs-ext");
+const errors_1 = require("./errors");
+function openFd(path) {
+    return new Promise((resolve, reject) => {
+        (0, node_fs_1.open)(path, node_fs_1.constants.O_RDWR | node_fs_1.constants.O_CREAT, 0o644, (err, fd) => {
+            if (err)
+                reject(err);
+            else
+                resolve(fd);
+        });
+    });
+}
+function closeFd(fd) {
+    return new Promise((resolve) => {
+        // Closing drops the flock; ignore close errors (fd may already be gone).
+        (0, node_fs_1.close)(fd, () => resolve());
+    });
+}
+function flockExclusiveNonblock(fd) {
+    return new Promise((resolve, reject) => {
+        (0, fs_ext_1.flock)(fd, "exnb", (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}
+async function acquireLock(path) {
+    const fd = await openFd(path);
+    try {
+        await flockExclusiveNonblock(fd);
+    }
+    catch (e) {
+        await closeFd(fd);
+        const code = e.code;
+        if (code === "EWOULDBLOCK" || code === "EAGAIN") {
+            throw new errors_1.MundaneLockedError(`${path}: locked by another process`);
+        }
+        throw e;
+    }
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await closeFd(fd);
+        },
+    };
+}

package/dist/src/names.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Step-name validation. Names must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/.
+ * Duplicate names within one task body raise MundaneDuplicateStepError;
+ * see ../src/index.ts.
+ */
+export declare function validateName(name: string): void;

package/dist/src/names.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Step-name validation. Names must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/.
+ * Duplicate names within one task body raise MundaneDuplicateStepError;
+ * see ../src/index.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateName = validateName;
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function validateName(name) {
+    if (typeof name !== "string" || !NAME_RE.test(name)) {
+        throw new Error(`invalid step name ${JSON.stringify(name)}: must match ${NAME_RE.source}`);
+    }
+}

package/dist/src/schema.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Schema definition shared across runtimes.
+ *
+ * The schema is pinned to v1. Opening a file whose meta.schema_version is
+ * not "1" is a hard error.
+ */
+import type { Db } from "./db";
+export declare const SCHEMA_VERSION = "1";
+export declare const CREATE_META = "\nCREATE TABLE IF NOT EXISTS mundane_meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n)\n";
+export declare const CREATE_STEPS = "\nCREATE TABLE IF NOT EXISTS mundane_steps (\n  id           INTEGER PRIMARY KEY AUTOINCREMENT,\n  name         TEXT NOT NULL,\n  kind         TEXT NOT NULL,\n  encoding     TEXT NOT NULL,\n  result       BLOB,\n  status       TEXT NOT NULL,\n  error        TEXT,\n  started_at   TEXT NOT NULL,\n  finished_at  TEXT,\n  UNIQUE(name)\n)\n";
+export declare const CREATE_INDEX = "\nCREATE INDEX IF NOT EXISTS mundane_steps_status ON mundane_steps(status)\n";
+export declare function bootstrap(db: Db): Promise<void>;

package/dist/src/schema.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Schema definition shared across runtimes.
+ *
+ * The schema is pinned to v1. Opening a file whose meta.schema_version is
+ * not "1" is a hard error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CREATE_INDEX = exports.CREATE_STEPS = exports.CREATE_META = exports.SCHEMA_VERSION = void 0;
+exports.bootstrap = bootstrap;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("./errors");
+exports.SCHEMA_VERSION = "1";
+exports.CREATE_META = `
+CREATE TABLE IF NOT EXISTS mundane_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+)
+`;
+exports.CREATE_STEPS = `
+CREATE TABLE IF NOT EXISTS mundane_steps (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  name         TEXT NOT NULL,
+  kind         TEXT NOT NULL,
+  encoding     TEXT NOT NULL,
+  result       BLOB,
+  status       TEXT NOT NULL,
+  error        TEXT,
+  started_at   TEXT NOT NULL,
+  finished_at  TEXT,
+  UNIQUE(name)
+)
+`;
+exports.CREATE_INDEX = `
+CREATE INDEX IF NOT EXISTS mundane_steps_status ON mundane_steps(status)
+`;
+async function bootstrap(db) {
+    await db.exec("PRAGMA journal_mode = DELETE");
+    // Pre-check: if mundane_meta exists with wrong schema_version, bail before
+    // running CREATE INDEX (which assumes columns we only promise at v1).
+    const existing = await db.get("SELECT name FROM sqlite_master WHERE type='table' AND name='mundane_meta'");
+    if (existing) {
+        const row = await db.get("SELECT value FROM mundane_meta WHERE key='schema_version'");
+        if (row && row.value !== exports.SCHEMA_VERSION) {
+            throw new errors_1.MundaneSchemaError(`schema_version is ${JSON.stringify(row.value)}, expected "${exports.SCHEMA_VERSION}"`);
+        }
+    }
+    await db.exec("BEGIN IMMEDIATE");
+    try {
+        await db.exec(exports.CREATE_META);
+        await db.exec(exports.CREATE_STEPS);
+        await db.exec(exports.CREATE_INDEX);
+        await db.run("INSERT OR IGNORE INTO mundane_meta (key, value) VALUES ('schema_version', ?)", [
+            exports.SCHEMA_VERSION,
+        ]);
+        await db.run("INSERT OR IGNORE INTO mundane_meta (key, value) VALUES ('task_id', ?)", [
+            (0, node_crypto_1.randomUUID)(),
+        ]);
+        await db.run("INSERT OR IGNORE INTO mundane_meta (key, value) VALUES ('created_at', ?)", [
+            new Date().toISOString(),
+        ]);
+        await db.exec("COMMIT");
+    }
+    catch (e) {
+        try {
+            await db.exec("ROLLBACK");
+        }
+        catch { }
+        throw e;
+    }
+    // Final check.
+    const row = await db.get("SELECT value FROM mundane_meta WHERE key='schema_version'");
+    if (!row || row.value !== exports.SCHEMA_VERSION) {
+        throw new errors_1.MundaneSchemaError(`schema_version is ${JSON.stringify(row?.value)}, expected "${exports.SCHEMA_VERSION}"`);
+    }
+}

package/dist/test/basic.test.d.ts

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

package/dist/test/basic.test.js

@@ -0,0 +1,295 @@
+"use strict";
+/* Basic tests for mundane-sdk */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_test_1 = require("node:test");
+const db_1 = require("../src/db");
+const index_1 = require("../src/index");
+// Inspection lives in the CLI now; tests read on-disk state directly.
+async function readSteps(path) {
+    const db = await (0, db_1.openDb)(path, { readonly: true });
+    try {
+        return await db.all("SELECT name, encoding, status FROM mundane_steps ORDER BY id");
+    }
+    finally {
+        await db.close();
+    }
+}
+async function readResult(path, name) {
+    const db = await (0, db_1.openDb)(path, { readonly: true });
+    try {
+        const row = await db.get("SELECT result, encoding FROM mundane_steps WHERE name = ?", [name]);
+        if (!row)
+            throw new Error(`no step ${name}`);
+        const text = typeof row.result === "string" ? row.result : row.result.toString("utf8");
+        return row.encoding === "json" ? JSON.parse(text) : text;
+    }
+    finally {
+        await db.close();
+    }
+}
+function newDb() {
+    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "mundane-test-"));
+    const path = (0, node_path_1.join)(dir, "task.db");
+    return {
+        path,
+        cleanup: () => {
+            try {
+                (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+            }
+            catch { }
+        },
+    };
+}
+(0, node_test_1.test)("three steps execute once; second run uses cache", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        const calls = [];
+        const wf = async (ctx) => {
+            const a = await ctx.step("a", async () => {
+                calls.push("a");
+                return 1;
+            });
+            const b = await ctx.step("b", async () => {
+                calls.push("b");
+                return { v: a + 1 };
+            });
+            return b;
+        };
+        const r1 = await (0, index_1.run)(path, wf);
+        strict_1.default.deepEqual(r1, { v: 2 });
+        strict_1.default.deepEqual(calls, ["a", "b"]);
+        const r2 = await (0, index_1.run)(path, wf);
+        strict_1.default.deepEqual(r2, { v: 2 });
+        strict_1.default.deepEqual(calls, ["a", "b"]); // not re-called
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("step is cached after a body throws", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        await strict_1.default.rejects((0, index_1.run)(path, async (ctx) => {
+            await ctx.step("a", async () => 42);
+            throw new Error("simulated crash");
+        }));
+        const calls = [];
+        const r = await (0, index_1.run)(path, async (ctx) => {
+            const v = await ctx.step("a", async () => {
+                calls.push("a");
+                return 0;
+            });
+            const w = await ctx.step("b", async () => {
+                calls.push("b");
+                return v + 1;
+            });
+            return w;
+        });
+        strict_1.default.equal(r, 43);
+        strict_1.default.deepEqual(calls, ["b"]);
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("invalid step name is rejected", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        await strict_1.default.rejects((0, index_1.run)(path, async (ctx) => {
+            await ctx.step("bad name", async () => 1);
+        }));
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("duplicate step name raises MundaneDuplicateStepError", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        await strict_1.default.rejects((0, index_1.run)(path, async (ctx) => {
+            await ctx.step("x", async () => 1);
+            await ctx.step("x", async () => 2);
+        }), (e) => e instanceof index_1.MundaneDuplicateStepError && e.stepName === "x");
+        // First step still committed before the dup raised.
+        const names = (await readSteps(path)).map((s) => s.name);
+        strict_1.default.deepEqual(names, ["x"]);
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("sleep persists wake_at and resumes", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        const t0 = Date.now();
+        await (0, index_1.run)(path, async (ctx) => {
+            await ctx.sleep("nap", "30ms");
+        });
+        const e1 = Date.now() - t0;
+        strict_1.default.ok(e1 < 500, `first sleep should be quick: ${e1}ms`);
+        strict_1.default.ok(e1 >= 25, `first sleep should be ~30ms: ${e1}ms`);
+        const t1 = Date.now();
+        // second run sees the wake_at in the past, returns immediately
+        await (0, index_1.run)(path, async (ctx) => {
+            await ctx.sleep("nap", "10s");
+        });
+        const e2 = Date.now() - t1;
+        strict_1.default.ok(e2 < 200, `second sleep should be near-instant: ${e2}ms`);
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("sleep resume ignores an invalid duration", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        await (0, index_1.run)(path, async (ctx) => {
+            await ctx.sleep("n", "1ms");
+        });
+        // Resume ignores the duration arg, so an invalid string must not throw.
+        await (0, index_1.run)(path, async (ctx) => {
+            await ctx.sleep("n", "not-a-duration");
+        });
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("sequential runs on the same file do not spuriously lock", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        // Back-to-back runs: if release() resolved before the helper actually
+        // dropped the flock, a later run would throw MundaneLockedError.
+        for (let i = 0; i < 5; i++) {
+            await (0, index_1.run)(path, async (ctx) => ctx.step(`s${i}`, async () => i));
+        }
+        const done = (await readSteps(path)).filter((s) => s.status === "done");
+        strict_1.default.equal(done.length, 5);
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("non-JSON value raises MundaneSerializationError", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        await strict_1.default.rejects((0, index_1.run)(path, async (ctx) => {
+            await ctx.step("a", async () => new Date());
+        }), (e) => e instanceof index_1.MundaneSerializationError);
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("locked task throws MundaneLockedError", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        let unblock;
+        const blocker = new Promise((r) => {
+            unblock = r;
+        });
+        const first = (0, index_1.run)(path, async (ctx) => {
+            await ctx.step("init", async () => 0);
+            await blocker;
+            return 0;
+        });
+        // Give the first run time to acquire the lock.
+        await new Promise((r) => setTimeout(r, 200));
+        await strict_1.default.rejects((0, index_1.run)(path, async () => { }), (e) => e instanceof index_1.MundaneLockedError);
+        unblock();
+        await first;
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("failed step re-runs on next invocation", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        await strict_1.default.rejects((0, index_1.run)(path, async (ctx) => {
+            await ctx.step("s", async () => {
+                throw new Error("boom");
+            });
+        }));
+        // A failed step is not cached; it must re-run.
+        const calls = [];
+        const r = await (0, index_1.run)(path, async (ctx) => ctx.step("s", async () => {
+            calls.push("s");
+            return 7;
+        }));
+        strict_1.default.equal(r, 7);
+        strict_1.default.deepEqual(calls, ["s"]);
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("failed row is reset to pending during re-run", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        await strict_1.default.rejects((0, index_1.run)(path, async (ctx) => {
+            await ctx.step("s", async () => {
+                throw new Error("boom");
+            });
+        }));
+        let midStatus = "";
+        let midError = "stale";
+        await (0, index_1.run)(path, async (ctx) => ctx.step("s", async () => {
+            const db = await (0, db_1.openDb)(path, { readonly: true });
+            const row = (await db.get("SELECT status, error FROM mundane_steps WHERE name='s'"));
+            await db.close();
+            midStatus = row.status;
+            midError = row.error;
+            return 7;
+        }));
+        strict_1.default.equal(midStatus, "pending");
+        strict_1.default.equal(midError, null);
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("pending step re-runs on resume", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        // Bootstrap, then leave a pending row behind (simulating a crash mid-step).
+        await (0, index_1.run)(path, async () => { });
+        const db = await (0, db_1.openDb)(path);
+        await db.run("INSERT INTO mundane_steps (name, kind, encoding, result, status, started_at) " +
+            "VALUES ('s', 'step', 'json', NULL, 'pending', ?)", [new Date().toISOString()]);
+        await db.close();
+        const calls = [];
+        const r = await (0, index_1.run)(path, async (ctx) => ctx.step("s", async () => {
+            calls.push("s");
+            return 5;
+        }));
+        strict_1.default.equal(r, 5);
+        strict_1.default.deepEqual(calls, ["s"]);
+    }
+    finally {
+        cleanup();
+    }
+});
+(0, node_test_1.test)("steps are committed and decode round-trips", async () => {
+    const { path, cleanup } = newDb();
+    try {
+        await (0, index_1.run)(path, async (ctx) => {
+            await ctx.step("a", async () => ({ x: 1 }));
+            await ctx.step("b", async () => "hello");
+        });
+        const done = (await readSteps(path)).filter((s) => s.status === "done");
+        strict_1.default.equal(done.length, 2);
+        strict_1.default.deepEqual(await readResult(path, "a"), { x: 1 });
+        strict_1.default.equal(await readResult(path, "b"), "hello");
+    }
+    finally {
+        cleanup();
+    }
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "mundane-sdk",
+  "version": "0.0.1",
+  "description": "Tiny durable-execution: one workflow run is one SQLite file.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paulbellamy/mundane.git"
+  },
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "node --test dist/test/"
+  },
+  "dependencies": {
+    "fs-ext": "^2.1.1",
+    "sqlite3": "^6.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "@types/fs-ext": "^2.0.3",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}