@ultimat3/jobs 11.1.0 → 11.2.0

package/CLAUDE.md

@@ -313,6 +313,24 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   `stop`, `JobExecution` carries `stopReason`, and `recordedFailure` appends the terminal verdict to
   the nack's `error` — `lastError` is the ONE failure field a row has, so without it `x jobs show`
   renders a dead letter at attempt 1 of 5 as a silent early stop.
+- **The backoff arithmetic is `@ultimat3/core`'s, and `retry.ts` is the option names over it**
+  (`As of 2026-08-23`). `backoffDelayMs` is `backoffDelay({ curve, jitter, base, max, attempt })`
+  with this package's spellings applied on the way in — `DurationInput` through `toMs`, the
+  `DEFAULT_RETRY` fallbacks, and `jitter: boolean` mapped to `'equal' | 'none'`. **EQUAL, never
+  `full`**: `jitter: true` here has meant half-fixed-half-random since it shipped, and `full`
+  would hand a job that already failed twice a near-zero wait. The public `RetryPolicy`,
+  `DEFAULT_RETRY` and `retrySchedule()` are unchanged — a declared `retry: { attempts: 5 }` is
+  durable API — and `BackoffStrategy` is now an ALIAS of core's `BackoffCurve` rather than a second
+  spelling of the same three names. `retry-core-parity.test.ts` is the pin: 13,824 comparisons
+  across every curve, base, cap, attempt and roll, plus the 1-based attempt and the clamp-before-
+  jitter. Never re-derive a delay here — four packages shipped four curves, which is why core has
+  one — `bun run flight-copies` is the guard, and it refuses a second curve-and-jitter function
+  anywhere in `packages/*/src`, matched on the literal shape rather than the name.
+- **`classifyThrown` / `statedDelayMs` are core's, RE-EXPORTED, not copied** (`As of 2026-08-23`).
+  They moved down to `packages/core/src/error-retry.ts` beside the table they read.
+  `retry-classification.test.ts` pins them by IDENTITY (`toBe`), not by agreement: two functions
+  that answer alike today are two that can drift, and the rule that must never drift is the one
+  above — an unregistered code carrying `terminal` reads as UNCLASSIFIED.
 - **The claim loop re-arms on the PASS, never on the jobs.** A slot belongs to its own job and is
   free the moment it settles, so `claimRound` starts what it claimed and returns the promises —
   ending the pass on `Promise.allSettled([...inFlight])` made the pool as slow as its slowest
@@ -757,7 +775,7 @@ picture from the other side.
 | `driver-pg-rows.ts` | a Postgres row → a wire record: `JobRow`/`StepRow`/`BackfillRow` and their mappings |
 | `driver-memory.ts` | `x dev` / tests |
 | `driver-redis.ts`, `driver-nats.ts` | honest `X_NOT_IMPLEMENTED` stubs |
-| `retry.ts` | backoff arithmetic, dead-letter decision |
+| `retry.ts` | the dead-letter decision, and this package's option names over core's `backoffDelay` — no curve of its own |
 | `retry-classification.ts` | the OTHER half of that decision: what the thrown error says, and the stop reason the row and the log carry |
 | `execute.ts` | `executeJob` — one claimed job run and settled, and the run's deadline/cancel |
 | `heartbeat.ts` | one claimed job's lease: the renewal interval and the loss it reports |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "11.1.0",
+  "version": "11.2.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.1.0",
-    "@ultimat3/entity": "11.1.0",
-    "@ultimat3/schema": "11.1.0",
-    "@ultimat3/time": "11.1.0"
+    "@ultimat3/core": "11.2.0",
+    "@ultimat3/entity": "11.2.0",
+    "@ultimat3/schema": "11.2.0",
+    "@ultimat3/time": "11.2.0"
   }
 }

package/src/retry-classification.ts

@@ -3,12 +3,7 @@
 // The backoff arithmetic stays in ./retry — nothing here recomputes a delay `nextRetry` owns.
 
 import type { ErrorRetry } from '@ultimat3/core';
-import {
-  DEFAULT_ERROR_RETRY,
-  declaredErrorRetry,
-  isErrorRetry,
-  isUltimateError,
-} from '@ultimat3/core';
+import { classifyThrown, statedDelayMs } from '@ultimat3/core';
 import { toMs } from './clock';
 import type { Random, RetryDecision, RetryPolicy } from './retry';
 import { DEFAULT_RETRY, nextRetry } from './retry';
