@ezghcloud/workflows 0.0.0-stage → 1.0.0

package/dist/runtime/execution.js

@@ -0,0 +1,608 @@
+import { MAX_PLANNED_STEPS } from "../protocol/validate.js";
+import { DEFAULT_RETRY, MAX_OUTPUT_BYTES, encodeValue, jsonByteLength, mintCallbackToken, parseDuration, shardOf, stepId, supportsMessages, supportsParallel, validStepIdOverride, validWorkflowName } from "../protocol/index.js";
+import { MAX_MESSAGE_TIMEOUT_MS, MESSAGE_KEY, MIN_MESSAGE_TIMEOUT_MS, UUID } from "../protocol/validate.js";
+import { utf8Length } from "../protocol/bytes.js";
+import { CancelledError, DuplicateStepName, NonRetriableError, OutputTooLarge, RetryAfterError, StepTimeout, decodeError, encodeError } from "./errors.js";
+import { QueuesApiError, sendToQueueDigest, withDedupIds } from "../queues.js";
+import { checkTimeout, definitionOf, mergeRetry } from "./workflow.js";
+const DEFAULT_MAX_RESULT_BYTES = 8 << 20;
+// The longest sleep: a run times out after a year at most.
+export const MAX_SLEEP_MS = 31_536_000_000;
+// The longest retryAfterMs the engine takes (a day).
+export const MAX_RETRY_AFTER_MS = 86_400_000;
+// Callback timeouts: default 7 days, from 1 s to a year.
+export const DEFAULT_CALLBACK_TIMEOUT_MS = 604_800_000;
+export const MIN_CALLBACK_TIMEOUT_MS = 1_000;
+export const DEFAULT_API_BASE = "https://workflows-api.ezghcloud.com";
+const NON_RETRIABLE_CODES = new Set(["workflows.non_retriable", "workflows.output_too_large"]);
+// inChain: the first error in e's cause chain (e first, at most 8 deep) that matches.
+function inChain(e, match) {
+    let cur = e;
+    for (let depth = 0; depth < 8 && typeof cur === "object" && cur !== null; depth++) {
+        if (match(cur))
+            return cur;
+        cur = cur.cause;
+    }
+    return undefined;
+}
+// replaySeq is where a recorded call settles in replay order: a callback's creation at its
+// createdSeq (protocol 1.1: the entry's seq moves to its completion, where wait() settles), every
+// other call at its entry's seq.
+const replaySeq = (c, e) => (c.kind === "callback" ? (e.createdSeq ?? e.seq) : e.seq);
+const RECORDED = new Set(["completed", "failed", "cancelled"]);
+const idle = () => new Promise((r) => setTimeout(r, 0));
+// quiet marks a promise handled, so a call the workflow never awaits (a race's loser, say) isn't an
+// unhandled rejection; whoever awaits it still sees the rejection.
+const quiet = (p) => { p.catch(() => { }); return p; };
+// Execution replays a workflow against its journal and runs it forward (plan S2 and T1 "Semantics"):
+//  - recorded outcomes resolve one at a time, lowest seq first, with a macrotask yield before each;
+//  - protocol 1.0: at the frontier the oldest pending call (by call order) decides: run sends
+//    stepStarted and awaits its acknowledgement before running; sleep ends the invocation; value
+//    is recorded;
+//  - protocol 1.1 (the frontier rule D2-19, the same in every SDK): the oldest new call decides: a
+//    value is recorded, a callback is created (acknowledged before its URL is visible);
+//    otherwise one lone actionable step runs inline and anything more is planned (planParallel)
+//    and suspended (sleep, invoke, waitForCallback) in one result;
+//  - a step invocation runs exactly its target step;
+//  - a failed attempt ends the invocation with stepFailed; the step and time budgets end it with
+//    no terminal command; the workflow's return or throw ends it with runCompleted or runFailed.
+class Execution {
+    inv;
+    wf;
+    io;
+    now;
+    maxSteps;
+    opts;
+    calls = [];
+    counters = new Map();
+    journal = new Map();
+    outbox = [];
+    cpSeq = 0;
+    executed = 0;
+    cancelThrown = false;
+    fatal;
+    finished;
+    stepOfError = new WeakMap();
+    explicitIds = new Set();
+    currentKey;
+    wake;
+    started;
+    deadline;
+    parallel;
+    apiBase;
+    constructor(inv, wf, io, now, maxSteps, opts) {
+        this.inv = inv;
+        this.wf = wf;
+        this.io = io;
+        this.now = now;
+        this.maxSteps = maxSteps;
+        this.opts = opts;
+        this.started = now().getTime();
+        this.deadline = opts.deadline ?? Date.parse(inv.deadline);
+        this.parallel = supportsParallel(inv.protocolVersion);
+        this.apiBase = (inv.endpoints.api || opts.apiBaseUrl || DEFAULT_API_BASE).replace(/\/+$/, "");
+    }
+    register(kind, name, explicitId, extra) {
+        if (typeof name !== "string" || name.length === 0 || utf8Length(name) > 256 || name.includes("\u0000"))
+            return quiet(Promise.reject(new TypeError("A step name is 1–256 bytes of UTF-8, without NUL")));
+        if (explicitId !== undefined && !validStepIdOverride(explicitId))
+            return quiet(Promise.reject(new TypeError(`Step IDs match ^[A-Za-z0-9._:-]{1,128}$; got "${explicitId}"`)));
+        // The engine wouldn't understand these at protocol 1.0: the run fails rather than misbehaves.
+        if ((kind === "callback" || kind === "invoke") && !this.parallel && !this.fatal)
+            this.fatal = encodeError(new NonRetriableError(`step.${kind === "callback" ? "createCallback" : "invoke"} needs protocol 1.1; this invocation is ${this.inv.protocolVersion}`));
+        if (kind === "message" && !supportsMessages(this.inv.protocolVersion) && !this.fatal)
+            this.fatal = encodeError(new NonRetriableError(`step.waitForMessage needs protocol 1.2; this invocation is ${this.inv.protocolVersion}`));
+        let id;
+        if (explicitId !== undefined) {
+            id = Promise.resolve(explicitId);
+            // An explicit id names one step for the whole run: reusing it, even after the first step
+            // settled, would replay the first step's outcome as the second's.
+            if (!this.fatal && this.explicitIds.has(explicitId))
+                this.fatal = encodeError(new DuplicateStepName(`The step id "${explicitId}" is used twice; give each step its own id`));
+            this.explicitIds.add(explicitId);
+        }
+        else {
+            const n = this.counters.get(name) ?? 0;
+            this.counters.set(name, n + 1);
+            id = stepId(name, n);
+            if (!this.fatal && this.calls.some((c) => !c.settled && !c.explicit && c.kind !== "wait" && c.name === name))
+                this.fatal = encodeError(new DuplicateStepName(`Two steps named "${name}" are pending at once; give each a distinct name or an { id }`));
+        }
+        return quiet(new Promise((resolve, reject) => {
+            this.calls.push({ order: this.calls.length, name, kind, id, settled: false, ...(explicitId !== undefined ? { explicit: explicitId } : {}), resolve, reject, ...extra });
+            this.wake?.();
+        }));
+    }
+    // waitFor registers Callback.wait(): a pending call on the callback's own step ID that neither
+    // advances the name's counter nor counts as a duplicate.
+    waitFor(sid, name) {
+        return quiet(new Promise((resolve, reject) => {
+            this.calls.push({ order: this.calls.length, name, kind: "wait", id: Promise.resolve(sid), stepId: sid, settled: false, resolve, reject });
+            this.wake?.();
+        }));
+    }
+    callbackOf(sid, name, token) {
+        const url = `${this.apiBase}/public/v1/callbacks/${token}`;
+        return Object.freeze({ url, token, wait: () => this.waitFor(sid, name) });
+    }
+    context() {
+        const self = this;
+        const step = {
+            run(name, fn, opts = {}) {
+                let retry;
+                try {
+                    if (typeof fn !== "function")
+                        throw new TypeError("step.run needs a function");
+                    if (opts.timeoutMs !== undefined)
+                        checkTimeout(opts.timeoutMs);
+                    retry = mergeRetry(self.wf.opts.retry ?? DEFAULT_RETRY, opts.retry);
+                }
+                catch (e) {
+                    return quiet(Promise.reject(e));
+                }
+                const timeoutMs = opts.timeoutMs ?? self.wf.opts.timeoutMs;
+                return self.register("run", name, opts.id, { fn, retry, ...(timeoutMs ? { timeoutMs } : {}) });
+            },
+            sleep(name, duration, opts = {}) {
+                let ms;
+                try {
+                    ms = parseDuration(duration);
+                    if (ms > MAX_SLEEP_MS)
+                        throw new TypeError("A sleep is at most a year");
+                }
+                catch (e) {
+                    return quiet(Promise.reject(e));
+                }
+                return self.register("sleep", name, opts.id, { untilMs: self.now().getTime() + ms });
+            },
+            sleepUntil(name, at, opts = {}) {
+                const t = typeof at === "string" ? Date.parse(at) : at instanceof Date ? at.getTime() : NaN;
+                if (!Number.isFinite(t))
+                    return quiet(Promise.reject(new TypeError("sleepUntil needs a valid time")));
+                const now = self.now().getTime();
+                if (t - now > MAX_SLEEP_MS)
+                    return quiet(Promise.reject(new TypeError("A sleep is at most a year")));
+                // A time in the past sleeps until now (and stays a valid RFC 3339 time).
+                return self.register("sleep", name, opts.id, { untilMs: Math.max(t, now) });
+            },
+            now(name) {
+                return quiet(self.register("value", name, undefined, { produce: () => self.now().toISOString() }).then((v) => new Date(v)));
+            },
+            uuid(name) {
+                return quiet(self.register("value", name, undefined, { produce: () => crypto.randomUUID() }));
+            },
+            createCallback(name, opts = {}) {
+                const timeoutMs = opts?.timeoutMs ?? DEFAULT_CALLBACK_TIMEOUT_MS;
+                if (!Number.isInteger(timeoutMs) || timeoutMs < MIN_CALLBACK_TIMEOUT_MS || timeoutMs > MAX_SLEEP_MS)
+                    return quiet(Promise.reject(new TypeError("A callback's timeoutMs is a whole number from 1,000 to 31,536,000,000")));
+                return self.register("callback", name, opts?.id, { timeoutMs });
+            },
+            invoke(name, opts) {
+                let workflow;
+                let input;
+                try {
+                    const w = opts?.workflow;
+                    workflow = typeof w === "string" ? w : typeof w === "object" && w !== null ? w.name : "";
+                    if (!validWorkflowName(workflow))
+                        throw new TypeError(`step.invoke needs a workflow name matching ^[A-Za-z0-9_-]{1,64}$; got "${workflow}"`);
+                    if (opts.input !== undefined) {
+                        try {
+                            input = encodeValue(opts.input);
+                        }
+                        catch (e) {
+                            throw new TypeError(`step.invoke's input isn't JSON: ${e.message}`);
+                        }
+                        if (jsonByteLength(input) > MAX_OUTPUT_BYTES)
+                            throw new TypeError("step.invoke's input is at most 1 MiB of JSON");
+                    }
+                }
+                catch (e) {
+                    return quiet(Promise.reject(e));
+                }
+                return self.register("invoke", name, opts.id, { workflow, ...(input !== undefined ? { input } : {}) });
+            },
+            sendToQueue(name, client, queueId, messages) {
+                try {
+                    if (typeof client?.send !== "function")
+                        throw new TypeError("step.sendToQueue needs a QueuesClient");
+                    if (typeof queueId !== "string" || queueId === "")
+                        throw new TypeError("step.sendToQueue needs a queueId");
+                    if (!Array.isArray(messages) || messages.length < 1 || messages.length > 10)
+                        throw new TypeError("step.sendToQueue takes 1 to 10 messages");
+                }
+                catch (e) {
+                    return quiet(Promise.reject(e));
+                }
+                return step.run(name, async ({ idempotencyKey }) => {
+                    // idempotencyKey is `${runId}:${stepId}:${attempt}`: without the attempt, it's the same
+                    // on every attempt of this step (and different for every other step and run).
+                    const digest = await sendToQueueDigest(self.inv.run.id, idempotencyKey.slice(self.inv.run.id.length + 1, idempotencyKey.lastIndexOf(":")));
+                    try {
+                        return await client.send(queueId, withDedupIds(messages, digest), { idempotencyKey: `wfq_${digest}` });
+                    }
+                    catch (e) {
+                        if (e instanceof QueuesApiError && e.status >= 300 && e.status < 500 && e.status !== 408 && e.status !== 429 && !(e.status === 409 && e.code === "idempotency_in_progress"))
+                            throw new NonRetriableError(`Sending to the queue ${queueId} was refused: ${e.status} ${e.code}: ${e.message}`, { cause: e });
+                        throw e;
+                    }
+                });
+            },
+            waitForMessage(name, opts) {
+                let timeoutMs;
+                try {
+                    if (typeof opts?.queueId !== "string" || !UUID.test(opts.queueId))
+                        throw new TypeError(`step.waitForMessage needs the queue's ID (a lowercase UUID, not its que_ slug); got ${JSON.stringify(opts?.queueId)}`);
+                    if (typeof opts.key !== "string" || !MESSAGE_KEY.test(opts.key))
+                        throw new TypeError(`step.waitForMessage's key matches ^[A-Za-z0-9_.:-]{1,256}$; got ${JSON.stringify(opts.key)}`);
+                    timeoutMs = Math.round(Number(opts.timeoutSeconds) * 1000);
+                    if (typeof opts.timeoutSeconds !== "number" || !(timeoutMs >= MIN_MESSAGE_TIMEOUT_MS && timeoutMs <= MAX_MESSAGE_TIMEOUT_MS))
+                        throw new TypeError("step.waitForMessage's timeoutSeconds is from 1 to 2,592,000 (30 days)");
+                }
+                catch (e) {
+                    return quiet(Promise.reject(e));
+                }
+                return self.register("message", name, opts.id, { queueId: opts.queueId, key: opts.key, timeoutMs });
+            },
+            idempotencyKey() {
+                if (!self.currentKey)
+                    throw new Error("idempotencyKey() is only available inside step.run");
+                return self.currentKey;
+            },
+        };
+        const run = this.inv.run;
+        const schedule = run.schedule && typeof run.schedule === "object" ? { id: run.schedule.id, scheduledTime: run.schedule.scheduledTime } : undefined;
+        return { input: run.input, run: { id: run.id, ...(run.runKey ? { runKey: run.runKey } : {}), attempt: run.attempt, ...(schedule ? { schedule } : {}) }, step, traceparent: typeof this.inv.traceparent === "string" ? this.inv.traceparent : "" };
+    }
+    // load pages the rest of an incomplete journal and fetches offloaded outputs and input, so the
+    // workflow code never waits on I/O during replay.
+    async load() {
+        const entries = this.inv.journal.entries.map((e) => ({ ...e }));
+        let complete = this.inv.journal.complete;
+        while (!complete) {
+            const last = entries.reduce((m, e) => Math.max(m, e.seq), 0);
+            const page = await this.io.journalPage(last);
+            entries.push(...page.entries.map((e) => ({ ...e })));
+            complete = page.complete || page.entries.length === 0;
+        }
+        // Pages are read against the run's current state: an entry that changed between fetches comes
+        // back on a later page at its new, higher seq. One entry per step: the highest seq wins.
+        for (const e of entries) {
+            const had = this.journal.get(e.stepId);
+            if (!had || e.seq > had.seq)
+                this.journal.set(e.stepId, e);
+        }
+        const refs = [...this.journal.values()].filter((e) => e.outputRef);
+        for (let i = 0; i < refs.length; i += 8)
+            await Promise.all(refs.slice(i, i + 8).map(async (e) => { e.output = await this.io.payload(e.outputRef); delete e.outputRef; }));
+        if (this.inv.run.inputRef)
+            this.inv.run = { ...this.inv.run, input: await this.io.payload(this.inv.run.inputRef) };
+    }
+    timeLeftOk() {
+        const total = this.deadline - this.started;
+        return this.deadline - this.now().getTime() > Math.max(5000, total * 0.1);
+    }
+    end(commands) {
+        const all = [...this.outbox.splice(0), ...commands];
+        if (this.inv.kind === "step")
+            return all; // a step invocation reports at most one 1 MiB output
+        const max = this.opts.maxResultBytes ?? DEFAULT_MAX_RESULT_BYTES;
+        let size = 0;
+        for (const c of all)
+            size += utf8Length(JSON.stringify(c)) + 1;
+        if (size + 1024 > max)
+            return [{ type: "runFailed", error: encodeError(new NonRetriableError(`The invocation's commands are ${size} bytes of JSON, more than the ${max} the transport takes (child inputs and outputs are at most 1 MiB each; start fewer at once)`)) }];
+        return all;
+    }
+    async checkpoint(commands) {
+        this.cpSeq++;
+        await this.io.checkpoint({ invocationId: this.inv.invocationId, seq: this.cpSeq, commands });
+    }
+    // recordedEntry: the journal entry that settles c, if any. A callback's creation is recorded once
+    // its token is journaled (whatever the callback's status); every other call once its step has an
+    // outcome.
+    recordedEntry(c) {
+        const e = this.journal.get(c.stepId);
+        if (!e)
+            return undefined;
+        if (c.kind === "callback")
+            return e.token ? e : undefined;
+        return RECORDED.has(e.status) ? e : undefined;
+    }
+    settleRecorded(c, e) {
+        c.settled = true;
+        if (c.kind === "callback")
+            return c.resolve(this.callbackOf(c.stepId, c.name, e.token));
+        if (e.status === "completed" && c.kind === "message")
+            return c.resolve(e.timedOut ? null : (e.output ?? null));
+        if (e.status === "completed")
+            return c.resolve(e.kind === "sleep" ? undefined : (e.output ?? null));
+        if (e.status === "cancelled") {
+            this.cancelThrown = true;
+            return c.reject(new CancelledError("The run was cancelled"));
+        }
+        const err = decodeError(e.error ?? { code: "user", name: "Error", message: "Step failed" });
+        this.stepOfError.set(err, c.stepId);
+        c.reject(err);
+    }
+    async runStep(c, attempt) {
+        const sid = c.stepId;
+        await this.checkpoint([...this.outbox.splice(0), { type: "stepStarted", stepId: sid, name: c.name, attempt, retry: c.retry, ...(c.timeoutMs ? { timeoutMs: c.timeoutMs } : {}) }]);
+        const key = `${this.inv.run.id}:${sid}:${attempt}`;
+        this.currentKey = key;
+        const abort = new AbortController();
+        const onCancel = () => { if (!abort.signal.aborted)
+            abort.abort(new CancelledError("The run is cancelling")); };
+        if (this.opts.cancelSignal?.aborted)
+            onCancel();
+        else
+            this.opts.cancelSignal?.addEventListener("abort", onCancel, { once: true });
+        let timer;
+        try {
+            const work = Promise.resolve().then(() => c.fn({ signal: abort.signal, attempt, idempotencyKey: key }));
+            const raw = c.timeoutMs
+                ? await Promise.race([work, new Promise((_, rej) => {
+                        timer = setTimeout(() => {
+                            const e = new StepTimeout(`Step "${c.name}" ran past ${c.timeoutMs} ms`);
+                            abort.abort(e);
+                            rej(e);
+                        }, c.timeoutMs);
+                    })])
+                : await work;
+            let value;
+            try {
+                value = encodeValue(raw);
+            }
+            catch (e) {
+                throw new NonRetriableError(e.message);
+            }
+            if (jsonByteLength(value) > MAX_OUTPUT_BYTES)
+                throw new OutputTooLarge(`Step "${c.name}" returned more than 1 MiB of JSON`);
+            this.executed++;
+            c.settled = true;
+            c.resolve(value);
+            this.outbox.push({ type: "stepCompleted", stepId: sid, name: c.name, output: value });
+            return undefined;
+        }
+        catch (e) {
+            // Classified through the cause chain: a wrapped NonRetriableError (or a non-retriable wire
+            // code) isn't retried, and a wrapped RetryAfterError keeps its delay.
+            const error = encodeError(e);
+            const nonRetriable = inChain(e, (x) => x instanceof NonRetriableError || x instanceof OutputTooLarge || NON_RETRIABLE_CODES.has(x.code))
+                || NON_RETRIABLE_CODES.has(error.code);
+            const cmd = { type: "stepFailed", stepId: sid, name: c.name, attempt, error, retryable: !nonRetriable };
+            const ra = inChain(e, (x) => x instanceof RetryAfterError);
+            if (ra && typeof ra.delayMs === "number" && !Number.isNaN(ra.delayMs))
+                cmd.retryAfterMs = Math.min(MAX_RETRY_AFTER_MS, Math.max(0, Math.floor(ra.delayMs)));
+            return cmd;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            this.opts.cancelSignal?.removeEventListener("abort", onCancel);
+            this.currentKey = undefined;
+        }
+    }
+    // createCallback mints the token (the run's shard), records it in an acknowledged checkpoint,
+    // and only then resolves the Callback, so its URL is never seen before the engine knows it.
+    async createCallback(c) {
+        const shard = shardOf(this.inv.run.id);
+        if (shard === undefined)
+            throw new TypeError("The run ID carries no shard; callbacks need a v7 or v8 run ID");
+        const token = mintCallbackToken(shard);
+        await this.checkpoint([...this.outbox.splice(0), { type: "callbackCreated", stepId: c.stepId, name: c.name, token, timeoutMs: c.timeoutMs }]);
+        // A wait() later in this invocation finds the callback waiting.
+        this.journal.set(c.stepId, { seq: Number.MAX_SAFE_INTEGER, stepId: c.stepId, name: c.name, kind: "callback", status: "waiting", attempt: 1, token });
+        c.settled = true;
+        c.resolve(this.callbackOf(c.stepId, c.name, token));
+    }
+    // createMessageWait records the wait (protocol 1.2) in an acknowledged checkpoint; the call stays
+    // pending, and the invocation ends with waitForMessage (plan), as Callback.wait() does.
+    async createMessageWait(c) {
+        await this.checkpoint([...this.outbox.splice(0), { type: "messageWaitCreated", stepId: c.stepId, name: c.name, queueId: c.queueId, key: c.key, timeoutMs: c.timeoutMs }]);
+        this.journal.set(c.stepId, { seq: Number.MAX_SAFE_INTEGER, stepId: c.stepId, name: c.name, kind: "message", status: "waiting", attempt: 1, queueId: c.queueId, key: c.key });
+    }
+    planned(c) {
+        return { stepId: c.stepId, name: c.name, retry: c.retry, ...(c.timeoutMs ? { timeoutMs: c.timeoutMs } : {}) };
+    }
+    // plan (protocol 1.1, the frontier rule D2-19, identical in every SDK): one actionable step with
+    // nothing else pending runs inline; otherwise every new step is planned together and every
+    // suspension sent with it, in call order. A retrying step alongside other work waits
+    // (planParallel skips existing steps); a running entry (a planned step at attempt 0 too) is
+    // awaited, never re-run.
+    plan(pending) {
+        const runs = [];
+        const retrying = [];
+        let busy = 0;
+        const suspends = [];
+        const waited = new Set();
+        for (const p of pending) {
+            const e = this.journal.get(p.stepId);
+            switch (p.kind) {
+                case "run":
+                    if (!e)
+                        runs.push(p);
+                    else if (e.status === "retrying")
+                        retrying.push(p);
+                    else
+                        busy++;
+                    break;
+                case "sleep":
+                    if (!e)
+                        suspends.push({ type: "sleep", stepId: p.stepId, name: p.name, until: new Date(p.untilMs).toISOString() });
+                    else
+                        busy++;
+                    break;
+                case "invoke":
+                    if (!e)
+                        suspends.push({ type: "invoke", stepId: p.stepId, name: p.name, workflow: p.workflow, ...(p.input !== undefined ? { input: p.input } : {}) });
+                    else
+                        busy++;
+                    break;
+                case "wait":
+                    // Sent for every pending wait, even one already waiting: a no-op for the engine.
+                    if (!waited.has(p.stepId)) {
+                        waited.add(p.stepId);
+                        suspends.push({ type: "waitForCallback", stepId: p.stepId });
+                    }
+                    break;
+                case "message":
+                    // A created wait (waiting) suspends, every time; a new one is created first (as the
+                    // oldest new call), like a callback.
+                    if (e && !waited.has(p.stepId)) {
+                        waited.add(p.stepId);
+                        suspends.push({ type: "waitForMessage", stepId: p.stepId });
+                    }
+                    break;
+                // value and callback calls (and new message waits) are handled when they're the oldest new call.
+            }
+        }
+        if (busy === 0 && suspends.length === 0 && runs.length + retrying.length === 1) {
+            const c = runs[0] ?? retrying[0];
+            const e = this.journal.get(c.stepId);
+            return { kind: "inline", call: c, attempt: e?.status === "retrying" ? e.attempt + 1 : 1 };
+        }
+        if (runs.length > MAX_PLANNED_STEPS)
+            return { kind: "end", commands: [{ type: "runFailed", error: encodeError(new NonRetriableError(`${runs.length} steps started at once; a run plans at most ${MAX_PLANNED_STEPS} together (start them in batches, or fan out through child workflows)`)) }] };
+        return { kind: "end", commands: [...(runs.length > 0 ? [{ type: "planParallel", steps: runs.map((r) => this.planned(r)) }] : []), ...suspends] };
+    }
+    // sequential (protocol 1.0, and while cancelling): phase 1, exactly.
+    sequential(c) {
+        const entry = this.journal.get(c.stepId);
+        // Any other recorded status (sleeping, running, waiting, or one a later version adds) means
+        // the engine is still waiting on it: end the invocation; only a retrying step runs again.
+        if (entry && entry.status !== "retrying")
+            return { kind: "end", commands: [] };
+        if (c.kind === "sleep")
+            return { kind: "end", commands: [{ type: "sleep", stepId: c.stepId, name: c.name, until: new Date(c.untilMs).toISOString() }] };
+        return { kind: "inline", call: c, attempt: entry?.status === "retrying" ? entry.attempt + 1 : 1 };
+    }
+    // stepInvocation runs exactly the target step, at its journal attempt + 1, and ends. It never
+    // records values, plans or suspends.
+    async stepInvocation(pending) {
+        const target = pending.find((c) => c.kind === "run" && c.stepId === this.inv.targetStepId);
+        if (!target || !this.timeLeftOk())
+            return this.end([]);
+        const entry = this.journal.get(target.stepId);
+        const failed = await this.runStep(target, (entry?.attempt ?? 0) + 1);
+        return this.end(failed ? [failed] : []);
+    }
+    terminal() {
+        const f = this.finished;
+        if (f.ok) {
+            let output;
+            try {
+                output = encodeValue(f.output);
+            }
+            catch (e) {
+                return [{ type: "runFailed", error: encodeError(new NonRetriableError(e.message)) }];
+            }
+            if (jsonByteLength(output) > MAX_OUTPUT_BYTES)
+                return [{ type: "runFailed", error: encodeError(new OutputTooLarge("The workflow returned more than 1 MiB of JSON")) }];
+            return [{ type: "runCompleted", output }];
+        }
+        const cause = typeof f.error === "object" && f.error !== null ? this.stepOfError.get(f.error) : undefined;
+        return [{ type: "runFailed", error: encodeError(f.error), ...(cause ? { causeStepId: cause } : {}) }];
+    }
+    async run() {
+        await this.load();
+        const done = Promise.resolve()
+            .then(() => this.wf.fn(this.context()))
+            .then((output) => { this.finished = { ok: true, output }; }, (error) => { this.finished = { ok: false, error }; })
+            .finally(() => this.wake?.());
+        for (;;) {
+            await idle();
+            // A step invocation reports only its target step (T1 rule 5): the run's outcome, even one
+            // its replay reaches (a race already won), is the orchestration's to report.
+            if (this.inv.kind === "step" && (this.fatal || this.finished))
+                return this.end([]);
+            if (this.fatal)
+                return this.end([{ type: "runFailed", error: this.fatal }]);
+            if (this.finished)
+                return this.end(this.terminal());
+            const pending = this.calls.filter((c) => !c.settled);
+            if (pending.length === 0) {
+                await Promise.race([done, new Promise((r) => (this.wake = r))]);
+                this.wake = undefined;
+                continue;
+            }
+            for (const c of pending)
+                c.stepId ??= await c.id;
+            const recorded = pending
+                .map((c) => [c, this.recordedEntry(c)])
+                .filter(([, e]) => e !== undefined)
+                .sort((a, b) => replaySeq(a[0], a[1]) - replaySeq(b[0], b[1]) || a[0].order - b[0].order);
+            if (recorded.length > 0) {
+                this.settleRecorded(recorded[0][0], recorded[0][1]);
+                continue;
+            }
+            pending.sort((a, b) => a.order - b.order);
+            // The run is cancelling (a pull heartbeat said so): start nothing new and end; the next
+            // invocation carries the cancel, so the workflow's cleanup runs there.
+            if (this.opts.cancelSignal?.aborted)
+                return this.end([]);
+            if (this.inv.kind === "step")
+                return this.stepInvocation(pending);
+            if (this.inv.cancel && !this.cancelThrown) {
+                const c0 = pending[0];
+                this.cancelThrown = true;
+                c0.settled = true;
+                c0.reject(new CancelledError("The run was cancelled"));
+                continue;
+            }
+            if (this.cancelThrown) {
+                const refused = pending.find((p) => p.kind !== "run");
+                if (refused) {
+                    refused.settled = true;
+                    refused.reject(new CancelledError("The run is cancelling: only step.run cleanup steps can run"));
+                    continue;
+                }
+            }
+            // While cancelling, a cleanup step doesn't wait behind steps the engine already owns (an
+            // in-flight parallel sibling): the next call is the oldest one the engine doesn't own.
+            const c = this.cancelThrown ? pending.find((p) => { const e = this.journal.get(p.stepId); return !e || e.status === "retrying"; }) : pending[0];
+            if (!c)
+                return this.end([]);
+            // The deciding call: at 1.1 the oldest call with no journal entry (D2-19; calls the engine
+            // owns don't hold values back), at 1.0 and while cancelling the oldest pending call (phase 1).
+            const head = this.parallel && !this.cancelThrown ? pending.find((p) => !this.journal.has(p.stepId)) : c;
+            if (head?.kind === "value" && !(this.journal.has(head.stepId))) {
+                const value = encodeValue(head.produce());
+                this.outbox.push({ type: "valueRecorded", stepId: head.stepId, name: head.name, value });
+                head.settled = true;
+                head.resolve(value);
+                continue;
+            }
+            if (head?.kind === "callback" && !this.journal.has(head.stepId)) {
+                try {
+                    await this.createCallback(head);
+                }
+                catch (e) {
+                    if (e instanceof TypeError) {
+                        head.settled = true;
+                        head.reject(e);
+                        continue;
+                    }
+                    throw e; // InvocationSuperseded, CheckpointFailed: the invocation stops
+                }
+                continue;
+            }
+            if (head?.kind === "message" && !this.journal.has(head.stepId)) {
+                await this.createMessageWait(head); // InvocationSuperseded, CheckpointFailed: the invocation stops
+                continue;
+            }
+            const next = this.parallel && !this.cancelThrown ? this.plan(pending) : this.sequential(c);
+            if (next.kind === "end")
+                return this.end(next.commands);
+            if (this.executed >= this.maxSteps || !this.timeLeftOk())
+                return this.end([]);
+            const failed = await this.runStep(next.call, next.attempt);
+            if (failed)
+                return this.end([failed]);
+        }
+    }
+}
+// execute runs one invocation of wf and returns the commands of its InvocationResult. It throws
+// InvocationSuperseded or CheckpointFailed when a checkpoint isn't applied.
+export function execute(inv, wf, io, opts = {}) {
+    return new Execution(inv, definitionOf(wf), io, opts.now ?? (() => new Date()), opts.maxStepsPerInvocation ?? 50, opts).run();
+}

