@voyantjs/workflows-orchestrator-cloudflare 0.6.7 → 0.6.8

package/dist/cf-container-runner.d.ts

@@ -0,0 +1,102 @@
+import type { StepRunner } from "@voyantjs/workflows/handler";
+/**
+ * Minimal subset of `DurableObjectNamespace` that the runner actually
+ * uses. Matches the shape exposed by `@cloudflare/containers`'
+ * `getContainer(namespace, id).fetch()` pattern — we keep it local so
+ * tests can pass a stub.
+ */
+export interface ContainerNamespaceLike {
+    idFromName(name: string): {
+        toString(): string;
+    };
+    get(id: {
+        toString(): string;
+    }): {
+        fetch(request: Request): Promise<Response>;
+    };
+}
+export interface BundleLocation {
+    /**
+     * Short-lived signed URL the container uses to fetch the bundle
+     * from R2. Expected TTL is minutes, not hours — scoped tightly to
+     * the specific `<projectId>/<workflowVersion>/container.mjs` key.
+     */
+    url: string;
+    /**
+     * SHA-256 hex of the bundle bytes, computed at deploy time and
+     * stored alongside the bundle. The container verifies the
+     * downloaded bytes match this hash before importing — both as an
+     * integrity check and as a pin preventing stale-cache confusion.
+     * Accepts both plain hex and `sha256:<hex>` formats.
+     */
+    hash: string;
+}
+export interface CfContainerRunnerDeps {
+    /**
+     * DO namespace backing the Cloudflare Container class. Typically
+     * `env.NODE_STEP_POOL` wired in wrangler.jsonc to a `Container`-
+     * extending class (from `@cloudflare/containers`).
+     */
+    namespace: ContainerNamespaceLike;
+    /**
+     * Resolve a signed R2 URL + manifest hash for the bundle the
+     * container should import for this dispatch. Called on every
+     * invocation (cache in the resolver if URL minting is expensive).
+     *
+     * If omitted, the dispatch payload has no `bundle` field and the
+     * container must have its bundle baked into the image (via the
+     * `WORKFLOW_BUNDLE` env var). Multi-tenant production uses the
+     * resolver; single-tenant / dev images can skip it.
+     */
+    resolveBundle?: (args: {
+        runId: string;
+        workflowId: string;
+        workflowVersion: string;
+        projectId: string;
+        organizationId: string;
+    }) => Promise<BundleLocation> | BundleLocation;
+    /**
+     * Base URL presented to the container. The container's Worker
+     * proxy only inspects the path, so this is cosmetic — defaults to
+     * `https://node-step.voyant.internal`.
+     */
+    baseUrl?: string;
+    /**
+     * Optional HMAC signer for the `X-Voyant-Step-Auth` header so the
+     * container can verify the request came from a Voyant orchestrator.
+     * Shape matches `createHmacSigner` from `@voyantjs/workflows/auth`.
+     */
+    sign?: (body: string) => Promise<string> | string;
+    /** Optional structured logger. */
+    logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+    /**
+     * Build the container-addressing id for a given step invocation.
+     * Default: `"<runId>:<attempt>:<stepId>"` — deterministic and
+     * parallel-safe (distinct step invocations get distinct
+     * containers, so the CF addressing model isolates them).
+     */
+    containerId?: (args: {
+        runId: string;
+        workflowId: string;
+        workflowVersion: string;
+        stepId: string;
+        attempt: number;
+    }) => string;
+}
+/**
+ * Build a `StepRunner` that dispatches each step invocation to a
+ * Cloudflare Container in the given namespace.
+ *
+ * Wire this into the orchestrator's step handler:
+ *
+ *   createStepHandler({
+ *     nodeStepRunner: createCfContainerStepRunner({
+ *       namespace: env.NODE_STEP_POOL,
+ *     }),
+ *   });
+ *
+ * Steps that declare `runtime: "node"` will route through here;
+ * `runtime: "edge"` (or unset) continues to run inline.
+ */
+export declare function createCfContainerStepRunner(deps: CfContainerRunnerDeps): StepRunner;
+//# sourceMappingURL=cf-container-runner.d.ts.map

