@ultimat3/jobs 17.0.0 → 18.0.0

package/CLAUDE.md

@@ -370,7 +370,7 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   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
+  with this package's spellings applied on the way in — `DurationInput` through `finiteDurationMs`, 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`,
@@ -842,8 +842,30 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 
 `clock.ts` calls `parseDuration(str)` and `scheduler.ts` calls
 `nextCronOccurrence(cron, { tz, from })`. Both are normalised in one place each
-(`toMs`, `defaultCronResolver`) and the scheduler's resolver is injectable, so a signature
-change in `@ultimat3/time` is a one-line fix, not a sweep.
+(`finiteDurationMs`, `defaultCronResolver`) and the scheduler's resolver is injectable, so a
+signature change in `@ultimat3/time` is a one-line fix, not a sweep.
+
+**`clock.ts`'s conversion is `finiteDurationMs(duration, subject, option)`, never a bare `toMs`**
+(`As of 2026-08-26`). It was `toMs` — a THIRD implementation of duration→ms with no finiteness
+screen at all, and the one every scheduling decision in this package goes through:
+`step.sleep(Number(process.env.DELAY))` on an unset variable made `wakeAt = at + NaN`, and every
+`wakeAt <= now` against a `NaN` is false forever — a sleep that never ends, on a row `x jobs show`
+prints as `sleeping`. Partial screening is what hid it: `events.ts`, `events-pg.ts` and `steps.ts`
+wrapped the RESULT in `finiteOption` while `retry.ts` and `step.sleep` did not, so a reader saw
+`finiteOption` in the file and concluded the package was screened.
+
+Three things about the shape are load-bearing. The floor is `finiteOption` and NOT `finiteCount`,
+measured rather than assumed: `retry-core-parity.test.ts` pins `maxDelay: -5` at `0` and four
+`.job.test.ts` suites configure `retry: { delay: 0 }`, so a negative and a zero duration are
+shipped behaviour here — only a non-finite one is refused, and a caller wanting a positive whole
+number narrows on top, which is what `job()` does for `stepTimeout` and `eventPoll`. `subject` and
+`option` are REQUIRED, so a call site that does not name the app author's own key
+(`retry.delay`, `job("x") timeout`, `step.sleep`'s argument) is `TS2554` at the call rather than a
+review note — `@ultimat3/time`'s `toMs` screens under the subject `toMs`, which names a framework
+internal. And the callee CARRIES `Finite`, because `bun run finite-bounds` reads a repair off the
+callee's name: that is what lets `finiteDurationMs(options.defaultTtl ?? 604_800_000, …)` be
+recognised as screened with no second wrapper around it. `duration-bounds.test.ts` is the
+enforcement `finite-bounds` cannot be — a `typeof duration === 'number'` arm has no `??` in it.
 
 `driver-pg.ts`'s `PgExecutor` (`:62-64`) is a one-method duck-typed interface — this package still
 has no `@ultimat3/db` dependency, and nothing here knows what an observer, a span or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "17.0.0",
+  "version": "18.0.0",
   "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
   "license": "MIT",
   "type": "module",
@@ -25,16 +25,16 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "17.0.0",
-    "@ultimat3/entity": "17.0.0",
-    "@ultimat3/schema": "17.0.0",
-    "@ultimat3/time": "17.0.0"
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/entity": "18.0.0",
+    "@ultimat3/schema": "18.0.0",
+    "@ultimat3/time": "18.0.0"
   }
 }

package/src/clock.ts

@@ -2,7 +2,7 @@
 // injected Clock, so tests never sleep and a frozen clock cannot be bypassed.
 
 import type { Clock } from '@ultimat3/core';
-import { systemClock } from '@ultimat3/core';
+import { finiteOption, systemClock } from '@ultimat3/core';
 import { parseDuration } from '@ultimat3/time';
 
 export type DurationInput = string | number;
@@ -14,10 +14,38 @@ export function nowMs(clock: Clock = systemClock): number {
   return Number(reading);
 }
 
