@porulle/jobs-cloudflare 0.31.0 → 0.32.0

package/dist/coordinator.d.ts

@@ -11,15 +11,31 @@ export interface CoordinatorStorage {
 export declare class JobCoordinatorLogic {
     private readonly storage;
     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, inputHash?: string): Promise<{
+    /** First enqueue phase: storage only. 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;
+     * under `supersedes` 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. When a pending instance carries the same input its id
+     * comes back as a CANDIDATE rather than a decision, so the Durable Object can check outside
+     * the gate whether that instance still exists. */
+    enqueueRead(key: string, supersedes: boolean, instanceId: string, inputHash?: string): Promise<{
+        terminated: string[];
+    } | {
+        coalesceCandidate: string;
+    }>;
+    /** Re-enter after the candidate was confirmed LIVE outside the gate. Coalesces only if the
+     * candidate is STILL pending under the same hash — if it started running meanwhile it has
+     * already read its input and the caller needs its own instance. */
+    enqueueAfterLiveCandidate(key: string, candidate: string, supersedes: boolean, instanceId: string, inputHash?: string): Promise<{
         terminated: string[];
         coalescedInto?: string;
     }>;
+    /** Re-enter after the candidate was found STALE outside the gate: enqueue normally, which
+     * under `supersedes` drops every pending id including the dead candidate. */
+    enqueueAfterStaleCandidate(key: string, supersedes: boolean, instanceId: string, inputHash?: string): Promise<{
+        terminated: string[];
+    }>;
+    private commitEnqueue;
     /** 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" | {

package/dist/coordinator.js

@@ -26,20 +26,44 @@ export class JobCoordinatorLogic {
     constructor(storage) {
         this.storage = storage;
     }
-    /** 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, inputHash) {
+    /** First enqueue phase: storage only. 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;
+     * under `supersedes` 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. When a pending instance carries the same input its id
+     * comes back as a CANDIDATE rather than a decision, so the Durable Object can check outside
+     * the gate whether that instance still exists. */
+    async enqueueRead(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 };
+                    return { coalesceCandidate: pendingId };
                 }
             }
         }
+        return this.commitEnqueue(key, supersedes, instanceId, inputHash, state);
+    }
+    /** Re-enter after the candidate was confirmed LIVE outside the gate. Coalesces only if the
+     * candidate is STILL pending under the same hash — if it started running meanwhile it has
+     * already read its input and the caller needs its own instance. */
+    async enqueueAfterLiveCandidate(key, candidate, supersedes, instanceId, inputHash) {
+        const state = await this.getState(key);
+        if (supersedes &&
+            inputHash !== undefined &&
+            state.pending.includes(candidate) &&
+            state.pendingHashes[candidate] === inputHash) {
+            return { terminated: [], coalescedInto: candidate };
+        }
+        return this.commitEnqueue(key, supersedes, instanceId, inputHash, state);
+    }
+    /** Re-enter after the candidate was found STALE outside the gate: enqueue normally, which
+     * under `supersedes` drops every pending id including the dead candidate. */
+    async enqueueAfterStaleCandidate(key, supersedes, instanceId, inputHash) {
+        const state = await this.getState(key);
+        return this.commitEnqueue(key, supersedes, instanceId, inputHash, state);
+    }
+    async commitEnqueue(key, supersedes, instanceId, inputHash, state) {
         const terminated = supersedes ? state.pending.filter((id) => id !== instanceId) : [];
         const kept = supersedes ? [] : state.pending.filter((id) => id !== instanceId);
         const pendingHashes = { ...state.pendingHashes };
@@ -184,8 +208,14 @@ export function porulleJobCoordinator(Base) {
                 return true;
             }
         }
