@ultimat3/jobs 11.2.0 → 12.0.0

package/CLAUDE.md

@@ -75,6 +75,19 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   has the table, so a column added only there reaches new installs and nothing else. Comments in
   that constant carry NO apostrophes and NO semicolons — `dev-queue.ts` splits it on `;` and
   `driver-pg-sql.test.ts` checks quote parity, neither of which can tell prose from a literal.
+- **`claim({ queues: [] })` is REFUSED by every driver, `As of 2026-08-24`.** It used to mean two
+  different things: EVERY queue on `driver-memory.ts` (`wanted.size === 0 ||`) and the `default`
+  queue on `driver-pg.ts` (`queues.length > 0 ? queues : [DEFAULT_QUEUE]`), with `ClaimOptions.queues`
+  documenting neither — so the memory driver every test in this repo runs against and the pg driver
+  production runs against answered one question two ways. Nothing reached it (`createWorker` passes
+  exactly ONE queue per pass, which is what keeps a slow queue from starving the others), so it could
+  only ever be found by an embedder, in production. Both meanings are silently wrong in the other's
+  deployment: claiming every queue is a worker taking work it was never configured for, claiming
+  `default` is a worker that drains nothing and reads as an idle queue. `assertClaimQueues` in
+  `driver.ts` is the one refusal (`X_JOB_CLAIM_QUEUES_EMPTY`), called by both drivers, and
+  `driver-memory.ts`'s `claim` is `async` so an empty list REJECTS on both rather than throwing
+  synchronously on one — a sync throw out of a method typed `Promise<…>` is itself a divergence.
+  **Breaking**: `driver-pg.test.ts` was leaning on the pg default and now names its queue.
 - **`ack` and `nack` are FENCED on `state = 'running'`, and that fence is what makes cancellation
   possible** (`As of 2026-08`). Without it the only way to stop a runaway pass was
   `UPDATE x_jobs SET state='dead'`, which the worker's next settle wrote straight over. Same fence

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "11.2.0",
+  "version": "12.0.0",
   "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
   "license": "MIT",
   "type": "module",
@@ -32,9 +32,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.2.0",
-    "@ultimat3/entity": "11.2.0",
-    "@ultimat3/schema": "11.2.0",
-    "@ultimat3/time": "11.2.0"
+    "@ultimat3/core": "12.0.0",
+    "@ultimat3/entity": "12.0.0",
+    "@ultimat3/schema": "12.0.0",
+    "@ultimat3/time": "12.0.0"
   }
 }

package/src/driver-memory.ts

@@ -20,7 +20,7 @@ import type {
   NackOptions,
   QueueStats,
 } from './driver';
-import { DEFAULT_QUEUE } from './driver';
+import { assertClaimQueues, DEFAULT_QUEUE } from './driver';
 import { JobDuplicateError } from './errors';
 import type { LeaseStore } from './leases';
 import { createMemoryLeaseStore } from './leases';
@@ -194,11 +194,15 @@ export function createMemoryDriver(options: MemoryDriverOptions = {}): MemoryJob
       return Promise.resolve({ id: record.id, runId: record.runId, deduped: false });
     },
 
