@voyantjs/workflows 0.6.7 → 0.6.8

package/dist/runtime/errors.d.ts

@@ -0,0 +1,21 @@
+declare const WAITPOINT_PENDING: unique symbol;
+declare const RUN_CANCELLED: unique symbol;
+declare const COMPENSATE_REQUESTED: unique symbol;
+export declare class WaitpointPendingSignal extends Error {
+    readonly [WAITPOINT_PENDING]: true;
+    readonly waitpointId: string;
+    constructor(waitpointId: string);
+}
+export declare class RunCancelledSignal extends Error {
+    readonly [RUN_CANCELLED]: true;
+    constructor(reason?: string);
+}
+export declare function isWaitpointPending(err: unknown): err is WaitpointPendingSignal;
+export declare function isRunCancelled(err: unknown): err is RunCancelledSignal;
+export declare class CompensateRequestedSignal extends Error {
+    readonly [COMPENSATE_REQUESTED]: true;
+    constructor();
+}
+export declare function isCompensateRequested(err: unknown): err is CompensateRequestedSignal;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/runtime/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAKA,QAAA,MAAM,iBAAiB,eAAkD,CAAA;AACzE,QAAA,MAAM,aAAa,eAA8C,CAAA;AACjE,QAAA,MAAM,oBAAoB,eAAqD,CAAA;AAE/E,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAG,IAAI,CAAS;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;gBAChB,WAAW,EAAE,MAAM;CAKhC;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAG,IAAI,CAAS;gBAC5B,MAAM,CAAC,EAAE,MAAM;CAI5B;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,sBAAsB,CAM9E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,kBAAkB,CAMtE;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAG,IAAI,CAAS;;CAKhD;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,yBAAyB,CAMpF"}

package/dist/runtime/errors.js

@@ -0,0 +1,45 @@
+// Internal runtime signal errors. Distinct from user-facing `@voyantjs/workflows-errors`:
+// these are thrown inside the executor to unwind the workflow body on
+// waitpoint yield or run cancellation. They must not be caught by user
+// code (the executor re-throws if it observes one being swallowed).
+const WAITPOINT_PENDING = Symbol.for("voyant.workflows.waitpointPending");
+const RUN_CANCELLED = Symbol.for("voyant.workflows.runCancelled");
+const COMPENSATE_REQUESTED = Symbol.for("voyant.workflows.compensateRequested");
+export class WaitpointPendingSignal extends Error {
+    [WAITPOINT_PENDING] = true;
+    waitpointId;
+    constructor(waitpointId) {
+        super(`waitpoint pending: ${waitpointId}`);
+        this.name = "WaitpointPendingSignal";
+        this.waitpointId = waitpointId;
+    }
+}
+export class RunCancelledSignal extends Error {
+    [RUN_CANCELLED] = true;
+    constructor(reason) {
+        super(reason ?? "run cancelled");
+        this.name = "RunCancelledSignal";
+    }
+}
+export function isWaitpointPending(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err[WAITPOINT_PENDING] === true);
+}
+export function isRunCancelled(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err[RUN_CANCELLED] === true);
+}
+export class CompensateRequestedSignal extends Error {
+    [COMPENSATE_REQUESTED] = true;
+    constructor() {
+        super("compensate requested");
+        this.name = "CompensateRequestedSignal";
+    }
+}
+export function isCompensateRequested(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err[COMPENSATE_REQUESTED] === true);
+}

package/dist/runtime/executor.d.ts

