@porulle/jobs-cloudflare 0.16.0 → 0.18.0

package/README.md

@@ -1,21 +1,116 @@
 # `@porulle/jobs-cloudflare`
 
-Cloudflare Workflows binding adapter and task runner for Porulle. Keyed exclusivity and supersession require a durable coordinator (normally a Durable Object); the adapter fails fast when a keyed task is used without one.
+Cloudflare Workflows binding adapter and task runner for Porulle. Keyed exclusivity and supersession require a durable coordinator — this package ships one, `DurableObjectConcurrencyCoordinator`, backed by a `PorulleJobCoordinator` Durable Object; the adapter fails fast when a keyed task is used without one.
+
+## Entrypoint
 
 ```ts
 import { WorkflowEntrypoint } from "cloudflare:workers";
-import { CloudflareExecutionEngine } from "@porulle/jobs-cloudflare";
+import { NonRetryableError } from "cloudflare:workflows";
+import {
+  CloudflareExecutionEngine,
+  DurableObjectConcurrencyCoordinator,
+  adaptWorkflowBinding,
+} from "@porulle/jobs-cloudflare";
 
-export const jobs = new CloudflareExecutionEngine({
-  workflow: env.PORULLE_WORKFLOW,
-  coordinator,
-});
+// Bindings arrive with the request/event, so build the engine from `env` once you have it.
+export function createJobsEngine(env: Env) {
+  const workflow = adaptWorkflowBinding(env.PORULLE_WORKFLOW);
+  return new CloudflareExecutionEngine({
+    workflow,
+    // Workflows stops retrying only for this exact class; the package cannot import it itself.
+    nonRetryableError: NonRetryableError,
+    coordinator: new DurableObjectConcurrencyCoordinator({
+      // One Durable Object per coordination key, so keys never queue behind each other.
+      stub: (key) => env.PORULLE_JOB_COORDINATOR.get(env.PORULLE_JOB_COORDINATOR.idFromName(key)),
+      workflow,
+    }),
+  });
+}
 
-export class PorulleWorkflow extends WorkflowEntrypoint {
+export class PorulleWorkflow extends WorkflowEntrypoint<Env> {
   async run(event, step) {
+    const jobs = createJobsEngine(this.env); // register(...) it with your tasks first
     return jobs.run(event.payload, step);
   }
 }
 ```
 
