@boardwalk-labs/engine 0.1.0

package/dist/server_main.js

@@ -0,0 +1,203 @@
+// The composition root for the `boardwalk-server` binary (SPEC §2.4 + §5): parse config,
+// construct the Engine, mount the HTTP surface, wire graceful shutdown. Everything here is
+// glue — run semantics live in the engine, routing in the server, so this file stays thin
+// enough that config parsing (tested below) plus the already-tested pieces carry the risk.
+//
+// Config is ENVIRONMENT VARIABLES ONLY in v0 (`BOARDWALK_` prefix). A `boardwalk.toml` file
+// is deferred: Node has no TOML built-in and the zero-dependency rule (CODE_QUALITY §10)
+// beats a hand-rolled parser. Env vars are also what Docker/systemd operators reach for
+// first, so the deferral costs nothing in practice.
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseEnv } from "node:util";
+import { z } from "zod";
+import { Engine } from "./engine.js";
+import { EngineError } from "./errors.js";
+import { createEngineServer } from "./server/server.js";
+const DEFAULT_PORT = 8080;
+const DEFAULT_HOST = "127.0.0.1";
+// Why strictObject: a typo'd provider key ("apikey_env") silently doing nothing is exactly
+// the config bug an operator can't see — fail loudly at boot instead.
+// Header values: most-specific-first — the { from_env } object before the bare string, so the
+// object variant can't be string-coerced (zod unions are first-match-wins).
+const headerValueSchema = z.union([
+    z.strictObject({ from_env: z.string().min(1) }),
+    z.string().min(1),
+]);
+const providerEntrySchema = z.strictObject({
+    base_url: z.url(),
+    api_key_env: z.string().min(1).optional(),
+    protocol: z.enum(["anthropic", "openai"]).optional(),
+    headers: z.record(z.string().min(1), headerValueSchema).optional(),
+});
+const providersSchema = z.record(z.string().min(1), providerEntrySchema);
+const PROVIDERS_HINT = "Expected a JSON object of named providers, e.g. " +
+    '{"ollama":{"base_url":"http://localhost:11434/v1"},' +
+    '"groq":{"base_url":"https://api.groq.com/openai/v1","api_key_env":"GROQ_API_KEY"}}.';
+/** One line per Zod issue, path-prefixed, so the operator sees which provider field is wrong. */
+function formatIssues(error) {
+    return error.issues
+        .map((issue) => issue.path.length > 0
+        ? `${issue.path.map(String).join(".")}: ${issue.message}`
+        : issue.message)
+        .join("; ");
+}
+// Why allow 0: `listen(0)` binds an ephemeral port, which embedders and tests rely on; the
+// engine server reports the resolved port, so it is never a silent surprise.
+const portSchema = z.coerce.number().int().min(0).max(65535);
+function parsePort(raw) {
+    if (raw === undefined)
+        return DEFAULT_PORT;
+    const parsed = portSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new EngineError("VALIDATION", `BOARDWALK_PORT must be an integer between 0 and 65535, got "${raw}".`, "Unset BOARDWALK_PORT to use the default (8080); 0 binds an ephemeral port.");
+    }
+    return parsed.data;
+}
+function parseProviders(raw) {
+    if (raw === undefined)
+        return undefined;
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new EngineError("VALIDATION", `BOARDWALK_PROVIDERS is not valid JSON: ${err instanceof Error ? err.message : String(err)}.`, PROVIDERS_HINT);
+    }
+    const parsed = providersSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new EngineError("VALIDATION", `BOARDWALK_PROVIDERS is malformed: ${formatIssues(parsed.error)}.`, PROVIDERS_HINT);
+    }
+    // Why rebuild instead of returning parsed.data: under exactOptionalPropertyTypes, Zod's
+    // optional fields type as `string | undefined` while ProviderConfig declares plain optional
+    // keys — constructing entries keyless-when-absent satisfies the stricter shape with no cast.
+    const providers = {};
+    for (const [name, entry] of Object.entries(parsed.data)) {
+        providers[name] = {
+            base_url: entry.base_url,
+            ...(entry.api_key_env !== undefined ? { api_key_env: entry.api_key_env } : {}),
+            ...(entry.protocol !== undefined ? { protocol: entry.protocol } : {}),
+            ...(entry.headers !== undefined ? { headers: entry.headers } : {}),
+        };
+    }
+    return providers;
+}
+/**
+ * Parse server config from an environment map. Pure (no filesystem, no process globals) so
+ * every default and failure mode is unit-testable; `main()` passes `process.env`.
+ */
+export function loadServerConfig(env) {
+    // Why empty string counts as unset: `docker run -e BOARDWALK_PORT=` (and compose files with
+    // blank values) produce empty strings, and nobody means "the empty data dir" by that.
+    const get = (name) => {
+        const value = env[name];
+        return value === undefined || value === "" ? undefined : value;
+    };
+    // BOARDWALK_IN_DOCKER is set by the Dockerfile so the image defaults to the conventional
+    // volume mount point without baking container assumptions into bare-metal installs.
+    const inDocker = get("BOARDWALK_IN_DOCKER") === "1";
+    const dataDir = get("BOARDWALK_DATA_DIR") ?? (inDocker ? "/data" : "./boardwalk-data");
+    const defaultModel = get("BOARDWALK_DEFAULT_MODEL");
+    const providers = parseProviders(get("BOARDWALK_PROVIDERS"));
+    // BOARDWALK_INFERENCE_URL overrides the managed-inference gateway; BOARDWALK_API_KEY (the
+    // managed credential) is read directly from the environment at resolve time, not here.
+    const boardwalkBaseUrl = get("BOARDWALK_INFERENCE_URL");
+    const inference = defaultModel === undefined && providers === undefined && boardwalkBaseUrl === undefined
+        ? undefined
+        : {
+            ...(defaultModel !== undefined ? { default_model: defaultModel } : {}),
+            ...(providers !== undefined ? { providers } : {}),
+            ...(boardwalkBaseUrl !== undefined ? { boardwalk_base_url: boardwalkBaseUrl } : {}),
+        };
+    return {
+        dataDir,
+        host: get("BOARDWALK_HOST") ?? DEFAULT_HOST,
+        port: parsePort(get("BOARDWALK_PORT")),
+        inference,
+        envFile: get("BOARDWALK_ENV_FILE"),
+    };
+}
+/**
+ * Resolve the engine's secret/env source (SPEC §2.3 `secrets.get`): the configured
+ * BOARDWALK_ENV_FILE, else `<dataDir>/.env` when present. An explicitly named file that does
+ * not exist fails closed — a typo'd path silently falling back to process.env would make
+ * `secrets.get` read the wrong values with no warning.
+ */
+export function resolveEngineEnv(config) {
+    const explicit = config.envFile !== undefined;
+    const path = config.envFile ?? join(config.dataDir, ".env");
+    if (!existsSync(path)) {
+        if (explicit) {
+            throw new EngineError("VALIDATION", `BOARDWALK_ENV_FILE points at "${path}" but no file exists there.`, "Create the file, or unset BOARDWALK_ENV_FILE to fall back to the process environment.");
+        }
+        return null;
+    }
+    const parsed = parseEnv(readFileSync(path, "utf8"));
+    const env = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return { env, envLabel: path };
+}
+/**
+ * Boot the engine + HTTP surface from a resolved config. Split from `main()` so the whole
+ * boot path (sweep, listen, startup logging, teardown) is testable without touching process
+ * signals or `process.exit`.
+ */
+export async function startServer(config, log) {
+    const engineEnv = resolveEngineEnv(config);
+    const engine = new Engine({
+        dataDir: config.dataDir,
+        log,
+        ...(engineEnv !== null ? { env: engineEnv.env, envLabel: engineEnv.envLabel } : {}),
+        ...(config.inference !== undefined ? { inference: config.inference } : {}),
+    });
+    try {
+        const swept = engine.start();
+        log(`recovery sweep: restarted ${String(swept.resumed.length)} run(s), ` +
+            `cancelled ${String(swept.cancelled.length)}`);
+        const server = createEngineServer(engine, { host: config.host, log });
+        const { port } = await server.listen(config.port);
+        log(`data dir: ${resolve(config.dataDir)}`);
+        log(`listening on http://${config.host}:${String(port)}`);
+        log(`workflows deployed: ${String(engine.store.listWorkflows().length)}`);
+        let closed = false;
+        return {
+            port,
+            shutdown: async () => {
+                if (closed)
+                    return;
+                closed = true;
+                // Server first so no new runs arrive while the engine is releasing the scheduler.
+                await server.close();
+                engine.close();
+            },
+        };
+    }
+    catch (err) {
+        // The engine owns the SQLite handle from construction; a failed listen must not leak it.
+        engine.close();
+        throw err;
+    }
+}
+/**
+ * The `boardwalk-server` entrypoint (invoked by bin/boardwalk-server.js). Owns the only
+ * process-global concerns in the package: process.env, signal handlers, and exit codes.
+ */
+export async function main() {
+    const log = (line) => {
+        process.stderr.write(`${line}\n`);
+    };
+    const config = loadServerConfig(process.env);
+    const running = await startServer(config, log);
+    const onSignal = (signal) => {
+        log(`${signal} received — shutting down`);
+        void running.shutdown().then(() => process.exit(0), (err) => {
+            log(`shutdown failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        });
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+}

package/dist/store/migrations.d.ts

@@ -0,0 +1,21 @@
+import type { DatabaseSync } from "node:sqlite";
+export interface Migration {
+    /** The schema version this migration produces — `PRAGMA user_version` after it applies. */
+    readonly version: number;
+    /**
+     * The DDL/DML for this migration. Must not contain transaction control (BEGIN/COMMIT) —
+     * {@link migrate} wraps each migration and its version bump in one transaction.
+     */
+    readonly sql: string;
+}
+/** Every migration the engine knows, ascending. Append-only — never edit a shipped entry. */
+export declare const MIGRATIONS: readonly Migration[];
+/**
+ * Bring `db` up to the latest schema version. Idempotent: already-applied versions are
+ * skipped via `PRAGMA user_version`, so calling this on every open is the deployment story —
+ * there is no separate "migrate" command to forget. Each pending migration applies in its own
+ * transaction together with the version bump (all-or-nothing per version).
+ *
+ * The `migrations` parameter exists for tests; production callers use the default.
+ */
+export declare function migrate(db: DatabaseSync, migrations?: readonly Migration[]): void;

package/dist/store/migrations.js

@@ -0,0 +1,159 @@
+// Versioned, forward-only schema migrations for the engine database.
+//
+// The schema version lives in SQLite's `PRAGMA user_version` (an integer in the database
+// header): reading it costs nothing, needs no bookkeeping table, and — crucially — setting it
+// participates in the same transaction as the migration's DDL. A crash mid-migration therefore
+// leaves the database exactly at the previous version with none of the new schema applied
+// (CODE_QUALITY §2.2: multi-row writes are transactional; a half-migrated database is a state
+// the engine could not recover from).
+//
+// Forward-only: an older engine refuses a newer database instead of guessing what future
+// columns mean. Downgrades are restore-from-backup, not code.
+import { EngineError } from "../errors.js";
+// v1 — the full SPEC §4 schema. STRICT tables so SQLite enforces the declared column types
+// (a TEXT primary key can never silently hold an integer; INTEGER columns reject REALs).
+// All timestamps are integer milliseconds since epoch; all ids are ULIDs (CODE_QUALITY §2.2).
+const V1_SQL = `
+-- Workflows: the deployed unit. \`manifest\` is the validated JSON projection of the program's
+-- pure-literal meta; \`program\` is the bundled ESM source the run host executes; \`config\` is
+-- the per-deploy JSON config object.
+CREATE TABLE workflows (
+  id          TEXT PRIMARY KEY,
+  name        TEXT NOT NULL UNIQUE,
+  manifest    TEXT NOT NULL,
+  program     TEXT NOT NULL,
+  config      TEXT NOT NULL,
+  created_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL
+) STRICT;
+
+-- Runs: one row per run, owned by run-lifecycle code. \`status\` holds the SDK RunStatus values;
+-- \`error\` is a JSON {code,message}; usage tallies accumulate from leaf usage reports.
+CREATE TABLE runs (
+  id               TEXT PRIMARY KEY,
+  workflow_id      TEXT NOT NULL REFERENCES workflows (id),
+  status           TEXT NOT NULL,
+  trigger_kind     TEXT NOT NULL,
+  input            TEXT,
+  output           TEXT,
+  error            TEXT,
+  parent_run_id    TEXT REFERENCES runs (id),
+  idempotency_key  TEXT,
+  restarts         INTEGER NOT NULL DEFAULT 0,
+  tokens_in        INTEGER NOT NULL DEFAULT 0,
+  tokens_out       INTEGER NOT NULL DEFAULT 0,
+  usd_micros       INTEGER NOT NULL DEFAULT 0,
+  created_at       INTEGER NOT NULL,
+  started_at       INTEGER,
+  ended_at         INTEGER
+) STRICT;
+
+-- The workflows.call idempotent re-attach guarantee: a restarted parent re-running the same
+-- call site finds the child it already spawned instead of spawning a second one. Partial so
+-- runs without a key are unconstrained.
+CREATE UNIQUE INDEX runs_parent_idempotency_key
+  ON runs (parent_run_id, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;
+
+-- The recovery sweep ("which runs are still running?") and per-workflow run lists.
+CREATE INDEX runs_workflow_id_status ON runs (workflow_id, status);
+CREATE INDEX runs_status ON runs (status);
+
+-- Run events: the append-only event log implementing the SDK wire format. The (run_id, cursor)
+-- primary key IS the append-only guarantee — a cursor can never be rewritten.
+CREATE TABLE run_events (
+  run_id  TEXT NOT NULL REFERENCES runs (id),
+  cursor  INTEGER NOT NULL,
+  event   TEXT NOT NULL,
+  PRIMARY KEY (run_id, cursor)
+) STRICT, WITHOUT ROWID;
+
+-- Cron fires: the exactly-once guarantee. The scheduler records the fire in the same
+-- transaction as the run it creates; a duplicate (workflow, trigger, fire-time) is a CONFLICT,
+-- so a restarted scheduler can never double-fire a tick it already handled.
+CREATE TABLE cron_fires (
+  workflow_id    TEXT NOT NULL REFERENCES workflows (id),
+  trigger_index  INTEGER NOT NULL,
+  fire_time      INTEGER NOT NULL,
+  run_id         TEXT NOT NULL REFERENCES runs (id),
+  created_at     INTEGER NOT NULL,
+  PRIMARY KEY (workflow_id, trigger_index, fire_time)
+) STRICT, WITHOUT ROWID;
+
+-- Artifacts: metadata for files written via artifacts.write; \`path\` points into the engine's
+-- content-addressed store on disk (the bytes never live in SQLite).
+CREATE TABLE artifacts (
+  id            TEXT PRIMARY KEY,
+  run_id        TEXT NOT NULL REFERENCES runs (id),
+  name          TEXT NOT NULL,
+  content_type  TEXT NOT NULL,
+  path          TEXT NOT NULL,
+  size          INTEGER NOT NULL,
+  metadata      TEXT,
+  created_at    INTEGER NOT NULL
+) STRICT;
+
+CREATE INDEX artifacts_run_id ON artifacts (run_id);
+`;
+/** Every migration the engine knows, ascending. Append-only — never edit a shipped entry. */
+export const MIGRATIONS = [{ version: 1, sql: V1_SQL }];
+/**
+ * Bring `db` up to the latest schema version. Idempotent: already-applied versions are
+ * skipped via `PRAGMA user_version`, so calling this on every open is the deployment story —
+ * there is no separate "migrate" command to forget. Each pending migration applies in its own
+ * transaction together with the version bump (all-or-nothing per version).
+ *
+ * The `migrations` parameter exists for tests; production callers use the default.
+ */
+export function migrate(db, migrations = MIGRATIONS) {
+    assertWellFormed(migrations);
+    const latest = migrations.at(-1)?.version ?? 0;
+    const current = readUserVersion(db);
+    if (current > latest) {
+        throw new EngineError("INTERNAL", `database schema version ${String(current)} is newer than this engine understands ` +
+            `(latest known: ${String(latest)})`, "upgrade the engine, or point it at a database created by this engine version");
+    }
+    for (const migration of migrations) {
+        if (migration.version <= current)
+            continue;
+        db.exec("BEGIN IMMEDIATE");
+        try {
+            db.exec(migration.sql);
+            // Why interpolation: PRAGMA statements cannot take bound parameters. Safe — the version
+            // is validated as a positive integer by assertWellFormed above.
+            db.exec(`PRAGMA user_version = ${String(migration.version)}`);
+            db.exec("COMMIT");
+        }
+        catch (err) {
+            // Why best-effort: some SQLite errors abort the transaction themselves, making an
+            // explicit ROLLBACK fail with "no transaction is active"; the original error is the one
+            // that matters either way.
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Intentionally ignored — see above.
+            }
+            throw err;
+        }
+    }
+}
+// Why validate the list (it's a compile-time constant): a typo'd or reordered version number
+// would silently skip or re-apply DDL on user databases — fail loudly at boot instead.
+function assertWellFormed(migrations) {
+    let previous = 0;
+    for (const migration of migrations) {
+        if (!Number.isInteger(migration.version) || migration.version <= previous) {
+            throw new EngineError("INTERNAL", `migration versions must be strictly ascending positive integers ` +
+                `(got ${String(migration.version)} after ${String(previous)})`);
+        }
+        previous = migration.version;
+    }
+}
+function readUserVersion(db) {
+    const row = db.prepare("PRAGMA user_version").get();
+    const value = row?.user_version;
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0)
+        return value;
+    throw new EngineError("INTERNAL", "could not read PRAGMA user_version from the database");
+}

package/dist/store/store.d.ts

@@ -0,0 +1,194 @@
+import type { JsonValue, RunEvent, RunStatus, WorkflowManifest } from "@boardwalk-labs/workflow";
+export type { RunStatus };
+/** A deployed workflow: validated manifest + bundled program source + per-deploy config. */
+export interface WorkflowRow {
+    id: string;
+    name: string;
+    manifest: WorkflowManifest;
+    program: string;
+    config: Record<string, JsonValue>;
+    createdAt: number;
+    updatedAt: number;
+}
+export type TriggerKind = "cron" | "manual" | "webhook";
+/** The persisted form of a run failure — mirrors `toErrorShape` in errors.ts. */
+export interface RunErrorShape {
+    code: string;
+    message: string;
+}
+/** One run of a workflow, including its budget tallies and the call-tree linkage. */
+export interface RunRow {
+    id: string;
+    workflowId: string;
+    status: RunStatus;
+    triggerKind: TriggerKind;
+    input: unknown;
+    output: JsonValue | null;
+    error: RunErrorShape | null;
+    parentRunId: string | null;
+    idempotencyKey: string | null;
+    restarts: number;
+    tokensIn: number;
+    tokensOut: number;
+    usdMicros: number;
+    createdAt: number;
+    startedAt: number | null;
+    endedAt: number | null;
+}
+/** One entry in a run's append-only event log (the SDK wire format, cursor-indexed). */
+export interface EventRow {
+    runId: string;
+    cursor: number;
+    event: RunEvent;
+}
+/** Metadata for a file written via `artifacts.write`; `path` points into the on-disk store. */
+export interface ArtifactRow {
+    id: string;
+    runId: string;
+    name: string;
+    contentType: string;
+    path: string;
+    size: number;
+    metadata: Record<string, unknown> | null;
+    createdAt: number;
+}
+export interface StoreOptions {
+    /** Injectable time source (ms since epoch) so tests can pin timestamps. Default: Date.now. */
+    now?: () => number;
+}
+/**
+ * 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 declare class Store {
+    private readonly db;
+    private readonly now;
+    private readonly statements;
+    private inTransaction;
+    /** Open (or create) the engine database at `path` (`":memory:"` for tests) and migrate. */
+    constructor(path: string, options?: StoreOptions);
+    close(): void;
+    /**
+     * 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<T>(fn: () => T): T;
+    /**
+     * 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: {
+        name: string;
+        manifest: WorkflowManifest;
+        program: string;
+        config?: Record<string, JsonValue>;
+    }): WorkflowRow;
+    getWorkflow(name: string): WorkflowRow | null;
+    getWorkflowById(id: string): WorkflowRow | null;
+    listWorkflows(): WorkflowRow[];
+    /**
+     * 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: {
+        workflowId: string;
+        triggerKind: TriggerKind;
+        input?: unknown;
+        parentRunId?: string;
+        idempotencyKey?: string;
+    }): {
+        run: RunRow;
+        created: boolean;
+    };
+    getRun(id: string): RunRow | null;
+    /** List runs newest first, optionally filtered — the shape the run-log UI and sweeps need. */
+    listRuns(filter?: {
+        workflowId?: string;
+        statuses?: readonly RunStatus[];
+        limit?: number;
+        offset?: number;
+    }): RunRow[];
+    /**
+     * 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: string, status: RunStatus, opts?: {
+        error?: RunErrorShape;
+        output?: JsonValue;
+        startedAt?: number;
+        endedAt?: number;
+    }): void;
+    /**
+     * 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: string): number;
+    /**
+     * 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: string, usage: {
+        tokensIn?: number;
+        tokensOut?: number;
+        usdMicros?: number;
+    }): void;
+    /** Current usage tallies for budget enforcement. Throws NOT_FOUND on an unknown run. */
+    getRunUsage(id: string): {
+        tokensIn: number;
+        tokensOut: number;
+        usdMicros: number;
+    };
+    /**
+     * 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: string, rows: readonly {
+        cursor: number;
+        event: RunEvent;
+    }[]): void;
+    /** Events in cursor order, optionally resuming after a cursor (SSE `Last-Event-ID`). */
+    listEvents(runId: string, opts?: {
+        afterCursor?: number;
+        limit?: number;
+    }): EventRow[];
+    /** The run's latest cursor, or 0 when it has no events (cursors are 1-based). */
+    maxCursor(runId: string): number;
+    /**
+     * 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: {
+        workflowId: string;
+        triggerIndex: number;
+        fireTime: number;
+        runId: string;
+    }): void;
+    /** The latest recorded fire time for a trigger, or null — the catch-up policy's anchor. */
+    lastCronFire(workflowId: string, triggerIndex: number): number | null;
+    /** Record an artifact's metadata (the bytes live on disk at `path`, never in SQLite). */
+    createArtifact(args: {
+        runId: string;
+        name: string;
+        contentType: string;
+        path: string;
+        size: number;
+        metadata?: Record<string, unknown>;
+    }): ArtifactRow;
+    /** A run's artifacts in creation order (ULIDs sort by time). */
+    listArtifacts(runId: string): ArtifactRow[];
+    private prepare;
+    private getRunOrThrow;
+}