@ultimat3/jobs 2.0.0 → 4.0.0

package/src/outbox-pg.ts

@@ -10,6 +10,7 @@
 // the transaction's connection — so the wiring is one line there and no tier crossing here.
 
 import type { Clock } from '@ultimat3/core';
+import { uuid } from '@ultimat3/core';
 import type { Tx } from '@ultimat3/entity';
 import { nowMs } from './clock';
 import type { PgExecutor } from './driver-pg';
@@ -17,9 +18,11 @@ import {
   SQL_OUTBOX_CLAIM,
   SQL_OUTBOX_MARK_PUBLISHED,
   SQL_OUTBOX_PENDING_COUNT,
+  SQL_OUTBOX_RELEASE,
   SQL_OUTBOX_STAGE,
 } from './driver-pg-sql';
 import type { OutboxRecord, OutboxStore } from './outbox';
+import { resolveClaimLeaseMs } from './outbox-lease';
 
 interface OutboxRow {
   readonly id: string;
@@ -33,6 +36,7 @@ interface OutboxRow {
   readonly tenant_id: string | null;
   readonly traceparent: string | null;
   readonly enqueued_by: string | null;
+  readonly claimed_by?: string | null;
 }
 
 export interface PgOutboxOptions {
@@ -47,6 +51,22 @@ export interface PgOutboxOptions {
    */
   readonly txExecutor: (tx: Tx) => PgExecutor;
   readonly clock?: Clock;
+  /**
+   * How long a claimed row stays this relay's before any relay may take it again. It bounds one
+   * thing only: how long the rows of a relay that DIED mid-batch sit unpublished. A pass that is
+   * merely slow keeps its rows because it published them; a pass that failed hands them back
+   * through `release`.
+   */
+  readonly claimLeaseMs?: number;
+  /**
+   * Written to `claimed_by`, and read back as the FENCE on `release` and `markPublished` — so it
+   * must be UNIQUE PER PROCESS. Two replicas passing one literal are one claimant to Postgres, and
+   * each can then release or retire the other's live batch. Omit it: the default is
+   * `relay-<uuid>`, minted once per store, which is unique by construction. Diagnostics second —
+   * it is what an operator reads to see which relay is sitting on a batch, and a value that
+   * changed every tick would answer nobody.
+   */
+  readonly relayId?: string;
 }
 
 function toRecord(row: OutboxRow): OutboxRecord {
@@ -62,6 +82,7 @@ function toRecord(row: OutboxRow): OutboxRecord {
     ...(row.tenant_id === null ? {} : { tenantId: row.tenant_id }),
     ...(row.traceparent === null ? {} : { traceparent: row.traceparent }),
     ...(row.enqueued_by === null ? {} : { enqueuedBy: row.enqueued_by }),
+    ...(typeof row.claimed_by === 'string' ? { claimedBy: row.claimed_by } : {}),
   };
 }
 
@@ -71,6 +92,13 @@ export function createPgOutboxStore(options: PgOutboxOptions): OutboxStore {
   // is neither committed nor rolled back (a process killed mid-request) leaves nothing behind.
   const staged = new WeakMap<object, OutboxRecord[]>();
   const key = (tx: Tx): object => tx as unknown as object;
+  // One id per store, minted here rather than per claim: `claimed_by` is read by an operator
+  // asking which relay is sitting on a batch, and a value that changed every tick answers nobody.
+  // Per-store is also the granularity the fence needs — two relays are two processes, two stores.
+  const relayId = options.relayId ?? `relay-${uuid()}`;
+  // Resolved once, at construction, so a lease this store could never honour fails where it was
+  // written instead of inside a relay tick whose only trace is a log line nobody reads.
+  const claimLeaseMs = resolveClaimLeaseMs(options.claimLeaseMs);
 
   return {
     async stage(tx, record) {
@@ -112,18 +140,41 @@ export function createPgOutboxStore(options: PgOutboxOptions): OutboxStore {
     },
 
     /**
-     * `for update skip locked` is in the statement, and under autocommit its row locks last only
-     * for that statement — so two relays can hand the same row to `enqueue`. That is the
-     * at-least-once the whole design already assumes and the idempotency key already collapses;
-     * what the clause buys is that two relays running side by side do not serialise on each other.
+     * A CLAIM, not a read. `for update skip locked` in a bare select held its locks only for that
+     * statement — which under autocommit is over before this method resolves — so two relays
+     * polling 200ms apart got the identical batch and both published it. The idempotency key
+     * collapses that only while the first job is still live, so the repeat that lands after it
+     * finished runs the handler a second time. `SQL_OUTBOX_CLAIM` stamps `claimed_at` in the same
+     * statement that locks the row; `skip locked` still keeps two relays from serialising.
      */
     async claim(limit) {
-      const rows = await options.executor.query<OutboxRow>(SQL_OUTBOX_CLAIM, [limit]);
+      const rows = await options.executor.query<OutboxRow>(SQL_OUTBOX_CLAIM, [
+        limit,
+        claimLeaseMs,
+        relayId,
+      ]);
       return rows.map(toRecord);
     },
 
-    async markPublished(id, at) {
-      await options.executor.query(SQL_OUTBOX_MARK_PUBLISHED, [id, at || nowMs(options.clock)]);
+    /**
+     * Fenced on the CLAIMANT, not only on the ids. A relay that stalled past its lease wakes into
+     * a world where its batch belongs to another relay, and an unfenced release frees rows that
+     * relay is mid-publish on — a third relay claims them and publishes them again. `relayId` is
+     * the fallback because it is what this store stamped: a caller with no token is this store's
+     * own relay, and one holding somebody else's token could not have got it from here.
+     */
+    async release(ids, claimant) {
+      if (ids.length === 0) return;
+      await options.executor.query(SQL_OUTBOX_RELEASE, [ids, claimant ?? relayId]);
+    },
+
+    /** Same fence, and worse to miss: marking a row published is losing the job behind it. */
+    async markPublished(id, at, claimant) {
+      await options.executor.query(SQL_OUTBOX_MARK_PUBLISHED, [
+        id,
+        at || nowMs(options.clock),
+        claimant ?? relayId,
+      ]);
     },
 
     async pendingCount() {

package/src/outbox.ts

@@ -31,6 +31,7 @@ import type { EnqueueResult, JobDriver } from './driver';
 import { DEFAULT_QUEUE, jobDriver } from './driver';
 import { DriverUnavailableError, OutboxNoTxError } from './errors';
 import type { JobHandle } from './job';
+import { resolveClaimLeaseMs } from './outbox-lease';
 
 export interface OutboxRecord {
   readonly id: string;
@@ -46,6 +47,11 @@ export interface OutboxRecord {
   readonly traceparent?: string;
   readonly enqueuedBy?: string;
   readonly publishedAt?: number;
+  /**
+   * Stamped by `claim()`, absent on a staged row. Hand it back to `release`/`markPublished`: it is
+   * the FENCE, so a claimant whose lease lapsed cannot touch the rows a newer one is publishing.
+   */
+  readonly claimedBy?: string;
 }
 
 export interface OutboxStore {
@@ -55,12 +61,44 @@ export interface OutboxStore {
   commit(tx: Tx): Promise<readonly OutboxRecord[]>;
   /** Called by the tx runner after ROLLBACK. Staged rows vanish with the transaction. */
   rollback(tx: Tx): Promise<void>;
-  /** Unpublished, committed rows — the relay's work queue. */
+  /**
+   * CLAIM unpublished, committed rows — the relay's work queue, and a lease rather than a read.
+   * A store that hands the same rows to two relays hands the same job to two workers, and the
+   * idempotency key only collapses that while the first job is still live.
+   */
   claim(limit: number): Promise<readonly OutboxRecord[]>;
-  markPublished(id: string, at: number): Promise<void>;
+  /**
+   * Hand a claim back before its lease runs out, for the batch a failed publish stopped. OPTIONAL
+   * so a store written before the claim became a lease still compiles: without it those rows wait
+   * out the whole lease, which is slower, never wrong.
+   *
+   * `claimant` is the `claimedBy` the claim stamped. Passing it is what makes a lapsed relay's
+   * late release a no-op instead of an unclaim of somebody else's live batch.
+   */
+  release?(ids: readonly string[], claimant?: string): Promise<void>;
+  /** `claimant` fences the same way, and here it is worse to miss: this retires the row. */
+  markPublished(id: string, at: number, claimant?: string): Promise<void>;
   pendingCount(): Promise<number>;
 }
 
+/**
+ * The claim's sort key, and it is TOTAL: `id` after `stagedAt`, exactly what `SQL_OUTBOX_CLAIM`
+ * orders by. Every row staged in one transaction shares a `stagedAt`, so the key ties for the
+ * batch that most depends on order — and a tie leaves both which rows a limit takes and the order
+ * they publish in to whatever the store iterated first. Code units, never `localeCompare`, for
+ * the reason `registeredJobs()` sorts that way.
+ */
+function byClaimOrder(a: OutboxRecord, b: OutboxRecord): number {
+  if (a.stagedAt !== b.stagedAt) return a.stagedAt - b.stagedAt;
+  if (a.id === b.id) return 0;
+  return a.id < b.id ? -1 : 1;
+}
+
+export interface MemoryOutboxOptions {
+  readonly clock?: Clock;
+  readonly claimLeaseMs?: number;
+}
+
 export interface MemoryOutboxStore extends OutboxStore {
   /**
    * Committed rows this process is still holding. The relay's backlog and nothing else — a
@@ -75,11 +113,29 @@ export interface MemoryOutboxStore extends OutboxStore {
  * transaction" guarantee needs no cooperation from the DB layer and rollback is a delete.
  * The pg store swaps this for a real `x_outbox` table written by the same connection.
  */
-export function createMemoryOutboxStore(): MemoryOutboxStore {
+export function createMemoryOutboxStore(options: MemoryOutboxOptions = {}): MemoryOutboxStore {
   const staged = new WeakMap<object, OutboxRecord[]>();
   const committed = new Map<string, OutboxRecord>();
+  /** Each claimed row's lease: when it was taken and by whom. Absent is `claimed_at is null`. */
+  const claims = new Map<string, { at: number; by: string }>();
+  const leaseMs = resolveClaimLeaseMs(options.claimLeaseMs);
+  // A token per CLAIM, where the pg store stamps one per RELAY. Two relays there are two stores
+  // with two ids; here they are two `claim()` calls on one store, so the claim is the only
+  // granularity at which this store can answer "is this mutation from the current holder".
+  let claimSeq = 0;
 
   const key = (tx: Tx): object => tx as unknown as object;
+  const free = (id: string, at: number): boolean => {
+    const claim = claims.get(id);
+    return claim === undefined || at - claim.at >= leaseMs;
+  };
+  /**
+   * A mutation from a claimant that no longer holds the row is a NO-OP. `undefined` is the caller
+   * that holds no token at all — a store-level caller, or one written before the fence — and is
+   * left unfenced rather than silently dropped, the way `release` itself is optional.
+   */
+  const owns = (id: string, claimant: string | undefined): boolean =>
+    claimant === undefined || claims.get(id)?.by === claimant;
 
   return {
     stage(tx, record) {
@@ -98,19 +154,36 @@ export function createMemoryOutboxStore(): MemoryOutboxStore {
       staged.delete(key(tx));
       return Promise.resolve();
     },
+    /**
+     * The same question `SQL_OUTBOX_CLAIM` answers, and it has to stay the same one: a row this
+     * store hands back is CLAIMED for `leaseMs`, so a second relay polling the same store gets
+     * nothing, and a claim whose holder died is reclaimable once the window passes.
+     */
     claim(limit) {
+      const at = nowMs(options.clock);
+      claimSeq += 1;
+      const by = `claim-${claimSeq}`;
       const ready = [...committed.values()]
-        .filter((record) => record.publishedAt === undefined)
-        .sort((a, b) => a.stagedAt - b.stagedAt)
+        .filter((record) => record.publishedAt === undefined && free(record.id, at))
+        .sort(byClaimOrder)
         .slice(0, limit);
-      return Promise.resolve(ready);
+      for (const record of ready) claims.set(record.id, { at, by });
+      return Promise.resolve(ready.map((record) => ({ ...record, claimedBy: by })));
+    },
+    release(ids, claimant) {
+      for (const id of ids) {
+        if (owns(id, claimant)) claims.delete(id);
+      }
+      return Promise.resolve();
     },
-    markPublished(id, _at) {
+    markPublished(id, _at, claimant) {
+      if (!owns(id, claimant)) return Promise.resolve();
       // Deleted, not stamped. A published row is out of the relay's reach either way, and the
       // pg store's `published_at` column is a retained audit trail this map is not: rewriting
       // it in place held every payload ever enqueued — arbitrary job input — for the life of
       // the process, and made `claim()` and `pendingCount()` walk all of them every 200ms.
       committed.delete(id);
+      claims.delete(id);
       return Promise.resolve();
     },
     pendingCount() {
@@ -331,7 +404,10 @@ export function createOutboxRelay(options: RelayOptions): OutboxRelay {
           ...(record.traceparent === undefined ? {} : { traceparent: record.traceparent }),
           ...(record.enqueuedBy === undefined ? {} : { enqueuedBy: record.enqueuedBy }),
         });
-        await options.store.markPublished(record.id, nowMs(options.clock));
+        // The claim's own token goes back with the mark. Without it a relay whose lease lapsed
+        // mid-stall retires a row the relay that reclaimed it has not published yet — the row is
+        // gone and nothing publishes it.
+        await options.store.markPublished(record.id, nowMs(options.clock), record.claimedBy);
         published += 1;
       } catch (error) {
         // STOP the batch. `claim()` returns rows in `staged_at` order and the loop used to log
@@ -347,6 +423,13 @@ export function createOutboxRelay(options: RelayOptions): OutboxRelay {
           remaining: batch.length - published,
           error: error instanceof Error ? error.message : String(error),
         });
+        // Hand the rest of the batch back rather than sit on a claim nobody is publishing. The
+        // claim is a lease now, so without this a single pool timeout parks every committed row
+        // behind it for the whole lease window instead of for one poll interval.
+        await options.store.release?.(
+          batch.slice(published).map((row) => row.id),
+          record.claimedBy,
+        );
         break;
       }
     }

package/src/register.ts

@@ -5,9 +5,24 @@
  */
 
 import { type RegisteredPrimitive, registerPrimitiveRegistrar } from '@ultimat3/core';
+import { ActionJobUnbridgedError } from './errors';
 import { isJobHandle, registerJob } from './job';
 import { isTaskHandle, registerTask } from './task';
 
+/**
+ * `@ultimat3/action`'s job PROJECTION, recognised structurally because that package is this tier
+ * and may never be imported here. `kind: 'action-job'` is a literal chosen to be distinguishable
+ * from `'job'` rather than a near-miss (`packages/action/src/job-handle.ts` says so), which is
+ * precisely what makes this check possible without an import.
+ */
+const isActionProjection = (
+  value: unknown,
+): value is { readonly kind: 'action-job'; readonly name: string } =>
+  typeof value === 'object' &&
+  value !== null &&
+  'kind' in value &&
+  (value as { readonly kind: unknown }).kind === 'action-job';
+
 /** `registerJobs(await import('./jobs'))` — export names become job names. */
 export function registerJobs(
   module: Readonly<Record<string, unknown>>,
@@ -15,7 +30,16 @@ export function registerJobs(
   const registered: RegisteredPrimitive[] = [];
   for (const name of Object.keys(module).sort()) {
     const value = module[name];
-    if (isJobHandle(value)) registered.push(registerJob(name, value));
+    if (isJobHandle(value)) {
+      registered.push(registerJob(name, value));
+      continue;
+    }
+    // Everything else is skipped in silence — a module namespace is full of constants, types and
+    // helpers exported beside the jobs. Everything else EXCEPT this one, which is unambiguously
+    // someone trying to queue an action and getting nothing at all.
+    if (isActionProjection(value)) {
+      throw new ActionJobUnbridgedError({ export: name, job: value.name });
+    }
   }
   return registered;
 }

package/src/renewal-timer.ts

@@ -0,0 +1,35 @@
+// A renewal loop that is TERMINAL once stopped, and the one shape two files renew against.
+// `heartbeat.ts` renews a job's lease and `worker-fleet-slots.ts` a fleet slot, and both decided a
+// LOSS from an answer that arrived after the run had already finished cleanly: `stop()` cleared
+// the interval, which does nothing to the request already on the wire. So a flag is what every
+// branch after an `await` re-reads — the shape `settleWithin`'s `decided` uses in core.
+
+export interface RenewalTimer {
+  /**
+   * True once `stop()` has been called. Read AFTER every await in the renewal body: a clean
+   * completion settles the row this renewal is fenced on, so the driver answering "not yours"
+   * past that point is a finished job, not a lost lease — and reporting it is an error-level page
+   * for a non-event, on exactly the signals that mean the queue re-delivered live work.
+   */
+  stopped(): boolean;
+  /** Stop renewing, for the pass in flight as well as the next one. Idempotent. */
+  stop(): void;
+}
+
+export function startRenewalTimer(
+  intervalMs: number,
+  renew: () => void | Promise<void>,
+): RenewalTimer {
+  let stopped = false;
+  const timer = setInterval(() => {
+    void renew();
+  }, intervalMs);
+  return {
+    stopped: () => stopped,
+    stop(): void {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    },
+  };
+}

package/src/retry-classification.ts

@@ -0,0 +1,112 @@
+// One retry decision from two questions the executor used to ask only half of: "are there
+// attempts left?" (./retry) and "is this error worth trying again at all?" (core's classification).
+// 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 { toMs } from './clock';
+import type { Random, RetryDecision, RetryPolicy } from './retry';
+import { DEFAULT_RETRY, nextRetry } from './retry';
+
+/** Why this attempt was the last one. Absent while the job is still being retried. */
+export type JobStopReason = 'terminal' | 'attempts-exhausted';
+
+export interface JobRetryDecision extends RetryDecision {
+  readonly stoppedBy: JobStopReason | undefined;
+  /** The classification consulted, or `undefined` when nobody classified the thrown code. */
+  readonly classification: ErrorRetry | undefined;
+}
+
+/**
+ * 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.
+ */
+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);
+}
+
+/**
+ * Retry, dead-letter, and when. `terminal` stops here on the attempt that failed — the same code
+ * run again is the same answer, and the attempts left are a queue slot, a provider bill, and (the
+ * case that forced this) three more wrong passwords at a site that locks the account after three.
+ *
+ * Everything else keeps the attempt count in charge: `retry-after` only replaces the delay, never
+ * the ceiling, and an unclassified code takes exactly the path it took before this existed.
+ */
+export function nextRetryForError(
+  policy: RetryPolicy,
+  attempt: number,
+  error: unknown,
+  random?: Random,
+): JobRetryDecision {
+  const classification = classifyThrown(error);
+  if (classification === 'terminal') {
+    return {
+      retry: false,
+      delayMs: 0,
+      // The policy still decides park-or-drop: `deadLetter: false` means this app does not keep
+      // failed jobs, and that is not a preference a classification gets to overturn.
+      deadLetter: policy.deadLetter ?? true,
+      nextAttempt: attempt,
+      stoppedBy: 'terminal',
+      classification,
+    };
+  }
+
+  const decision = nextRetry(policy, attempt, random);
+  if (!decision.retry) {
+    return { ...decision, stoppedBy: 'attempts-exhausted', classification };
+  }
+  if (classification !== 'retry-after')
+    return { ...decision, stoppedBy: undefined, classification };
+
+  const stated = statedDelayMs(error);
+  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);
+  return { ...decision, delayMs: Math.min(stated, cap), stoppedBy: undefined, classification };
+}
+
+/**
+ * What the job ROW records. `lastError` is the one failure field a row carries, so a dead letter
+ * that stopped at attempt 1 of 5 has to explain itself there or `x jobs show` reads as a silent
+ * early stop. Only the terminal verdict is appended: exhaustion is already legible from
+ * `attempt === maxAttempts`.
+ */
+export function recordedFailure(message: string, decision: JobRetryDecision): string {
+  return decision.stoppedBy === 'terminal'
+    ? `${message} — not retried: this code is classified terminal, so every remaining attempt fails the same way`
+    : message;
+}

package/src/retry.ts

@@ -1,6 +1,7 @@
-// Retry arithmetic, kept pure so the schedule is testable and printable. `x jobs schedule`
-// renders `retrySchedule()` verbatim — an agent should be able to see when attempt 5 lands
-// without running the queue.
+// Retry arithmetic, kept pure so the schedule is testable and printable. `x jobs show <id>`
+// renders `retrySchedule()` verbatim as `JobTrace.retryDelaysMs` — an agent should be able to see
+// when attempt 5 lands without running the queue. There is no `x jobs schedule`: the subcommands
+// are `ls`, `show`, `retry`, `cancel`, `drain`.
 
 import type { DurationInput } from './clock';
 import { toMs } from './clock';

package/src/steps.ts

@@ -12,7 +12,20 @@ import type { DurationInput } from './clock';
 import { nowMs, toMs } from './clock';
 import { JobAbortedError, JobTimeoutError, StepDuplicateError } from './errors';
 
-export type StepStatus = 'completed' | 'sleeping' | 'waiting' | 'failed';
+/**
+ * The runtime list is the declaration and `StepStatus` is derived from it, the shape
+ * `BACKFILL_STATUSES` and `PRIMITIVE_KINDS` already have. A bare union cannot narrow a `text`
+ * column, so `driver-pg-rows.ts` cast one instead — and a cast that lands an unknown status on a
+ * record makes `stepRun`'s `existing?.status === 'completed'` false, which RE-EXECUTES a step
+ * this file promises runs once.
+ */
+export const STEP_STATUSES = ['completed', 'sleeping', 'waiting', 'failed'] as const;
+
+export type StepStatus = (typeof STEP_STATUSES)[number];
+
+/** Narrows a status read back out of a store. Never a cast — the list decides. */
+export const isStepStatus = (value: string): value is StepStatus =>
+  (STEP_STATUSES as readonly string[]).includes(value);
 
 export interface StepRecord {
   readonly runId: string;

package/src/task.ts

@@ -54,6 +54,7 @@ export interface TaskDefinition {
    */
   enqueue: (occurrenceMs: number) => readonly TaskEnqueueEntry[];
   readonly catchUp?: CatchUpPolicy;
+  /** Whole occurrences per round, one or more. Zero fires nothing at all, and `task()` refuses it. */
   readonly maxCatchUp?: number;
 }
 
@@ -98,6 +99,9 @@ export interface TaskHandle {
 const registry = new Map<string, TaskHandle>();
 let anonymous = 0;
 
+/** Occurrences one round may fire when neither the declaration nor a catch-up says otherwise. */
+const DEFAULT_MAX_CATCH_UP = 10;
+
 /** Job's store, for tasks: proof `task()` built the handle, plus whether it named itself. */
 interface TaskOrigin {
   readonly declaredName: boolean;
@@ -127,13 +131,26 @@ export function task(definition: TaskDefinition): TaskHandle {
     `use the full zone id on task("${name}"), e.g. tz: 'America/Bogota' — list the valid ones with: bun -e "console.log(Intl.supportedValuesOf('timeZone').join('\\n'))"`,
   );
 
+  // `maxCatchUp: 0` is not "no ceiling" — `occurrencesSince` walks
+  // `for (let i = 0; i < handle.maxCatchUp; i += 1)`, so zero (and any negative, and any fraction
+  // below one) returns an empty list on every round and the task NEVER fires: no error, no log
+  // line, no queue row, forever. Refused where it is written, exactly as `job()` refuses
+  // `concurrency: 0` and `createPacer` refuses `rate: 0`. `Number.isInteger` covers `NaN` and
+  // `Infinity` in the same predicate — an unbounded catch-up is a burst nobody declared.
+  assert(
+    definition.maxCatchUp === undefined ||
+      (Number.isInteger(definition.maxCatchUp) && definition.maxCatchUp >= 1),
+    `task "${name}" declares maxCatchUp ${String(definition.maxCatchUp)}, so no occurrence can ever fire`,
+    `set a whole maxCatchUp of 1 or more on task("${name}"), or omit the field for the default of ${DEFAULT_MAX_CATCH_UP}`,
+  );
+
   const handle: TaskHandle = {
     kind: 'task',
     name,
     cron: definition.cron,
     tz: definition.tz,
     catchUp: definition.catchUp ?? 'skip',
-    maxCatchUp: definition.maxCatchUp ?? 10,
+    maxCatchUp: definition.maxCatchUp ?? DEFAULT_MAX_CATCH_UP,
     // `nowMs()` and not `Date.now()`: every reading of time in this package goes through a
     // Clock so a frozen one cannot be bypassed.
     entries: (occurrenceMs: number = nowMs()) => definition.enqueue(occurrenceMs),
@@ -215,8 +232,18 @@ export function nameTasks(record: Readonly<Record<string, TaskHandle>>): void {
   for (const [exportName, handle] of Object.entries(record)) registerTask(exportName, handle);
 }
 
+/**
+ * Code-unit compare, never `localeCompare`. This list is projected into `x.manifest.json`, which
+ * both tracked apps COMMIT and `x verify`'s drift step diffs byte for byte — and `localeCompare`
+ * with no locale argument answers from the runtime's ICU default and collation version, so the
+ * same source could sort two ways on two machines. `@ultimat3/http`'s `describeRoutes` states the
+ * same rule; the comparator is restated rather than imported because `http` is not below this
+ * package on the tier table.
+ */
+const byName = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
 export function registeredTasks(): readonly TaskHandle[] {
-  return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return [...registry.values()].sort((a, b) => byName(a.name, b.name));
 }
 
 export function getTask(name: string): TaskHandle | undefined {

package/src/worker-fleet-slots.ts

@@ -8,6 +8,7 @@ import type { ClaimedJob } from './driver';
 import { getJob } from './job';
 import type { HeldLease, LeaseStore } from './leases';
 import { jobLeaseKey } from './leases';
+import { startRenewalTimer } from './renewal-timer';
 
 /**
  * A renewal that REJECTED is not a lost slot: there is a TTL behind it and the interval gets
@@ -79,21 +80,25 @@ export function createFleetSlots(options: FleetSlotOptions): FleetSlots {
     startRenewal(jobId, onLost) {
       const slot = held.get(jobId);
       if (slot === undefined) return noop;
-      const stop = (): void => {
-        clearInterval(timer);
-      };
       // Renewed on the lease heartbeat's own interval and released in the same `finally`: one
       // clock for "this worker still owns the job" and "this worker still owns the slot" is one
-      // fewer way for them to disagree.
-      const timer = setInterval(() => {
-        void options.leases
+      // fewer way for them to disagree — and `timer.stopped()` is the same latch `heartbeat.ts`
+      // reads, for the same reason.
+      const timer = startRenewalTimer(options.renewIntervalMs, () =>
+        options.leases
           ?.renew(slot, options.ttlMs)
           .then((renewed) => {
             // `=== false`, never `!renewed`, for the reason `heartbeat.ts` reads `held` that way:
             // a store written before this return value existed resolves `undefined`, and treating
             // that as a loss would cancel every job on every renewal. Only an explicit no is one.
-            if (renewed !== false) return;
-            stop();
+            //
+            // `stopped()` re-read AFTER the await for the other half: the run settles, this timer
+            // is stopped and `worker.ts` releases the slot — so the renewal already on the wire
+            // finds the row gone and answers `false` for a job that FINISHED. Reported, that is
+            // `jobs.worker.slot-lost` at error and an abort on a controller `runSignal.dispose()`
+            // has already torn down: noise about a run nobody lost.
+            if (renewed !== false || timer.stopped()) return;
+            timer.stop();
             logger.error('jobs.worker.slot-lost', {
               workerId: options.workerId,
               jobId,
@@ -102,9 +107,9 @@ export function createFleetSlots(options: FleetSlotOptions): FleetSlots {
             });
             onLost?.(slot);
           })
-          .catch(noop);
-      }, options.renewIntervalMs);
-      return stop;
+          .catch(noop),
+      );
+      return () => timer.stop();
     },
 
     async release(jobId) {

package/src/worker-run.ts

@@ -48,10 +48,13 @@ export async function runClaimedJob(options: RunClaimedOptions): Promise<JobExec
   const handle = getJob(claimed.name);
   if (handle === undefined) {
     // Park it, do not burn attempts: the job may well be registered by the pod next to this one.
+    // A genuine park — no worker in this deploy can run it — so it leaves the ready bucket, unlike
+    // a limiter shed, which is a job this fleet will pick up on its next pass.
     await driver.nack(claimed.id, {
       delayMs: 30_000,
       error: `no job registered as "${claimed.name}"`,
       countsAsAttempt: false,
+      park: true,
     });
     return unknownJob(claimed);
   }