-The coordinator must durably supersede pending instances at enqueue and serialize `run()` by concurrency key. Unkeyed tasks can use the Workflow binding directly.
+`adaptWorkflowBinding` folds Cloudflare's instance status onto the six-value `JobInstanceStatus` (`paused`/`waitingForPause` → `waiting`, anything unknown → `errored`) and flattens the error to its message.
+
+Task handlers that need durable, per-phase steps read `ctx.step` — absent on push engines that have not wired one, present here and on the drizzle engine:
+
+```ts
+const enrichEntityTask: TaskDefinition = {
+  slug: "loom/enrich-entity",
+  durableSteps: true,
+  handler: async ({ input, ctx }) => {
+    const loaded = await ctx.step!.do("load", () => loadEntity(input.entityId));
+    const generated = await ctx.step!.do("generate", () => callModel(loaded), {
+      timeout: 40_000,
+    });
+    if (generated.refused) {
+      throw new TaskNonRetryableError("Model refused the request");
+    }
+    await ctx.step!.do("write-ledger", () => writeLedgerRow(generated));
+    return { output: generated };
+  },
+};
+```
+
+Steps are never nested. A task that sets `durableSteps: true` runs its handler in the Workflow body: each `ctx.step.do(name, fn, options?)` call becomes its own top-level Workflow step (named `porulle:<slug>:<name>`), retried independently per `options.retries` (falling back to the task's own `retries`), and code between steps re-runs on every wake — keep side effects inside steps. A task without the flag runs as today: one step named `porulle:<slug>` retried as a unit up to `retries.attempts` times, with a pass-through `ctx.step` inside it. `TaskNonRetryableError` — thrown directly, or requested via `options.nonRetryable` — maps to Cloudflare's `NonRetryableError`, so that step (and the instance) does not retry it.
+
+## Coordinator wiring
+
+Add the Durable Object and Workflow bindings to `wrangler.jsonc`:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      { "name": "PORULLE_JOB_COORDINATOR", "class_name": "PorulleJobCoordinator" },
+    ],
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["PorulleJobCoordinator"] }],
+  "workflows": [
+    { "binding": "PORULLE_WORKFLOW", "name": "porulle-jobs", "class_name": "PorulleWorkflow" },
+  ],
+}
+```
+
+Build the Durable Object class on your Worker's own `DurableObject` base (this package cannot import `cloudflare:workers` itself) and export it from the Worker entrypoint alongside the Workflow:
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { porulleJobCoordinator } from "@porulle/jobs-cloudflare";
+
+export class PorulleJobCoordinator extends porulleJobCoordinator(DurableObject) {}
+```
+
+The Durable Object reads `PORULLE_WORKFLOW` from its `env` — the Worker's own bindings, since the class lives in the same script — to detect dead lock holders and wake the next waiting instance.
+
+Per key (`organizationId:taskSlug:concurrencyKey`), `enqueue` terminates every pending instance when `supersedes` is set (never the currently running one — matching the drizzle adapter, only unstarted jobs are dropped). An instance is registered with the coordinator before it is created, so a supersede also terminates instances that exist but have not started running. `run` serializes same-key instances through the DO's `acquire`/`release`; each call is its own Workflow step, so a replay of the body never re-acquires or re-releases. An instance that loses the race parks in `step.waitForEvent` for the turn event and re-acquires when the wait times out — one minute for the first round, doubling to a one-hour ceiling, so waiters recover from a holder cancelled without releasing while a long queue costs tens of steps rather than thousands. A holder the Workflow reports as `complete`, `errored`, `terminated` or no longer knows is treated as gone; a `paused` holder keeps the key.
+
+This package imports only `@porulle/core/jobs` (types and two small helpers), so a Worker bundle does not pull the core server runtime through it. The app's own `commerce.config` still needs whatever compatibility flags it needs.
+
+## Instance status and cancellation
+
+```ts
+await jobs.status(jobId); // { status: "running" | "queued" | "waiting" | "complete" | "errored" | "terminated", error? }
+await jobs.cancel(jobId); // terminates the Workflow instance
+```
+
+`adaptWorkflowBinding` (above) performs the status mapping; a hand-written `WorkflowBinding` must map Cloudflare's richer `InstanceStatus` onto this six-value set itself.
+
+## Node fallback
+
+In local development, or anywhere without the Workers runtime, register the drizzle engine instead — it implements the same `ExecutionEngine` contract (including `status`/`cancel`) against the app's own `commerce_jobs` table and can run tasks in-process:
+
+```ts
+import { DrizzleJobsAdapter } from "@porulle/core";
+
+export const jobs = new DrizzleJobsAdapter(db);
+// config.jobs.autorun.enabled = true polls commerce_jobs in-process.
+```
+
+A handler written against `ctx.step` runs unchanged there — the drizzle engine passes a pass-through `TaskStep` (`do` runs the callback immediately, `sleep` waits in-process).

package/dist/coordinator.d.ts

