@voyantjs/workflows 0.6.7 → 0.6.9

package/dist/runtime/ctx.js

@@ -0,0 +1,607 @@
+// Builds the `ctx` object passed to the workflow body.
+//
+// The executor owns the waitpoint-pending queue and the callbacks
+// into the orchestrator; ctx is a thin shell that delegates.
+import { advanceClockTo, createRandomUUID, now } from "./determinism.js";
+import { CompensateRequestedSignal, isCompensateRequested, isRunCancelled, isWaitpointPending, RunCancelledSignal, WaitpointPendingSignal, } from "./errors.js";
+export function buildCtx(args) {
+    const { env, journal, callbacks, clock, random, retryOverride } = args;
+    // Per-ctx client-id counter. Reset on each ctx (= each invocation),
+    // which means ids are stable relative to body execution order.
+    let clientIdSeq = 0;
+    const nextClientId = () => ++clientIdSeq;
+    function checkCancel() {
+        if (callbacks.abortSignal.aborted) {
+            throw new RunCancelledSignal();
+        }
+    }
+    // ---- step ----
+    const step = (async (id, optsOrFn, maybeFn) => {
+        checkCancel();
+        const opts = typeof optsOrFn === "function" ? {} : optsOrFn;
+        const fn = typeof optsOrFn === "function" ? optsOrFn : maybeFn;
+        // Journal hit? Return cached.
+        const cached = journal.stepResults[id];
+        if (cached) {
+            advanceClockTo(clock, cached.finishedAt);
+            if (cached.status === "ok") {
+                // Re-register compensable on replay so compensations are available
+                // if this invocation ends up rolling back.
+                if (opts.compensate) {
+                    callbacks.recordCompensable({
+                        stepId: id,
+                        output: cached.output,
+                        compensate: opts.compensate,
+                    });
+                }
+                return cached.output;
+            }
+            // Journaled error rethrows on replay so catch blocks behave consistently.
+            const e = new Error(cached.error?.message ?? "step failed");
+            e.code = cached.error?.code;
+            throw e;
+        }
+        // Execute a new step via the callback, with the retry loop.
+        const mergedOpts = {
+            ...opts,
+            retry: opts.retry ?? retryOverride.current,
+        };
+        const policy = normalizeRetry(mergedOpts.retry);
+        let attempt = 0;
+        let lastEntry;
+        // Per-step timeout: compose the run-level abort signal with a
+        // per-call AbortSignal.timeout so cooperative step bodies (fetch,
+        // setTimeout wrappers, custom AbortSignal observers) stop early
+        // on timeout. Hard enforcement for uncooperative bodies is done
+        // below by racing the wrapped fn against a timeout rejection.
+        const timeoutMs = mergedOpts.timeout !== undefined ? toMs(mergedOpts.timeout) : undefined;
+        const fnWithTimeout = timeoutMs !== undefined
+            ? async (stepCtx) => {
+                let timer;
+                try {
+                    return await Promise.race([
+                        fn(stepCtx),
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => {
+                                const e = new Error(`step "${id}" timed out after ${timeoutMs}ms`);
+                                e.code = "TIMEOUT";
+                                reject(e);
+                            }, timeoutMs);
+                        }),
+                    ]);
+                }
+                finally {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                }
+            }
+            : fn;
+        while (attempt < policy.max) {
+            attempt += 1;
+            const stepCtx = {
+                signal: timeoutMs !== undefined
+                    ? AbortSignal.any([callbacks.abortSignal, AbortSignal.timeout(timeoutMs)])
+                    : callbacks.abortSignal,
+                attempt,
+                log: (level, msg, data) => {
+                    console[level === "error" ? "error" : level === "warn" ? "warn" : "log"](`[${id}]`, msg, data ?? "");
+                },
+            };
+            const entry = await callbacks.runStep({
+                stepId: id,
+                attempt,
+                input: undefined,
+                options: mergedOpts,
+                fn: fnWithTimeout,
+                stepCtx,
+            });
+            lastEntry = entry;
+            if (entry.status === "ok") {
+                journal.stepResults[id] = entry;
+                advanceClockTo(clock, entry.finishedAt);
+                if (opts.compensate) {
+                    callbacks.recordCompensable({
+                        stepId: id,
+                        output: entry.output,
+                        compensate: opts.compensate,
+                    });
+                }
+                return entry.output;
+            }
+            // Failed attempt. Check if we should stop retrying.
+            if (entry.error?.code === "FATAL")
+                break;
+            if (attempt >= policy.max)
+                break;
+            // In production the step handler returns { retryAfter } to the DO
+            // which sets an alarm; here the spike/test harness continues
+            // immediately. retryAfter from RetryableError wins over the policy
+            // backoff when set.
+            const retryAfter = readRetryAfter(entry.error);
+            await maybeDelay(retryAfter ?? backoffDelay(policy, attempt));
+        }
+        // Retries exhausted (or never retried).
+        const finalEntry = lastEntry;
+        journal.stepResults[id] = finalEntry;
+        advanceClockTo(clock, finalEntry.finishedAt);
+        const e = new Error(finalEntry.error?.message ?? "step failed");
+        e.code = finalEntry.error?.code;
+        throw e;
+    });
+    // ---- waits ----
+    function yieldWaitpoint(clientWaitpointId, kind, meta, timeoutMs) {
+        callbacks.registerWaitpoint({ clientWaitpointId, kind, meta, timeoutMs });
+        throw new WaitpointPendingSignal(clientWaitpointId);
+    }
+    function lookupWaitpoint(id) {
+        return journal.waitpointsResolved[id];
+    }
+    const sleep = async (duration) => {
+        checkCancel();
+        const id = `sleep:${nextClientId()}`;
+        const resolved = lookupWaitpoint(id);
+        if (resolved) {
+            advanceClockTo(clock, resolved.resolvedAt);
+            return;
+        }
+        const ms = toMs(duration);
+        yieldWaitpoint(id, "DATETIME", { durationMs: ms }, ms);
+    };
+    function makeWaitable(kind, clientWaitpointId, iterIdPrefix, meta, timeoutMs, onTimeout = "null") {
+        // --- thenable: single first-match-wins resolution ---
+        const resolve = () => {
+            const resolved = lookupWaitpoint(clientWaitpointId);
+            if (!resolved) {
+                yieldWaitpoint(clientWaitpointId, kind, meta, timeoutMs);
+            }
+            advanceClockTo(clock, resolved.resolvedAt);
+            if (resolved.payload === undefined && onTimeout === "throw") {
+                throw new Error(`waitpoint ${clientWaitpointId} timed out`);
+            }
+            return (resolved.payload ?? null);
+        };
+        // --- iterable: fresh waitpoint per .next() call ---
+        function makeIterator() {
+            let closed = false;
+            return {
+                async next() {
+                    if (closed)
+                        return { value: undefined, done: true };
+                    checkCancel();
+                    const iterId = `${iterIdPrefix}:iter:${nextClientId()}`;
+                    const resolvedIter = lookupWaitpoint(iterId);
+                    if (!resolvedIter) {
+                        yieldWaitpoint(iterId, kind, { ...meta, iter: true }, timeoutMs);
+                    }
+                    advanceClockTo(clock, resolvedIter.resolvedAt);
+                    // End-of-stream marker. Harness / orchestrator writes this to
+                    // tell the iterator the source has no more events.
+                    const payload = resolvedIter.payload;
+                    if (isStreamEnd(payload)) {
+                        closed = true;
+                        return { value: undefined, done: true };
+                    }
+                    if (payload === undefined && onTimeout === "throw") {
+                        throw new Error(`waitpoint ${iterId} timed out`);
+                    }
+                    return { value: payload, done: false };
+                },
+                async return() {
+                    closed = true;
+                    return { value: undefined, done: true };
+                },
+                [Symbol.asyncIterator]() {
+                    return this;
+                },
+            };
+        }
+        const thenable = {
+            // biome-ignore lint/suspicious/noThenProperty: Waitable intentionally implements PromiseLike for `await`.
+            then(onFulfilled, onRejected) {
+                try {
+                    const r = resolve();
+                    return Promise.resolve(r).then(onFulfilled, onRejected);
+                }
+                catch (e) {
+                    return Promise.reject(e).then(onFulfilled, onRejected);
+                }
+            },
+            [Symbol.asyncIterator]() {
+                return makeIterator();
+            },
+            close() {
+                // no-op; `return()` on the iterator handles early break.
+            },
+        };
+        return thenable;
+    }
+    function isStreamEnd(payload) {
+        return (typeof payload === "object" &&
+            payload !== null &&
+            payload.__voyantStreamEnd === true);
+    }
+    const waitForEvent = ((eventType, opts) => {
+        checkCancel();
+        const thenableId = `event:${eventType}:${nextClientId()}`;
+        const iterPrefix = `event:${eventType}`;
+        return makeWaitable("EVENT", thenableId, iterPrefix, { eventType }, opts?.timeout ? toMs(opts.timeout) : undefined, opts?.onTimeout);
+    });
+    const waitForSignal = ((name, opts) => {
+        checkCancel();
+        const thenableId = `signal:${name}:${nextClientId()}`;
+        const iterPrefix = `signal:${name}`;
+        return makeWaitable("SIGNAL", thenableId, iterPrefix, { signalName: name }, opts?.timeout ? toMs(opts.timeout) : undefined, opts?.onTimeout);
+    });
+    const waitForToken = (async (opts) => {
+        checkCancel();
+        // Allocate a stable id per call. User-supplied `tokenId` is kept
+        // verbatim so external systems can reference the same value.
+        const tokenId = opts?.tokenId ?? `tok_${nextClientId()}`;
+        const waitpointId = `token:${tokenId}`;
+        const timeoutMs = opts?.timeout ? toMs(opts.timeout) : undefined;
+        const onTimeout = opts?.onTimeout ?? "null";
+        return {
+            tokenId,
+            url: `/__voyant/tokens/${tokenId}`,
+            wait: async () => {
+                checkCancel();
+                const resolved = lookupWaitpoint(waitpointId);
+                if (resolved) {
+                    advanceClockTo(clock, resolved.resolvedAt);
+                    if (resolved.payload === undefined && onTimeout === "throw") {
+                        throw new Error(`token ${tokenId} timed out`);
+                    }
+                    return resolved.payload ?? null;
+                }
+                yieldWaitpoint(waitpointId, "MANUAL", { tokenId }, timeoutMs);
+            },
+        };
+    });
+    // ---- invoke / parallel ----
+    const invoke = (async (wf, input, opts) => {
+        checkCancel();
+        const id = `invoke:${wf.id}:${nextClientId()}`;
+        const resolved = journal.waitpointsResolved[id];
+        if (resolved) {
+            advanceClockTo(clock, resolved.resolvedAt);
+            if (resolved.error) {
+                const e = new Error(resolved.error.message);
+                e.code = resolved.error.code;
+                throw e;
+            }
+            return resolved.payload;
+        }
+        yieldWaitpoint(id, "RUN", {
+            childWorkflowId: wf.id,
+            childInput: input,
+            detach: opts?.detach ?? false,
+            tags: opts?.tags ?? [],
+            lockToVersion: opts?.lockToVersion,
+            idempotencyKey: opts?.idempotencyKey,
+        });
+    });
+    const parallel = async (items, fn, opts) => {
+        checkCancel();
+        const total = items.length;
+        if (total === 0)
+            return [];
+        const concurrency = Math.max(1, opts?.concurrency ?? total);
+        const settle = opts?.settle ?? false;
+        const results = new Array(total);
+        const errors = [];
+        let cursor = 0;
+        let aborted = false;
+        async function worker() {
+            while (!aborted) {
+                const i = cursor++;
+                if (i >= total)
+                    return;
+                try {
+                    results[i] = await fn(items[i], i);
+                }
+                catch (err) {
+                    if (settle) {
+                        errors.push({ index: i, error: err });
+                    }
+                    else {
+                        aborted = true;
+                        throw err;
+                    }
+                }
+            }
+        }
+        const workerCount = Math.min(concurrency, total);
+        const workers = Array.from({ length: workerCount }, () => worker());
+        if (settle) {
+            await Promise.all(workers);
+            if (errors.length > 0) {
+                // Attach details so callers can inspect which items failed.
+                const agg = new AggregateError(errors.map((e) => (e.error instanceof Error ? e.error : new Error(String(e.error)))), `ctx.parallel: ${errors.length}/${total} iteration${errors.length === 1 ? "" : "s"} failed`);
+                agg.failedIndices = errors.map((e) => e.index);
+                throw agg;
+            }
+            return results;
+        }
+        await Promise.all(workers);
+        return results;
+    };
+    // ---- streams ----
+    const activeStreamIds = new Set();
+    async function consumeStream(streamId, source, encoding) {
+        checkCancel();
+        if (activeStreamIds.has(streamId)) {
+            throw new Error(`ctx.stream: duplicate streamId "${streamId}" within the same run`);
+        }
+        activeStreamIds.add(streamId);
+        // Replay skip: the prior invocation already drained this source
+        // and the orchestrator has the chunks. Re-iterating would double
+        // any side effects (LLM calls, billable APIs, file reads).
+        if (journal.streamsCompleted[streamId]) {
+            return;
+        }
+        let seq = 0;
+        const iter = source[Symbol.asyncIterator]();
+        try {
+            while (true) {
+                checkCancel();
+                const { value, done } = await iter.next();
+                if (done) {
+                    callbacks.pushStreamChunk({ streamId, seq: seq + 1, encoding, chunk: null, final: true });
+                    journal.streamsCompleted[streamId] = { chunkCount: seq + 1 };
+                    return;
+                }
+                seq += 1;
+                const chunk = normalizeChunk(value, encoding);
+                callbacks.pushStreamChunk({ streamId, seq, encoding, chunk, final: false });
+            }
+        }
+        catch (err) {
+            // Emit a final frame so consumers know the stream closed, then
+            // propagate so the workflow body's error handling kicks in. No
+            // journal entry — a failed stream should re-iterate on replay
+            // (so the error surfaces deterministically).
+            callbacks.pushStreamChunk({ streamId, seq: seq + 1, encoding, chunk: null, final: true });
+            throw err;
+        }
+    }
+    const streamImpl = async (streamId, sourceOrFn) => {
+        const source = typeof sourceOrFn === "function"
+            ? sourceOrFn()
+            : sourceOrFn;
+        await consumeStream(streamId, source, inferEncoding(source));
+    };
+    streamImpl.text = async (id, source) => {
+        await consumeStream(id, source, "text");
+    };
+    streamImpl.json = async (id, source) => {
+        await consumeStream(id, source, "json");
+    };
+    streamImpl.bytes = async (id, source) => {
+        await consumeStream(id, source, "base64");
+    };
+    const stream = streamImpl;
+    // ---- groups ----
+    // `ctx.group(name, fn)` creates a compensation scope. Implementation
+    // strategy: the outer compensable list is the single source of truth;
+    // each group tracks a checkpoint index. If the scope's body throws or
+    // explicitly calls `scope.compensate()`, we splice off compensables
+    // added since the checkpoint and run them LIFO, leaving outer
+    // compensables untouched.
+    //
+    // If the scope body completes normally, compensables stay in the
+    // outer list — they'll still be rolled back if the enclosing workflow
+    // later throws.
+    const runScopedCompensations = async (fromIndex) => {
+        const scopeEntries = callbacks.spliceCompensable(fromIndex);
+        for (let i = scopeEntries.length - 1; i >= 0; i--) {
+            const c = scopeEntries[i];
+            try {
+                await c.compensate(c.output);
+            }
+            catch {
+                // One bad compensation in a scope does not abort the others.
+                // Errors here don't surface to the executor — the outer rollback
+                // machinery only sees the user error that triggered the scope
+                // unwind.
+            }
+        }
+    };
+    const group = async (_name, fn) => {
+        checkCancel();
+        const checkpointStart = callbacks.compensableLength();
+        try {
+            return await fn({
+                step,
+                compensate: async () => {
+                    await runScopedCompensations(checkpointStart);
+                    throw new CompensateRequestedSignal();
+                },
+            });
+        }
+        catch (err) {
+            // Only run scoped compensations for real user errors — internal
+            // signals (waitpoint yield, cancellation, compensate-requested)
+            // are re-thrown unchanged so the executor can route them.
+            if (!isWaitpointPending(err) && !isRunCancelled(err) && !isCompensateRequested(err)) {
+                await runScopedCompensations(checkpointStart);
+            }
+            throw err;
+        }
+    };
+    // ---- metadata ----
+    const metadata = {
+        set(key, value) {
+            callbacks.pushMetadata({ op: "set", key, value });
+        },
+        increment(key, by = 1) {
+            callbacks.pushMetadata({ op: "increment", key, value: by });
+        },
+        append(key, value) {
+            callbacks.pushMetadata({ op: "append", key, value });
+        },
+        remove(key) {
+            callbacks.pushMetadata({ op: "remove", key });
+        },
+        // Mutations are pushed immediately via `callbacks.pushMetadata`
+        // and collected on the response envelope; no explicit flush is
+        // needed.
+        flush: async () => { },
+    };
+    // ---- retry override ----
+    function setRetry(policy) {
+        retryOverride.current = policy;
+    }
+    return {
+        run: env.run,
+        workflow: env.workflow,
+        environment: env.environment,
+        project: env.project,
+        organization: env.organization,
+        invocationCount: callbacks.invocationCount,
+        signal: callbacks.abortSignal,
+        step,
+        sleep,
+        waitForEvent,
+        waitForSignal,
+        waitForToken,
+        invoke,
+        parallel,
+        stream,
+        group,
+        metadata,
+        now: () => now(clock),
+        random,
+        randomUUID: createRandomUUID(random),
+        setRetry,
+        compensate: async () => {
+            checkCancel();
+            throw new CompensateRequestedSignal();
+        },
+    };
+}
+// ---- helpers ----
+function inferEncoding(source) {
+    // Default to json for the generic ctx.stream(id, generator) call. The
+    // typed variants (text/json/bytes) override this.
+    void source;
+    return "json";
+}
+function normalizeChunk(value, encoding) {
+    if (encoding === "text") {
+        return typeof value === "string" ? value : String(value);
+    }
+    if (encoding === "base64") {
+        if (value instanceof Uint8Array) {
+            return toBase64(value);
+        }
+        throw new Error("ctx.stream.bytes: expected Uint8Array chunks");
+    }
+    return value; // json — pass through
+}
+function toBase64(bytes) {
+    // Node + modern runtimes provide Buffer or btoa. Use Buffer when
+    // available for efficiency; fall back to manual encode for isolates.
+    const g = globalThis;
+    if (g.Buffer)
+        return g.Buffer.from(bytes).toString("base64");
+    if (g.btoa) {
+        let s = "";
+        for (let i = 0; i < bytes.length; i++)
+            s += String.fromCharCode(bytes[i]);
+        return g.btoa(s);
+    }
+    // Manual fallback (rare).
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let out = "";
+    let i = 0;
+    while (i < bytes.length) {
+        const b1 = bytes[i++];
+        const b2 = i < bytes.length ? bytes[i++] : 0;
+        const b3 = i < bytes.length ? bytes[i++] : 0;
+        out += chars[b1 >> 2];
+        out += chars[((b1 & 3) << 4) | (b2 >> 4)];
+        out += i - 1 > bytes.length ? "=" : chars[((b2 & 15) << 2) | (b3 >> 6)];
+        out += i > bytes.length ? "=" : chars[b3 & 63];
+    }
+    return out;
+}
+function normalizeRetry(input) {
+    if (!input)
+        return { max: 1, backoff: "exponential", initial: 1000, maxDelay: 60_000 };
+    const max = input.max ?? 3;
+    const policy = input;
+    return {
+        max: Math.max(1, max),
+        backoff: policy.backoff ?? "exponential",
+        initial: policy.initial !== undefined ? toMs(policy.initial) : 1000,
+        maxDelay: policy.maxDelay !== undefined ? toMs(policy.maxDelay) : 60_000,
+    };
+}
+function backoffDelay(policy, attempt) {
+    // `attempt` is 1-indexed; delay applies *before* the next attempt.
+    if (policy.backoff === "fixed")
+        return Math.min(policy.initial, policy.maxDelay);
+    if (policy.backoff === "linear")
+        return Math.min(policy.initial * attempt, policy.maxDelay);
+    // exponential
+    return Math.min(policy.initial * 2 ** (attempt - 1), policy.maxDelay);
+}
+function readRetryAfter(err) {
+    if (!err)
+        return undefined;
+    if (err.code !== "RETRYABLE")
+        return undefined;
+    const raw = err.data?.retryAfter;
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === "number")
+        return raw;
+    if (raw instanceof Date)
+        return raw.getTime() - Date.now();
+    if (typeof raw === "string") {
+        try {
+            return toMs(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * In the real runtime, retry delay is expressed to the orchestrator as a
+ * `retryAfter` field on the step callback response, and the DO sets an
+ * alarm — no worker sits idle. In tests we skip the delay (pass it
+ * through `setTimeout(0)` at most) so the suite stays fast.
+ */
+async function maybeDelay(ms) {
+    if (ms <= 0)
+        return;
+    // Cap at 10ms in-process regardless of declared delay. Test harness
+    // doesn't model real time; production replaces this with a DO alarm.
+    await new Promise((resolve) => setTimeout(resolve, Math.min(ms, 10)));
+}
+function toMs(d) {
+    if (typeof d === "number")
+        return d;
+    const m = /^(\d+)(ms|s|m|h|d|w)$/.exec(d);
+    if (!m)
+        throw new Error(`invalid duration: ${String(d)}`);
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "ms":
+            return n;
+        case "s":
+            return n * 1000;
+        case "m":
+            return n * 60_000;
+        case "h":
+            return n * 3_600_000;
+        case "d":
+            return n * 86_400_000;
+        case "w":
+            return n * 604_800_000;
+        default:
+            throw new Error(`invalid duration unit: ${m[2]}`);
+    }
+}

package/dist/runtime/determinism.d.ts

@@ -0,0 +1,19 @@
+export interface ClockState {
+    /** Base wall-clock time recorded at run start. */
+    readonly baseWallClock: number;
+    /** Offset from baseWallClock at which ctx.now() should return — set by the executor when replaying journaled events. */
+    offset: number;
+}
+export declare function createClock(runStartedAt: number): ClockState;
+export declare function now(clock: ClockState): number;
+/** Advance the clock to the event currently being replayed. */
+export declare function advanceClockTo(clock: ClockState, eventAt: number): void;
+/**
+ * Mulberry32 PRNG — fast, fine for workflow-determinism use. Seeded
+ * from a 32-bit hash of the run id. Not cryptographic.
+ */
+export declare function seededRandom(seed: number): () => number;
+export declare function hashSeed(runId: string): number;
+export declare function createRandom(runId: string): () => number;
+export declare function createRandomUUID(rng: () => number): () => string;
+//# sourceMappingURL=determinism.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"determinism.d.ts","sourceRoot":"","sources":["../../src/runtime/determinism.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,wHAAwH;IACxH,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAE5D;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAE7C;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CASvD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ9C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,MAAM,CAExD;AAID,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,MAAM,GAAG,MAAM,MAAM,CAgBhE"}

package/dist/runtime/determinism.js

@@ -0,0 +1,61 @@
+// Deterministic clock and RNG used by the workflow body.
+//
+// `ctx.now()` must return the timestamp of the event currently being
+// consumed from the journal during replay (§4.5 of docs/design.md).
+// `ctx.random()` / `ctx.randomUUID()` are seeded from the run id so
+// replays produce the same values.
+export function createClock(runStartedAt) {
+    return { baseWallClock: runStartedAt, offset: 0 };
+}
+export function now(clock) {
+    return clock.baseWallClock + clock.offset;
+}
+/** Advance the clock to the event currently being replayed. */
+export function advanceClockTo(clock, eventAt) {
+    clock.offset = eventAt - clock.baseWallClock;
+}
+/**
+ * Mulberry32 PRNG — fast, fine for workflow-determinism use. Seeded
+ * from a 32-bit hash of the run id. Not cryptographic.
+ */
+export function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function hashSeed(runId) {
+    // FNV-1a 32-bit
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < runId.length; i++) {
+        hash ^= runId.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+export function createRandom(runId) {
+    return seededRandom(hashSeed(runId));
+}
+const HEX = "0123456789abcdef";
+export function createRandomUUID(rng) {
+    // v4-shaped deterministic UUID. Not cryptographically random; matches
+    // the style of crypto.randomUUID but is reproducible across replays.
+    return () => {
+        const bytes = new Uint8Array(16);
+        for (let i = 0; i < 16; i++)
+            bytes[i] = Math.floor(rng() * 256);
+        bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4 (high nibble of byte 6)
+        bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant RFC 4122 (high bits of byte 8)
+        let s = "";
+        for (let i = 0; i < 16; i++) {
+            const b = bytes[i];
+            s += HEX[b >>> 4] + HEX[b & 0x0f];
+        }
+        // s is 32 hex chars; slice into 8-4-4-4-12 groups.
+        return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`;
+    };
+}