@@ -0,0 +1,159 @@
+import type { SerializedError } from "../protocol/index.js";
+import { type RateLimiter } from "../rate-limit/index.js";
+import type { RunStatus, RunTrigger, WaitpointKind } from "../types.js";
+import type { WorkflowDefinition } from "../workflow.js";
+import { type RuntimeEnvironment } from "./ctx.js";
+import { RunCancelledSignal, WaitpointPendingSignal } from "./errors.js";
+import type { JournalSlice, StepJournalEntry } from "./journal.js";
+export type StepRunner = (
+/**
+ * Executes a step body and returns the journal entry to record.
+ *
+ * In-process runners (the default edge runner, local-dev passthrough)
+ * call `fn(stepCtx)` directly. Dispatching runners (e.g. the CF
+ * Container runner) ignore `fn` — they can't serialize a closure —
+ * and use the run/workflow identity + step options to address the
+ * remote container and POST the required context.
+ */
+args: {
+    stepId: string;
+    attempt: number;
+    input: unknown;
+    fn: (stepCtx: import("../workflow.js").StepContext) => Promise<unknown>;
+    stepCtx: import("../workflow.js").StepContext;
+    /** Identity of the run — used by dispatching runners. */
+    runId: string;
+    workflowId: string;
+    workflowVersion: string;
+    /** Project / organization id from the runtime environment — used by
+     *  dispatching runners to resolve per-tenant bundle storage keys. */
+    projectId: string;
+    organizationId: string;
+    /** Merged step options (runtime, machine, timeout, …). */
+    options: import("../workflow.js").StepOptions<unknown>;
+    /**
+     * Current journal slice at dispatch time — steps already completed,
+     * waitpoints already resolved, etc. Dispatching runners pass this
+     * to the remote executor so body replay there short-circuits on
+     * cached steps, and the container can stop cleanly after the
+     * target step runs.
+     */
+    journal: JournalSlice;
+}) => Promise<StepJournalEntry>;
+export interface WaitpointRegistration {
+    clientWaitpointId: string;
+    kind: WaitpointKind;
+    meta: Record<string, unknown>;
+    timeoutMs?: number;
+}
+export interface MetadataMutation {
+    op: "set" | "increment" | "append" | "remove";
+    key: string;
+    value?: unknown;
+    target?: "self" | "parent" | "root";
+}
+export interface CompensationReport {
+    stepId: string;
+    status: "ok" | "err";
+    error?: SerializedError;
+    durationMs: number;
+}
+export interface StreamChunk {
+    streamId: string;
+    seq: number;
+    encoding: "text" | "json" | "base64";
+    chunk: unknown;
+    final: boolean;
+    at: number;
+}
+export interface ExecuteWorkflowStepRequest {
+    runId: string;
+    workflowId: string;
+    workflowVersion: string;
+    input: unknown;
+    journal: JournalSlice;
+    invocationCount: number;
+    environment: RuntimeEnvironment;
+    triggeredBy: RunTrigger;
+    runStartedAt: number;
+    tags: string[];
+    abortSignal?: AbortSignal;
+    /**
+     * Default step executor (the "edge" runtime) — runs step bodies
+     * in-process. Used for any step whose `options.runtime` is unset or
+     * explicitly `"edge"`.
+     */
+    stepRunner: StepRunner;
+    /**
+     * Optional runner for steps declared with `options.runtime === "node"`.
+     * Typical impl dispatches to a Cloudflare Container sized for the
+     * step (or, in local dev, an in-process passthrough).
+     *
+     * If a step requests `"node"` and this is unset, the step fails with
+     * `NODE_RUNTIME_UNAVAILABLE` — declaring a runtime and then silently
+     * falling back to edge would hide deployment bugs.
+     */
+    nodeStepRunner?: StepRunner;
+    /**
+     * Optional rate limiter. When a step declares `options.rateLimit`,
+     * the executor calls `rateLimiter.acquire(...)` before invoking the
+     * step runner. Without a limiter, a step that declares `rateLimit`
+     * fails with `RATE_LIMITER_MISSING` — declaring a limit and not
+     * enforcing it would be silently dangerous.
+     */
+    rateLimiter?: RateLimiter;
+    /** `() => number` used for compensation durations. Defaults to Date.now. */
+    now?: () => number;
+    /**
+     * Optional per-chunk callback fired synchronously from
+     * `ctx.stream.*` as each chunk is produced. Enables live streaming
+     * (dashboards, queues) in-process before the invocation completes.
+     * Chunks are still accumulated in the response's `streamChunks`
+     * array so the at-end delivery keeps working.
+     */
+    onStreamChunk?: (chunk: StreamChunk) => void;
+}
+export type ExecuteWorkflowStepResponse = {
+    status: "completed";
+    output: unknown;
+    metadataUpdates: MetadataMutation[];
+    journal: JournalSlice;
+    streamChunks: StreamChunk[];
+} | {
+    status: "failed";
+    error: SerializedError;
+    metadataUpdates: MetadataMutation[];
+    journal: JournalSlice;
+    streamChunks: StreamChunk[];
+} | {
+    status: "cancelled";
+    metadataUpdates: MetadataMutation[];
+    journal: JournalSlice;
+    compensations: CompensationReport[];
+    streamChunks: StreamChunk[];
+} | {
+    status: "waiting";
+    waitpoints: WaitpointRegistration[];
+    metadataUpdates: MetadataMutation[];
+    journal: JournalSlice;
+    streamChunks: StreamChunk[];
+} | {
+    status: "compensated";
+    /** Only set when compensation was triggered by an uncaught body error. */
+    error?: SerializedError;
+    compensations: CompensationReport[];
+    metadataUpdates: MetadataMutation[];
+    journal: JournalSlice;
+    streamChunks: StreamChunk[];
+} | {
+    status: "compensation_failed";
+    error?: SerializedError;
+    compensations: CompensationReport[];
+    metadataUpdates: MetadataMutation[];
+    journal: JournalSlice;
+    streamChunks: StreamChunk[];
+};
+export declare function executeWorkflowStep(def: WorkflowDefinition, req: ExecuteWorkflowStepRequest): Promise<ExecuteWorkflowStepResponse>;
+export type { RunStatus };
+export { RunCancelledSignal, WaitpointPendingSignal };
+//# sourceMappingURL=executor.d.ts.map

