@porulle/jobs-cloudflare 0.46.0 → 0.47.0

package/dist/coordinator.d.ts

@@ -137,7 +137,17 @@ export interface DurableObjectConcurrencyCoordinatorOptions {
 /** `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. */
+ * `step.waitForEvent` when another instance already holds the key.
+ *
+ * CHOOSE THE CONCURRENCY KEY FOR WHAT MAY SUPERSEDE WHAT. `supersedes` terminates
+ * EVERY other pending instance under the key (`commitEnqueue`), which is what you
+ * want when the key identifies the thing being worked — a second enqueue for one
+ * entity should replace the first. It is destructive when the key groups work that
+ * is meant to run in full: a page-per-job walk keyed on the store would have each
+ * page terminate the one before it, and the symptom is missing output, not an error.
+ * If the unit of work is a page rather than a record, either drop `supersedes` or
+ * key on the page. An uncoordinated enqueue is a bare `workflow.create()` and skips
+ * this object entirely. */
 export declare class DurableObjectConcurrencyCoordinator implements CloudflareConcurrencyCoordinator {
     private readonly options;
     constructor(options: DurableObjectConcurrencyCoordinatorOptions);

package/dist/coordinator.js

@@ -250,7 +250,17 @@ export function porulleJobCoordinator(Base) {
 /** `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. */
+ * `step.waitForEvent` when another instance already holds the key.
+ *
+ * CHOOSE THE CONCURRENCY KEY FOR WHAT MAY SUPERSEDE WHAT. `supersedes` terminates
+ * EVERY other pending instance under the key (`commitEnqueue`), which is what you
+ * want when the key identifies the thing being worked — a second enqueue for one
+ * entity should replace the first. It is destructive when the key groups work that
+ * is meant to run in full: a page-per-job walk keyed on the store would have each
+ * page terminate the one before it, and the symptom is missing output, not an error.
+ * If the unit of work is a page rather than a record, either drop `supersedes` or
+ * key on the page. An uncoordinated enqueue is a bare `workflow.create()` and skips
+ * this object entirely. */
 export class DurableObjectConcurrencyCoordinator {
     options;
     constructor(options) {
@@ -266,6 +276,15 @@ export class DurableObjectConcurrencyCoordinator {
             .enqueue(key, payload.supersedes, payload.jobId, inputHash);
         if (coalescedInto)
             return { id: coalescedInto };
+        // The swallow is deliberate, not a silenced error. `commitEnqueue` dropped these
+        // ids from the DO's pending set before we got here, and the commonest reason a
+        // terminate fails is that the instance had already finished — the same lag
+        // `#isStale` exists for. Distinguishing "already done" from "still alive and we
+        // failed to kill it" costs a status call per id on the enqueue path, to catch a
+        // case whose worst outcome is a superseded instance running once more. Every
+        // superseding task today is an idempotent sweep, so that costs duplicate work
+        // rather than wrong state. Revisit if a task ever supersedes work that is not
+        // safe to run twice.
         await Promise.all(terminated.map((id) => this.options.workflow
             .get(id)
             .then((handle) => handle.terminate())

package/dist/index.d.ts

@@ -40,6 +40,29 @@ export interface WorkflowInstanceHandle {
         payload?: unknown;
     }): Promise<void>;
 }
+/**
+ * No `createBatch` YET, and the reason is a measurement nobody has taken rather than
+ * an absent use case. Cloudflare's binding creates up to 100 instances per call and it
+ * is what Inngest's `batchEvents` and Trigger.dev's `batchTrigger` exist for: fixing
+ * per-RECORD enqueueing.
+ *
+ * On the import path there is nothing to batch — one instance per page of work, ids in
+ * the payload, one `create`. But `enrichment-reenqueue` in the consuming app fires up
+ * to 500 enqueues by default and 5,000 capped, one per entity, and already hand-rolls
+ * bounded concurrency at six to stay under the subrequest budget. That is the case this
+ * would serve, and it survives the page-major rewrite because it is an operator route,
+ * not part of the import.
+ *
+ * What stops it being obviously worth it: those enqueues are coordinated, so each is a
+ * Durable Object round trip PLUS a `create`, and `createBatch` replaces only the second.
+ * The DO half cannot batch at all — N entity ids are N keys are N objects. So the payoff
+ * is whatever share of the measured ~0.9 s per enqueue is creation rather than
+ * coordination, and `do:enqueue` currently lumps the two. Split that class first, then
+ * decide.
+ *
+ * Keep the payload to identifiers. Params ride with the instance, so a page of ids is
+ * kilobytes and a page of product bodies is a size limit waiting to be hit.
+ */
 export interface WorkflowBinding {
     create(options: {
         id?: string;

package/package.json

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

package/src/coordinator.ts

@@ -388,7 +388,17 @@ export interface DurableObjectConcurrencyCoordinatorOptions {
 /** `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. */
+ * `step.waitForEvent` when another instance already holds the key.
+ *
+ * CHOOSE THE CONCURRENCY KEY FOR WHAT MAY SUPERSEDE WHAT. `supersedes` terminates
+ * EVERY other pending instance under the key (`commitEnqueue`), which is what you
+ * want when the key identifies the thing being worked — a second enqueue for one
+ * entity should replace the first. It is destructive when the key groups work that
+ * is meant to run in full: a page-per-job walk keyed on the store would have each
+ * page terminate the one before it, and the symptom is missing output, not an error.
+ * If the unit of work is a page rather than a record, either drop `supersedes` or
+ * key on the page. An uncoordinated enqueue is a bare `workflow.create()` and skips
+ * this object entirely. */
 export class DurableObjectConcurrencyCoordinator
   implements CloudflareConcurrencyCoordinator
 {
@@ -405,6 +415,15 @@ export class DurableObjectConcurrencyCoordinator
       .stub(key)
       .enqueue(key, payload.supersedes, payload.jobId, inputHash);
     if (coalescedInto) return { id: coalescedInto };
+    // The swallow is deliberate, not a silenced error. `commitEnqueue` dropped these
+    // ids from the DO's pending set before we got here, and the commonest reason a
+    // terminate fails is that the instance had already finished — the same lag
+    // `#isStale` exists for. Distinguishing "already done" from "still alive and we
+    // failed to kill it" costs a status call per id on the enqueue path, to catch a
+    // case whose worst outcome is a superseded instance running once more. Every
+    // superseding task today is an idempotent sweep, so that costs duplicate work
+    // rather than wrong state. Revisit if a task ever supersedes work that is not
+    // safe to run twice.
     await Promise.all(
       terminated.map((id) =>
         this.options.workflow

package/src/index.ts

@@ -49,6 +49,29 @@ export interface WorkflowInstanceHandle {
   sendEvent(event: { type: string; payload?: unknown }): Promise<void>;
 }
 
+/**
+ * No `createBatch` YET, and the reason is a measurement nobody has taken rather than
+ * an absent use case. Cloudflare's binding creates up to 100 instances per call and it
+ * is what Inngest's `batchEvents` and Trigger.dev's `batchTrigger` exist for: fixing
+ * per-RECORD enqueueing.
+ *
+ * On the import path there is nothing to batch — one instance per page of work, ids in
+ * the payload, one `create`. But `enrichment-reenqueue` in the consuming app fires up
+ * to 500 enqueues by default and 5,000 capped, one per entity, and already hand-rolls
+ * bounded concurrency at six to stay under the subrequest budget. That is the case this
+ * would serve, and it survives the page-major rewrite because it is an operator route,
+ * not part of the import.
+ *
+ * What stops it being obviously worth it: those enqueues are coordinated, so each is a
+ * Durable Object round trip PLUS a `create`, and `createBatch` replaces only the second.
+ * The DO half cannot batch at all — N entity ids are N keys are N objects. So the payoff
+ * is whatever share of the measured ~0.9 s per enqueue is creation rather than
+ * coordination, and `do:enqueue` currently lumps the two. Split that class first, then
+ * decide.
+ *
+ * Keep the payload to identifiers. Params ride with the instance, so a page of ids is
+ * kilobytes and a page of product bodies is a size limit waiting to be hit.
+ */
 export interface WorkflowBinding {
   create(options: {
     id?: string;