@boardwalk-labs/engine 0.1.0

package/dist/scheduler/scheduler.d.ts

@@ -0,0 +1,54 @@
+import { type Clock } from "../clock.js";
+import type { Store } from "../store/store.js";
+export interface SchedulerOptions {
+    store: Store;
+    /** Start executing a queued run (the engine wires supervisor.supervise here). */
+    dispatch: (runId: string) => void;
+    /** Emit the `queued` lifecycle event for a run this scheduler created. */
+    emitQueued: (runId: string) => void;
+    clock?: Clock;
+    /** Engine diagnostics (catch-up notices, tick overruns). Default: console.error. */
+    log?: (line: string) => void;
+    /** Tick cadence of the background loop. Default 1s. */
+    tickIntervalMs?: number;
+    /** Ticks slower than this are logged (CODE_QUALITY §4.2). Default 250ms. */
+    tickBudgetMs?: number;
+}
+export declare class Scheduler {
+    private readonly store;
+    private readonly dispatch;
+    private readonly emitQueued;
+    private readonly clock;
+    private readonly log;
+    private readonly tickIntervalMs;
+    private readonly tickBudgetMs;
+    /** Per (workflow, trigger) fire anchor: the last fire time we are PAST (epoch ms). */
+    private readonly anchors;
+    private readonly scheduleCache;
+    /** Runs handed to `dispatch` that haven't left `queued` yet — prevents re-dispatch spam. */
+    private readonly handedOut;
+    private stopController;
+    constructor(opts: SchedulerOptions);
+    /** Start the background loop. Idempotent; `stop()` to end it. */
+    start(): void;
+    stop(): void;
+    private loop;
+    /**
+     * One scheduler pass: fire every due cron trigger, then dispatch queued runs through the
+     * concurrency gate. Public so tests (and the engine's boot path) can drive it directly.
+     */
+    tick(): void;
+    private fireDueTriggers;
+    /** Create the run + the fire record atomically; a duplicate fire is impossible by schema. */
+    private fireOnce;
+    /**
+     * The anchor for a trigger, establishing the catch-up policy on first sight: a trigger with
+     * fire history starts from its last recorded fire — missed fires in between are counted and
+     * either skipped (default, with a notice) or coalesced into ONE immediate run
+     * (`catch_up: "once"`). A trigger never seen before starts from now (no retroactive fires).
+     */
+    private ensureAnchor;
+    private dispatchQueued;
+    private groupHasActiveRun;
+    private schedule;
+}

package/dist/scheduler/scheduler.js