package/dist/runtime/invocation.d.ts

@@ -0,0 +1,5 @@
+import type { Invocation } from "../protocol/index.ts";
+export declare class InvalidInvocation extends Error {
+    name: string;
+}
+export declare function parseInvocation(text: string): Invocation;

package/dist/runtime/invocation.js

@@ -0,0 +1,47 @@
+export class InvalidInvocation extends Error {
+    name = "InvalidInvocation";
+}
+const KINDS = new Set(["orchestrate", "step", "sync"]);
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+// parseInvocation checks what the runtime relies on and ignores unknown fields (protocol minor
+// versions add fields).
+export function parseInvocation(text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        throw new InvalidInvocation("The body isn't JSON");
+    }
+    if (!isObject(v))
+        throw new InvalidInvocation("The body isn't an invocation");
+    const inv = v;
+    if (typeof inv.protocolVersion !== "string" || inv.protocolVersion.split(".")[0] !== "1")
+        throw new InvalidInvocation(`Unsupported protocol version ${String(inv.protocolVersion)}`);
+    if (typeof inv.kind !== "string" || !KINDS.has(inv.kind))
+        throw new InvalidInvocation(`Unknown invocation kind ${String(inv.kind)}`);
+    if (typeof inv.invocationId !== "string" || typeof inv.deadline !== "string" || Number.isNaN(Date.parse(inv.deadline)))
+        throw new InvalidInvocation("Missing invocationId or deadline");
+    if (inv.kind !== "sync") {
+        const run = inv.run;
+        const journal = inv.journal;
+        if (!isObject(run) || typeof run.id !== "string" || typeof run.workflow !== "string" || typeof run.attempt !== "number")
+            throw new InvalidInvocation("Missing run");
+        if (!isObject(journal) || typeof journal.complete !== "boolean" || !Array.isArray(journal.entries))
+            throw new InvalidInvocation("Missing journal");
+        for (const e of journal.entries)
+            if (!isObject(e) || typeof e.seq !== "number" || typeof e.stepId !== "string" || typeof e.status !== "string")
+                throw new InvalidInvocation("A journal entry needs seq, stepId and status");
+            else if (e.createdSeq !== undefined && !(Number.isInteger(e.createdSeq) && e.createdSeq >= 1))
+                throw new InvalidInvocation("A journal entry's createdSeq is an integer ≥ 1");
+            else if (e.kind === "message" && (typeof e.queueId !== "string" || typeof e.key !== "string"))
+                throw new InvalidInvocation("A message entry needs queueId and key");
+        if (typeof inv.token !== "string" || inv.token === "" || !isObject(inv.endpoints) || typeof inv.endpoints.live !== "string")
+            throw new InvalidInvocation("Missing token or endpoints.live");
+        if (inv.kind === "step" && (typeof inv.targetStepId !== "string" || inv.targetStepId === ""))
+            throw new InvalidInvocation("A step invocation needs targetStepId");
+    }
+    if (inv.cancel !== undefined && inv.cancel !== null && !isObject(inv.cancel))
+        throw new InvalidInvocation("cancel isn't an object");
+    return { ...inv, cancel: inv.cancel ?? null };
+}