@voyantjs/workflows-orchestrator-cloudflare 0.28.1 → 0.29.0

package/README.md

@@ -1,21 +1,36 @@
 # @voyantjs/workflows-orchestrator-cloudflare
 
 Cloudflare Worker + Durable Object adapter for
-[`@voyantjs/workflows-orchestrator`](../workflows-orchestrator). Composes the
-protocol-agnostic state machine with DO-backed storage and a
-Workers-for-Platforms dispatch namespace that fans step requests out
-to tenant Workers.
+[`@voyantjs/workflows-orchestrator`](../workflows-orchestrator). Composes
+the protocol-agnostic state machine with DO-backed storage and a
+pluggable **step dispatcher** that delivers step requests to wherever
+workflow code lives.
 
 This package is the building block; the deployable artifact lives in
-[`apps/workflows-orchestrator-worker`](../../apps/workflows-orchestrator-worker), which
-wires it into a `wrangler.jsonc` + default-exports.
+[`apps/workflows-orchestrator-worker`](../../apps/workflows-orchestrator-worker),
+which wires it into a `wrangler.jsonc` + default-exports.
+
+## Picking a dispatcher
+
+The orchestrator forwards step requests through a `StepDispatcher`. Pick
+the factory that matches your deployment:
+
+| Factory | Use case | Bindings needed |
+|---|---|---|
+| `createInlineDispatcher` | Single-Worker (workflows + API in same isolate) | None |
+| `createServiceBindingDispatcher` | Two-Worker (orchestrator + sibling workflows Worker) | Service binding |
+| `createHttpDispatcher` | Cross-host (e.g. CF orchestrator → Node-side workflows) | HTTP endpoint |
+
+Hosted multi-tenant providers implement custom `StepDispatcher`s in
+their own deployment code — multi-tenancy is a deployment concern, not
+a runtime one, so it doesn't ship here.
 
 ```ts
 import {
   handleWorkerRequest,
   handleDurableObjectRequest,
   handleDurableObjectAlarm,
-  createDispatchStepHandler,
+  createServiceBindingDispatcher,
 } from "@voyantjs/workflows-orchestrator-cloudflare";
 
 export default {
@@ -38,10 +53,7 @@ export class WorkflowRunDO implements DurableObject {
   private deps() {
     return {
       storage: this.state.storage,
-      resolveStepHandler: (tenantScript: string) =>
-        createDispatchStepHandler(tenantScript, {
-          dispatcher: this.env.DISPATCHER,
-        }),
+      dispatcher: createServiceBindingDispatcher({ binding: this.env.WORKFLOWS }),
     };
   }
 }

package/dist/cloudflare-edge-driver.d.ts

@@ -0,0 +1,49 @@
+import type { EnvironmentName } from "@voyantjs/workflows";
+import type { DriverFactory } from "@voyantjs/workflows/driver";
+import { type KvNamespaceLike } from "./manifest-kv-store.js";
+import type { DurableObjectNamespaceLike } from "./worker.js";
+export interface CloudflareEdgeDriverOptions {
+    /** Durable Object namespace holding one DO per run. */
+    orchestratorNamespace: DurableObjectNamespaceLike;
+    /** KV namespace storing serialized manifests. */
+    manifestKv: KvNamespaceLike;
+    /**
+     * Adapter-specific tenant identifier stamped onto every triggered
+     * run as `tenantMeta.tenantScript`. Opaque to the OSS runtime —
+     * surfaces on `StepDispatcherContext` for custom dispatchers that
+     * need a routing key. Built-in dispatchers (inline, service-binding,
+     * HTTP) ignore it.
+     */
+    tenantScript?: string;
+    /** Default environment for `trigger()` calls without an explicit one. */
+    defaultEnvironment?: EnvironmentName;
+    /** Tenant metadata stamped onto every triggered run. Defaults to "default" tripled. */
+    tenantMeta?: {
+        tenantId: string;
+        projectId: string;
+        organizationId: string;
+    };
+    /** Injectable clock; defaults to Date.now. */
+    now?: () => number;
+    /** id generator for runs; defaults to `run_<random>`. */
+    idGenerator?: () => string;
+    /** Optional structured logger; falls back to the framework logger. */
+    logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+}
+/**
+ * Build the Cloudflare-edge driver factory. The returned `DriverFactory`
+ * is invoked once by `createApp()` with `DriverFactoryDeps`.
+ *
+ * Usage in a Worker template:
+ *
+ *     createApp({
+ *       workflows: {
+ *         driver: createCloudflareEdgeDriver({
+ *           orchestratorNamespace: env.WORKFLOW_RUN_DO,
+ *           manifestKv:            env.WORKFLOW_MANIFESTS,
+ *         }),
+ *       },
+ *     })
+ */
+export declare function createCloudflareEdgeDriver(opts: CloudflareEdgeDriverOptions): DriverFactory;
+//# sourceMappingURL=cloudflare-edge-driver.d.ts.map

package/dist/cloudflare-edge-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-edge-driver.d.ts","sourceRoot":"","sources":["../src/cloudflare-edge-driver.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EACV,aAAa,EAOd,MAAM,4BAA4B,CAAA;AAKnC,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAA;AAI7D,MAAM,WAAW,2BAA2B;IAC1C,uDAAuD;IACvD,qBAAqB,EAAE,0BAA0B,CAAA;IACjD,iDAAiD;IACjD,UAAU,EAAE,eAAe,CAAA;IAC3B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,eAAe,CAAA;IACpC,uFAAuF;IACvF,UAAU,CAAC,EAAE;QACX,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,cAAc,EAAE,MAAM,CAAA;KACvB,CAAA;IACD,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;IAC1B,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAChF;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,2BAA2B,GAAG,aAAa,CA8T3F"}

package/dist/cloudflare-edge-driver.js

@@ -0,0 +1,317 @@
+// Mode 1 driver — Cloudflare edge composition.
+//
+// `createApp({ workflows: { driver: createCloudflareEdgeDriver({ ... }) } })`
+// is the entry point for any deployment that runs the orchestrator on
+// Cloudflare Workers + Durable Objects. Composes:
+//
+//   * `voyant_run_DO` (Durable Object namespace)  — primary state
+//   * `WORKFLOW_MANIFESTS` KV namespace            — manifest store
+//
+// Step delivery is configured separately on the run DO via a
+// `StepDispatcher` — see `./dispatchers.ts` for built-in factories
+// (inline / service binding / HTTP).
+//
+// The factory is invoked by `createApp()` after the framework's
+// `ModuleContainer` is built — see architecture doc §6.3 for the
+// `DriverFactory` contract.
+//
+// See architecture doc §8.
+import { deriveStableEventId } from "@voyantjs/workflows/events";
+import { routeEvent } from "@voyantjs/workflows-orchestrator";
+import { createKvManifestStore, } from "./manifest-kv-store.js";
+const DEFAULT_TENANT_META = {
+    tenantId: "default",
+    projectId: "default",
+    organizationId: "default",
+};
+// ---- Public factory ----
+/**
+ * Build the Cloudflare-edge driver factory. The returned `DriverFactory`
+ * is invoked once by `createApp()` with `DriverFactoryDeps`.
+ *
+ * Usage in a Worker template:
+ *
+ *     createApp({
+ *       workflows: {
+ *         driver: createCloudflareEdgeDriver({
+ *           orchestratorNamespace: env.WORKFLOW_RUN_DO,
+ *           manifestKv:            env.WORKFLOW_MANIFESTS,
+ *         }),
+ *       },
+ *     })
+ */
+export function createCloudflareEdgeDriver(opts) {
+    return (deps) => {
+        const manifestStore = createKvManifestStore({ kv: opts.manifestKv });
+        const now = opts.now ?? deps.now ?? (() => Date.now());
+        const tenantMeta = {
+            ...DEFAULT_TENANT_META,
+            ...(opts.tenantMeta ?? {}),
+            ...(opts.tenantScript ? { tenantScript: opts.tenantScript } : {}),
+        };
+        const defaultEnv = opts.defaultEnvironment ?? "development";
+        const logger = opts.logger ?? deps.logger;
+        let shuttingDown = false;
+        // ---- Helpers ----
+        function assertNotShutdown() {
+            if (shuttingDown) {
+                throw new Error("CloudflareEdgeDriver: shutdown() has been called; new operations are refused.");
+            }
+        }
+        async function forwardToRunDO(runId, request) {
+            const id = opts.orchestratorNamespace.idFromName(runId);
+            const stub = opts.orchestratorNamespace.get(id);
+            return stub.fetch(request);
+        }
+        function genRunId(seed) {
+            if (seed !== undefined)
+                return seed;
+            if (opts.idGenerator)
+                return opts.idGenerator();
+            const ts = now().toString(36);
+            const rand = Math.floor(Math.random() * 1_000_000)
+                .toString(36)
+                .padStart(4, "0");
+            return `run_${ts}_${rand}`;
+        }
+        // ---- WorkflowDriver implementation ----
+        async function registerManifest(args) {
+            assertNotShutdown();
+            return manifestStore.registerManifest({
+                environment: args.environment,
+                versionId: args.manifest.versionId,
+                manifest: args.manifest,
+            });
+        }
+        async function getManifest(args) {
+            const envelope = await manifestStore.getCurrent(args.environment);
+            if (!envelope)
+                return null;
+            return envelope.manifest;
+        }
+        async function trigger(workflow, input, triggerOpts) {
+            assertNotShutdown();
+            const workflowId = typeof workflow === "string" ? workflow : workflow.id;
+            const env = triggerOpts?.environment ?? defaultEnv;
+            const runId = triggerOpts?.idempotencyKey !== undefined
+                ? `idem-${workflowId}-${triggerOpts.idempotencyKey}`
+                : genRunId();
+            const payload = {
+                runId,
+                workflowId,
+                workflowVersion: triggerOpts?.lockToVersion ?? "v1",
+                input: input,
+                tenantMeta,
+                environment: env,
+                tags: triggerOpts?.tags,
+                idempotencyKey: triggerOpts?.idempotencyKey,
+                triggeredBy: { kind: "api" },
+            };
+            const resp = await forwardToRunDO(runId, new Request("https://do-internal/trigger", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(payload),
+            }));
+            if (!resp.ok) {
+                const body = await safeText(resp);
+                throw new Error(`CloudflareEdgeDriver: trigger DO returned ${resp.status}: ${body.slice(0, 256)}`);
+            }
+            const record = (await resp.json());
+            return {
+                id: record.id,
+                workflowId: record.workflowId,
+                status: record.status,
+                startedAt: record.startedAt,
+            };
+        }
+        async function ingestEvent(args) {
+            assertNotShutdown();
+            const stored = await manifestStore.getCurrent(args.environment);
+            if (!stored) {
+                return {
+                    ok: false,
+                    reason: "manifest_not_registered",
+                    message: `No manifest is registered for environment "${args.environment}".`,
+                };
+            }
+            const manifest = stored.manifest;
+            const eventId = args.envelope.metadata?.eventId ?? (await deriveStableEventId(args.envelope));
+            const routed = routeEvent({
+                manifest,
+                envelope: {
+                    name: args.envelope.name,
+                    data: args.envelope.data,
+                    metadata: args.envelope.metadata,
+                    emittedAt: args.envelope.emittedAt,
+                },
+                eventId,
+                idempotencyOverride: args.idempotencyKey,
+            });
+            const matches = [];
+            let anyTriggered = false;
+            let anyFailed = false;
+            for (const entry of routed) {
+                if (entry.status === "skipped") {
+                    matches.push({
+                        filterId: entry.filterId,
+                        status: "skipped",
+                        reason: entry.reason,
+                        details: entry.details,
+                    });
+                    continue;
+                }
+                const runId = `idem-${entry.targetWorkflowId}-${entry.idempotencyKey}`;
+                const payload = {
+                    runId,
+                    workflowId: entry.targetWorkflowId,
+                    workflowVersion: "v1",
+                    input: entry.input,
+                    tenantMeta,
+                    environment: args.environment,
+                    idempotencyKey: entry.idempotencyKey,
+                    triggeredBy: {
+                        kind: "event",
+                        eventId,
+                        eventType: args.envelope.name,
+                        filterId: entry.filterId,
+                    },
+                };
+                try {
+                    const resp = await forwardToRunDO(runId, new Request("https://do-internal/trigger", {
+                        method: "POST",
+                        headers: { "content-type": "application/json" },
+                        body: JSON.stringify(payload),
+                    }));
+                    if (resp.ok) {
+                        matches.push({
+                            filterId: entry.filterId,
+                            targetWorkflowId: entry.targetWorkflowId,
+                            runId,
+                            idempotencyKey: entry.idempotencyKey,
+                            status: "queued",
+                        });
+                        anyTriggered = true;
+                    }
+                    else {
+                        const body = await safeText(resp);
+                        logger?.("error", "CloudflareEdgeDriver: trigger DO failed", {
+                            status: resp.status,
+                            body: body.slice(0, 256),
+                        });
+                        matches.push({
+                            filterId: entry.filterId,
+                            targetWorkflowId: entry.targetWorkflowId,
+                            status: "error",
+                            reason: `do_returned_${resp.status}`,
+                        });
+                        anyFailed = true;
+                    }
+                }
+                catch (err) {
+                    matches.push({
+                        filterId: entry.filterId,
+                        targetWorkflowId: entry.targetWorkflowId,
+                        status: "error",
+                        reason: err instanceof Error ? err.message : String(err),
+                    });
+                    anyFailed = true;
+                }
+            }
+            if (matches.length > 0 && !anyTriggered && anyFailed) {
+                return {
+                    ok: false,
+                    reason: "trigger_failed_for_all_matches",
+                    message: "every matched filter failed to trigger",
+                };
+            }
+            return { ok: true, eventId, matches };
+        }
+        async function shutdown() {
+            shuttingDown = true;
+        }
+        // ---- WorkflowAdmin (partial — Mode 1 has no native cross-run query
+        //      layer; getRun + cancelRun are direct DO RPC; listRuns +
+        //      streamRun are explicitly unsupported per architecture
+        //      doc §8.3) ----
+        const admin = {
+            async getRun(runId) {
+                try {
+                    const resp = await forwardToRunDO(runId, new Request("https://do-internal/get", { method: "GET" }));
+                    if (resp.status === 404)
+                        return null;
+                    if (!resp.ok)
+                        return null;
+                    const rec = (await resp.json());
+                    return {
+                        id: rec.id,
+                        workflowId: rec.workflowId,
+                        status: rec.status,
+                        startedAt: rec.startedAt,
+                        completedAt: rec.completedAt,
+                        tags: [...rec.tags],
+                        environment: rec.environment,
+                        version: rec.workflowVersion,
+                        input: rec.input,
+                        output: rec.output,
+                        error: rec.error,
+                        durationMs: rec.completedAt !== undefined
+                            ? Math.max(0, rec.completedAt - rec.startedAt)
+                            : undefined,
+                    };
+                }
+                catch {
+                    return null;
+                }
+            },
+            async cancelRun(runId, cancelOpts) {
+                // Per architecture doc §21.21, cancel does NOT run compensations
+                // by default; the `compensate` flag is accepted but no-op in v1.
+                void cancelOpts?.compensate;
+                await forwardToRunDO(runId, new Request("https://do-internal/cancel", {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ reason: cancelOpts?.reason }),
+                }));
+            },
+            async listRuns(_listOpts) {
+                // Self-host Mode 1 has no native cross-run query layer; voyant-cloud
+                // provides one in its index repo. Surface the limit to consumers
+                // (the dashboard) so they can fall back gracefully.
+                return { runs: [], nextCursor: undefined };
+            },
+            streamRun(_runId) {
+                // Live journal-event streaming is a follow-up; return an
+                // immediately-exhausted iterable so probes see a clean empty
+                // stream rather than undefined.
+                return {
+                    [Symbol.asyncIterator]() {
+                        return {
+                            next: async () => ({ value: undefined, done: true }),
+                        };
+                    },
+                };
+            },
+        };
+        return {
+            registerManifest,
+            trigger,
+            ingestEvent,
+            getManifest,
+            shutdown,
+            admin,
+        };
+    };
+}
+// ---- Internal helpers ----
+// Fallback id derivation lives in `@voyantjs/workflows/events`'s
+// `deriveStableEventId` and is used inline at the call site above —
+// content-derived so external callers without a forwarder still get
+// dedup across retries (architecture doc §15.2).
+async function safeText(resp) {
+    try {
+        return await resp.text();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/dispatchers.d.ts

@@ -0,0 +1,87 @@
+import { type StepHandler } from "@voyantjs/workflows-orchestrator";
+/**
+ * Context the run DO supplies when asking a dispatcher for a
+ * StepHandler. Most dispatchers ignore it; it carries the run's
+ * adapter-specific tenant identifier (when set) and the workflow id
+ * for logging / per-tenant routing in custom dispatchers.
+ */
+export interface StepDispatcherContext {
+    /**
+     * Adapter-specific tenant identifier from the run's `tenantMeta`.
+     * Opaque to the OSS runtime — interpretation is up to whichever
+     * dispatcher consumes it (e.g. a custom multi-tenant dispatcher
+     * may use it as a routing key).
+     */
+    tenantScript?: string;
+    /** Workflow id, useful for label / logging. */
+    workflowId?: string;
+}
+/**
+ * Pluggable step-dispatch primitive. The run DO calls the dispatcher
+ * once per drive and forwards step requests through the handler it
+ * returns.
+ *
+ * Pick a factory below based on where workflow code lives in your
+ * deployment, or implement the type directly for custom transports.
+ */
+export type StepDispatcher = (ctx: StepDispatcherContext) => StepHandler;
+/**
+ * Subset of a Cloudflare service-binding interface (`env.SOMETHING`
+ * declared as `services: [{ binding, service }]` in wrangler.jsonc).
+ * `fetch(req)` delivers to the bound Worker.
+ */
+export interface ServiceBindingLike {
+    fetch(request: Request): Promise<Response>;
+}
+export interface ServiceBindingDispatcherOptions {
+    /** Service binding to a sibling Worker that hosts the workflow code. */
+    binding: ServiceBindingLike;
+    /** Optional HMAC signer. */
+    sign?: (body: string) => Promise<string> | string;
+    /** Optional structured logger. */
+    logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+    /** URL presented to the bound Worker. Defaults to `https://tenant.voyant.internal`. */
+    baseUrl?: string;
+    /** Optional label for logs. Defaults to `"service-binding"`. */
+    label?: string;
+}
+/**
+ * Service-binding dispatcher. Routes step requests to a sibling Worker
+ * via `services: [{ binding, service }]` in the orchestrator's
+ * wrangler.jsonc. Use this for self-host two-Worker deployments
+ * (orchestrator + workflows are separate Workers in the same account).
+ * No WfP needed; works on the standard Workers paid plan.
+ */
+export declare function createServiceBindingDispatcher(opts: ServiceBindingDispatcherOptions): StepDispatcher;
+/**
+ * Inline dispatcher. Returns the supplied StepHandler directly — used
+ * when workflow code lives in the SAME Worker as the orchestrator
+ * (single-Worker self-host). No HTTP, no DO traversal, just a function
+ * call. Pair with `handleStepRequest` from `@voyantjs/workflows/handler`
+ * for the typical setup.
+ */
+export declare function createInlineDispatcher(handler: StepHandler): StepDispatcher;
+export interface HttpDispatcherOptions {
+    /** Absolute URL of the workflow-step endpoint. */
+    url: string;
+    /** Optional HMAC signer. */
+    sign?: (body: string) => Promise<string> | string;
+    /** Optional structured logger. */
+    logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+    /**
+     * Optional fetch override (e.g. `env.SOMETHING.fetch.bind(env.SOMETHING)`
+     * for typed bindings, or a custom client for testing). Defaults to
+     * `globalThis.fetch`.
+     */
+    fetch?: (request: Request) => Promise<Response>;
+    /** Optional label for logs; defaults to the URL host. */
+    label?: string;
+}
+/**
+ * HTTP dispatcher. Routes step requests to a configurable URL via
+ * `globalThis.fetch` (or a supplied fetch). Use for cross-host setups
+ * (e.g. a CF orchestrator forwarding to a Node-side workflows Worker)
+ * or test fakes.
+ */
+export declare function createHttpDispatcher(opts: HttpDispatcherOptions): StepDispatcher;
+//# sourceMappingURL=dispatchers.d.ts.map