-    claim(claimOptions: ClaimOptions): Promise<readonly ClaimedJob[]> {
+    // `async`, so an empty queue list REJECTS here exactly as it does on the pg driver: a
+    // synchronous throw out of a method typed `Promise<…>` is a different answer to the same
+    // question, which is the class of divergence this pair is checked for.
+    async claim(claimOptions: ClaimOptions): Promise<readonly ClaimedJob[]> {
+      assertClaimQueues('memory', claimOptions);
       const at = nowMs(clock);
       const wanted = new Set(claimOptions.queues);
       const claimable = [...jobs.values()]
-        .filter((record) => wanted.size === 0 || wanted.has(record.queue))
+        .filter((record) => wanted.has(record.queue))
         .filter((record) => {
           if (record.runAt > at) return false;
           if (record.state === 'ready' || record.state === 'delayed') return true;

package/src/driver-pg.ts

@@ -20,7 +20,7 @@ import type {
   NackOptions,
   QueueStats,
 } from './driver';
-import { DEFAULT_QUEUE } from './driver';
+import { assertClaimQueues, DEFAULT_QUEUE } from './driver';
 import type { BackfillRow, JobRow, StepRow } from './driver-pg-rows';
 import { num, toBackfillRun, toJobRecord, toStepRecord } from './driver-pg-rows';
 import {
@@ -57,7 +57,7 @@ import type { StepStore } from './steps';
  * The one thing this driver needs from the DB layer, declared structurally so this package can
  * depend on no database package at all.
  *
- * **Not satisfied by `Bun.sql`** — verified against Bun 1.3.14: `Bun.sql.query` is `undefined`.
+ * **Not satisfied by `Bun.sql`** — verified against Bun 1.4.0: `Bun.sql.query` is `undefined`.
  * `Bun.sql` is a tagged template whose positional form is `unsafe`, so a `{ executor: Bun.sql }`
  * would `TypeError` on the first claim. What satisfies it is a one-line adapter over a client that
  * already speaks `(text, values)` — `@ultimat3/cli`'s `pgExecutorFor(client)` is the framework's
@@ -292,9 +292,9 @@ export function createPgDriver(options: PgDriverOptions = {}): JobDriver {
     },
 
     async claim(claimOptions: ClaimOptions): Promise<readonly ClaimedJob[]> {
-      const queues = claimOptions.queues.length > 0 ? claimOptions.queues : [DEFAULT_QUEUE];
+      assertClaimQueues('pg', claimOptions);
       const rows = await exec().query<JobRow>(SQL_CLAIM, [
-        queues,
+        claimOptions.queues,
         claimOptions.limit,
         claimOptions.workerId,
         claimOptions.visibilityTimeoutMs,

package/src/driver.ts

@@ -9,6 +9,7 @@
 // `setJobDriver(other)` and ZERO job-code change — and that is what the interface buys.
 
 import type { BackfillLedger } from './backfill-ledger';
+import { ClaimQueuesEmptyError } from './errors';
 import type { LeaseStore } from './leases';
 import type { StepStore } from './steps';
 
@@ -104,6 +105,11 @@ export interface EnqueueResult {
 }
 
 export interface ClaimOptions {
+  /**
+   * The queues this pass may take work from, by name. **At least one, and an empty list is
+   * refused** (`X_JOB_CLAIM_QUEUES_EMPTY`) — see `assertClaimQueues`. `createWorker` passes exactly
+   * one per pass, which is what keeps a slow queue from starving the others.
+   */
   readonly queues: readonly string[];
   readonly limit: number;
   /** Lease length. A worker that dies without ack makes the job claimable again after this. */
@@ -249,3 +255,18 @@ export function jobDriver(): JobDriver | undefined {
 export function resetJobDriver(): void {
   ambient = undefined;
 }
+
+/**
+ * Every driver's `claim` opens with this, so the two cannot answer an empty list differently — and
+ * they DID: `driver-memory.ts` read it as every queue and `driver-pg.ts` as the `default` one, with
+ * this interface documenting neither. A semantic only one driver holds is a guarantee that passes
+ * CI on memory and behaves differently on the deploy that runs Postgres, which is the whole reason
+ * `driver-parity.test.ts` exists.
+ *
+ * Refused, never defaulted, for `X_RATE_LIMIT_BUCKET_CONFLICT`'s reason one package over: whichever
+ * meaning a merge picked would leave the other a deployment somebody wrote against and nothing
+ * enforces.
+ */
+export const assertClaimQueues = (driver: string, options: ClaimOptions): void => {
+  if (options.queues.length === 0) throw new ClaimQueuesEmptyError(driver);
+};

package/src/errors.ts

@@ -25,6 +25,7 @@ export const JOB_OWNED_ERROR_CODES = [
   'X_BACKFILL_UNKNOWN',
   'X_JOB_ROW_STATUS_UNKNOWN',
   'X_ACTION_JOB_UNBRIDGED',
+  'X_JOB_CLAIM_QUEUES_EMPTY',
 ] as const;
 
 /**
@@ -62,6 +63,7 @@ export const JOB_ERROR_TITLES: Readonly<Record<JobOwnedErrorCode, string>> = {
   X_BACKFILL_UNKNOWN: 'no declaration carries this backfill name',
   X_JOB_ROW_STATUS_UNKNOWN: 'a queue row carries a status this build does not know',
   X_ACTION_JOB_UNBRIDGED: 'an action projection was registered as a job',
+  X_JOB_CLAIM_QUEUES_EMPTY: 'a claim named no queue, and the drivers do not agree what that means',
 };
 
 // One unconditional call, so a second package claiming one of jobs' codes throws
@@ -386,3 +388,25 @@ export class JobsNotImplementedError extends UltimateError {
     });
   }
 }
+
+/**
+ * `claim({ queues: [] })`, refused by every driver rather than answered by each.
+ *
+ * The two shipped drivers had two meanings for it — every queue on `driver-memory.ts`, the
+ * `default` queue on `driver-pg.ts` — and `ClaimOptions.queues` documented neither. Nothing reached
+ * it (`createWorker` passes exactly one queue per pass), so the divergence could only ever be found
+ * by an embedder in production, and each meaning is silently wrong in the other's deployment: one
+ * takes work this worker was never configured for, the other drains nothing and reads as an idle
+ * queue. There is no third meaning to pick — an empty list is a caller that has not said what to
+ * claim.
+ */
+export class ClaimQueuesEmptyError extends UltimateError {
+  constructor(driver: string) {
+    super({
+      code: 'X_JOB_CLAIM_QUEUES_EMPTY',
+      cause: `the ${driver} driver was asked to claim with queues: [] — an empty list names no queue, and "every queue" and "the default queue" are different deployments`,
+      fix: "pass the queue by name — driver.claim({ queues: ['default'], limit, visibilityTimeoutMs, workerId }) — or read the list from config.jobs.queues, which is what createWorker walks one queue at a time",
+      meta: { driver },
+    });
+  }
+}

package/src/index.ts

@@ -84,6 +84,7 @@ export type {
   QueueStats,
 } from './driver';
 export {
+  assertClaimQueues,
   DEFAULT_QUEUE,
   DEFAULT_VISIBILITY_TIMEOUT_MS,
   isJobState,
@@ -134,6 +135,7 @@ export type { JobErrorCode } from './errors';
 export {
   ActionJobUnbridgedError,
   CancelUnsupportedError,
+  ClaimQueuesEmptyError,
   ConcurrencyUnenforceableError,
   DriverUnavailableError,
   IdempotencyRequiredError,