package/dist/runtime/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/runtime/executor.ts"],"names":[],"mappings":"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"}

package/dist/runtime/executor.js

@@ -0,0 +1,225 @@
+// The workflow-step executor. Takes a registered workflow + journal and
+// runs the body exactly once, yielding a response envelope.
+//
+// Corresponds to the tenant-side handler of POST /__voyant/workflow-step
+// described in docs/runtime-protocol.md §2.1.
+import { durationToMs } from "../rate-limit/index.js";
+import { buildCtx } from "./ctx.js";
+import { createClock, createRandom } from "./determinism.js";
+import { isCompensateRequested, isRunCancelled, isWaitpointPending, RunCancelledSignal, WaitpointPendingSignal, } from "./errors.js";
+export async function executeWorkflowStep(def, req) {
+    const abortSignal = req.abortSignal ?? new AbortController().signal;
+    const now = req.now ?? (() => Date.now());
+    const clock = createClock(req.runStartedAt);
+    const random = createRandom(req.runId);
+    const waitpoints = [];
+    const metadataUpdates = [];
+    const compensable = [];
+    const streamChunks = [];
+    const retryOverride = {
+        current: def.config.retry,
+    };
+    const callbacks = {
+        invocationCount: req.invocationCount,
+        abortSignal,
+        async runStep(args) {
+            if (args.options.rateLimit) {
+                await acquireRateLimit({
+                    spec: args.options.rateLimit,
+                    stepId: args.stepId,
+                    input: req.input,
+                    runId: req.runId,
+                    projectId: req.environment.project.id,
+                    limiter: req.rateLimiter,
+                    signal: abortSignal,
+                });
+            }
+            const runtime = args.options.runtime ?? "edge";
+            const runner = runtime === "node" ? req.nodeStepRunner : req.stepRunner;
+            if (!runner) {
+                const e = new Error(`step "${args.stepId}" declared runtime="node" but the handler has no nodeStepRunner wired; ` +
+                    `pass { nodeStepRunner } to createStepHandler() or remove options.runtime`);
+                e.code = "NODE_RUNTIME_UNAVAILABLE";
+                throw e;
+            }
+            const entry = await runner({
+                stepId: args.stepId,
+                attempt: args.attempt,
+                input: args.input,
+                fn: args.fn,
+                stepCtx: args.stepCtx,
+                runId: req.runId,
+                workflowId: req.workflowId,
+                workflowVersion: req.workflowVersion,
+                projectId: req.environment.project.id,
+                organizationId: req.environment.organization.id,
+                options: args.options,
+                journal: req.journal,
+            });
+            // Stamp the runtime on the journal entry so downstream consumers
+            // (journal persistence, dashboard events) can report where each
+            // step actually ran.
+            entry.runtime = runtime;
+            return entry;
+        },
+        registerWaitpoint(args) {
+            waitpoints.push(args);
+        },
+        pushMetadata(op) {
+            metadataUpdates.push(op);
+        },
+        recordCompensable(args) {
+            compensable.push(args);
+        },
+        compensableLength() {
+            return compensable.length;
+        },
+        spliceCompensable(fromIndex) {
+            return compensable.splice(fromIndex);
+        },
+        pushStreamChunk(args) {
+            const chunk = { ...args, at: now() };
+            streamChunks.push(chunk);
+            // Fire the live hook synchronously. Errors are swallowed — a
+            // misbehaving subscriber must not break the workflow body.
+            if (req.onStreamChunk) {
+                try {
+                    req.onStreamChunk(chunk);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        },
+    };
+    const ctx = buildCtx({
+        env: req.environment,
+        journal: req.journal,
+        callbacks,
+        clock,
+        random,
+        retryOverride,
+    });
+    try {
+        const output = await def.config.run(req.input, ctx);
+        // If the body registered a waitpoint but a user try/catch swallowed
+        // the internal yield signal, honour the waitpoint — the body can't
+        // both register a waitpoint and complete in the same invocation.
+        if (waitpoints.length > 0) {
+            return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks };
+        }
+        return { status: "completed", output, metadataUpdates, journal: req.journal, streamChunks };
+    }
+    catch (err) {
+        if (isWaitpointPending(err)) {
+            return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks };
+        }
+        // Same guard for the error path: a swallowed signal shouldn't let
+        // the body claim failure while waitpoints are pending.
+        if (waitpoints.length > 0 && !isRunCancelled(err) && !isCompensateRequested(err)) {
+            return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks };
+        }
+        if (isRunCancelled(err)) {
+            // Default: compensate on cancel. Terminal status stays `cancelled`
+            // to reflect why the run ended.
+            const compensations = await runCompensations(compensable, now);
+            return {
+                status: "cancelled",
+                metadataUpdates,
+                journal: req.journal,
+                compensations,
+                streamChunks,
+            };
+        }
+        if (isCompensateRequested(err)) {
+            const compensations = await runCompensations(compensable, now);
+            const anyErr = compensations.some((c) => c.status === "err");
+            return {
+                status: anyErr ? "compensation_failed" : "compensated",
+                compensations,
+                metadataUpdates,
+                journal: req.journal,
+                streamChunks,
+            };
+        }
+        // Uncaught user error. Run compensations LIFO; adjust terminal status
+        // based on whether compensations were registered and all succeeded.
+        const compensations = await runCompensations(compensable, now);
+        const serialized = serializeError(err);
+        if (compensations.length === 0) {
+            return {
+                status: "failed",
+                error: serialized,
+                metadataUpdates,
+                journal: req.journal,
+                streamChunks,
+            };
+        }
+        const anyErr = compensations.some((c) => c.status === "err");
+        return {
+            status: anyErr ? "compensation_failed" : "compensated",
+            error: serialized,
+            compensations,
+            metadataUpdates,
+            journal: req.journal,
+            streamChunks,
+        };
+    }
+}
+async function runCompensations(compensable, now) {
+    const reports = [];
+    // Reverse order: last-completed compensates first.
+    for (let i = compensable.length - 1; i >= 0; i--) {
+        const c = compensable[i];
+        const startedAt = now();
+        try {
+            await c.compensate(c.output);
+            reports.push({ stepId: c.stepId, status: "ok", durationMs: now() - startedAt });
+        }
+        catch (err) {
+            reports.push({
+                stepId: c.stepId,
+                status: "err",
+                error: serializeError(err),
+                durationMs: now() - startedAt,
+            });
+            // Continue with remaining compensations; don't abort on one failure.
+        }
+    }
+    return reports;
+}
+function serializeError(err) {
+    if (err instanceof Error) {
+        const code = err.code;
+        const cause = err.cause;
+        return {
+            category: "USER_ERROR",
+            code: typeof code === "string" ? code : "UNKNOWN",
+            message: err.message,
+            name: err.name,
+            stack: err.stack,
+            cause: cause !== undefined ? serializeError(cause) : undefined,
+        };
+    }
+    return { category: "USER_ERROR", code: "UNKNOWN", message: String(err) };
+}
+async function acquireRateLimit(args) {
+    const ctx = { run: { id: args.runId }, project: { id: args.projectId } };
+    const key = typeof args.spec.key === "function" ? args.spec.key(args.input, ctx) : args.spec.key;
+    const limit = typeof args.spec.limit === "function" ? args.spec.limit(args.input) : args.spec.limit;
+    const units = args.spec.units === undefined
+        ? 1
+        : typeof args.spec.units === "function"
+            ? args.spec.units(args.input)
+            : args.spec.units;
+    const windowMs = durationToMs(args.spec.window);
+    const onLimit = args.spec.onLimit ?? "queue";
+    if (!args.limiter) {
+        const e = new Error(`step "${args.stepId}" declared options.rateLimit but the handler has no rateLimiter wired; ` +
+            `pass { rateLimiter } to createStepHandler()`);
+        e.code = "RATE_LIMITER_MISSING";
+        throw e;
+    }
+    await args.limiter.acquire({ key, limit, units, windowMs, onLimit, signal: args.signal });
+}
+export { RunCancelledSignal, WaitpointPendingSignal };