package/dist/dispatchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatchers.d.ts","sourceRoot":"","sources":["../src/dispatchers.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAE1F;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,qBAAqB,KAAK,WAAW,CAAA;AAIxE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC3C;AAED,MAAM,WAAW,+BAA+B;IAC9C,wEAAwE;IACxE,OAAO,EAAE,kBAAkB,CAAA;IAC3B,4BAA4B;IAC5B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,kCAAkC;IAClC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/E,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,+BAA+B,GACpC,cAAc,CAiBhB;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAE3E;AAID,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IACX,4BAA4B;IAC5B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,kCAAkC;IAClC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/E;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC/C,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,cAAc,CAwBhF"}

package/dist/dispatchers.js

@@ -0,0 +1,83 @@
+// Step dispatchers — abstract "given a run's context, produce a
+// StepHandler that delivers step requests to whatever Worker (or
+// isolate) hosts the workflow code."
+//
+// The OSS runtime ships three universal factories:
+//   * createInlineDispatcher          — same isolate as the orchestrator
+//   * createServiceBindingDispatcher  — sibling Worker via service binding
+//   * createHttpDispatcher            — arbitrary HTTP endpoint
+//
+// Hosted multi-tenant providers (Voyant Cloud, etc.) implement their
+// own dispatchers in their private deployment code — Workers-for-
+// Platforms is one such option, but it doesn't belong in the OSS
+// runtime because it bakes in a CF-specific multi-tenancy story that
+// most self-host users don't need or want.
+//
+// See issue #528 + docs/architecture/workflows-runtime-architecture.md §8.
+import { createHttpStepHandler } from "@voyantjs/workflows-orchestrator";
+/**
+ * Service-binding dispatcher. Routes step requests to a sibling Worker
+ * via `services: [{ binding, service }]` in the orchestrator's
+ * wrangler.jsonc. Use this for self-host two-Worker deployments
+ * (orchestrator + workflows are separate Workers in the same account).
+ * No WfP needed; works on the standard Workers paid plan.
+ */
+export function createServiceBindingDispatcher(opts) {
+    const baseUrl = opts.baseUrl ?? "https://tenant.voyant.internal";
+    const label = opts.label ?? "service-binding";
+    return (_ctx) => createHttpStepHandler({
+        sign: opts.sign ? (body) => opts.sign(body) : undefined,
+        logger: opts.logger,
+        resolveTarget() {
+            return {
+                url: `${baseUrl}/__voyant/workflow-step`,
+                label,
+                fetch(request) {
+                    return opts.binding.fetch(request);
+                },
+            };
+        },
+    });
+}
+// ---- Factory: Inline ----
+/**
+ * Inline dispatcher. Returns the supplied StepHandler directly — used
+ * when workflow code lives in the SAME Worker as the orchestrator
+ * (single-Worker self-host). No HTTP, no DO traversal, just a function
+ * call. Pair with `handleStepRequest` from `@voyantjs/workflows/handler`
+ * for the typical setup.
+ */
+export function createInlineDispatcher(handler) {
+    return () => handler;
+}
+/**
+ * HTTP dispatcher. Routes step requests to a configurable URL via
+ * `globalThis.fetch` (or a supplied fetch). Use for cross-host setups
+ * (e.g. a CF orchestrator forwarding to a Node-side workflows Worker)
+ * or test fakes.
+ */
+export function createHttpDispatcher(opts) {
+    const fetchImpl = opts.fetch ?? ((req) => globalThis.fetch(req));
+    let label = opts.label;
+    if (!label) {
+        try {
+            label = new URL(opts.url).host;
+        }
+        catch {
+            label = opts.url;
+        }
+    }
+    return (_ctx) => createHttpStepHandler({
+        sign: opts.sign ? (body) => opts.sign(body) : undefined,
+        logger: opts.logger,
+        resolveTarget() {
+            return {
+                url: opts.url,
+                label,
+                fetch(request) {
+                    return fetchImpl(request);
+                },
+            };
+        },
+    });
+}