package/dist/cf-container-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-container-runner.d.ts","sourceRoot":"","sources":["../src/cf-container-runner.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAoB,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAE/E;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,QAAQ,IAAI,MAAM,CAAA;KAAE,CAAA;IAChD,GAAG,CAAC,EAAE,EAAE;QAAE,QAAQ,IAAI,MAAM,CAAA;KAAE,GAAG;QAAE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAA;CAChF;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,SAAS,EAAE,sBAAsB,CAAA;IACjC;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QACrB,KAAK,EAAE,MAAM,CAAA;QACb,UAAU,EAAE,MAAM,CAAA;QAClB,eAAe,EAAE,MAAM,CAAA;QACvB,SAAS,EAAE,MAAM,CAAA;QACjB,cAAc,EAAE,MAAM,CAAA;KACvB,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAA;IAC9C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,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;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QACnB,KAAK,EAAE,MAAM,CAAA;QACb,UAAU,EAAE,MAAM,CAAA;QAClB,eAAe,EAAE,MAAM,CAAA;QACvB,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;KAChB,KAAK,MAAM,CAAA;CACb;AA2BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,qBAAqB,GAAG,UAAU,CA2HnF"}

package/dist/cf-container-runner.js

@@ -0,0 +1,153 @@
+// Cloudflare Container-backed step runner for `runtime: "node"`.
+//
+// Given a Durable Object namespace that proxies a Cloudflare Container
+// class (the `@cloudflare/containers` pattern), this factory returns a
+// `StepRunner` the workflows handler can wire via its `nodeStepRunner`
+// dep. The returned runner:
+//
+//   1. Serializes the step identity + input into a compact request.
+//   2. Picks a container by deterministic id (`<runId>:<stepId>` so
+//      parallel step invocations land on distinct instances).
+//   3. POSTs the request to `/step` on that container via `fetch`
+//      through the DO namespace binding.
+//   4. Reads the container's response — which *is* a `StepJournalEntry`
+//      (status, output/error, timestamps) — and returns it verbatim.
+//
+// The container side is expected to:
+//   - import the tenant workflow bundle,
+//   - expose `POST /step` that accepts `{ workflowId, workflowVersion,
+//     stepId, attempt, input, envVars? }` and runs the step body,
+//   - return a `StepJournalEntry` JSON.
+//
+// The container entry point is a short adapter around
+// `@voyantjs/workflows/handler`'s `executeWorkflowStep` with the
+// workflow registry already loaded. See
+// `apps/workflows-node-step-container/` for the reference image.
+/**
+ * Build a `StepRunner` that dispatches each step invocation to a
+ * Cloudflare Container in the given namespace.
+ *
+ * Wire this into the orchestrator's step handler:
+ *
+ *   createStepHandler({
+ *     nodeStepRunner: createCfContainerStepRunner({
+ *       namespace: env.NODE_STEP_POOL,
+ *     }),
+ *   });
+ *
+ * Steps that declare `runtime: "node"` will route through here;
+ * `runtime: "edge"` (or unset) continues to run inline.
+ */
+export function createCfContainerStepRunner(deps) {
+    const baseUrl = deps.baseUrl ?? "https://node-step.voyant.internal";
+    const idOf = deps.containerId ?? (({ runId, attempt, stepId }) => `${runId}:${attempt}:${stepId}`);
+    return async ({ stepId, attempt, input, stepCtx, runId, workflowId, workflowVersion, projectId, organizationId, options, journal, }) => {
+        const startedAt = Date.now();
+        let bundle;
+        if (deps.resolveBundle) {
+            try {
+                bundle = await deps.resolveBundle({
+                    runId,
+                    workflowId,
+                    workflowVersion,
+                    projectId,
+                    organizationId,
+                });
+            }
+            catch (err) {
+                deps.logger?.("error", "cf-container: resolveBundle threw", {
+                    runId,
+                    stepId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return failed(attempt, startedAt, "BUNDLE_RESOLVE_FAILED", err);
+            }
+        }
+        const payload = {
+            runId,
+            workflowId,
+            workflowVersion,
+            projectId,
+            organizationId,
+            stepId,
+            attempt,
+            input,
+            options: {
+                machine: options.machine,
+                timeout: typeof options.timeout === "string" || typeof options.timeout === "number"
+                    ? options.timeout
+                    : undefined,
+            },
+            bundle,
+            journal,
+        };
+        const body = JSON.stringify(payload);
+        const headers = {
+            "content-type": "application/json; charset=utf-8",
+        };
+        if (deps.sign) {
+            headers["x-voyant-step-auth"] = await deps.sign(body);
+        }
+        const id = deps.namespace.idFromName(idOf({ runId, workflowId, workflowVersion, stepId, attempt }));
+        const stub = deps.namespace.get(id);
+        const request = new Request(`${baseUrl}/step`, {
+            method: "POST",
+            headers,
+            body,
+            signal: stepCtx.signal,
+        });
+        deps.logger?.("info", "cf-container: dispatching step", {
+            runId,
+            workflowId,
+            stepId,
+            attempt,
+        });
+        let response;
+        try {
+            response = await stub.fetch(request);
+        }
+        catch (err) {
+            deps.logger?.("error", "cf-container: fetch threw", {
+                runId,
+                stepId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return failed(attempt, startedAt, "CONTAINER_DISPATCH_FAILED", err);
+        }
+        const text = await response.text();
+        if (response.status !== 200) {
+            deps.logger?.("warn", "cf-container: non-200 response", {
+                runId,
+                stepId,
+                status: response.status,
+                body: text.slice(0, 500),
+            });
+            return failed(attempt, startedAt, "CONTAINER_HTTP_ERROR", new Error(`container returned HTTP ${response.status}: ${text}`));
+        }
+        try {
+            const entry = JSON.parse(text);
+            // Trust the container's own timestamps; they reflect the actual
+            // step body execution, not the dispatch round-trip.
+            return entry;
+        }
+        catch (err) {
+            return failed(attempt, startedAt, "CONTAINER_INVALID_RESPONSE", new Error(`container returned non-JSON body: ${String(err)}`));
+        }
+    };
+}
+function failed(attempt, startedAt, code, err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    return {
+        attempt,
+        status: "err",
+        startedAt,
+        finishedAt: Date.now(),
+        error: {
+            category: "RUNTIME_ERROR",
+            code,
+            message: e.message,
+            name: e.name,
+            stack: e.stack,
+        },
+    };
+}

package/dist/dispatch-handler.d.ts

@@ -0,0 +1,20 @@
+import { type StepHandler } from "@voyantjs/workflows-orchestrator";
+import type { DispatchNamespaceLike } from "./types.js";
+export interface DispatchHandlerDeps {
+    dispatcher: DispatchNamespaceLike;
+    /** Optional HMAC signer for the X-Voyant-Dispatch-Auth header. */
+    sign?: (body: string) => Promise<string> | string;
+    /** Optional logger for step-level observability. */
+    logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+    /** Base URL to present to the tenant. Defaults to `https://tenant.voyant.internal`. */
+    baseUrl?: string;
+}
+/**
+ * The dispatcher binding expects a name corresponding to the tenant
+ * script slot. `createDispatchStepHandler` binds the step handler to
+ * a specific tenant script; different tenants need different handlers
+ * (trivial via `createDispatchStepHandler(...)` with the script name
+ * resolved from the run's tenantMeta).
+ */
+export declare function createDispatchStepHandler(tenantScript: string, deps: DispatchHandlerDeps): StepHandler;
+//# sourceMappingURL=dispatch-handler.d.ts.map

package/dist/dispatch-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-handler.d.ts","sourceRoot":"","sources":["../src/dispatch-handler.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,WAAW,EAEjB,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAEvD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,qBAAqB,CAAA;IACjC,kEAAkE;IAClE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,oDAAoD;IACpD,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;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,mBAAmB,GACxB,WAAW,CAgBb"}

package/dist/dispatch-handler.js

@@ -0,0 +1,31 @@
+// Builds a `StepHandler` (the thing the orchestrator calls on every
+// invocation) by routing the request through a Workers-for-Platforms
+// dispatch namespace to the tenant's bundled Worker.
+//
+// The tenant Worker is expected to mount `@voyantjs/workflows/handler`
+// at `POST /__voyant/workflow-step` (see docs/runtime-protocol.md §2.1).
+import { createHttpStepHandler, } from "@voyantjs/workflows-orchestrator";
+/**
+ * The dispatcher binding expects a name corresponding to the tenant
+ * script slot. `createDispatchStepHandler` binds the step handler to
+ * a specific tenant script; different tenants need different handlers
+ * (trivial via `createDispatchStepHandler(...)` with the script name
+ * resolved from the run's tenantMeta).
+ */
+export function createDispatchStepHandler(tenantScript, deps) {
+    const baseUrl = deps.baseUrl ?? "https://tenant.voyant.internal";
+    return createHttpStepHandler({
+        sign: deps.sign ? (body) => deps.sign(body) : undefined,
+        logger: deps.logger,
+        resolveTarget(_req) {
+            const binding = deps.dispatcher.get(tenantScript);
+            return {
+                url: `${baseUrl}/__voyant/workflow-step`,
+                label: tenantScript,
+                fetch(request) {
+                    return binding.fetch(request);
+                },
+            };
+        },
+    });
+}

package/dist/do-store.d.ts

@@ -0,0 +1,4 @@
+import type { RunRecordStore } from "@voyantjs/workflows-orchestrator";
+import type { DurableObjectStorageLike } from "./types.js";
+export declare function createDurableObjectRunStore(storage: DurableObjectStorageLike): RunRecordStore;
+//# sourceMappingURL=do-store.d.ts.map

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

@@ -0,0 +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"}

package/dist/do-store.js

@@ -0,0 +1,34 @@
+// A RunRecordStore backed by `DurableObjectStorage`. In production
+// this is the DO's transactional KV; in tests, any
+// DurableObjectStorageLike (e.g. in-memory Map wrapper) works.
+//
+// Layout: one run record per DO. Stored under the fixed key
+// `record`. The adapter assumes one DO per runId, so "list" scans a
+// single key. If a caller wants multi-run listing they should go
+// through the global run index (lives in voyant-cloud's Postgres,
+// not here).
+const RECORD_KEY = "record";
+export function createDurableObjectRunStore(storage) {
+    return {
+        async get(id) {
+            const r = await storage.get(RECORD_KEY);
+            if (!r || r.id !== id)
+                return undefined;
+            return r;
+        },
+        async save(record) {
+            await storage.put(RECORD_KEY, record);
+            return record;
+        },
+        async list(filter = {}) {
+            const r = await storage.get(RECORD_KEY);
+            if (!r)
+                return [];
+            if (filter.workflowId && r.workflowId !== filter.workflowId)
+                return [];
+            if (filter.status && r.status !== filter.status)
+                return [];
+            return [r];
+        },
+    };
+}

package/dist/durable-object.d.ts

@@ -0,0 +1,24 @@
+import { applyWaitpointInjection, driveUntilPaused, type RunRecord, type StepHandler } from "@voyantjs/workflows-orchestrator";
+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.
+     */
+    resolveStepHandler: (tenantScript: string) => StepHandler;
+    now?: () => number;
+}
+export declare function handleDurableObjectRequest(req: Request, deps: DurableObjectDeps): Promise<Response>;
+/**
+ * Fire this from your DO's `alarm()` method. Walks pending
+ * waitpoints, resolves every DATETIME whose `wakeAt` is <= now,
+ * re-drives the run, and reschedules the next alarm if the run
+ * parked on another DATETIME.
+ */
+export declare function handleDurableObjectAlarm(deps: DurableObjectDeps): Promise<void>;
+export type { RunRecord };
+export { applyWaitpointInjection, driveUntilPaused };
+//# sourceMappingURL=durable-object.d.ts.map

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

@@ -0,0 +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"}

package/dist/durable-object.js

@@ -0,0 +1,173 @@
+// The WorkflowRunDO — one Durable Object per run. Holds the
+// RunRecord in storage, drives the run through the tenant via a
+// dispatch-namespace StepHandler, exposes a tiny HTTP surface to
+// the outer Worker, and schedules DO alarms for DATETIME waitpoints
+// so `ctx.sleep(...)` wakes back up.
+//
+// Routes:
+//   POST /trigger      { ...TriggerPayload }        → RunRecord
+//   POST /resume       { injection }                → RunRecord | error
+//   POST /cancel       { reason? }                  → RunRecord | error
+//   GET  /get                                       → RunRecord | 404
+//
+// Alarm entry point: handleDurableObjectAlarm(deps). Fired by the CF
+// runtime at the wake time scheduled by setAlarm; resolves due
+// DATETIME waitpoints, re-drives, and reschedules if needed.
+//
+// Callers should treat the HTTP surface as an implementation detail;
+// the public surface is the outer Worker's /api/* routes.
+import { applyWaitpointInjection, driveUntilPaused, cancel as orchestratorCancel, resume as orchestratorResume, trigger as orchestratorTrigger, } from "@voyantjs/workflows-orchestrator";
+import { createDurableObjectRunStore } from "./do-store.js";
+export async function handleDurableObjectRequest(req, deps) {
+    const url = new URL(req.url);
+    const store = createDurableObjectRunStore(deps.storage);
+    if (req.method === "POST" && url.pathname === "/trigger") {
+        const payload = (await req.json());
+        const handler = deps.resolveStepHandler(payload.tenantMeta.tenantScript);
+        const record = await orchestratorTrigger({
+            workflowId: payload.workflowId,
+            workflowVersion: payload.workflowVersion,
+            input: payload.input,
+            tenantMeta: payload.tenantMeta,
+            environment: payload.environment,
+            tags: payload.tags,
+            runId: payload.runId,
+        }, { store, handler, now: deps.now });
+        await reconcileAlarm(record, store, deps);
+        return json(200, record);
+    }
+    if (req.method === "POST" && url.pathname === "/resume") {
+        const payload = (await req.json());
+        const existing = await store.get((await getStoredRunId(store)) ?? "");
+        if (!existing)
+            return json(404, { error: "not_found", message: "no run stored in this DO" });
+        const handler = deps.resolveStepHandler(existing.tenantMeta.tenantScript ?? "");
+        const out = await orchestratorResume({ runId: existing.id, injection: payload.injection }, { store, handler, now: deps.now });
+        if (!out.ok) {
+            const status = out.status === "not_found" ? 404 : out.status === "no_match" ? 400 : 409;
+            return json(status, { error: out.status, message: out.message });
+        }
+        await reconcileAlarm(out.record, store, deps);
+        return json(200, out.record);
+    }
+    if (req.method === "POST" && url.pathname === "/cancel") {
+        const payload = (await req.json());
+        const existing = await store.get((await getStoredRunId(store)) ?? "");
+        if (!existing)
+            return json(404, { error: "not_found", message: "no run stored in this DO" });
+        const handler = deps.resolveStepHandler(existing.tenantMeta.tenantScript ?? "");
+        const out = await orchestratorCancel({ runId: existing.id, reason: payload.reason }, { store, handler, now: deps.now });
+        if (!out.ok) {
+            const status = out.status === "not_found" ? 404 : 409;
+            return json(status, { error: out.status, message: out.message });
+        }
+        await reconcileAlarm(out.record, store, deps);
+        return json(200, out.record);
+    }
+    if (req.method === "GET" && url.pathname === "/get") {
+        const existing = await store.get((await getStoredRunId(store)) ?? "");
+        if (!existing)
+            return json(404, { error: "not_found" });
+        return json(200, existing);
+    }
+    return json(404, { error: "route_not_found", path: url.pathname });
+}
+/**
+ * Fire this from your DO's `alarm()` method. Walks pending
+ * waitpoints, resolves every DATETIME whose `wakeAt` is <= now,
+ * re-drives the run, and reschedules the next alarm if the run
+ * parked on another DATETIME.
+ */
+export async function handleDurableObjectAlarm(deps) {
+    const store = createDurableObjectRunStore(deps.storage);
+    const existingId = await getStoredRunId(store);
+    if (!existingId)
+        return;
+    const record = await store.get(existingId);
+    if (!record)
+        return;
+    if (record.status !== "waiting") {
+        await deps.storage.deleteAlarm?.();
+        return;
+    }
+    const now = (deps.now ?? (() => Date.now()))();
+    const stillPending = [];
+    let resolvedAny = false;
+    for (const wp of record.pendingWaitpoints) {
+        const wakeAt = typeof wp.meta.wakeAt === "number" ? wp.meta.wakeAt : undefined;
+        if (wp.kind === "DATETIME" && wakeAt !== undefined && wakeAt <= now) {
+            record.journal.waitpointsResolved[wp.clientWaitpointId] = {
+                kind: "DATETIME",
+                resolvedAt: now,
+                source: "replay",
+            };
+            resolvedAny = true;
+        }
+        else {
+            stillPending.push(wp);
+        }
+    }
+    record.pendingWaitpoints = stillPending;
+    if (!resolvedAny) {
+        // Spurious alarm — nothing due. Persist and reconcile.
+        await store.save(record);
+        await reconcileAlarm(record, store, deps);
+        return;
+    }
+    record.status = "running";
+    const handler = deps.resolveStepHandler(record.tenantMeta.tenantScript ?? "");
+    await driveUntilPaused(record, { handler, now: deps.now });
+    await store.save(record);
+    await reconcileAlarm(record, store, deps);
+}
+/**
+ * Look at the record's pending waitpoints; if any are DATETIME,
+ * stamp a `wakeAt` into meta (if not already set) and schedule the
+ * earliest via `setAlarm`. Clears any prior alarm when the run is
+ * terminal or has no DATETIME waitpoints left.
+ */
+async function reconcileAlarm(record, store, deps) {
+    const now = (deps.now ?? (() => Date.now()))();
+    if (record.status !== "waiting") {
+        await deps.storage.deleteAlarm?.();
+        return;
+    }
+    let earliest;
+    let dirty = false;
+    for (const wp of record.pendingWaitpoints) {
+        if (wp.kind !== "DATETIME")
+            continue;
+        let wakeAt = typeof wp.meta.wakeAt === "number" ? wp.meta.wakeAt : undefined;
+        if (wakeAt === undefined) {
+            const ms = wp.timeoutMs ?? (typeof wp.meta.durationMs === "number" ? wp.meta.durationMs : 0);
+            wakeAt = now + ms;
+            wp.meta.wakeAt = wakeAt;
+            dirty = true;
+        }
+        earliest = earliest === undefined ? wakeAt : Math.min(earliest, wakeAt);
+    }
+    if (dirty)
+        await store.save(record);
+    if (earliest !== undefined) {
+        await deps.storage.setAlarm?.(earliest);
+    }
+    else {
+        await deps.storage.deleteAlarm?.();
+    }
+}
+/**
+ * One DO holds one run, keyed by `record`. Returns the id of that
+ * stored run, if any.
+ */
+async function getStoredRunId(store) {
+    const all = await store.list();
+    return all[0]?.id;
+}
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
+    });
+}
+// Re-exported for callers building their own DO class via composition.
+export { applyWaitpointInjection, driveUntilPaused };

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type BundleLocation, type CfContainerRunnerDeps, type ContainerNamespaceLike, createCfContainerStepRunner, } from "./cf-container-runner.js";
+export { createDispatchStepHandler, type DispatchHandlerDeps, } from "./dispatch-handler.js";
+export { createDurableObjectRunStore } from "./do-store.js";
+export { type DurableObjectDeps, handleDurableObjectAlarm, handleDurableObjectRequest, } from "./durable-object.js";
+export { createR2Presigner, type PresignArgs, type R2PresignerOptions, } from "./r2-sign.js";
+export * from "./types.js";
+export { type DurableObjectNamespaceLike, handleWorkerRequest, type WorkerFetchDeps, } from "./worker.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA4BA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,2BAA2B,GAC5B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EACL,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAA;AACrB,cAAc,YAAY,CAAA;AAC1B,OAAO,EACL,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,34 @@
+// @voyantjs/workflows-orchestrator-cloudflare
+//
+// Cloudflare Worker + Durable Object adapter for @voyantjs/workflows-orchestrator.
+// Composes the protocol-agnostic state machine in @voyantjs/workflows-orchestrator
+// with a DO-backed run store and a dispatch-namespace step handler.
+//
+// Typical wrangler.jsonc layout:
+//
+//   {
+//     "name": "voyant-orchestrator",
+//     "main": "src/worker.ts",
+//     "compatibility_date": "2025-01-01",
+//     "durable_objects": {
+//       "bindings": [
+//         { "name": "WORKFLOW_RUN_DO", "class_name": "WorkflowRunDO" }
+//       ]
+//     },
+//     "dispatch_namespaces": [
+//       { "binding": "DISPATCHER", "namespace": "voyant-tenants" }
+//     ],
+//     "migrations": [
+//       { "tag": "v1", "new_sqlite_classes": ["WorkflowRunDO"] }
+//     ]
+//   }
+//
+// See docs/runtime-protocol.md §2 and docs/design.md §6 for the
+// design this adapter implements.
+export { createCfContainerStepRunner, } from "./cf-container-runner.js";
+export { createDispatchStepHandler, } from "./dispatch-handler.js";
+export { createDurableObjectRunStore } from "./do-store.js";
+export { handleDurableObjectAlarm, handleDurableObjectRequest, } from "./durable-object.js";
+export { createR2Presigner, } from "./r2-sign.js";
+export * from "./types.js";
+export { handleWorkerRequest, } from "./worker.js";

package/dist/r2-sign.d.ts

@@ -0,0 +1,18 @@
+export interface R2PresignerOptions {
+    /** Cloudflare account id (32-char hex). */
+    accountId: string;
+    /** R2 Access Key ID from your CF dashboard — scope read-only. */
+    accessKeyId: string;
+    /** R2 Secret Access Key. Store as a Worker Secret. */
+    secretAccessKey: string;
+    /** R2 bucket name. */
+    bucket: string;
+}
+export interface PresignArgs {
+    /** Object key, e.g. `"prj_42/v1/container.mjs"`. Leading `/` is optional. */
+    key: string;
+    /** Seconds until the URL stops being valid. Min 1, max 604800. */
+    expiresIn: number;
+}
+export declare function createR2Presigner(opts: R2PresignerOptions): (args: PresignArgs) => Promise<string>;
+//# sourceMappingURL=r2-sign.d.ts.map

package/dist/r2-sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2-sign.d.ts","sourceRoot":"","sources":["../src/r2-sign.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;IACnB,sDAAsD;IACtD,eAAe,EAAE,MAAM,CAAA;IACvB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,kBAAkB,GACvB,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAsDxC"}