@boardwalk-labs/engine 0.1.0

package/dist/store/store.js

@@ -0,0 +1,567 @@
+// The engine's one persistence module — every SQL statement in the engine lives here
+// (CODE_QUALITY §7.2: "storage access goes through one persistence module"). The backend is
+// node:sqlite, synchronous on purpose: a single-node engine gains nothing from an async
+// driver, and synchronous statements make multi-row invariants trivially transactional.
+//
+// Conventions (CODE_QUALITY §2.2): ULID primary keys, integer-ms timestamps, and JSON columns
+// Zod-validated on READ — a row that fails validation throws EngineError("INTERNAL") naming
+// the table and column, so corrupt state surfaces as a loud error instead of flowing into the
+// scheduler as data.
+import { DatabaseSync } from "node:sqlite";
+import { z } from "zod";
+import { runEventSchema, workflowManifestSchema } from "@boardwalk-labs/workflow";
+import { EngineError } from "../errors.js";
+import { ulid } from "../ids.js";
+import { migrate } from "./migrations.js";
+// ============================================================================
+// Column schemas — every JSON/enum column has exactly one validator (CODE_QUALITY §2.2)
+// ============================================================================
+/**
+ * Build a Zod enum from an exhaustive flag record. Why a Record and not a plain array: the
+ * `Record<T, true>` argument makes the value list provably complete — adding a member to the
+ * union type without adding it here is a compile error, so reads can never reject a value a
+ * newer engine legitimately wrote.
+ */
+function enumFromKeys(flags) {
+    // Why the cast: Object.keys erases key types; the Record argument guarantees the keys are
+    // exactly the members of T.
+    return z.enum(Object.keys(flags));
+}
+const runStatusSchema = enumFromKeys({
+    queued: true,
+    pending: true,
+    running: true,
+    completed: true,
+    failed: true,
+    cancelled: true,
+    cancelling: true,
+});
+const triggerKindSchema = enumFromKeys({ cron: true, manual: true, webhook: true });
+const runErrorSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+});
+const jsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+]));
+const configSchema = z.record(z.string(), jsonValueSchema);
+const metadataSchema = z.record(z.string(), z.unknown());
+function columnError(table, column, problem) {
+    return new EngineError("INTERNAL", `corrupt row in ${table}.${column}: ${problem}`);
+}
+function describeValue(value) {
+    if (value === undefined)
+        return "missing column";
+    if (value === null)
+        return "NULL";
+    return typeof value;
+}
+function readText(row, table, column) {
+    const value = row[column];
+    if (typeof value === "string")
+        return value;
+    throw columnError(table, column, `expected TEXT, got ${describeValue(value)}`);
+}
+function readTextOrNull(row, table, column) {
+    return row[column] === null ? null : readText(row, table, column);
+}
+function readInteger(row, table, column) {
+    const value = row[column];
+    if (typeof value === "number" && Number.isInteger(value))
+        return value;
+    // Why bigint handling: node:sqlite returns bigint for values outside the JS safe-integer
+    // range. Our integers (timestamps, counters) always fit, so an overflow is corruption.
+    if (typeof value === "bigint") {
+        throw columnError(table, column, "INTEGER exceeds Number.MAX_SAFE_INTEGER");
+    }
+    throw columnError(table, column, `expected INTEGER, got ${describeValue(value)}`);
+}
+function readIntegerOrNull(row, table, column) {
+    return row[column] === null ? null : readInteger(row, table, column);
+}
+function readJson(row, table, column, schema) {
+    const raw = readText(row, table, column);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw columnError(table, column, "invalid JSON");
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        throw columnError(table, column, `failed schema validation: ${result.error.message}`);
+    }
+    return result.data;
+}
+function readJsonOrNull(row, table, column, schema) {
+    return row[column] === null ? null : readJson(row, table, column, schema);
+}
+function readEnum(row, table, column, schema) {
+    const raw = readText(row, table, column);
+    const result = schema.safeParse(raw);
+    if (!result.success)
+        throw columnError(table, column, `unexpected value "${raw}"`);
+    return result.data;
+}
+function mapWorkflow(row) {
+    return {
+        id: readText(row, "workflows", "id"),
+        name: readText(row, "workflows", "name"),
+        manifest: readJson(row, "workflows", "manifest", workflowManifestSchema),
+        program: readText(row, "workflows", "program"),
+        config: readJson(row, "workflows", "config", configSchema),
+        createdAt: readInteger(row, "workflows", "created_at"),
+        updatedAt: readInteger(row, "workflows", "updated_at"),
+    };
+}
+function mapRun(row) {
+    return {
+        id: readText(row, "runs", "id"),
+        workflowId: readText(row, "runs", "workflow_id"),
+        status: readEnum(row, "runs", "status", runStatusSchema),
+        triggerKind: readEnum(row, "runs", "trigger_kind", triggerKindSchema),
+        input: readJsonOrNull(row, "runs", "input", jsonValueSchema),
+        output: readJsonOrNull(row, "runs", "output", jsonValueSchema),
+        error: readJsonOrNull(row, "runs", "error", runErrorSchema),
+        parentRunId: readTextOrNull(row, "runs", "parent_run_id"),
+        idempotencyKey: readTextOrNull(row, "runs", "idempotency_key"),
+        restarts: readInteger(row, "runs", "restarts"),
+        tokensIn: readInteger(row, "runs", "tokens_in"),
+        tokensOut: readInteger(row, "runs", "tokens_out"),
+        usdMicros: readInteger(row, "runs", "usd_micros"),
+        createdAt: readInteger(row, "runs", "created_at"),
+        startedAt: readIntegerOrNull(row, "runs", "started_at"),
+        endedAt: readIntegerOrNull(row, "runs", "ended_at"),
+    };
+}
+function mapEvent(row) {
+    return {
+        runId: readText(row, "run_events", "run_id"),
+        cursor: readInteger(row, "run_events", "cursor"),
+        event: readJson(row, "run_events", "event", runEventSchema),
+    };
+}
+function mapArtifact(row) {
+    return {
+        id: readText(row, "artifacts", "id"),
+        runId: readText(row, "artifacts", "run_id"),
+        name: readText(row, "artifacts", "name"),
+        contentType: readText(row, "artifacts", "content_type"),
+        path: readText(row, "artifacts", "path"),
+        size: readInteger(row, "artifacts", "size"),
+        metadata: readJsonOrNull(row, "artifacts", "metadata", metadataSchema),
+        createdAt: readInteger(row, "artifacts", "created_at"),
+    };
+}
+// ============================================================================
+// SQLite error classification
+// ============================================================================
+const SQLITE_CONSTRAINT_FOREIGNKEY = 787;
+const SQLITE_CONSTRAINT_PRIMARYKEY = 1555;
+const SQLITE_CONSTRAINT_UNIQUE = 2067;
+function sqliteErrcode(err) {
+    if (typeof err === "object" && err !== null && "errcode" in err) {
+        const code = err.errcode;
+        if (typeof code === "number")
+            return code;
+    }
+    return undefined;
+}
+function isUniqueViolation(err) {
+    const code = sqliteErrcode(err);
+    return code === SQLITE_CONSTRAINT_PRIMARYKEY || code === SQLITE_CONSTRAINT_UNIQUE;
+}
+function isForeignKeyViolation(err) {
+    return sqliteErrcode(err) === SQLITE_CONSTRAINT_FOREIGNKEY;
+}
+/** Serialize a JSON column value; `undefined` stores NULL. Rejects unserializable values. */
+function serializeJson(value, what) {
+    if (value === undefined)
+        return null;
+    const json = JSON.stringify(value);
+    // Why the check: JSON.stringify returns undefined (despite its declared type) for values
+    // like bare functions; storing that would write the literal string "undefined".
+    if (typeof json !== "string") {
+        throw new EngineError("VALIDATION", `${what} is not JSON-serializable`);
+    }
+    return json;
+}
+function assertCountInteger(value, what) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new EngineError("VALIDATION", `${what} must be a non-negative integer (got ${String(value)})`);
+    }
+}
+// ============================================================================
+// The Store
+// ============================================================================
+/**
+ * The engine database. One instance per engine process; all access is synchronous and goes
+ * through this class — no other module writes SQL. Opening migrates the schema to the latest
+ * version, so "open the database" and "deploy the schema" are the same operation and can never
+ * drift apart.
+ */
+export class Store {
+    db;
+    now;
+    // Why a cache: prepared statements are compiled once and reused; event appends and run
+    // polling are hot paths, and the set of distinct SQL strings in this module is small and
+    // bounded, so the cache cannot grow without limit.
+    statements = new Map();
+    inTransaction = false;
+    /** Open (or create) the engine database at `path` (`":memory:"` for tests) and migrate. */
+    constructor(path, options = {}) {
+        this.now = options.now ?? Date.now;
+        this.db = new DatabaseSync(path);
+        // WAL lets readers (SSE tails, the local UI) proceed while a write is in flight. Foreign
+        // keys are per-connection in SQLite and OFF by default, so enable them on every open —
+        // they are what keeps an orphaned run/event/artifact row from ever existing.
+        this.db.exec("PRAGMA journal_mode = WAL");
+        this.db.exec("PRAGMA foreign_keys = ON");
+        migrate(this.db);
+    }
+    close() {
+        this.statements.clear();
+        this.db.close();
+    }
+    /**
+     * Run `fn` inside a single SQLite transaction (BEGIN IMMEDIATE … COMMIT/ROLLBACK).
+     * Composable: the scheduler wraps createRun + recordCronFire in one transaction so the
+     * exactly-once fire record and the run it spawned commit or vanish together. Nested calls
+     * join the outer transaction — an inner throw propagates and rolls back the whole thing
+     * (SQLite has no real nested transactions; partial inner commits would break the outer
+     * invariant anyway).
+     */
+    transaction(fn) {
+        if (this.inTransaction)
+            return fn();
+        // Why IMMEDIATE: take the write lock up front so the transaction can never fail with
+        // SQLITE_BUSY halfway through after reads have already happened.
+        this.db.exec("BEGIN IMMEDIATE");
+        this.inTransaction = true;
+        try {
+            const result = fn();
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (err) {
+            try {
+                this.db.exec("ROLLBACK");
+            }
+            catch {
+                // Some SQLite errors abort the transaction themselves; the original error matters.
+            }
+            throw err;
+        }
+        finally {
+            this.inTransaction = false;
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Workflows
+    // --------------------------------------------------------------------------
+    /**
+     * Insert a workflow or update it by name (deploying again is always an update — the name is
+     * the user-facing identity, so the id stays stable across redeploys and existing runs keep
+     * their foreign keys). `updated_at` bumps on update; `created_at` and `id` never change.
+     */
+    upsertWorkflow(args) {
+        // Why validate on write too: the manifest column is read back through this same schema; a
+        // caller bug is better rejected here than persisted and discovered as INTERNAL on read.
+        const manifest = workflowManifestSchema.safeParse(args.manifest);
+        if (!manifest.success) {
+            throw new EngineError("VALIDATION", `manifest for workflow "${args.name}" failed validation: ${manifest.error.message}`);
+        }
+        const manifestJson = JSON.stringify(manifest.data);
+        const configJson = JSON.stringify(args.config ?? {});
+        return this.transaction(() => {
+            const t = this.now();
+            const existing = this.prepare("SELECT id FROM workflows WHERE name = ?").get(args.name);
+            if (existing === undefined) {
+                this.prepare(`INSERT INTO workflows (id, name, manifest, program, config, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`).run(ulid(t), args.name, manifestJson, args.program, configJson, t, t);
+            }
+            else {
+                this.prepare("UPDATE workflows SET manifest = ?, program = ?, config = ?, updated_at = ? WHERE name = ?").run(manifestJson, args.program, configJson, t, args.name);
+            }
+            const row = this.getWorkflow(args.name);
+            if (row === null) {
+                throw new EngineError("INTERNAL", `workflow "${args.name}" vanished mid-upsert`);
+            }
+            return row;
+        });
+    }
+    getWorkflow(name) {
+        const row = this.prepare("SELECT * FROM workflows WHERE name = ?").get(name);
+        return row === undefined ? null : mapWorkflow(row);
+    }
+    getWorkflowById(id) {
+        const row = this.prepare("SELECT * FROM workflows WHERE id = ?").get(id);
+        return row === undefined ? null : mapWorkflow(row);
+    }
+    listWorkflows() {
+        return this.prepare("SELECT * FROM workflows ORDER BY name ASC").all().map(mapWorkflow);
+    }
+    // --------------------------------------------------------------------------
+    // Runs
+    // --------------------------------------------------------------------------
+    /**
+     * Create a run in status `queued`. With an `idempotencyKey` this is an atomic
+     * find-or-create on (parentRunId, idempotencyKey): a restarted parent re-running the same
+     * `workflows.call` site re-attaches to the child it already spawned (`created: false`)
+     * instead of spawning a duplicate — the heart of restart-on-crash semantics.
+     */
+    createRun(args) {
+        const inputJson = serializeJson(args.input, "run input");
+        return this.transaction(() => {
+            const parentRunId = args.parentRunId ?? null;
+            if (args.idempotencyKey !== undefined) {
+                // Why `IS ?`: top-level runs carry idempotency keys with a NULL parent, and `=` never
+                // matches NULL. The lookup runs inside the same transaction as the insert, so the
+                // find-or-create is atomic.
+                const existing = this.prepare("SELECT * FROM runs WHERE parent_run_id IS ? AND idempotency_key = ?").get(parentRunId, args.idempotencyKey);
+                if (existing !== undefined)
+                    return { run: mapRun(existing), created: false };
+            }
+            // Why explicit existence checks: a bare FK violation can't say WHICH reference was bad;
+            // these turn caller mistakes into precise NOT_FOUND errors.
+            if (this.prepare("SELECT id FROM workflows WHERE id = ?").get(args.workflowId) === undefined) {
+                throw new EngineError("NOT_FOUND", `workflow ${args.workflowId} not found`);
+            }
+            if (parentRunId !== null &&
+                this.prepare("SELECT id FROM runs WHERE id = ?").get(parentRunId) === undefined) {
+                throw new EngineError("NOT_FOUND", `parent run ${parentRunId} not found`);
+            }
+            const t = this.now();
+            const id = ulid(t);
+            this.prepare(`INSERT INTO runs (id, workflow_id, status, trigger_kind, input, parent_run_id, idempotency_key, created_at)
+         VALUES (?, ?, 'queued', ?, ?, ?, ?, ?)`).run(id, args.workflowId, args.triggerKind, inputJson, parentRunId, args.idempotencyKey ?? null, t);
+            return { run: this.getRunOrThrow(id), created: true };
+        });
+    }
+    getRun(id) {
+        const row = this.prepare("SELECT * FROM runs WHERE id = ?").get(id);
+        return row === undefined ? null : mapRun(row);
+    }
+    /** List runs newest first, optionally filtered — the shape the run-log UI and sweeps need. */
+    listRuns(filter = {}) {
+        const where = [];
+        const params = [];
+        if (filter.workflowId !== undefined) {
+            where.push("workflow_id = ?");
+            params.push(filter.workflowId);
+        }
+        if (filter.statuses !== undefined) {
+            if (filter.statuses.length === 0)
+                return [];
+            where.push(`status IN (${filter.statuses.map(() => "?").join(", ")})`);
+            params.push(...filter.statuses);
+        }
+        const whereSql = where.length > 0 ? ` WHERE ${where.join(" AND ")}` : "";
+        // Why the rowid tiebreak: created_at has millisecond resolution and a ULID's random tail
+        // does NOT order same-millisecond inserts — rowid is the only true insertion order, and
+        // "newest first" must be exact for the scheduler's oldest-first dispatch to be fair.
+        // LIMIT -1 is SQLite for "no limit".
+        const sql = `SELECT * FROM runs${whereSql} ORDER BY created_at DESC, rowid DESC LIMIT ? OFFSET ?`;
+        return this.prepare(sql)
+            .all(...params, filter.limit ?? -1, filter.offset ?? 0)
+            .map(mapRun);
+    }
+    /**
+     * Transition a run's status, optionally recording the outcome (`output` on completion,
+     * `error` on failure) and lifecycle timestamps in the same write — a crash can never leave
+     * a terminal status without its outcome.
+     */
+    updateRunStatus(id, status, opts = {}) {
+        const sets = ["status = ?"];
+        const params = [status];
+        if (opts.error !== undefined) {
+            sets.push("error = ?");
+            params.push(JSON.stringify(opts.error));
+        }
+        if (opts.output !== undefined) {
+            sets.push("output = ?");
+            params.push(JSON.stringify(opts.output));
+        }
+        if (opts.startedAt !== undefined) {
+            sets.push("started_at = ?");
+            params.push(opts.startedAt);
+        }
+        if (opts.endedAt !== undefined) {
+            sets.push("ended_at = ?");
+            params.push(opts.endedAt);
+        }
+        const result = this.prepare(`UPDATE runs SET ${sets.join(", ")} WHERE id = ?`).run(...params, id);
+        if (Number(result.changes) === 0) {
+            throw new EngineError("NOT_FOUND", `run ${id} not found`);
+        }
+    }
+    /**
+     * Bump the restart counter and return the new value in one statement, so the supervisor's
+     * "have we exhausted restarts?" check is race-free even across its own crash-recovery.
+     */
+    incrementRestarts(id) {
+        const row = this.prepare("UPDATE runs SET restarts = restarts + 1 WHERE id = ? RETURNING restarts").get(id);
+        if (row === undefined)
+            throw new EngineError("NOT_FOUND", `run ${id} not found`);
+        return readInteger(row, "runs", "restarts");
+    }
+    /**
+     * Accumulate leaf usage onto the run's tallies. Additive (not a set) because each `agent()`
+     * leaf reports independently and budgets are checked against the running total.
+     */
+    addRunUsage(id, usage) {
+        const tokensIn = usage.tokensIn ?? 0;
+        const tokensOut = usage.tokensOut ?? 0;
+        const usdMicros = usage.usdMicros ?? 0;
+        assertCountInteger(tokensIn, "tokensIn");
+        assertCountInteger(tokensOut, "tokensOut");
+        assertCountInteger(usdMicros, "usdMicros");
+        const result = this.prepare(`UPDATE runs SET tokens_in = tokens_in + ?, tokens_out = tokens_out + ?, usd_micros = usd_micros + ?
+       WHERE id = ?`).run(tokensIn, tokensOut, usdMicros, id);
+        if (Number(result.changes) === 0) {
+            throw new EngineError("NOT_FOUND", `run ${id} not found`);
+        }
+    }
+    /** Current usage tallies for budget enforcement. Throws NOT_FOUND on an unknown run. */
+    getRunUsage(id) {
+        const row = this.prepare("SELECT tokens_in, tokens_out, usd_micros FROM runs WHERE id = ?").get(id);
+        if (row === undefined)
+            throw new EngineError("NOT_FOUND", `run ${id} not found`);
+        return {
+            tokensIn: readInteger(row, "runs", "tokens_in"),
+            tokensOut: readInteger(row, "runs", "tokens_out"),
+            usdMicros: readInteger(row, "runs", "usd_micros"),
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Run events (append-only)
+    // --------------------------------------------------------------------------
+    /**
+     * Append a batch of events in one transaction: all rows land or none do, so a consumer can
+     * never observe a half-written batch and cursor resumption stays gap-free. A duplicate
+     * cursor throws CONFLICT — the log is append-only and a cursor is never rewritten.
+     */
+    appendEvents(runId, rows) {
+        if (rows.length === 0)
+            return;
+        for (const row of rows) {
+            if (!Number.isInteger(row.cursor) || row.cursor < 1) {
+                throw new EngineError("VALIDATION", `event cursor must be a positive integer (got ${String(row.cursor)})`);
+            }
+        }
+        this.transaction(() => {
+            const insert = this.prepare("INSERT INTO run_events (run_id, cursor, event) VALUES (?, ?, ?)");
+            for (const row of rows) {
+                try {
+                    insert.run(runId, row.cursor, JSON.stringify(row.event));
+                }
+                catch (err) {
+                    if (isUniqueViolation(err)) {
+                        throw new EngineError("CONFLICT", `event cursor ${String(row.cursor)} already exists for run ${runId}`);
+                    }
+                    if (isForeignKeyViolation(err)) {
+                        throw new EngineError("NOT_FOUND", `run ${runId} not found`);
+                    }
+                    throw err;
+                }
+            }
+        });
+    }
+    /** Events in cursor order, optionally resuming after a cursor (SSE `Last-Event-ID`). */
+    listEvents(runId, opts = {}) {
+        return this.prepare("SELECT * FROM run_events WHERE run_id = ? AND cursor > ? ORDER BY cursor ASC LIMIT ?")
+            .all(runId, opts.afterCursor ?? 0, opts.limit ?? -1)
+            .map(mapEvent);
+    }
+    /** The run's latest cursor, or 0 when it has no events (cursors are 1-based). */
+    maxCursor(runId) {
+        const row = this.prepare("SELECT COALESCE(MAX(cursor), 0) AS max_cursor FROM run_events WHERE run_id = ?").get(runId);
+        // An aggregate always yields one row; its absence means the connection is broken.
+        if (row === undefined)
+            throw new EngineError("INTERNAL", "MAX(cursor) returned no row");
+        return readInteger(row, "run_events", "max_cursor");
+    }
+    // --------------------------------------------------------------------------
+    // Cron fires (exactly-once)
+    // --------------------------------------------------------------------------
+    /**
+     * Record that a cron tick fired. The (workflowId, triggerIndex, fireTime) primary key is the
+     * exactly-once guarantee: a scheduler that crashed after firing and restarted gets CONFLICT
+     * here instead of silently double-running the workflow. Callers wrap this with createRun in
+     * one {@link transaction} so the fire record and the run commit together.
+     */
+    recordCronFire(args) {
+        try {
+            this.prepare(`INSERT INTO cron_fires (workflow_id, trigger_index, fire_time, run_id, created_at)
+         VALUES (?, ?, ?, ?, ?)`).run(args.workflowId, args.triggerIndex, args.fireTime, args.runId, this.now());
+        }
+        catch (err) {
+            if (isUniqueViolation(err)) {
+                throw new EngineError("CONFLICT", `cron fire already recorded for workflow ${args.workflowId} ` +
+                    `trigger ${String(args.triggerIndex)} at ${String(args.fireTime)}`);
+            }
+            if (isForeignKeyViolation(err)) {
+                throw new EngineError("NOT_FOUND", `workflow ${args.workflowId} or run ${args.runId} not found`);
+            }
+            throw err;
+        }
+    }
+    /** The latest recorded fire time for a trigger, or null — the catch-up policy's anchor. */
+    lastCronFire(workflowId, triggerIndex) {
+        const row = this.prepare("SELECT MAX(fire_time) AS last_fire FROM cron_fires WHERE workflow_id = ? AND trigger_index = ?").get(workflowId, triggerIndex);
+        return row === undefined ? null : readIntegerOrNull(row, "cron_fires", "last_fire");
+    }
+    // --------------------------------------------------------------------------
+    // Artifacts
+    // --------------------------------------------------------------------------
+    /** Record an artifact's metadata (the bytes live on disk at `path`, never in SQLite). */
+    createArtifact(args) {
+        assertCountInteger(args.size, "artifact size");
+        const metadataJson = serializeJson(args.metadata, "artifact metadata");
+        const t = this.now();
+        const id = ulid(t);
+        try {
+            this.prepare(`INSERT INTO artifacts (id, run_id, name, content_type, path, size, metadata, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(id, args.runId, args.name, args.contentType, args.path, args.size, metadataJson, t);
+        }
+        catch (err) {
+            if (isForeignKeyViolation(err)) {
+                throw new EngineError("NOT_FOUND", `run ${args.runId} not found`);
+            }
+            throw err;
+        }
+        const row = this.prepare("SELECT * FROM artifacts WHERE id = ?").get(id);
+        if (row === undefined)
+            throw new EngineError("INTERNAL", `artifact ${id} vanished mid-write`);
+        return mapArtifact(row);
+    }
+    /** A run's artifacts in creation order (ULIDs sort by time). */
+    listArtifacts(runId) {
+        return this.prepare("SELECT * FROM artifacts WHERE run_id = ? ORDER BY id ASC")
+            .all(runId)
+            .map(mapArtifact);
+    }
+    // --------------------------------------------------------------------------
+    // Internals
+    // --------------------------------------------------------------------------
+    prepare(sql) {
+        let statement = this.statements.get(sql);
+        if (statement === undefined) {
+            statement = this.db.prepare(sql);
+            this.statements.set(sql, statement);
+        }
+        return statement;
+    }
+    getRunOrThrow(id) {
+        const run = this.getRun(id);
+        if (run === null)
+            throw new EngineError("INTERNAL", `run ${id} vanished mid-write`);
+        return run;
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@boardwalk-labs/engine",
+  "version": "0.1.0",
+  "description": "The Boardwalk single-node engine: cron scheduling, run lifecycle, SQLite state, and the local run log. Powers `boardwalk dev` and the self-hosted server.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boardwalk-labs/boardwalk.git"
+  },
+  "homepage": "https://github.com/boardwalk-labs/boardwalk#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "packageManager": "pnpm@10.23.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "boardwalk-server": "bin/boardwalk-server.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p conformance --noEmit",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix --max-warnings 0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@boardwalk-labs/workflow": "^0.1.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.4.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.20.0",
+    "vitest": "^3.0.0"
+  }
+}