package/dist/do-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"do-store.d.ts","sourceRoot":"","sources":["../src/do-store.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACjF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAI1D,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,wBAAwB,GAAG,cAAc,CAqB7F"}
+{"version":3,"file":"do-store.d.ts","sourceRoot":"","sources":["../src/do-store.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACjF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAI1D,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,wBAAwB,GAAG,cAAc,CAkC7F"}

package/dist/do-store.js

@@ -20,6 +20,18 @@ export function createDurableObjectRunStore(storage) {
             await storage.put(RECORD_KEY, record);
             return record;
         },
+        async tryInsert(record) {
+            // DO storage is single-threaded per DO instance: concurrent fetches
+            // to `idFromName(runId)` are serialized inside the DO's request
+            // queue, so get-then-put is naturally atomic. This is just the
+            // contract-shape implementation.
+            const existing = await storage.get(RECORD_KEY);
+            if (existing && existing.id === record.id) {
+                return { record: existing, created: false };
+            }
+            await storage.put(RECORD_KEY, record);
+            return { record, created: true };
+        },
         async list(filter = {}) {
             const r = await storage.get(RECORD_KEY);
             if (!r)

package/dist/durable-object.d.ts

@@ -1,14 +1,21 @@
-import { applyWaitpointInjection, driveUntilPaused, type RunRecord, type StepHandler } from "@voyantjs/workflows-orchestrator";
+import { applyWaitpointInjection, driveUntilPaused, type RunRecord } from "@voyantjs/workflows-orchestrator";
+import type { StepDispatcher } from "./dispatchers.js";
 import type { DurableObjectStorageLike } from "./types.js";
 export interface DurableObjectDeps {
     storage: DurableObjectStorageLike;
     /**
-     * Resolve the StepHandler to use for a given tenant script. Called
-     * with the tenantScript (from the trigger payload) so the DO can
-     * route to the correct tenant Worker. In production this closes
-     * over the dispatch namespace; in tests it returns a mock.
+     * Pluggable dispatcher producing a StepHandler for a given run's
+     * context. The DO calls `dispatcher({ tenantScript, workflowId })`
+     * once per drive; the returned handler delivers step requests to
+     * whatever Worker (or isolate) hosts the workflow code.
+     *
+     * Pick a factory from `./dispatchers.ts`:
+     *  - `createWfpDispatcher`           — multi-tenant via dispatch namespace
+     *  - `createServiceBindingDispatcher` — sibling Worker via service binding
+     *  - `createInlineDispatcher`         — same Worker / direct call
+     *  - `createHttpDispatcher`           — arbitrary HTTP endpoint
      */
-    resolveStepHandler: (tenantScript: string) => StepHandler;
+    dispatcher: StepDispatcher;
     now?: () => number;
 }
 export declare function handleDurableObjectRequest(req: Request, deps: DurableObjectDeps): Promise<Response>;

package/dist/durable-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durable-object.d.ts","sourceRoot":"","sources":["../src/durable-object.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAKhB,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,kCAAkC,CAAA;AAEzC,OAAO,KAAK,EAEV,wBAAwB,EAGzB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,wBAAwB,CAAA;IACjC;;;;;OAKG;IACH,kBAAkB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,WAAW,CAAA;IACzD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,QAAQ,CAAC,CAgEnB;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCrF;AAyDD,YAAY,EAAE,SAAS,EAAE,CAAA;AAEzB,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,CAAA"}
+{"version":3,"file":"durable-object.d.ts","sourceRoot":"","sources":["../src/durable-object.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAKhB,KAAK,SAAS,EAEf,MAAM,kCAAkC,CAAA;AAEzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,OAAO,KAAK,EAEV,wBAAwB,EAGzB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,wBAAwB,CAAA;IACjC;;;;;;;;;;;OAWG;IACH,UAAU,EAAE,cAAc,CAAA;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAYD,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,QAAQ,CAAC,CAmEnB;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCrF;AAyDD,YAAY,EAAE,SAAS,EAAE,CAAA;AAEzB,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,CAAA"}