-/** `'3d'` | `'30s'` | `1500` -> ms. Numbers pass through so callers may stay explicit. */
-export function toMs(duration: DurationInput): number {
-  if (typeof duration === 'number') return duration;
-  const parsed: unknown = parseDuration(duration);
-  if (parsed instanceof Date) return parsed.getTime();
-  return Number(parsed);
+/**
+ * `'3d'` | `'30s'` | `1500` -> ms, refused under the name the CALLER wrote.
+ *
+ * NOT a copy of `@ultimat3/time`'s `toMs`, and the name says which one this is — three functions
+ * spelled `toMs`, `toMs` and `toDurationMs` are exactly the trap a rule spelled by NAME falls into.
+ * The STRING arm delegates to `parseDuration`, the one duration vocabulary, which refuses
+ * everything it cannot read (an overflowing amount included). What this adds is the NUMBER arm and
+ * the two names on it.
+ *
+ * The number arm passed straight through, and this is the conversion every scheduling decision in
+ * this package goes through: `step.sleep(Number(process.env.DELAY))` on an unset variable made
+ * `wakeAt = at + NaN`, and every `wakeAt <= now` against a `NaN` is false forever — a sleep that
+ * never ends, a retry ceiling that is not one, an event that never expires, with no error
+ * anywhere. `??` does not guard it, because `NaN` is not nullish.
+ *
+ * `finiteOption`, not `finiteCount`, and the floor is measured rather than assumed:
+ * `backoffDelayMs({ ...policy, maxDelay: -5 }, 1) === 0` is pinned by `retry-core-parity.test.ts`
+ * and `retry: { delay: 0 }` is what four of this package's own `.job.test.ts` suites configure, so
+ * a negative and a zero duration are shipped behaviour here. Only a non-finite one is refused. A
+ * caller needing a positive whole number narrows ON TOP — `job()` does exactly that for
+ * `stepTimeout` and `eventPoll`.
+ *
+ * `subject` and `option` are REQUIRED, and that is the enforcement rather than a convention: a new
+ * call site that does not name the key the app author actually wrote is `TS2554: Expected 3
+ * arguments` at the call. `@ultimat3/time`'s screen names the subject `toMs`, a framework internal
+ * that tells an app author nothing about which knob of theirs is wrong — the shape
+ * `@ultimat3/notify`'s `toDurationMs` already has. The name no longer has to carry `Finite`:
+ * `bun run finite-bounds` read a repair off the callee's NAME until 2026-08-26 — which is what
+ * forced this rename — and now reads `SCREENING_CALLEES` in `scripts/lib/finite-screens.ts`.
+ * Rename it freely; move the row with it.
+ */
+export function finiteDurationMs(duration: DurationInput, subject: string, option: string): number {
+  if (typeof duration === 'number') return finiteOption(subject, option, duration);
+  return parseDuration(duration);
 }

package/src/events-pg.ts

@@ -9,7 +9,7 @@
 import type { Clock } from '@ultimat3/core';
 import { finiteOption, logger, renderThrowable, systemClock, uuid } from '@ultimat3/core';
 import type { DurationInput } from './clock';
-import { nowMs, toMs } from './clock';
+import { finiteDurationMs, nowMs } from './clock';
 import type { PgExecutor } from './driver-pg';
 import {
   SQL_EVENT_FIND,
@@ -49,10 +49,10 @@ export function createPgEventBus(options: PgEventBusOptions): EventBus {
   // TWO screens, for the reason `events.ts` states: `defaultTtl` is the constructor's knob and
   // `ttl` is the publish call's, so one screen over `ttl ?? defaultTtl` names the wrong one for
   // whichever value actually arrived.
-  const defaultTtlMs = finiteOption(
+  const defaultTtlMs = finiteDurationMs(
+    options.defaultTtl ?? 604_800_000,
     'the pg event bus',
     'defaultTtl',
-    toMs(options.defaultTtl ?? 604_800_000),
   );
   const listLimit = finiteOption('the pg event bus', 'listLimit', options.listLimit ?? 1_000);
   const exec = options.executor;
@@ -79,7 +79,7 @@ export function createPgEventBus(options: PgEventBusOptions): EventBus {
           at +
           (publishOptions.ttl === undefined
             ? defaultTtlMs
-            : finiteOption('the pg event bus', 'ttl', toMs(publishOptions.ttl))),
+            : finiteDurationMs(publishOptions.ttl, 'the pg event bus', 'ttl')),
         ...(publishOptions.correlationKey === undefined
           ? {}
           : { correlationKey: publishOptions.correlationKey }),

package/src/events.ts

@@ -5,7 +5,7 @@
 import type { Clock } from '@ultimat3/core';
 import { finiteOption, logger, systemClock, uuid } from '@ultimat3/core';
 import type { DurationInput } from './clock';
-import { nowMs, toMs } from './clock';
+import { finiteDurationMs, nowMs } from './clock';
 import type { EventLookup } from './steps';
 
 export interface JobEvent {
@@ -44,10 +44,10 @@ export function createMemoryEventBus(options: MemoryEventBusOptions = {}): Event
   // told a caller who wrote `{ ttl: NaN }` to "pass a finite defaultTtl" — an instruction naming an
   // option they never set, on a constructor usually in another file. `steps.ts` names `timeout` for
   // the same value shape.
-  const defaultTtlMs = finiteOption(
+  const defaultTtlMs = finiteDurationMs(
+    options.defaultTtl ?? 604_800_000,
     'the memory event bus',
     'defaultTtl',
-    toMs(options.defaultTtl ?? 604_800_000),
   );
   const maxEvents = finiteOption('the memory event bus', 'maxEvents', options.maxEvents ?? 10_000);
   const events = new Map<string, JobEvent>();
@@ -77,7 +77,7 @@ export function createMemoryEventBus(options: MemoryEventBusOptions = {}): Event
           at +
           (publishOptions.ttl === undefined
             ? defaultTtlMs
-            : finiteOption('the memory event bus', 'ttl', toMs(publishOptions.ttl))),
+            : finiteDurationMs(publishOptions.ttl, 'the memory event bus', 'ttl')),
         ...(publishOptions.correlationKey === undefined
           ? {}
           : { correlationKey: publishOptions.correlationKey }),

package/src/job.ts

@@ -12,7 +12,7 @@ import { assert } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse } from '@ultimat3/schema';
 import type { DurationInput } from './clock';
-import { toMs } from './clock';
+import { finiteDurationMs } from './clock';
 import type { JobDescriptor } from './describe';
 import { describeJob } from './describe';
 import type { EnqueueResult } from './driver';
@@ -204,8 +204,13 @@ export function job<I>(definition: JobDefinition<I>): JobHandle<I> {
   );
 
   const stepTimeoutMs =
-    definition.stepTimeout === undefined ? undefined : toMs(definition.stepTimeout);
-  const eventPollMs = definition.eventPoll === undefined ? undefined : toMs(definition.eventPoll);
+    definition.stepTimeout === undefined
+      ? undefined
+      : finiteDurationMs(definition.stepTimeout, `job "${name}"`, 'stepTimeout');
+  const eventPollMs =
+    definition.eventPoll === undefined
+      ? undefined
+      : finiteDurationMs(definition.eventPoll, `job "${name}"`, 'eventPoll');
   // `withStepTimeout` reads `<= 0` as "no ceiling at all" and a poll of zero is a suspension that
   // resumes immediately, forever. Both are an author who asked for a limit and got the opposite,
   // so they are refused where they are written — the same answer `concurrency: 0` gets.
@@ -231,7 +236,10 @@ export function job<I>(definition: JobDefinition<I>): JobHandle<I> {
     queue: definition.queue ?? DEFAULT_QUEUE,
     retry: { ...DEFAULT_RETRY, ...definition.retry },
     concurrency: definition.concurrency,
-    timeoutMs: definition.timeout === undefined ? undefined : toMs(definition.timeout),
+    timeoutMs:
+      definition.timeout === undefined
+        ? undefined
+        : finiteDurationMs(definition.timeout, `job "${name}"`, 'timeout'),
     stepTimeoutMs,
     eventPollMs,
     input: definition.input,

package/src/outbox.ts

@@ -205,7 +205,7 @@ export function createMemoryOutboxStore(options: MemoryOutboxOptions = {}): Memo
 }
 
 export interface EnqueueOptions {
-  /** Epoch ms, or a delay via `runAt: nowMs() + toMs('5m')`. */
+  /** Epoch ms, or a delay off the caller's own clock: `clock.now().getTime() + toMs('5m')`. */
   readonly runAt?: number;
   readonly tenantId?: string;
   readonly queue?: string;

package/src/retry-classification.ts

@@ -4,7 +4,7 @@
 
 import type { ErrorRetry } from '@ultimat3/core';
 import { classifyThrown, statedDelayMs } from '@ultimat3/core';
-import { toMs } from './clock';
+import { finiteDurationMs } from './clock';
 import type { Random, RetryDecision, RetryPolicy } from './retry';
 import { DEFAULT_RETRY, nextRetry } from './retry';
 
@@ -67,7 +67,7 @@ export function nextRetryForError(
   if (stated === undefined) return { ...decision, stoppedBy: undefined, classification };
   // Clamped by the policy's own ceiling, which is what `maxDelay` is for: a responder naming a
   // day is still a responder this deployment has not agreed to wait a day for.
-  const cap = toMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay);
+  const cap = finiteDurationMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay, 'retry', 'maxDelay');
   return { ...decision, delayMs: Math.min(stated, cap), stoppedBy: undefined, classification };
 }
 

package/src/retry.ts

@@ -6,7 +6,7 @@
 import type { BackoffCurve, Random } from '@ultimat3/core';
 import { backoffDelay } from '@ultimat3/core';
 import type { DurationInput } from './clock';
-import { toMs } from './clock';
+import { finiteDurationMs } from './clock';
 
 /**
  * This package's name for core's curve, and an ALIAS rather than a second union: two spellings of
@@ -60,8 +60,8 @@ export type { Random };
 export function backoffDelayMs(policy: RetryPolicy, attempt: number, random?: Random): number {
   return backoffDelay({
     attempt,
-    base: toMs(policy.delay ?? DEFAULT_RETRY.delay),
-    max: toMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay),
+    base: finiteDurationMs(policy.delay ?? DEFAULT_RETRY.delay, 'retry', 'delay'),
+    max: finiteDurationMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay, '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.

package/src/steps.ts

@@ -9,7 +9,7 @@
 import type { Clock } from '@ultimat3/core';
 import { finiteOption, logger, renderThrowable } from '@ultimat3/core';
 import type { DurationInput } from './clock';
-import { nowMs, toMs } from './clock';
+import { finiteDurationMs, nowMs } from './clock';
 import { JobAbortedError, JobTimeoutError, StepDuplicateError } from './errors';
 import { createRunSignal } from './run-signal';
 
@@ -361,7 +361,8 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
       throw new StepSuspension({ step: name, resumeAt: existing.wakeAt, reason: 'sleep' });
     }
 
-    const wakeAt = at + toMs(duration);
+    const wakeAt =
+      at + finiteDurationMs(duration, `job "${jobName}" step.sleep("${name}")`, 'duration');
     await put({
       runId,
       name,
@@ -389,7 +390,7 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
     const startedAt = existing?.startedAt ?? at;
     const deadline =
       startedAt +
-      finiteOption('step.waitForEvent', 'timeout', toMs(waitOptions.timeout ?? 86_400_000));
+      finiteDurationMs(waitOptions.timeout ?? 86_400_000, 'step.waitForEvent', 'timeout');
     const correlationKey = waitOptions.match;
 
     const hit = await options.events?.find(event, correlationKey, startedAt);
@@ -413,10 +414,10 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
         throw new JobTimeoutError({
           job: jobName,
           step: name,
-          timeoutMs: finiteOption(
+          timeoutMs: finiteDurationMs(
+            waitOptions.timeout ?? 86_400_000,
             'step.waitForEvent',
             'timeout',
-            toMs(waitOptions.timeout ?? 86_400_000),
           ),
         });
       }