@porulle/jobs-cloudflare 0.30.0 → 0.31.0

package/dist/coordinator.d.ts

@@ -10,17 +10,28 @@ export interface CoordinatorStorage {
  */
 export declare class JobCoordinatorLogic {
     private readonly storage;
-    private readonly isStale;
-    constructor(storage: CoordinatorStorage, isStale: (instanceId: string) => Promise<boolean>);
+    constructor(storage: CoordinatorStorage);
     /** 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<{
+    enqueue(key: string, supersedes: boolean, instanceId: string, inputHash?: string): Promise<{
         terminated: string[];
+        coalescedInto?: string;
     }>;
-    acquire(key: string, instanceId: string): Promise<"granted" | "pending">;
+    /** First gate phase: storage only. Returns `needsStaleCheck` when another instance
+     * holds the key so the Durable Object can ask the Workflow binding outside the gate. */
+    acquireRead(key: string, instanceId: string): Promise<"granted" | {
+        needsStaleCheck: string;
+    }>;
+    /** Re-enter after a live holder was confirmed outside the gate. */
+    acquireWhenHolderLive(key: string, instanceId: string): Promise<"granted" | "pending">;
+    /** Re-enter after the holder was stale outside the gate — only grants when the
+     * same id still holds the key, so a concurrent acquirer cannot be raced. */
+    acquireAfterStale(key: string, instanceId: string, checkedHolderId: string): Promise<"granted" | "pending">;
+    private grantKey;
+    private enqueuePending;
     /** 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. */
@@ -66,32 +77,36 @@ type DurableObjectConstructor = abstract new (...args: any[]) => object;
  * 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.
+ * State mutations run under `blockConcurrencyWhile`; Workflow binding calls
+ * (stale-holder checks and turn events) run outside it so a long release loop
+ * cannot block every other RPC on the object. 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<{
+    #isStale(instanceId: string): Promise<boolean>;
+    enqueue(key: string, supersedes: boolean, instanceId: string, inputHash?: string): Promise<{
         terminated: string[];
+        coalescedInto?: 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>;
+    #releaseAndWake(key: string, holder: 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<{
+    enqueue(key: string, supersedes: boolean, instanceId: string, inputHash?: string): Promise<{
         terminated: string[];
+        coalescedInto?: string;
     }>;
     acquire(key: string, instanceId: string): Promise<"granted" | "pending">;
     release(key: string, instanceId: string): Promise<void>;

package/dist/coordinator.js

@@ -1,3 +1,4 @@
+import { hashJobInput } from "./index.js";
 const STALE_INSTANCE_STATUSES = new Set(["complete", "errored", "terminated"]);
 const TURN_EVENT_TYPE = "porulle-turn";
 const FIRST_TURN_WAIT_MS = 60_000;
@@ -22,37 +23,82 @@ function coordinatorKey(payload) {
  */
 export class JobCoordinatorLogic {
     storage;
-    isStale;
-    constructor(storage, isStale) {
+    constructor(storage) {
         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) {
+    async enqueue(key, supersedes, instanceId, inputHash) {
         const state = await this.getState(key);
+        if (supersedes && inputHash !== undefined) {
+            for (const pendingId of state.pending) {
+                if (state.pendingHashes[pendingId] === inputHash) {
+                    return { terminated: [], coalescedInto: pendingId };
+                }
+            }
+        }
         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] });
+        const pendingHashes = { ...state.pendingHashes };
+        for (const id of terminated)
+            delete pendingHashes[id];
+        if (inputHash !== undefined)
+            pendingHashes[instanceId] = inputHash;
+        await this.putState(key, {
+            ...state,
+            pending: [...kept, instanceId],
+            pendingHashes,
+        });
         return { terminated };
     }
-    async acquire(key, instanceId) {
-        let state = await this.getState(key);
+    /** First gate phase: storage only. Returns `needsStaleCheck` when another instance
+     * holds the key so the Durable Object can ask the Workflow binding outside the gate. */
+    async acquireRead(key, instanceId) {
+        const 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.grantKey(key, instanceId, state);
+            return "granted";
         }
+        return { needsStaleCheck: state.running };
+    }
+    /** Re-enter after a live holder was confirmed outside the gate. */
+    async acquireWhenHolderLive(key, instanceId) {
+        const state = await this.getState(key);
+        if (state.running === instanceId)
+            return "granted";
         if (state.running === null) {
-            await this.putState(key, {
-                pending: state.pending.filter((id) => id !== instanceId),
-                running: instanceId,
-            });
+            await this.grantKey(key, instanceId, state);
             return "granted";
         }
+        return this.enqueuePending(key, instanceId, state);
+    }
+    /** Re-enter after the holder was stale outside the gate — only grants when the
+     * same id still holds the key, so a concurrent acquirer cannot be raced. */
+    async acquireAfterStale(key, instanceId, checkedHolderId) {
+        const state = await this.getState(key);
+        if (state.running === instanceId)
+            return "granted";
+        if (state.running === checkedHolderId) {
+            await this.grantKey(key, instanceId, state);
+            return "granted";
+        }
+        return this.acquireWhenHolderLive(key, instanceId);
+    }
+    async grantKey(key, instanceId, state) {
+        const pendingHashes = { ...state.pendingHashes };
+        delete pendingHashes[instanceId];
+        await this.putState(key, {
+            pending: state.pending.filter((id) => id !== instanceId),
+            running: instanceId,
+            pendingHashes,
+        });
+    }
+    async enqueuePending(key, instanceId, state) {
         if (!state.pending.includes(instanceId)) {
             await this.putState(key, {
                 ...state,
@@ -69,12 +115,21 @@ export class JobCoordinatorLogic {
         if (state.running !== instanceId)
             return { next: null };
         const [next, ...rest] = state.pending;
-        await this.putState(key, { pending: rest, running: next ?? null });
+        const pendingHashes = { ...state.pendingHashes };
+        if (next)
+            delete pendingHashes[next];
+        await this.putState(key, { pending: rest, running: next ?? null, pendingHashes });
         return { next: next ?? null };
     }
     async getState(key) {
         const existing = await this.storage.get(this.storageKey(key));
-        return existing ?? { pending: [], running: null };
+        if (!existing)
+            return { pending: [], running: null, pendingHashes: {} };
+        // `pendingHashes` arrived after this object was already storing state in production, so a row
+        // written by an earlier release has no such key. Backfilling on READ rather than migrating
+        // keeps a coordinator from crashing on its own history — and a crash here takes every job on
+        // that key with it.
+        return { ...existing, pendingHashes: existing.pendingHashes ?? {} };
     }
     async putState(key, state) {
         await this.storage.put(this.storageKey(key), state);
@@ -93,12 +148,12 @@ export class JobCoordinatorLogic {
  * 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.
+ * State mutations run under `blockConcurrencyWhile`; Workflow binding calls
+ * (stale-holder checks and turn events) run outside it so a long release loop
+ * cannot block every other RPC on the object. 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 {
@@ -117,42 +172,47 @@ export function porulleJobCoordinator(Base) {
                 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));
+        async #isStale(instanceId) {
+            try {
+                const handle = await this.#workflow.get(instanceId);
+                const { status } = await handle.status();
+                return STALE_INSTANCE_STATUSES.has(status);
+            }
+            catch {
+                return true;
+            }
+        }
+        enqueue(key, supersedes, instanceId, inputHash) {
+            return this.#state.blockConcurrencyWhile(() => this.#logic.enqueue(key, supersedes, instanceId, inputHash));
         }
-        acquire(key, instanceId) {
-            return this.#state.blockConcurrencyWhile(() => this.#logic.acquire(key, instanceId));
+        async acquire(key, instanceId) {
+            const first = await this.#state.blockConcurrencyWhile(() => this.#logic.acquireRead(key, instanceId));
+            if (first === "granted")
+                return "granted";
+            const stale = await this.#isStale(first.needsStaleCheck);
+            return this.#state.blockConcurrencyWhile(() => stale
+                ? this.#logic.acquireAfterStale(key, instanceId, first.needsStaleCheck)
+                : this.#logic.acquireWhenHolderLive(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 this.#releaseAndWake(key, instanceId);
+        }
+        async #releaseAndWake(key, holder) {
+            const { next } = await this.#state.blockConcurrencyWhile(() => 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;
+            return this.#releaseAndWake(key, next);
         }
     }
     return PorulleJobCoordinator;
@@ -170,9 +230,12 @@ export class DurableObjectConcurrencyCoordinator {
         if (!payload.concurrencyKey)
             return create();
         const key = coordinatorKey(payload);
-        const { terminated } = await this.options
+        const inputHash = hashJobInput(payload.input);
+        const { terminated, coalescedInto } = await this.options
             .stub(key)
-            .enqueue(key, payload.supersedes, payload.jobId);
+            .enqueue(key, payload.supersedes, payload.jobId, inputHash);
+        if (coalescedInto)
+            return { id: coalescedInto };
         await Promise.all(terminated.map((id) => this.options.workflow
             .get(id)
             .then((handle) => handle.terminate())

package/dist/index.d.ts

@@ -72,6 +72,8 @@ export interface RawWorkflowBinding {
         }): Promise<void>;
     }>;
 }
+/** Short, dependency-free hash of task input for coordinator coalescing. */
+export declare function hashJobInput(input: Record<string, unknown>): string;
 /** 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. */
@@ -101,6 +103,12 @@ export declare class CloudflareExecutionEngine implements ExecutionEngine {
     private setup;
     constructor(options: CloudflareExecutionEngineOptions);
     register(setup: ExecutionEngineSetup): void;
+    /** Enqueues a Workflow instance for `taskSlug`.
+     *
+     * When a superseding enqueue coalesces into an existing pending instance with identical input,
+     * instance creation is skipped. That loses nothing: a job derives its work from state read when
+     * it **starts**; the enqueue payload is identity, not data. A pending instance created before a
+     * later write will still observe that write when it runs. */
     enqueue(taskSlug: string, input: Record<string, unknown>, options: EnqueueOptions): Promise<string>;
     run(payload: CloudflareJobPayload, step: WorkflowStep): Promise<Record<string, unknown>>;
     status(jobId: string): Promise<{

package/dist/index.js

@@ -1,4 +1,23 @@
 import { TaskNonRetryableError, createPassThroughTaskStep, } from "@porulle/core/jobs";
+/** Deterministic JSON with sorted object keys — key order must not change the hash. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(",")}}`;
+}
+/** Short, dependency-free hash of task input for coordinator coalescing. */
+export function hashJobInput(input) {
+    const serialized = stableStringify(input);
+    let hash = 5381;
+    for (let index = 0; index < serialized.length; index += 1) {
+        hash = ((hash << 5) + hash) ^ serialized.charCodeAt(index);
+    }
+    return (hash >>> 0).toString(36);
+}
 const INSTANCE_STATUS_MAP = {
     queued: "queued",
     running: "running",
@@ -88,6 +107,12 @@ export class CloudflareExecutionEngine {
     register(setup) {
         this.setup = setup;
     }
+    /** Enqueues a Workflow instance for `taskSlug`.
+     *
+     * When a superseding enqueue coalesces into an existing pending instance with identical input,
+     * instance creation is skipped. That loses nothing: a job derives its work from state read when
+     * it **starts**; the enqueue payload is identity, not data. A pending instance created before a
+     * later write will still observe that write when it runs. */
     async enqueue(taskSlug, input, options) {
         const task = this.requireSetup().tasks.get(taskSlug);
         if (!task)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/jobs-cloudflare",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@porulle/core": "0.30.0"
+    "@porulle/core": "0.31.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/coordinator.ts

@@ -4,6 +4,7 @@ import type {
   WorkflowBinding,
   WorkflowStep,
 } from "./index.js";
+import { hashJobInput } from "./index.js";
 
 const STALE_INSTANCE_STATUSES = new Set(["complete", "errored", "terminated"]);
 const TURN_EVENT_TYPE = "porulle-turn";
@@ -33,6 +34,8 @@ export interface CoordinatorStorage {
 interface CoordinatorKeyState {
   pending: string[];
   running: string | null;
+  /** Hash of `payload.input` for each pending instance — pruned whenever the id leaves `pending`. */
+  pendingHashes: Record<string, string>;
 }
 
 /**
@@ -41,10 +44,7 @@ interface CoordinatorKeyState {
  * with an in-memory `CoordinatorStorage` and a fake `isStale` check.
  */
 export class JobCoordinatorLogic {
-  constructor(
-    private readonly storage: CoordinatorStorage,
-    private readonly isStale: (instanceId: string) => Promise<boolean>,
-  ) {}
+  constructor(private readonly storage: CoordinatorStorage) {}
 
   /** 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
@@ -55,27 +55,93 @@ export class JobCoordinatorLogic {
     key: string,
     supersedes: boolean,
     instanceId: string,
-  ): Promise<{ terminated: string[] }> {
+    inputHash?: string,
+  ): Promise<{ terminated: string[]; coalescedInto?: string }> {
     const state = await this.getState(key);
+    if (supersedes && inputHash !== undefined) {
+      for (const pendingId of state.pending) {
+        if (state.pendingHashes[pendingId] === inputHash) {
+          return { terminated: [], coalescedInto: pendingId };
+        }
+      }
+    }
     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] });
+    const pendingHashes = { ...state.pendingHashes };
+    for (const id of terminated) delete pendingHashes[id];
+    if (inputHash !== undefined) pendingHashes[instanceId] = inputHash;
+    await this.putState(key, {
+      ...state,
+      pending: [...kept, instanceId],
+      pendingHashes,
+    });
     return { terminated };
   }
 
-  async acquire(key: string, instanceId: string): Promise<"granted" | "pending"> {
-    let state = await this.getState(key);
+  /** First gate phase: storage only. Returns `needsStaleCheck` when another instance
+   * holds the key so the Durable Object can ask the Workflow binding outside the gate. */
+  async acquireRead(
+    key: string,
+    instanceId: string,
+  ): Promise<"granted" | { needsStaleCheck: string }> {
+    const 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.grantKey(key, instanceId, state);
+      return "granted";
     }
+    return { needsStaleCheck: state.running };
+  }
+
+  /** Re-enter after a live holder was confirmed outside the gate. */
+  async acquireWhenHolderLive(
+    key: string,
+    instanceId: string,
+  ): Promise<"granted" | "pending"> {
+    const state = await this.getState(key);
+    if (state.running === instanceId) return "granted";
     if (state.running === null) {
-      await this.putState(key, {
-        pending: state.pending.filter((id) => id !== instanceId),
-        running: instanceId,
-      });
+      await this.grantKey(key, instanceId, state);
       return "granted";
     }
+    return this.enqueuePending(key, instanceId, state);
+  }
+
+  /** Re-enter after the holder was stale outside the gate — only grants when the
+   * same id still holds the key, so a concurrent acquirer cannot be raced. */
+  async acquireAfterStale(
+    key: string,
+    instanceId: string,
+    checkedHolderId: string,
+  ): Promise<"granted" | "pending"> {
+    const state = await this.getState(key);
+    if (state.running === instanceId) return "granted";
+    if (state.running === checkedHolderId) {
+      await this.grantKey(key, instanceId, state);
+      return "granted";
+    }
+    return this.acquireWhenHolderLive(key, instanceId);
+  }
+
+  private async grantKey(
+    key: string,
+    instanceId: string,
+    state: CoordinatorKeyState,
+  ): Promise<void> {
+    const pendingHashes = { ...state.pendingHashes };
+    delete pendingHashes[instanceId];
+    await this.putState(key, {
+      pending: state.pending.filter((id) => id !== instanceId),
+      running: instanceId,
+      pendingHashes,
+    });
+  }
+
+  private async enqueuePending(
+    key: string,
+    instanceId: string,
+    state: CoordinatorKeyState,
+  ): Promise<"pending"> {
     if (!state.pending.includes(instanceId)) {
       await this.putState(key, {
         ...state,
@@ -92,13 +158,20 @@ export class JobCoordinatorLogic {
     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 });
+    const pendingHashes = { ...state.pendingHashes };
+    if (next) delete pendingHashes[next];
+    await this.putState(key, { pending: rest, running: next ?? null, pendingHashes });
     return { next: next ?? null };
   }
 
   private async getState(key: string): Promise<CoordinatorKeyState> {
     const existing = await this.storage.get<CoordinatorKeyState>(this.storageKey(key));
-    return existing ?? { pending: [], running: null };
+    if (!existing) return { pending: [], running: null, pendingHashes: {} };
+    // `pendingHashes` arrived after this object was already storing state in production, so a row
+    // written by an earlier release has no such key. Backfilling on READ rather than migrating
+    // keeps a coordinator from crashing on its own history — and a crash here takes every job on
+    // that key with it.
+    return { ...existing, pendingHashes: existing.pendingHashes ?? {} };
   }
 
   private async putState(key: string, state: CoordinatorKeyState): Promise<void> {
@@ -144,12 +217,12 @@ type DurableObjectConstructor = abstract new (...args: any[]) => object;
  * 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.
+ * State mutations run under `blockConcurrencyWhile`; Workflow binding calls
+ * (stale-holder checks and turn events) run outside it so a long release loop
+ * cannot block every other RPC on the object. 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<TBase extends DurableObjectConstructor>(
   Base: TBase,
@@ -164,40 +237,47 @@ export function porulleJobCoordinator<TBase extends DurableObjectConstructor>(
       const [ctx, env] = args as [DurableObjectStateLike, PorulleJobCoordinatorEnv];
       this.#state = ctx;
       this.#workflow = env.PORULLE_WORKFLOW;
-      this.#logic = new JobCoordinatorLogic(
-        {
-          get<T>(key: string) {
-            return ctx.storage.get<T>(key);
-          },
-          put<T>(key: string, value: T) {
-            return ctx.storage.put(key, value);
-          },
+      this.#logic = new JobCoordinatorLogic({
+        get<T>(key: string) {
+          return ctx.storage.get<T>(key);
         },
-        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;
-          }
+        put<T>(key: string, value: T) {
+          return ctx.storage.put(key, value);
         },
-      );
+      });
+    }
+
+    async #isStale(instanceId: string): Promise<boolean> {
+      try {
+        const handle = await this.#workflow.get(instanceId);
+        const { status } = await handle.status();
+        return STALE_INSTANCE_STATUSES.has(status);
+      } catch {
+        return true;
+      }
     }
 
     enqueue(
       key: string,
       supersedes: boolean,
       instanceId: string,
-    ): Promise<{ terminated: string[] }> {
+      inputHash?: string,
+    ): Promise<{ terminated: string[]; coalescedInto?: string }> {
       return this.#state.blockConcurrencyWhile(() =>
-        this.#logic.enqueue(key, supersedes, instanceId),
+        this.#logic.enqueue(key, supersedes, instanceId, inputHash),
       );
     }
 
-    acquire(key: string, instanceId: string): Promise<"granted" | "pending"> {
+    async acquire(key: string, instanceId: string): Promise<"granted" | "pending"> {
+      const first = await this.#state.blockConcurrencyWhile(() =>
+        this.#logic.acquireRead(key, instanceId),
+      );
+      if (first === "granted") return "granted";
+      const stale = await this.#isStale(first.needsStaleCheck);
       return this.#state.blockConcurrencyWhile(() =>
-        this.#logic.acquire(key, instanceId),
+        stale
+          ? this.#logic.acquireAfterStale(key, instanceId, first.needsStaleCheck)
+          : this.#logic.acquireWhenHolderLive(key, instanceId),
       );
     }
 
@@ -205,19 +285,20 @@ export function porulleJobCoordinator<TBase extends DurableObjectConstructor>(
      * 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> {
-      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 this.#releaseAndWake(key, instanceId);
+    }
+
+    async #releaseAndWake(key: string, holder: string): Promise<void> {
+      const { next } = await this.#state.blockConcurrencyWhile(() =>
+        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;
+      return this.#releaseAndWake(key, next);
     }
   }
   return PorulleJobCoordinator;
@@ -231,7 +312,8 @@ export interface CoordinatorStub {
     key: string,
     supersedes: boolean,
     instanceId: string,
-  ): Promise<{ terminated: string[] }>;
+    inputHash?: string,
+  ): Promise<{ terminated: string[]; coalescedInto?: string }>;
   acquire(key: string, instanceId: string): Promise<"granted" | "pending">;
   release(key: string, instanceId: string): Promise<void>;
 }
@@ -259,9 +341,11 @@ export class DurableObjectConcurrencyCoordinator
   ): Promise<{ id: string }> {
     if (!payload.concurrencyKey) return create();
     const key = coordinatorKey(payload);
-    const { terminated } = await this.options
+    const inputHash = hashJobInput(payload.input);
+    const { terminated, coalescedInto } = await this.options
       .stub(key)
-      .enqueue(key, payload.supersedes, payload.jobId);
+      .enqueue(key, payload.supersedes, payload.jobId, inputHash);
+    if (coalescedInto) return { id: coalescedInto };
     await Promise.all(
       terminated.map((id) =>
         this.options.workflow

package/src/index.ts

@@ -67,6 +67,25 @@ export interface RawWorkflowBinding {
   }>;
 }
 
+/** Deterministic JSON with sorted object keys — key order must not change the hash. */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(",")}}`;
+}
+
+/** Short, dependency-free hash of task input for coordinator coalescing. */
+export function hashJobInput(input: Record<string, unknown>): string {
+  const serialized = stableStringify(input);
+  let hash = 5381;
+  for (let index = 0; index < serialized.length; index += 1) {
+    hash = ((hash << 5) + hash) ^ serialized.charCodeAt(index);
+  }
+  return (hash >>> 0).toString(36);
+}
+
 const INSTANCE_STATUS_MAP: Record<string, JobInstanceStatus> = {
   queued: "queued",
   running: "running",
@@ -200,6 +219,12 @@ export class CloudflareExecutionEngine implements ExecutionEngine {
     this.setup = setup;
   }
 
+  /** Enqueues a Workflow instance for `taskSlug`.
+   *
+   * When a superseding enqueue coalesces into an existing pending instance with identical input,
+   * instance creation is skipped. That loses nothing: a job derives its work from state read when
+   * it **starts**; the enqueue payload is identity, not data. A pending instance created before a
+   * later write will still observe that write when it runs. */
   async enqueue(
     taskSlug: string,
     input: Record<string, unknown>,