@@ -23,38 +18,15 @@ export interface JobRetryDecision extends RetryDecision {
 }
 
 /**
- * The classification that was DECLARED for this throw, or `undefined` when there is none.
- *
- * Deliberately not `error.retry` alone. That field is `init.retry ?? retryFor(code)` and
- * `retryFor` fails closed, so every unclassified `UltimateError` already carries `terminal` —
- * reading it would dead-letter the first attempt of every job in every app whose codes nobody has
- * classified yet. So `terminal` counts only when it can have come from somewhere: an explicit
- * per-instance override is indistinguishable from the default here, which is why an UNCLASSIFIED
- * code carrying an instance `retry: 'terminal'` is read as unclassified. Register the code
- * (`registerErrorRetry({ X_YOUR_CODE: 'terminal' })`) to have it honoured — one way, and the same
- * way every other package declares it.
- */
-export function classifyThrown(error: unknown): ErrorRetry | undefined {
-  if (!isUltimateError(error)) return undefined;
-  const retry: unknown = error.retry;
-  if (!isErrorRetry(retry)) return undefined;
-  // Anything other than the fail-closed default can only have come from the code table or from an
-  // explicit override, so it is somebody's answer either way.
-  if (retry !== DEFAULT_ERROR_RETRY) return retry;
-  return declaredErrorRetry(error.code) === undefined ? undefined : retry;
-}
-
-/**
- * The delay a `retry-after` error NAMED, in ms. `retryAfterSeconds` on the error's `meta` is the
- * framework's one spelling for it — `@ultimat3/http`'s `rateLimited` writes it and the 429's
- * `Retry-After` header renders it — so a job and an HTTP client read the same number.
+ * Core's, re-exported rather than copied — they are the readers of core's classification table and
+ * every executor in the framework has to answer them the same way. Both were declared here first
+ * and moved down a tier VERBATIM, the subtle rule included: an UNCLASSIFIED code carrying an
+ * instance `retry: 'terminal'` reads as unclassified, because a per-instance `terminal` is
+ * indistinguishable from the fail-closed default and honouring it would dead-letter the first
+ * attempt of every job in every app whose codes nobody has classified. `retry-classification.test.ts`
+ * pins that they are the same FUNCTION, not merely two functions that agree today.
  */
-export function statedDelayMs(error: unknown): number | undefined {
-  if (!isUltimateError(error)) return undefined;
-  const seconds: unknown = error.meta?.['retryAfterSeconds'];
-  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds < 0) return undefined;
-  return Math.round(seconds * 1_000);
-}
+export { classifyThrown, statedDelayMs };
 
 /**
  * Retry, dead-letter, and when. `terminal` stops here on the attempt that failed — the same code

package/src/retry.ts

@@ -3,10 +3,17 @@
 // when attempt 5 lands without running the queue. There is no `x jobs schedule`: the subcommands
 // are `ls`, `show`, `retry`, `cancel`, `drain`.
 
+import type { BackoffCurve, Random } from '@ultimat3/core';
+import { backoffDelay } from '@ultimat3/core';
 import type { DurationInput } from './clock';
 import { toMs } from './clock';
 
-export type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+/**
+ * This package's name for core's curve, and an ALIAS rather than a second union: two spellings of
+ * `'exponential' | 'linear' | 'fixed'` can drift, and a `retry: { backoff: … }` an app declares has
+ * to mean the same thing the arithmetic reads.
+ */
+export type BackoffStrategy = BackoffCurve;
 
 export interface RetryPolicy {
   /** Total attempts including the first. `attempts: 1` means no retry. */
@@ -34,29 +41,33 @@ export const DEFAULT_RETRY = {
   deadLetter: true,
 } satisfies RetryPolicy;
 
-export type Random = () => number;
+export type { Random };
 
-/** Delay before `attempt` (1-based: the delay after attempt 1 failed is `attempt: 1`). */
+/**
+ * Delay before `attempt` (1-based: the delay after attempt 1 failed is `attempt: 1`).
+ *
+ * The arithmetic is core's — one curve-and-jitter function for the framework, because four
+ * packages shipped four of them. What stays here is the part that is this package's and not the
+ * framework's: `DurationInput` (`'30s'` as well as a number), the `DEFAULT_RETRY` fallbacks, and
+ * the `jitter: boolean` this package's public `RetryPolicy` has always spelled as a flag.
+ *
+ * `?? DEFAULT_RETRY.jitter`, like every other option. It read `!== true` before, so an omitted
+ * `jitter` meant OFF while the field's own doc says "Equal jitter … by default" — a burst of
+ * failures then retried in lockstep, which is the thundering herd the default exists to break.
+ * Masked for jobs declared through `job()` (it merges the defaults) and live for every direct
+ * caller of this exported function, `retrySchedule` included.
+ */
 export function backoffDelayMs(policy: RetryPolicy, attempt: number, random?: Random): number {
-  const base = toMs(policy.delay ?? DEFAULT_RETRY.delay ?? 1_000);
-  const cap = toMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay ?? 3_600_000);
-  const strategy = policy.backoff ?? 'exponential';
-  const step = Math.max(1, attempt);
-
-  let raw: number;
-  if (strategy === 'fixed') raw = base;
-  else if (strategy === 'linear') raw = base * step;
-  else raw = base * 2 ** (step - 1);
-
-  const capped = Math.min(raw, cap);
-  // `?? DEFAULT_RETRY.jitter`, like every other option above. It read `!== true`, so an omitted
-  // `jitter` meant OFF while the field's own doc says "Equal jitter … by default" — a burst of
-  // failures then retried in lockstep, which is the thundering herd the default exists to break.
-  // Masked for jobs declared through `job()` (it merges the defaults) and live for every direct
-  // caller of this exported function, `retrySchedule` included.
-  if ((policy.jitter ?? DEFAULT_RETRY.jitter) !== true) return Math.round(capped);
-  const roll = (random ?? Math.random)();
-  return Math.round(capped / 2 + (capped / 2) * roll);
+  return backoffDelay({
+    attempt,
+    base: toMs(policy.delay ?? DEFAULT_RETRY.delay),
+    max: toMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay),
+    curve: policy.backoff ?? DEFAULT_RETRY.backoff,
+    // EQUAL, not full: a job that has already failed twice must not be handed a near-zero wait,
+    // and this package's `jitter: true` has meant "half fixed, half random" since it shipped.
+    jitter: (policy.jitter ?? DEFAULT_RETRY.jitter) === true ? 'equal' : 'none',
+    random,
+  });
 }
 
 export interface RetryDecision {