package/dist/runtime/journal.d.ts

@@ -0,0 +1,55 @@
+import type { SerializedError } from "../protocol/index.js";
+import type { WaitpointKind } from "../types.js";
+export interface StepJournalEntry {
+    attempt: number;
+    status: "ok" | "err";
+    output?: unknown;
+    error?: SerializedError;
+    startedAt: number;
+    finishedAt: number;
+    /**
+     * Which runtime actually executed the step. Set by the executor when
+     * routing between `stepRunner` (edge) and `nodeStepRunner`.
+     * Informational only — doesn't affect replay.
+     */
+    runtime?: "edge" | "node";
+}
+export interface WaitpointResolutionEntry {
+    kind: WaitpointKind;
+    resolvedAt: number;
+    matchedEventId?: string;
+    payload?: unknown;
+    source: "live" | "inbox" | "replay";
+    /** Populated for RUN waitpoints when the child run ended in a failure state. */
+    error?: SerializedError;
+}
+export interface CompensationJournalEntry {
+    status: "ok" | "err";
+    finishedAt: number;
+    error?: SerializedError;
+}
+export interface JournalSlice {
+    stepResults: Record<string, StepJournalEntry>;
+    waitpointsResolved: Record<string, WaitpointResolutionEntry>;
+    compensationsRun: Record<string, CompensationJournalEntry>;
+    metadataState: Record<string, unknown>;
+    /**
+     * Stream ids whose generator has already been consumed in a prior
+     * invocation. The orchestrator already has the chunks on the run
+     * record; replaying the body must skip re-iterating the source
+     * (generators often have side effects — LLM calls, file reads,
+     * billable API usage).
+     */
+    streamsCompleted: Record<string, {
+        chunkCount: number;
+    }>;
+}
+export declare function emptyJournal(): JournalSlice;
+/**
+ * Clone the journal into a slice that the body sees. Each step /
+ * waitpoint the body replays is *consumed* from the slice so we can
+ * detect leftover journal entries that the code no longer produces
+ * (which is a versioning hazard — see §6.7 of design.md).
+ */
+export declare function forkJournal(j: JournalSlice): JournalSlice;
+//# sourceMappingURL=journal.d.ts.map