-        enqueue(key, supersedes, instanceId, inputHash) {
-            return this.#state.blockConcurrencyWhile(() => this.#logic.enqueue(key, supersedes, instanceId, inputHash));
+        async enqueue(key, supersedes, instanceId, inputHash) {
+            const first = await this.#state.blockConcurrencyWhile(() => this.#logic.enqueueRead(key, supersedes, instanceId, inputHash));
+            if (!("coalesceCandidate" in first))
+                return first;
+            const stale = await this.#isStale(first.coalesceCandidate);
+            return this.#state.blockConcurrencyWhile(() => stale
+                ? this.#logic.enqueueAfterStaleCandidate(key, supersedes, instanceId, inputHash)
+                : this.#logic.enqueueAfterLiveCandidate(key, first.coalesceCandidate, supersedes, instanceId, inputHash));
         }
         async acquire(key, instanceId) {
             const first = await this.#state.blockConcurrencyWhile(() => this.#logic.acquireRead(key, instanceId));

package/package.json

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

package/src/coordinator.ts

@@ -46,25 +46,71 @@ interface CoordinatorKeyState {
 export class JobCoordinatorLogic {
   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
-   * `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(
+  /** First enqueue phase: storage only. 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;
+   * under `supersedes` 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. When a pending instance carries the same input its id
+   * comes back as a CANDIDATE rather than a decision, so the Durable Object can check outside
+   * the gate whether that instance still exists. */
+  async enqueueRead(
     key: string,
     supersedes: boolean,
     instanceId: string,
     inputHash?: string,
-  ): Promise<{ terminated: string[]; coalescedInto?: string }> {
+  ): Promise<{ terminated: string[] } | { coalesceCandidate: 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 };
+          return { coalesceCandidate: pendingId };
         }
       }
     }
+    return this.commitEnqueue(key, supersedes, instanceId, inputHash, state);
+  }
+
+  /** Re-enter after the candidate was confirmed LIVE outside the gate. Coalesces only if the
+   * candidate is STILL pending under the same hash — if it started running meanwhile it has
+   * already read its input and the caller needs its own instance. */
+  async enqueueAfterLiveCandidate(
+    key: string,
+    candidate: string,
+    supersedes: boolean,
+    instanceId: string,
+    inputHash?: string,
+  ): Promise<{ terminated: string[]; coalescedInto?: string }> {
+    const state = await this.getState(key);
+    if (
+      supersedes &&
+      inputHash !== undefined &&
+      state.pending.includes(candidate) &&
+      state.pendingHashes[candidate] === inputHash
+    ) {
+      return { terminated: [], coalescedInto: candidate };
+    }
+    return this.commitEnqueue(key, supersedes, instanceId, inputHash, state);
+  }
+
+  /** Re-enter after the candidate was found STALE outside the gate: enqueue normally, which
+   * under `supersedes` drops every pending id including the dead candidate. */
+  async enqueueAfterStaleCandidate(
+    key: string,
+    supersedes: boolean,
+    instanceId: string,
+    inputHash?: string,
+  ): Promise<{ terminated: string[] }> {
+    const state = await this.getState(key);
+    return this.commitEnqueue(key, supersedes, instanceId, inputHash, state);
+  }
+
+  private async commitEnqueue(
+    key: string,
+    supersedes: boolean,
+    instanceId: string,
+    inputHash: string | undefined,
+    state: CoordinatorKeyState,
+  ): Promise<{ terminated: string[] }> {
     const terminated = supersedes ? state.pending.filter((id) => id !== instanceId) : [];
     const kept = supersedes ? [] : state.pending.filter((id) => id !== instanceId);
     const pendingHashes = { ...state.pendingHashes };
@@ -257,14 +303,27 @@ export function porulleJobCoordinator<TBase extends DurableObjectConstructor>(
       }
     }
 
-    enqueue(
+    async enqueue(
       key: string,
       supersedes: boolean,
       instanceId: string,
       inputHash?: string,
     ): Promise<{ terminated: string[]; coalescedInto?: string }> {
+      const first = await this.#state.blockConcurrencyWhile(() =>
+        this.#logic.enqueueRead(key, supersedes, instanceId, inputHash),
+      );
+      if (!("coalesceCandidate" in first)) return first;
+      const stale = await this.#isStale(first.coalesceCandidate);
       return this.#state.blockConcurrencyWhile(() =>
-        this.#logic.enqueue(key, supersedes, instanceId, inputHash),
+        stale
+          ? this.#logic.enqueueAfterStaleCandidate(key, supersedes, instanceId, inputHash)
+          : this.#logic.enqueueAfterLiveCandidate(
+              key,
+              first.coalesceCandidate,
+              supersedes,
+              instanceId,
+              inputHash,
+            ),
       );
     }