@@ -0,0 +1,215 @@
+// The cron scheduler (SPEC §2.1). Layering: it fires runs; it knows nothing about what a
+// workflow does (CODE_QUALITY §7.2). Execution is injected (`dispatch`) so this module never
+// touches processes, and time is injected (`Clock`) so tests drive it deterministically.
+//
+// Correctness rules implemented here:
+//   - A due fire happens exactly once: the fire record and the run row are written in ONE
+//     store transaction, keyed (workflow, trigger index, fire time) — a crash between tick
+//     and dispatch leaves a queued run the boot sweep picks up, never a duplicate.
+//   - Catch-up on restart: missed fires are detected from the persisted fire history and
+//     SKIPPED with a logged notice by default; deploy config `catch_up: "once"` runs a single
+//     run for any number of missed fires (the manifest has no catch_up field — this is
+//     engine-operational policy, so it lives in the engine's deploy-time config).
+//     Never silent, never a thundering herd.
+//   - Concurrency modes gate DISPATCH, not queueing: `serial` / `serial_by_key` hold queued
+//     runs until the group's active run reaches a terminal status.
+import { systemClock } from "../clock.js";
+import { nextFire, parseCron } from "../cron/cron.js";
+/** How many missed fires we enumerate before giving up counting (the notice says "≥"). */
+const MISSED_SCAN_CAP = 10_000;
+const ACTIVE_STATUSES = ["pending", "running", "cancelling"];
+export class Scheduler {
+    store;
+    dispatch;
+    emitQueued;
+    clock;
+    log;
+    tickIntervalMs;
+    tickBudgetMs;
+    /** Per (workflow, trigger) fire anchor: the last fire time we are PAST (epoch ms). */
+    anchors = new Map();
+    scheduleCache = new Map();
+    /** Runs handed to `dispatch` that haven't left `queued` yet — prevents re-dispatch spam. */
+    handedOut = new Set();
+    stopController = null;
+    constructor(opts) {
+        this.store = opts.store;
+        this.dispatch = opts.dispatch;
+        this.emitQueued = opts.emitQueued;
+        this.clock = opts.clock ?? systemClock;
+        this.log = opts.log ?? ((line) => console.error(line));
+        this.tickIntervalMs = opts.tickIntervalMs ?? 1000;
+        this.tickBudgetMs = opts.tickBudgetMs ?? 250;
+    }
+    /** Start the background loop. Idempotent; `stop()` to end it. */
+    start() {
+        if (this.stopController !== null)
+            return;
+        const controller = new AbortController();
+        this.stopController = controller;
+        void this.loop(controller.signal);
+    }
+    stop() {
+        this.stopController?.abort();
+        this.stopController = null;
+    }
+    async loop(signal) {
+        while (!signal.aborted) {
+            this.tick();
+            try {
+                await this.clock.sleep(this.tickIntervalMs, signal);
+            }
+            catch {
+                return; // aborted — clean stop
+            }
+        }
+    }
+    /**
+     * One scheduler pass: fire every due cron trigger, then dispatch queued runs through the
+     * concurrency gate. Public so tests (and the engine's boot path) can drive it directly.
+     */
+    tick() {
+        const started = this.clock.now();
+        for (const workflow of this.store.listWorkflows()) {
+            this.fireDueTriggers(workflow);
+        }
+        this.dispatchQueued();
+        const elapsed = this.clock.now() - started;
+        if (elapsed > this.tickBudgetMs) {
+            this.log(`[scheduler] tick took ${String(elapsed)}ms (budget ${String(this.tickBudgetMs)}ms)`);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Firing
+    // --------------------------------------------------------------------------
+    fireDueTriggers(workflow) {
+        const now = this.clock.now();
+        workflow.manifest.triggers.forEach((trigger, index) => {
+            if (trigger.kind !== "cron")
+                return;
+            const schedule = this.schedule(trigger.expr, trigger.timezone);
+            let anchor = this.ensureAnchor(workflow, index, schedule, trigger.timezone, now);
+            let due = nextFire(schedule, anchor, trigger.timezone);
+            while (due !== null && due <= now) {
+                this.fireOnce(workflow, index, due);
+                anchor = due;
+                due = nextFire(schedule, anchor, trigger.timezone);
+            }
+            this.anchors.set(anchorKey(workflow.id, index), anchor);
+        });
+    }
+    /** Create the run + the fire record atomically; a duplicate fire is impossible by schema. */
+    fireOnce(workflow, triggerIndex, fireTime) {
+        const runId = this.store.transaction(() => {
+            const { run } = this.store.createRun({ workflowId: workflow.id, triggerKind: "cron" });
+            this.store.recordCronFire({ workflowId: workflow.id, triggerIndex, fireTime, runId: run.id });
+            return run.id;
+        });
+        this.emitQueued(runId);
+    }
+    /**
+     * The anchor for a trigger, establishing the catch-up policy on first sight: a trigger with
+     * fire history starts from its last recorded fire — missed fires in between are counted and
+     * either skipped (default, with a notice) or coalesced into ONE immediate run
+     * (`catch_up: "once"`). A trigger never seen before starts from now (no retroactive fires).
+     */
+    ensureAnchor(workflow, triggerIndex, schedule, timezone, now) {
+        const key = anchorKey(workflow.id, triggerIndex);
+        const existing = this.anchors.get(key);
+        if (existing !== undefined)
+            return existing;
+        const lastFire = this.store.lastCronFire(workflow.id, triggerIndex);
+        if (lastFire === null) {
+            this.anchors.set(key, now);
+            return now;
+        }
+        // Count what was missed while no engine was running.
+        let missedCount = 0;
+        let latestMissed = null;
+        let cursor = lastFire;
+        while (missedCount < MISSED_SCAN_CAP) {
+            const next = nextFire(schedule, cursor, timezone);
+            if (next === null || next > now)
+                break;
+            missedCount += 1;
+            latestMissed = next;
+            cursor = next;
+        }
+        let anchor = lastFire;
+        if (latestMissed !== null) {
+            anchor = latestMissed;
+            const mode = catchUpMode(workflow);
+            const counted = missedCount >= MISSED_SCAN_CAP ? `≥${String(missedCount)}` : String(missedCount);
+            if (mode === "once") {
+                this.fireOnce(workflow, triggerIndex, latestMissed);
+                this.log(`[scheduler] ${workflow.name}: ${counted} missed cron fire(s) while the engine was down; ran once (catch_up: "once").`);
+            }
+            else {
+                this.log(`[scheduler] ${workflow.name}: skipped ${counted} missed cron fire(s) while the engine was down (catch_up: "skip").`);
+            }
+        }
+        this.anchors.set(key, anchor);
+        return anchor;
+    }
+    // --------------------------------------------------------------------------
+    // Dispatch (the concurrency gate)
+    // --------------------------------------------------------------------------
+    dispatchQueued() {
+        const queued = this.store.listRuns({ statuses: ["queued"] });
+        // Prune the handed-out set: anything no longer queued has been picked up (or finished).
+        const queuedIds = new Set(queued.map((r) => r.id));
+        for (const id of this.handedOut) {
+            if (!queuedIds.has(id))
+                this.handedOut.delete(id);
+        }
+        // Oldest first — listRuns returns newest first.
+        queued.reverse();
+        const groupsDispatchedNow = new Set();
+        for (const run of queued) {
+            if (this.handedOut.has(run.id))
+                continue;
+            const workflow = this.store.getWorkflowById(run.workflowId);
+            if (workflow === null)
+                continue;
+            const group = concurrencyGroup(workflow);
+            if (group !== null) {
+                if (groupsDispatchedNow.has(group))
+                    continue;
+                if (this.groupHasActiveRun(workflow, run))
+                    continue;
+                groupsDispatchedNow.add(group);
+            }
+            this.handedOut.add(run.id);
+            this.dispatch(run.id);
+        }
+    }
+    groupHasActiveRun(workflow, _candidate) {
+        // serial_by_key's key is a static manifest string (SDK schema), so within one workflow it
+        // gates exactly like serial: any active run of the workflow blocks dispatch.
+        return this.store.listRuns({ workflowId: workflow.id, statuses: ACTIVE_STATUSES }).length > 0;
+    }
+    schedule(expr, timezone) {
+        const key = `${expr}${timezone ?? ""}`;
+        let parsed = this.scheduleCache.get(key);
+        if (parsed === undefined) {
+            parsed = parseCron(expr);
+            this.scheduleCache.set(key, parsed);
+        }
+        return parsed;
+    }
+}
+function anchorKey(workflowId, triggerIndex) {
+    return `${workflowId}#${String(triggerIndex)}`;
+}
+function catchUpMode(workflow) {
+    return workflow.config.catch_up === "once" ? "once" : "skip";
+}
+/** The dispatch-gate group for a workflow, or null for unlimited concurrency. */
+function concurrencyGroup(workflow) {
+    const concurrency = workflow.manifest.concurrency;
+    if (concurrency === undefined || concurrency.mode === "unlimited")
+        return null;
+    if (concurrency.mode === "serial")
+        return workflow.id;
+    return `${workflow.id}:${concurrency.key}`;
+}

package/dist/server/http.d.ts

@@ -0,0 +1,42 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import type { Channel, JsonValue } from "@boardwalk-labs/workflow";
+/** Bodies above this reject with 413 — nothing on this surface needs more than 1 MiB. */
+export declare const MAX_BODY_BYTES: number;
+/**
+ * An error that already knows its HTTP response. Routes throw these (or EngineErrors) and the
+ * top-level dispatcher renders them, so every endpoint shares one wire shape:
+ * `{ error: { code, message, hint? } }`.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** A one-line pointer at the fix (env var to set, valid values) — safe to show anywhere. */
+    readonly hint: string | undefined;
+    constructor(status: number, code: string, message: string, hint?: string);
+}
+/**
+ * JSON values as a Zod schema, for narrowing parsed request bodies. The store keeps its own
+ * private copy — two private copies beat widening the store's public surface for one schema.
+ */
+export declare const jsonValueSchema: z.ZodType<JsonValue>;
+/** Serialize `payload` and finish the response. The one place response JSON is written. */
+export declare function sendJson(res: ServerResponse, status: number, payload: object, headers?: Record<string, string>): void;
+/**
+ * Render any thrown value as the JSON error contract. `err` is `unknown` because this sits
+ * behind a catch boundary — the one place that type is unavoidable; it is narrowed immediately
+ * via instanceof. Internals (stacks, unexpected messages) go to `log`, never to the client.
+ */
+export declare function sendError(res: ServerResponse, err: unknown, log: (line: string) => void): void;
+/** Buffer a request body, rejecting 413 as soon as it exceeds `limitBytes`. */
+export declare function readBody(req: IncomingMessage, limitBytes: number): Promise<Buffer>;
+/** Parse a body as JSON and narrow it with `schema` — the trust boundary for HTTP input. */
+export declare function parseJsonBody<T>(raw: Buffer, schema: z.ZodType<T>, what: string): T;
+/** Parse `?name=<n>` as a non-negative integer, falling back when the parameter is absent. */
+export declare function parseNonNegativeInt(url: URL, name: string, fallback: number): number;
+/**
+ * The channel subscription for an event read (`/events` and `/stream` share this so a tail and
+ * its catch-up reads can never disagree): `?verbose=true` = everything, `?channels=a,b` = an
+ * explicit set, neither = MASTER_SPEC §2.5's default of lifecycle + phase + output.
+ */
+export declare function parseChannelSelection(url: URL): readonly Channel[];

package/dist/server/http.js

@@ -0,0 +1,183 @@
+// Shared HTTP plumbing for the engine server: the error type every route throws, JSON
+// request/response helpers, and query/body parsing. Bare node:http is deliberate (no
+// third-party HTTP framework anywhere in the Boardwalk stack) — these helpers are the entire
+// "framework", so every trust boundary (bodies, query params, headers) is narrowed with Zod
+// or a type predicate before any engine call sees the data.
+import { z } from "zod";
+import { CHANNELS, DEFAULT_CHANNELS } from "@boardwalk-labs/workflow";
+import { EngineError } from "../errors.js";
+/** Bodies above this reject with 413 — nothing on this surface needs more than 1 MiB. */
+export const MAX_BODY_BYTES = 1024 * 1024;
+/**
+ * An error that already knows its HTTP response. Routes throw these (or EngineErrors) and the
+ * top-level dispatcher renders them, so every endpoint shares one wire shape:
+ * `{ error: { code, message, hint? } }`.
+ */
+export class HttpError extends Error {
+    status;
+    code;
+    /** A one-line pointer at the fix (env var to set, valid values) — safe to show anywhere. */
+    hint;
+    constructor(status, code, message, hint) {
+        super(message);
+        this.name = "HttpError";
+        this.status = status;
+        this.code = code;
+        this.hint = hint;
+    }
+}
+/**
+ * JSON values as a Zod schema, for narrowing parsed request bodies. The store keeps its own
+ * private copy — two private copies beat widening the store's public surface for one schema.
+ */
+export const jsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+]));
+/** Serialize `payload` and finish the response. The one place response JSON is written. */
+export function sendJson(res, status, payload, headers = {}) {
+    // Why stringify before writeHead: a serialization failure must not escape after the status
+    // line is on the wire, where the JSON error contract is unreachable.
+    const body = JSON.stringify(payload);
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", ...headers });
+    res.end(body);
+}
+/**
+ * Render any thrown value as the JSON error contract. `err` is `unknown` because this sits
+ * behind a catch boundary — the one place that type is unavoidable; it is narrowed immediately
+ * via instanceof. Internals (stacks, unexpected messages) go to `log`, never to the client.
+ */
+export function sendError(res, err, log) {
+    if (res.headersSent || res.destroyed) {
+        // Mid-stream failure (e.g. SSE): the JSON contract is unreachable; drop the connection.
+        res.destroy();
+        return;
+    }
+    if (err instanceof HttpError) {
+        // Why connection: close on 413: the client may still be sending the oversized body; close
+        // tells it to stop instead of stalling the kept-alive socket on unread data.
+        const headers = err.status === 413 ? { connection: "close" } : {};
+        sendJson(res, err.status, { error: { code: err.code, message: err.message, hint: err.hint } }, headers);
+        return;
+    }
+    if (err instanceof EngineError) {
+        const status = engineErrorStatus(err);
+        if (status !== null) {
+            sendJson(res, status, { error: { code: err.code, message: err.message, hint: err.hint } });
+            return;
+        }
+    }
+    log(`internal error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+    sendJson(res, 500, { error: { code: "INTERNAL", message: "Internal server error." } });
+}
+/**
+ * The HTTP status an EngineError code implies, or null for codes that must render as an
+ * opaque 500 (anything unexpected at this surface could leak engine internals).
+ */
+function engineErrorStatus(err) {
+    switch (err.code) {
+        case "NOT_FOUND":
+            return 404;
+        case "VALIDATION":
+            return 400;
+        case "CONFLICT":
+            return 409;
+        case "UNSUPPORTED":
+            return 400;
+        default:
+            return null;
+    }
+}
+/** Buffer a request body, rejecting 413 as soon as it exceeds `limitBytes`. */
+export function readBody(req, limitBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let received = 0;
+        let settled = false;
+        const fail = (failure) => {
+            if (settled)
+                return;
+            settled = true;
+            chunks.length = 0;
+            reject(failure);
+        };
+        // Why the Buffer annotation: no encoding is set on the stream, so chunks are Buffers per
+        // the node:http contract; the generic listener type erases that to `any`.
+        req.on("data", (chunk) => {
+            if (settled)
+                return;
+            received += chunk.length;
+            if (received > limitBytes) {
+                fail(new HttpError(413, "PAYLOAD_TOO_LARGE", `Request body exceeds the ${String(limitBytes)}-byte limit.`));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(Buffer.concat(chunks));
+        });
+        req.on("error", () => {
+            fail(new HttpError(400, "VALIDATION", "Request body could not be read."));
+        });
+    });
+}
+/** Parse a body as JSON and narrow it with `schema` — the trust boundary for HTTP input. */
+export function parseJsonBody(raw, schema, what) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString("utf8"));
+    }
+    catch {
+        throw new HttpError(400, "VALIDATION", `${what} is not valid JSON.`);
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        throw new HttpError(400, "VALIDATION", `${what} failed validation: ${result.error.message}`);
+    }
+    return result.data;
+}
+/** Parse `?name=<n>` as a non-negative integer, falling back when the parameter is absent. */
+export function parseNonNegativeInt(url, name, fallback) {
+    const raw = url.searchParams.get(name);
+    if (raw === null)
+        return fallback;
+    const value = Number(raw);
+    if (raw.trim() === "" || !Number.isInteger(value) || value < 0) {
+        throw new HttpError(400, "VALIDATION", `Query parameter "${name}" must be a non-negative integer (got "${raw}").`);
+    }
+    return value;
+}
+function isChannel(value) {
+    return CHANNELS.some((channel) => channel === value);
+}
+/**
+ * The channel subscription for an event read (`/events` and `/stream` share this so a tail and
+ * its catch-up reads can never disagree): `?verbose=true` = everything, `?channels=a,b` = an
+ * explicit set, neither = MASTER_SPEC §2.5's default of lifecycle + phase + output.
+ */
+export function parseChannelSelection(url) {
+    const verbose = url.searchParams.get("verbose");
+    if (verbose !== null && verbose !== "true" && verbose !== "false") {
+        throw new HttpError(400, "VALIDATION", `Query parameter "verbose" must be "true" or "false" (got "${verbose}").`);
+    }
+    if (verbose === "true")
+        return CHANNELS;
+    const raw = url.searchParams.get("channels");
+    if (raw === null)
+        return DEFAULT_CHANNELS;
+    const channels = [];
+    for (const name of raw.split(",").map((part) => part.trim())) {
+        if (!isChannel(name)) {
+            throw new HttpError(400, "VALIDATION", `Unknown channel "${name}".`, `Valid channels: ${CHANNELS.join(", ")}.`);
+        }
+        channels.push(name);
+    }
+    return channels;
+}

package/dist/server/routes/api.d.ts

@@ -0,0 +1,17 @@
+import type { RouteContext } from "./router.js";
+/** GET /api/workflows — names + manifest-derived fields, enough to render a picker. */
+export declare function handleListWorkflows(ctx: RouteContext): void;
+/** GET /api/runs?workflow=&status=&limit=&offset= — newest first, full RunRow shape. */
+export declare function handleListRuns(ctx: RouteContext): void;
+/** POST /api/workflows/:name/runs — start a manual run; 201 with the queued row. */
+export declare function handleStartRun(ctx: RouteContext, workflowName: string): Promise<void>;
+/** GET /api/runs/:id */
+export declare function handleGetRun(ctx: RouteContext, runId: string): void;
+/**
+ * GET /api/runs/:id/events?after=&channels=|verbose= — persisted events after a cursor,
+ * filtered server-side by channel. Cursors are run-global and untouched by filtering, so a
+ * client can resume here (or on /stream) with any channel set (MASTER_SPEC §2.5).
+ */
+export declare function handleListEvents(ctx: RouteContext, runId: string): void;
+/** POST /api/runs/:id/cancel — 202: accepted now, completes after the cooperative grace. */
+export declare function handleCancelRun(ctx: RouteContext, runId: string): void;

package/dist/server/routes/api.js

@@ -0,0 +1,107 @@
+// The JSON API (SPEC §2.4): list workflows/runs, trigger a manual run, read a run + its
+// events, cancel. Handlers translate HTTP into engine/store calls and nothing else — all SQL
+// lives in the store, all run semantics in the engine.
+import { z } from "zod";
+import { matchesChannels } from "@boardwalk-labs/workflow";
+import { HttpError, MAX_BODY_BYTES, jsonValueSchema, parseChannelSelection, parseJsonBody, parseNonNegativeInt, readBody, sendJson, } from "../http.js";
+/**
+ * Default page size for run listings. Unbounded-by-default would make the run-log UI's
+ * "recent runs" fetch grow forever; callers page with limit/offset for more.
+ */
+const DEFAULT_RUNS_LIMIT = 100;
+const startRunBodySchema = z.strictObject({ input: jsonValueSchema.optional() });
+// Why a Record and not an array: the Record<RunStatus, true> shape makes the value list
+// provably complete — a status added to the union without a flag here is a compile error, so
+// the filter can never reject a status the store legitimately writes.
+const RUN_STATUS_FLAGS = {
+    queued: true,
+    pending: true,
+    running: true,
+    completed: true,
+    failed: true,
+    cancelled: true,
+    cancelling: true,
+};
+function isRunStatus(value) {
+    return Object.hasOwn(RUN_STATUS_FLAGS, value);
+}
+/** GET /api/workflows — names + manifest-derived fields, enough to render a picker. */
+export function handleListWorkflows(ctx) {
+    const workflows = ctx.engine.store.listWorkflows().map((row) => ({
+        name: row.name,
+        description: row.manifest.description ?? null,
+        triggers: row.manifest.triggers,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    }));
+    sendJson(ctx.res, 200, { workflows });
+}
+/** GET /api/runs?workflow=&status=&limit=&offset= — newest first, full RunRow shape. */
+export function handleListRuns(ctx) {
+    const filter = {
+        limit: parseNonNegativeInt(ctx.url, "limit", DEFAULT_RUNS_LIMIT),
+        offset: parseNonNegativeInt(ctx.url, "offset", 0),
+    };
+    const workflowName = ctx.url.searchParams.get("workflow");
+    if (workflowName !== null) {
+        const workflow = ctx.engine.store.getWorkflow(workflowName);
+        if (workflow === null) {
+            throw new HttpError(404, "NOT_FOUND", `Workflow "${workflowName}" is not deployed on this engine.`);
+        }
+        filter.workflowId = workflow.id;
+    }
+    const status = ctx.url.searchParams.get("status");
+    if (status !== null) {
+        if (!isRunStatus(status)) {
+            throw new HttpError(400, "VALIDATION", `Unknown run status "${status}".`, `Valid statuses: ${Object.keys(RUN_STATUS_FLAGS).join(", ")}.`);
+        }
+        filter.statuses = [status];
+    }
+    sendJson(ctx.res, 200, { runs: ctx.engine.store.listRuns(filter) });
+}
+/** POST /api/workflows/:name/runs — start a manual run; 201 with the queued row. */
+export async function handleStartRun(ctx, workflowName) {
+    const raw = await readBody(ctx.req, MAX_BODY_BYTES);
+    // An empty body means "no input" — the curl-without-data ergonomics of a run-now button.
+    const body = raw.length === 0 ? {} : parseJsonBody(raw, startRunBodySchema, "run-start body");
+    const run = ctx.engine.startRun(workflowName, {
+        triggerKind: "manual",
+        ...(body.input !== undefined ? { input: body.input } : {}),
+    });
+    sendJson(ctx.res, 201, { run });
+}
+/** GET /api/runs/:id */
+export function handleGetRun(ctx, runId) {
+    const run = ctx.engine.store.getRun(runId);
+    if (run === null)
+        throw new HttpError(404, "NOT_FOUND", `Unknown run: ${runId}`);
+    sendJson(ctx.res, 200, { run });
+}
+/**
+ * GET /api/runs/:id/events?after=&channels=|verbose= — persisted events after a cursor,
+ * filtered server-side by channel. Cursors are run-global and untouched by filtering, so a
+ * client can resume here (or on /stream) with any channel set (MASTER_SPEC §2.5).
+ */
+export function handleListEvents(ctx, runId) {
+    if (ctx.engine.store.getRun(runId) === null) {
+        throw new HttpError(404, "NOT_FOUND", `Unknown run: ${runId}`);
+    }
+    const channels = parseChannelSelection(ctx.url);
+    const afterCursor = parseNonNegativeInt(ctx.url, "after", 0);
+    const events = ctx.engine.store
+        .listEvents(runId, { afterCursor })
+        .filter((row) => matchesChannels(row.event, channels));
+    sendJson(ctx.res, 200, { events });
+}
+/** POST /api/runs/:id/cancel — 202: accepted now, completes after the cooperative grace. */
+export function handleCancelRun(ctx, runId) {
+    if (ctx.engine.store.getRun(runId) === null) {
+        throw new HttpError(404, "NOT_FOUND", `Unknown run: ${runId}`);
+    }
+    // Why not awaited: cancellation holds the SIGTERM→SIGKILL grace window open (seconds); 202
+    // promises "accepted", and the caller observes completion via the run's status.
+    void ctx.engine.cancelRun(runId).catch((err) => {
+        ctx.log(`cancel of run ${runId} failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
+    sendJson(ctx.res, 202, {});
+}

package/dist/server/routes/hooks.d.ts

@@ -0,0 +1,2 @@
+import type { RouteContext } from "./router.js";
+export declare function handleWebhook(ctx: RouteContext, workflowName: string, triggerIndexRaw: string): Promise<void>;