@@ -0,0 +1,126 @@
+import type { CloudflareConcurrencyCoordinator, CloudflareJobPayload, WorkflowBinding, WorkflowStep } from "./index.js";
+export interface CoordinatorStorage {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+}
+/**
+ * Pure per-key lock state machine behind `PorulleJobCoordinator`, kept free of
+ * any `cloudflare:workers` dependency so it is directly unit-testable in Node
+ * with an in-memory `CoordinatorStorage` and a fake `isStale` check.
+ */
+export declare class JobCoordinatorLogic {
+    private readonly storage;
+    private readonly isStale;
+    constructor(storage: CoordinatorStorage, isStale: (instanceId: string) => Promise<boolean>);
+    /** Registers `instanceId` as pending for `key` before the caller creates it, so
+     * a later supersede can see it even if it has not started running yet. When
+     * `supersedes` is set, the previously pending ids are cleared and returned for
+     * the caller to terminate. Never touches the currently running instance —
+     * matching the drizzle adapter, supersede only drops jobs that have not started. */
+    enqueue(key: string, supersedes: boolean, instanceId: string): Promise<{
+        terminated: string[];
+    }>;
+    acquire(key: string, instanceId: string): Promise<"granted" | "pending">;
+    /** Releases the lock if `instanceId` holds it and hands it to the next
+     * pending instance (if any), returning that instance's id so the caller can
+     * wake it. A release from an instance that does not hold the lock is a no-op. */
+    release(key: string, instanceId: string): Promise<{
+        next: string | null;
+    }>;
+    private getState;
+    private putState;
+    private storageKey;
+}
+/** What the Durable Object needs from the Workflow binding — satisfied by
+ * Cloudflare's raw binding and by an adapted `WorkflowBinding` alike. */
+export interface CoordinatorWorkflowBinding {
+    get(id: string): Promise<{
+        status(): Promise<{
+            status: string;
+        }>;
+        sendEvent(event: {
+            type: string;
+            payload?: unknown;
+        }): Promise<void>;
+    }>;
+}
+export interface PorulleJobCoordinatorEnv {
+    PORULLE_WORKFLOW: CoordinatorWorkflowBinding;
+}
+/** The subset of the real `DurableObjectState` this coordinator touches. */
+export interface DurableObjectStateLike {
+    storage: {
+        get<T>(key: string): Promise<T | undefined>;
+        put<T>(key: string, value: T): Promise<void>;
+    };
+    blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+}
+type DurableObjectConstructor = abstract new (...args: any[]) => object;
+/**
+ * Builds the coordinator Durable Object on the app's own `DurableObject` base
+ * class. `cloudflare:workers` only resolves inside the Workers runtime, so the
+ * Worker imports it and passes it in — this package stays importable under Node:
+ *
+ * ```ts
+ * import { DurableObject } from "cloudflare:workers";
+ * export class PorulleJobCoordinator extends porulleJobCoordinator(DurableObject) {}
+ * ```
+ *
+ * Every RPC runs under `blockConcurrencyWhile`: the stale-holder check is a
+ * Workflow subrequest, which would otherwise open the input gate between the
+ * read and the write and let two acquirers both be granted. On `enqueue` with
+ * `supersedes` the object reports the pending instances the caller must
+ * terminate. It needs a `PORULLE_WORKFLOW` binding on its environment to detect
+ * dead lock holders and to wake the next waiting instance.
+ */
+export declare function porulleJobCoordinator<TBase extends DurableObjectConstructor>(Base: TBase): (abstract new (...args: any[]) => {
+    readonly #logic: JobCoordinatorLogic;
+    readonly #workflow: CoordinatorWorkflowBinding;
+    readonly #state: DurableObjectStateLike;
+    enqueue(key: string, supersedes: boolean, instanceId: string): Promise<{
+        terminated: string[];
+    }>;
+    acquire(key: string, instanceId: string): Promise<"granted" | "pending">;
+    /** Hands the key to the next pending instance that can still be woken; a
+     * pending instance that died or was terminated meanwhile is skipped so the
+     * key never ends up held by an instance that will never release it. */
+    release(key: string, instanceId: string): Promise<void>;
+}) & TBase;
+/** The RPC surface `DurableObjectConcurrencyCoordinator` calls on a
+ * `PorulleJobCoordinator` stub — the subset of `DurableObjectStub<PorulleJobCoordinator>`
+ * this package needs, so callers can inject a fake in tests without the Workers runtime. */
+export interface CoordinatorStub {
+    enqueue(key: string, supersedes: boolean, instanceId: string): Promise<{
+        terminated: string[];
+    }>;
+    acquire(key: string, instanceId: string): Promise<"granted" | "pending">;
+    release(key: string, instanceId: string): Promise<void>;
+}
+export interface DurableObjectConcurrencyCoordinatorOptions {
+    /** Resolves the Durable Object for a coordination key
+     * (`organizationId:taskSlug:concurrencyKey`); return one object per key so
+     * keys never queue behind each other. */
+    stub: (key: string) => CoordinatorStub;
+    workflow: WorkflowBinding;
+}
+/** `CloudflareConcurrencyCoordinator` backed by a `PorulleJobCoordinator` Durable
+ * Object: supersede terminates pending instances at enqueue, and `run` serialises
+ * same-key instances through the DO's `acquire`/`release`, waiting with
+ * `step.waitForEvent` when another instance already holds the key. */
+export declare class DurableObjectConcurrencyCoordinator implements CloudflareConcurrencyCoordinator {
+    private readonly options;
+    constructor(options: DurableObjectConcurrencyCoordinatorOptions);
+    enqueue(payload: CloudflareJobPayload, create: () => Promise<{
+        id: string;
+    }>): Promise<{
+        id: string;
+    }>;
+    /** Every coordinator call is its own Workflow step, so a replay of the body
+     * neither re-acquires nor re-releases. A parked instance wakes on the turn
+     * event or, at the latest, after `turnWaitMs(round)`, and re-acquires — which
+     * is how waiters recover when the holder was terminated without releasing. A
+     * release that fails after its retries is dropped rather than masking the
+     * handler's outcome: the next acquirer sees the finished holder as stale. */
+    run<T>(payload: CloudflareJobPayload, step: WorkflowStep, handler: () => Promise<T>): Promise<T>;
+}
+export {};