package/dist/runtime/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/runtime/journal.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,IAAI,GAAG,KAAK,CAAA;IACpB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,aAAa,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;IACnC,gFAAgF;IAChF,KAAK,CAAC,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,IAAI,GAAG,KAAK,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IAC7C,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAA;IAC5D,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAA;IAC1D,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACzD;AAED,wBAAgB,YAAY,IAAI,YAAY,CAQ3C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,GAAG,YAAY,CAQzD"}

package/dist/runtime/journal.js

@@ -0,0 +1,28 @@
+// Tenant-side view of the journal sent by the orchestrator on every
+// `/__voyant/workflow-step` invocation.
+//
+// Wire shape defined in docs/runtime-protocol.md §2.1 (JournalSlice).
+export function emptyJournal() {
+    return {
+        stepResults: {},
+        waitpointsResolved: {},
+        compensationsRun: {},
+        metadataState: {},
+        streamsCompleted: {},
+    };
+}
+/**
+ * Clone the journal into a slice that the body sees. Each step /
+ * waitpoint the body replays is *consumed* from the slice so we can
+ * detect leftover journal entries that the code no longer produces
+ * (which is a versioning hazard — see §6.7 of design.md).
+ */
+export function forkJournal(j) {
+    return {
+        stepResults: { ...j.stepResults },
+        waitpointsResolved: { ...j.waitpointsResolved },
+        compensationsRun: { ...j.compensationsRun },
+        metadataState: { ...j.metadataState },
+        streamsCompleted: { ...j.streamsCompleted },
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,117 @@
+import type { SerializedError } from "../protocol/index.js";
+import { type CompensationReport, type StreamChunk, type WaitpointRegistration } from "../runtime/executor.js";
+import type { JournalSlice } from "../runtime/journal.js";
+import type { RunStatus } from "../types.js";
+import type { EnvironmentContext, MetadataValue, StepContext, WorkflowHandle } from "../workflow.js";
+export interface TestOptions<_TIn> {
+    /** Map of stepId → function run in place of the real step body. */
+    steps?: Record<string, (stepCtx: StepContext) => unknown | Promise<unknown>>;
+    /**
+     * Map of eventType → payload (or payload array). First
+     * match-per-eventType wins.
+     */
+    waitForEvent?: Record<string, unknown | unknown[]>;
+    /** Map of signalName → payload. */
+    waitForSignal?: Record<string, unknown>;
+    /** Map of tokenId → payload. */
+    waitForToken?: Record<string, unknown>;
+    /** Workflow invoke stubs keyed by child workflow id. */
+    invoke?: Record<string, unknown>;
+    /** Fake env bindings, passed through to `ctx.environment` for tests. */
+    env?: Record<string, unknown>;
+    environment?: Partial<EnvironmentContext>;
+    /** Fixed wall-clock basis for the run. Defaults to Date.now(). */
+    now?: () => number;
+    random?: () => number;
+    /** Max resumption cycles. Defaults to 16 — guards runaway loops. */
+    maxInvocations?: number;
+    /**
+     * When true, the harness stops and returns a "waiting" TestResult as
+     * soon as any registered waitpoint has no fixture resolution (instead
+     * of throwing). Callers can then persist the run and resume it later
+     * via `resumeWorkflowForTest` once the waitpoint is resolved from a
+     * live source (e.g. a dashboard HTTP injection).
+     *
+     * DATETIME waitpoints (sleeps) are always auto-resolved regardless of
+     * this flag, since a local dev loop is not the right place to
+     * synthesize wall-clock delays.
+     */
+    pauseOnWait?: boolean;
+}
+export interface TestResult<TOut> {
+    status: Extract<RunStatus, "completed" | "failed" | "cancelled" | "compensated" | "compensation_failed" | "waiting">;
+    output?: TOut;
+    error?: {
+        category: SerializedError["category"];
+        code: string;
+        message: string;
+    };
+    steps: {
+        id: string;
+        status: "ok" | "err" | "skipped";
+        duration: number;
+        output?: unknown;
+    }[];
+    events: {
+        type: string;
+        at: number;
+        data: unknown;
+    }[];
+    metadata: Record<string, MetadataValue>;
+    compensations: CompensationReport[];
+    /** Chunks emitted via `ctx.stream()` / `ctx.stream.{text,json,bytes}`, grouped by streamId in emission order. */
+    streams: Record<string, StreamChunk[]>;
+    invocations: number;
+    /**
+     * Populated when `status === "waiting"`. Holds the persisted executor
+     * state needed to resume the run via `resumeWorkflowForTest`.
+     */
+    pause?: {
+        journal: JournalSlice;
+        pendingWaitpoints: WaitpointRegistration[];
+        startedAt: number;
+        invocationCount: number;
+        metadataAppliedCount: number;
+        fixtureCursors: {
+            event: Record<string, number>;
+            signal: Record<string, number>;
+        };
+    };
+}
+export declare function runWorkflowForTest<TIn, TOut>(workflow: WorkflowHandle<TIn, TOut>, input: TIn, opts?: TestOptions<TIn>): Promise<TestResult<TOut>>;
+/**
+ * A single injected waitpoint resolution — the tenant-side analogue of
+ * the orchestrator delivering an event, signal, or token payload to a
+ * parked run. The matcher (`kind` + `key`) identifies which pending
+ * waitpoint to resolve; `payload` is the value surfaced to the body.
+ */
+export type WaitpointInjection = {
+    kind: "EVENT";
+    eventType: string;
+    payload?: unknown;
+} | {
+    kind: "SIGNAL";
+    name: string;
+    payload?: unknown;
+} | {
+    kind: "MANUAL";
+    tokenId: string;
+    payload?: unknown;
+};
+export interface ResumeOptions<TIn> extends TestOptions<TIn> {
+    /** Persisted pause state returned from a previous `runWorkflowForTest` or `resumeWorkflowForTest`. */
+    pause: NonNullable<TestResult<unknown>["pause"]>;
+    /** The single waitpoint resolution to inject on resume. */
+    injection: WaitpointInjection;
+}
+/**
+ * Resume a parked run. Matches the injection against one of the
+ * `pause.pendingWaitpoints`, records it in the journal, and re-enters
+ * the executor loop until the next pause or terminal state.
+ */
+export declare function resumeWorkflowForTest<TIn, TOut>(workflow: WorkflowHandle<TIn, TOut>, input: TIn, opts: ResumeOptions<TIn>): Promise<TestResult<TOut>>;
+export interface FixtureCursors {
+    event: Map<string, number>;
+    signal: Map<string, number>;
+}
+//# sourceMappingURL=index.d.ts.map