package/dist/coordinator.js

@@ -0,0 +1,213 @@
+const STALE_INSTANCE_STATUSES = new Set(["complete", "errored", "terminated"]);
+const TURN_EVENT_TYPE = "porulle-turn";
+const FIRST_TURN_WAIT_MS = 60_000;
+const MAX_TURN_WAIT_MS = 3_600_000;
+const COORDINATOR_STEP = {
+    retries: { limit: 3, delay: 1_000, backoff: "exponential" },
+};
+/** Each wait round costs two Workflow steps against the instance's step budget,
+ * so the timeout doubles per round from one minute up to one hour: a waiter
+ * still recovers from a holder that died without releasing, and a day-long
+ * queue costs tens of steps rather than thousands. */
+function turnWaitMs(round) {
+    return Math.min(FIRST_TURN_WAIT_MS * 2 ** round, MAX_TURN_WAIT_MS);
+}
+function coordinatorKey(payload) {
+    return `${payload.organizationId}:${payload.taskSlug}:${payload.concurrencyKey}`;
+}
+/**
+ * Pure per-key lock state machine behind `PorulleJobCoordinator`, kept free of
+ * any `cloudflare:workers` dependency so it is directly unit-testable in Node
+ * with an in-memory `CoordinatorStorage` and a fake `isStale` check.
+ */
+export class JobCoordinatorLogic {
+    storage;
+    isStale;
+    constructor(storage, isStale) {
+        this.storage = storage;
+        this.isStale = isStale;
+    }
+    /** Registers `instanceId` as pending for `key` before the caller creates it, so
+     * a later supersede can see it even if it has not started running yet. When
+     * `supersedes` is set, the previously pending ids are cleared and returned for
+     * the caller to terminate. Never touches the currently running instance —
+     * matching the drizzle adapter, supersede only drops jobs that have not started. */
+    async enqueue(key, supersedes, instanceId) {
+        const state = await this.getState(key);
+        const terminated = supersedes ? state.pending.filter((id) => id !== instanceId) : [];
+        const kept = supersedes ? [] : state.pending.filter((id) => id !== instanceId);
+        await this.putState(key, { ...state, pending: [...kept, instanceId] });
+        return { terminated };
+    }
+    async acquire(key, instanceId) {
+        let state = await this.getState(key);
+        if (state.running === instanceId)
+            return "granted";
+        if (state.running !== null && (await this.isStale(state.running))) {
+            state = { ...state, running: null };
+        }
+        if (state.running === null) {
+            await this.putState(key, {
+                pending: state.pending.filter((id) => id !== instanceId),
+                running: instanceId,
+            });
+            return "granted";
+        }
+        if (!state.pending.includes(instanceId)) {
+            await this.putState(key, {
+                ...state,
+                pending: [...state.pending, instanceId],
+            });
+        }
+        return "pending";
+    }
+    /** Releases the lock if `instanceId` holds it and hands it to the next
+     * pending instance (if any), returning that instance's id so the caller can
+     * wake it. A release from an instance that does not hold the lock is a no-op. */
+    async release(key, instanceId) {
+        const state = await this.getState(key);
+        if (state.running !== instanceId)
+            return { next: null };
+        const [next, ...rest] = state.pending;
+        await this.putState(key, { pending: rest, running: next ?? null });
+        return { next: next ?? null };
+    }
+    async getState(key) {
+        const existing = await this.storage.get(this.storageKey(key));
+        return existing ?? { pending: [], running: null };
+    }
+    async putState(key, state) {
+        await this.storage.put(this.storageKey(key), state);
+    }
+    storageKey(key) {
+        return `porulle-job-coordinator:${key}`;
+    }
+}
+/**
+ * Builds the coordinator Durable Object on the app's own `DurableObject` base
+ * class. `cloudflare:workers` only resolves inside the Workers runtime, so the
+ * Worker imports it and passes it in — this package stays importable under Node:
+ *
+ * ```ts
+ * import { DurableObject } from "cloudflare:workers";
+ * export class PorulleJobCoordinator extends porulleJobCoordinator(DurableObject) {}
+ * ```
+ *
+ * Every RPC runs under `blockConcurrencyWhile`: the stale-holder check is a
+ * Workflow subrequest, which would otherwise open the input gate between the
+ * read and the write and let two acquirers both be granted. On `enqueue` with
+ * `supersedes` the object reports the pending instances the caller must
+ * terminate. It needs a `PORULLE_WORKFLOW` binding on its environment to detect
+ * dead lock holders and to wake the next waiting instance.
+ */
+export function porulleJobCoordinator(Base) {
+    class PorulleJobCoordinator extends Base {
+        #logic;
+        #workflow;
+        #state;
+        constructor(...args) {
+            super(...args);
+            const [ctx, env] = args;
+            this.#state = ctx;
+            this.#workflow = env.PORULLE_WORKFLOW;
+            this.#logic = new JobCoordinatorLogic({
+                get(key) {
+                    return ctx.storage.get(key);
+                },
+                put(key, value) {
+                    return ctx.storage.put(key, value);
+                },
+            }, async (instanceId) => {
+                try {
+                    const handle = await env.PORULLE_WORKFLOW.get(instanceId);
+                    const { status } = await handle.status();
+                    return STALE_INSTANCE_STATUSES.has(status);
+                }
+                catch {
+                    return true;
+                }
+            });
+        }
+        enqueue(key, supersedes, instanceId) {
+            return this.#state.blockConcurrencyWhile(() => this.#logic.enqueue(key, supersedes, instanceId));
+        }
+        acquire(key, instanceId) {
+            return this.#state.blockConcurrencyWhile(() => this.#logic.acquire(key, instanceId));
+        }
+        /** Hands the key to the next pending instance that can still be woken; a
+         * pending instance that died or was terminated meanwhile is skipped so the
+         * key never ends up held by an instance that will never release it. */
+        release(key, instanceId) {
+            return this.#state.blockConcurrencyWhile(async () => {
+                let holder = instanceId;
+                for (;;) {
+                    const { next } = await this.#logic.release(key, holder);
+                    if (!next)
+                        return;
+                    const woken = await this.#workflow
+                        .get(next)
+                        .then((handle) => handle.sendEvent({ type: TURN_EVENT_TYPE }))
+                        .then(() => true, () => false);
+                    if (woken)
+                        return;
+                    holder = next;
+                }
+            });
+        }
+    }
+    return PorulleJobCoordinator;
+}
+/** `CloudflareConcurrencyCoordinator` backed by a `PorulleJobCoordinator` Durable
+ * Object: supersede terminates pending instances at enqueue, and `run` serialises
+ * same-key instances through the DO's `acquire`/`release`, waiting with
+ * `step.waitForEvent` when another instance already holds the key. */
+export class DurableObjectConcurrencyCoordinator {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async enqueue(payload, create) {
+        if (!payload.concurrencyKey)
+            return create();
+        const key = coordinatorKey(payload);
+        const { terminated } = await this.options
+            .stub(key)
+            .enqueue(key, payload.supersedes, payload.jobId);
+        await Promise.all(terminated.map((id) => this.options.workflow
+            .get(id)
+            .then((handle) => handle.terminate())
+            .catch(() => undefined)));
+        return create();
+    }
+    /** Every coordinator call is its own Workflow step, so a replay of the body
+     * neither re-acquires nor re-releases. A parked instance wakes on the turn
+     * event or, at the latest, after `turnWaitMs(round)`, and re-acquires — which
+     * is how waiters recover when the holder was terminated without releasing. A
+     * release that fails after its retries is dropped rather than masking the
+     * handler's outcome: the next acquirer sees the finished holder as stale. */
+    async run(payload, step, handler) {
+        if (!payload.concurrencyKey)
+            return handler();
+        const key = coordinatorKey(payload);
+        const stub = this.options.stub(key);
+        for (let round = 0;; round += 1) {
+            const turn = await step.do(`porulle-turn:acquire:${round}`, COORDINATOR_STEP, () => stub.acquire(key, payload.jobId));
+            if (turn === "granted")
+                break;
+            await step
+                .waitForEvent(`porulle-turn:wait:${round}`, {
+                type: TURN_EVENT_TYPE,
+                timeout: turnWaitMs(round),
+            })
+                .catch(() => undefined);
+        }
+        try {
+            return await handler();
+        }
+        finally {
+            await step
+                .do("porulle-turn:release", COORDINATOR_STEP, () => stub.release(key, payload.jobId))
+                .catch(() => undefined);
+        }
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import type { EnqueueOptions, ExecutionEngine, ExecutionEngineSetup } from "@porulle/core";
+import type { EnqueueOptions, ExecutionEngine, ExecutionEngineSetup, JobInstanceStatus } from "@porulle/core/jobs";
 export interface CloudflareJobPayload {
+    /** This Workflow instance's own id — the value passed as `create({ id })`. */
+    jobId: string;
     taskSlug: string;
     input: Record<string, unknown>;
     organizationId: string;
@@ -9,6 +11,35 @@ export interface CloudflareJobPayload {
     exclusive: boolean;
     supersedes: boolean;
 }
+export interface WorkflowStepRetries {
+    limit: number;
+    delay: number;
+    backoff: "constant" | "exponential";
+}
+export interface WorkflowStep {
+    sleep(name: string, duration: number | string): Promise<void>;
+    do<T>(name: string, config: {
+        retries: WorkflowStepRetries;
+        timeout?: number | string;
+    }, callback: (context: {
+        attempt: number;
+    }) => Promise<T>): Promise<T>;
+    waitForEvent(name: string, options: {
+        type: string;
+        timeout?: number | string;
+    }): Promise<unknown>;
+}
+export interface WorkflowInstanceHandle {
+    status(): Promise<{
+        status: JobInstanceStatus;
+        error?: string;
+    }>;
+    terminate(): Promise<void>;
+    sendEvent(event: {
+        type: string;
+        payload?: unknown;
+    }): Promise<void>;
+}
 export interface WorkflowBinding {
     create(options: {
         id?: string;
@@ -16,29 +47,50 @@ export interface WorkflowBinding {
     }): Promise<{
         id: string;
     }>;
+    get(id: string): Promise<WorkflowInstanceHandle>;
 }
-export interface WorkflowStep {
-    sleep(name: string, duration: number | string): Promise<void>;
-    do<T>(name: string, config: {
-        retries: {
-            limit: number;
-            delay: number;
-            backoff: "constant" | "exponential";
-        };
-    }, callback: (context: {
-        attempt: number;
-    }) => Promise<T>): Promise<T>;
+/** The shape of Cloudflare's own `Workflow` binding this package needs. */
+export interface RawWorkflowBinding {
+    create(options: {
+        id?: string;
+        params: CloudflareJobPayload;
+    }): Promise<{
+        id: string;
+    }>;
+    get(id: string): Promise<{
+        status(): Promise<{
+            status: string;
+            error?: {
+                name: string;
+                message: string;
+            };
+        }>;
+        terminate(): Promise<void>;
+        sendEvent(event: {
+            type: string;
+            payload?: unknown;
+        }): Promise<void>;
+    }>;
 }
+/** Wraps the real Workflows binding: Cloudflare's richer instance status folds
+ * into `JobInstanceStatus` (`paused`/`waitingForPause` → `waiting`, anything
+ * unknown → `errored`) and the error becomes its message. */
+export declare function adaptWorkflowBinding(binding: RawWorkflowBinding): WorkflowBinding;
 export interface CloudflareConcurrencyCoordinator {
     enqueue(payload: CloudflareJobPayload, create: () => Promise<{
         id: string;
     }>): Promise<{
         id: string;
     }>;
-    run<T>(key: string, handler: () => Promise<T>): Promise<T>;
+    run<T>(payload: CloudflareJobPayload, step: WorkflowStep, handler: () => Promise<T>): Promise<T>;
 }
+export type NonRetryableErrorConstructor = new (message: string) => Error;
 export interface CloudflareExecutionEngineOptions {
     workflow: WorkflowBinding;
+    /** `NonRetryableError` from `cloudflare:workflows`. Workflows stops retrying a
+     * step only for that exact class, and this package cannot import the module
+     * outside the Workers runtime, so the Worker passes it in. */
+    nonRetryableError: NonRetryableErrorConstructor;
     coordinator?: CloudflareConcurrencyCoordinator;
 }
 export declare class CloudflareExecutionEngine implements ExecutionEngine {
@@ -51,5 +103,12 @@ export declare class CloudflareExecutionEngine implements ExecutionEngine {
     register(setup: ExecutionEngineSetup): void;
     enqueue(taskSlug: string, input: Record<string, unknown>, options: EnqueueOptions): Promise<string>;
     run(payload: CloudflareJobPayload, step: WorkflowStep): Promise<Record<string, unknown>>;
+    status(jobId: string): Promise<{
+        status: JobInstanceStatus;
+        error?: string;
+    }>;
+    cancel(jobId: string): Promise<void>;
     private requireSetup;
 }
+export { DurableObjectConcurrencyCoordinator, JobCoordinatorLogic, porulleJobCoordinator, } from "./coordinator.js";
+export type { CoordinatorStorage, CoordinatorStub, CoordinatorWorkflowBinding, DurableObjectConcurrencyCoordinatorOptions, DurableObjectStateLike, PorulleJobCoordinatorEnv, } from "./coordinator.js";