@ultimat3/jobs 30.9.0 → 31.0.0

package/src/retry.ts

@@ -3,7 +3,7 @@
 // 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 type { BackoffCurve, JitterMode, Random } from '@ultimat3/core';
 import { backoffDelay } from '@ultimat3/core';
 import type { DurationInput } from './clock';
 import { finiteDurationMs } from './clock';
@@ -24,10 +24,11 @@ export interface RetryPolicy {
   /** Ceiling for any single delay. Default 1h. */
   readonly maxDelay?: DurationInput;
   /**
-   * Equal jitter (half fixed, half random) by default. Without it, a burst of failures
-   * retries in lockstep and re-creates the thundering herd that killed the dependency.
+   * Core's `JitterMode`. `'equal'` (half fixed, half random) by default: a job that has already
+   * failed twice keeps a floor. `'none'` retries a burst in lockstep — the thundering herd that
+   * killed the dependency — and is for tests and printable schedules.
    */
-  readonly jitter?: boolean;
+  readonly jitter?: JitterMode;
   /** Default true: an exhausted job is parked, never dropped. */
   readonly deadLetter?: boolean;
 }
@@ -37,7 +38,7 @@ export const DEFAULT_RETRY = {
   backoff: 'exponential',
   delay: 1_000,
   maxDelay: 3_600_000,
-  jitter: true,
+  jitter: 'equal',
   deadLetter: true,
 } satisfies RetryPolicy;
 
@@ -48,14 +49,12 @@ export type { Random };
  *
  * 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.
+ * framework's: `DurationInput` (`'30s'` as well as a number) and the `DEFAULT_RETRY` fallbacks.
+ * `jitter` is core's `JitterMode` itself since 31.0.0, never a flag mapped onto two of its modes.
  *
- * `?? 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.
+ * `?? DEFAULT_RETRY.jitter`, like every other option: an omitted `jitter` is the documented
+ * `'equal'`, never off — 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 {
   return backoffDelay({
@@ -63,9 +62,7 @@ export function backoffDelayMs(policy: RetryPolicy, attempt: number, random?: Ra
     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.
-    jitter: (policy.jitter ?? DEFAULT_RETRY.jitter) === true ? 'equal' : 'none',
+    jitter: policy.jitter ?? DEFAULT_RETRY.jitter,
     random,
   });
 }
@@ -132,7 +129,7 @@ export function nextRetry(policy: RetryPolicy, attempt: number, random?: Random)
 
 /** Every delay in the policy, jitter off, for docs and `--json` output. */
 export function retrySchedule(policy: RetryPolicy): readonly number[] {
-  const deterministic: RetryPolicy = { ...policy, jitter: false };
+  const deterministic: RetryPolicy = { ...policy, jitter: 'none' };
   const out: number[] = [];
   for (let attempt = 1; attempt < policy.attempts; attempt += 1) {
     out.push(backoffDelayMs(deterministic, attempt));

package/src/scheduler.ts

@@ -27,6 +27,7 @@ import type { DrainBudget } from './drain-wait';
 import { createDrainBudget, settleAllBy } from './drain-wait';
 import type { JobDriver } from './driver';
 import { signalEnqueued } from './enqueue-signal';
+import { instrumentedFire } from './job-instrument';
 import { enqueuedAttempts } from './retry';
 import type { LeaderElection } from './scheduler-leader';
 import { soleLeader } from './scheduler-leader';
@@ -165,12 +166,15 @@ export function jobScheduler(options: SchedulerOptions): Scheduler {
     });
     // Jobs and watermark in ONE step (`SchedulerState.fire`). `undefined` is an occurrence some
     // other dispatcher already fired: nothing was queued, and nothing is reported as dispatched.
-    const results = await schedulerState.fire(options.driver, {
-      task: handle.name,
-      occurrenceMs,
-      ...(watermarkMs === undefined ? {} : { watermarkMs }),
-      jobs: requests,
-    });
+    // Under the fire's producer span, which stamps each request's `traceparent` (`job-instrument.ts`).
+    const results = await instrumentedFire(handle.name, requests, (jobs) =>
+      schedulerState.fire(options.driver, {
+        task: handle.name,
+        occurrenceMs,
+        ...(watermarkMs === undefined ? {} : { watermarkMs }),
+        jobs,
+      }),
+    );
     if (results === undefined) {
       logger.info('jobs.scheduler.already-fired', {
         task: handle.name,

package/src/steps-api.ts

@@ -14,6 +14,18 @@ export const DEFAULT_EVENT_POLL_MS = 30_000;
  */
 export const WAKING_EVENT_POLL_MS = 900_000;
 
+/**
+ * Where a wait begins — its stamp, and what the bus could see then (`EventLookup.mark`) — and the
+ * events it refused BEHIND its cursor: one owed through the horizon sorts before the cursor, so
+ * the cursor stays and its id is excluded by name. Moving the cursor back to it re-opened every
+ * event between the two, the one refused before it included.
+ */
+export interface EventSince {
+  readonly at: number;
+  readonly horizon?: string | undefined;
+  readonly refused?: readonly string[] | undefined;
+}
+
 /** The slice of the event bus a waiting step needs. Implemented by `events.ts`. */
 export interface EventLookup {
   /**
@@ -31,18 +43,45 @@ export interface EventLookup {
    */
   now(): Promise<number>;
   /**
-   * The earliest match published at or after `afterMs` — and, given `afterId`, strictly past THAT
-   * event in the bus's own (published, id) order. The id is the cursor a refused event leaves: a
-   * floor of `publishedAt + 1` stepped over every valid event stamped in the same millisecond.
-   * An `afterId` the bus no longer holds narrows nothing: the event it named cannot match again.
+   * A NEW wait's starting line, read in ONE statement: the bus's `now()`, and the `horizon` — what
+   * the bus could see at that instant. Over a database an event is stamped at INSERT and visible
+   * at COMMIT, so a publish whose transaction was still open when the wait began carries a stamp
+   * BEFORE it: by `afterMs` alone every later search skips it and the wait runs to its timeout.
+   * `find` given the horizon also matches every event the horizon could not see. Absent on a bus
+   * with no transactions (the memory one): there every publish is visible as it is stamped.
+   */
+  mark?(): Promise<{ readonly at: number; readonly horizon?: string }>;
+  /**
+   * The earliest match past the cursor in the bus's own `(published, id)` order
+   * (`events-cursor.ts`): published at or after `afterMs` — and, given `afterId`, strictly past
+   * `(afterMs, afterId)`. The id is the cursor a refused event leaves: a floor of
+   * `publishedAt + 1` stepped over every valid event stamped in the same millisecond. Compared,
+   * never looked up, so a cursor whose event was purged still excludes what it excluded.
+   *
+   * Given a `horizon` (from `mark`, or a hit's own), ALSO every event that horizon could not see,
+   * whatever its stamp. A hit answers the horizon of the search that found it, which is the one a
+   * refusal's cursor must carry: anything that search could not see is still owed to the wait.
+   *
+   * `since` is the WAIT's own line, which a refusal's cursor never moves: only an event stamped at
+   * or after `since.at`, or unseen by `since.horizon` (the mark's), is the wait's at all. Absent,
+   * it is `{ at: afterMs, horizon }` — right for a search that never refused anything. A cursor
+   * alone let an event committed BEFORE the wait sort past a refused one and be handed out.
    */
   find(
     event: string,
     correlationKey: string | undefined,
     afterMs: number,
     afterId?: string,
+    horizon?: string,
+    since?: EventSince,
   ): Promise<
-    { readonly id: string; readonly payload: unknown; readonly publishedAt: number } | undefined
+    | {
+        readonly id: string;
+        readonly payload: unknown;
+        readonly publishedAt: number;
+        readonly horizon?: string;
+      }
+    | undefined
   >;
 }
 

package/src/steps-suspension.ts

@@ -43,11 +43,22 @@ export function isWaitTimedOut(output: unknown): boolean {
 
 const WAIT_FLOOR_KEY = '~ultimate.waitFloor';
 const WAIT_FLOOR_ID_KEY = '~ultimate.waitFloorId';
+const WAIT_HORIZON_KEY = '~ultimate.waitHorizon';
+const WAIT_SINCE_HORIZON_KEY = '~ultimate.waitSinceHorizon';
+const WAIT_REFUSED_KEY = '~ultimate.waitRefused';
 
-/** Where a wait's next search starts: at `afterMs`, and past the event `afterId` names. */
+/**
+ * Where a wait's next search starts: at `afterMs`, past the event `afterId` names — and, given a
+ * `horizon` (`EventLookup.mark`), at every event that horizon could not see, whatever its stamp.
+ */
 export interface WaitFloor {
   readonly afterMs: number;
   readonly afterId?: string;
+  readonly horizon?: string;
+  /** The MARK's horizon: the wait's own line, kept by every refusal (`EventSince`). */
+  readonly sinceHorizon?: string;
+  /** Events refused BEHIND the cursor, excluded by id (`EventSince.refused`). */
+  readonly refused?: readonly string[];
 }
 
 /**
@@ -56,10 +67,19 @@ export interface WaitFloor {
  * event, so without this a repaired publisher's event sat behind the refused one until its TTL.
  * The refused event's id rides with its instant: a floor of `publishedAt + 1` skipped every valid
  * event stamped in the same millisecond. A record written before the id has `afterMs` alone.
+ * Over a bus that marks (`EventLookup.mark`), every parked wait holds one from its first park: the
+ * horizon rides here, since a re-poll must search under the line its wait began at.
  */
-export const waitFloor = (floor: WaitFloor): Record<string, number | string> => ({
+export const waitFloor = (
+  floor: WaitFloor,
+): Record<string, number | string | readonly string[]> => ({
   [WAIT_FLOOR_KEY]: floor.afterMs,
   ...(floor.afterId === undefined ? {} : { [WAIT_FLOOR_ID_KEY]: floor.afterId }),
+  ...(floor.horizon === undefined ? {} : { [WAIT_HORIZON_KEY]: floor.horizon }),
+  ...(floor.sinceHorizon === undefined ? {} : { [WAIT_SINCE_HORIZON_KEY]: floor.sinceHorizon }),
+  ...(floor.refused === undefined || floor.refused.length === 0
+    ? {}
+    : { [WAIT_REFUSED_KEY]: floor.refused }),
 });
 
 export function waitFloorOf(output: unknown): WaitFloor | undefined {
@@ -68,7 +88,18 @@ export function waitFloorOf(output: unknown): WaitFloor | undefined {
   const afterMs = record[WAIT_FLOOR_KEY];
   if (typeof afterMs !== 'number') return undefined;
   const afterId = record[WAIT_FLOOR_ID_KEY];
-  return typeof afterId === 'string' ? { afterMs, afterId } : { afterMs };
+  const horizon = record[WAIT_HORIZON_KEY];
+  const sinceHorizon = record[WAIT_SINCE_HORIZON_KEY];
+  const refused = record[WAIT_REFUSED_KEY];
+  return {
+    afterMs,
+    ...(typeof afterId === 'string' ? { afterId } : {}),
+    ...(typeof horizon === 'string' ? { horizon } : {}),
+    ...(typeof sinceHorizon === 'string' ? { sinceHorizon } : {}),
+    ...(Array.isArray(refused)
+      ? { refused: refused.filter((id): id is string => typeof id === 'string') }
+      : {}),
+  };
 }
 
 /**

package/src/steps-wait.ts

@@ -8,10 +8,12 @@ import { formatIssues, validateAsync } from '@ultimat3/schema';
 import { finiteDurationMs } from './clock';
 import { JobTimeoutError } from './errors';
 import { JobEventInvalidError } from './errors-steps';
+import { eventBefore } from './events-cursor';
 import type { WaitForEventOptions } from './steps-api';
 import type { RunnerCore } from './steps-core';
 import { jsonForm } from './steps-output';
 import type { StepRecord } from './steps-store';
+import type { WaitFloor } from './steps-suspension';
 import {
   isWaitTimedOut,
   StepSuspension,
@@ -22,7 +24,12 @@ import {
 
 const DEFAULT_WAIT_MS = 86_400_000;
 
-type Hit = { readonly id: string; readonly payload: unknown; readonly publishedAt: number };
+type Hit = {
+  readonly id: string;
+  readonly payload: unknown;
+  readonly publishedAt: number;
+  readonly horizon?: string;
+};
 
 export function waitForEventStep(core: RunnerCore) {
   const { runId, jobName } = core;
@@ -50,7 +57,10 @@ export function waitForEventStep(core: RunnerCore) {
     const at = core.now();
     // A NEW wait is stamped by the bus, whose clock stamps every `publishedAt` it is compared
     // with; the runner's own only when there is no bus to ask. A re-poll keeps what it persisted.
-    const startedAt = existing?.startedAt ?? (await core.events?.now()) ?? at;
+    // Its horizon is read in the same statement and persisted as the floor: a publish whose
+    // transaction was open at this instant is stamped before it, and is owed to this wait.
+    const mark = existing === undefined ? await core.events?.mark?.() : undefined;
+    const startedAt = existing?.startedAt ?? mark?.at ?? (await core.events?.now()) ?? at;
     const timeoutMs = finiteDurationMs(
       waitOptions.timeout ?? DEFAULT_WAIT_MS,
       'step.waitForEvent',
@@ -61,7 +71,41 @@ export function waitForEventStep(core: RunnerCore) {
     const attempts = (existing?.attempts ?? 0) + 1;
     const keyed = correlationKey === undefined ? {} : { correlationKey };
 
-    const floor = waitFloorOf(existing?.output);
+    const floor =
+      waitFloorOf(existing?.output) ??
+      (mark?.horizon === undefined
+        ? undefined
+        : { afterMs: startedAt, horizon: mark.horizon, sinceHorizon: mark.horizon });
+    // The wait's own line, which a refusal's cursor never moves: `startedAt` and the mark's horizon.
+    const since = { at: startedAt, horizon: floor?.sinceHorizon, refused: floor?.refused };
+
+    /**
+     * The floor after `hit` is refused — monotone, so no refused event can match again. A hit past
+     * the cursor moves it there, under the horizon of the search that found it: what that search
+     * could not see is still owed, and everything it saw up to the hit is spent. A hit BEHIND the
+     * cursor (owed through a horizon) leaves the cursor where it is and is excluded by id: moving
+     * the cursor back re-opened every event between the two, the one refused before it included.
+     */
+    const refusedFloor = (hit: Hit): WaitFloor => {
+      const cursor = { publishedAt: floor?.afterMs ?? startedAt, id: floor?.afterId ?? '' };
+      const sinceHorizon =
+        floor?.sinceHorizon === undefined ? {} : { sinceHorizon: floor.sinceHorizon };
+      if (eventBefore(cursor, hit)) {
+        return {
+          afterMs: hit.publishedAt,
+          afterId: hit.id,
+          ...(hit.horizon === undefined ? {} : { horizon: hit.horizon }),
+          ...sinceHorizon,
+        };
+      }
+      return {
+        afterMs: cursor.publishedAt,
+        ...(floor?.afterId === undefined ? {} : { afterId: floor.afterId }),
+        ...(floor?.horizon === undefined ? {} : { horizon: floor.horizon }),
+        ...sinceHorizon,
+        refused: [...(floor?.refused ?? []), hit.id],
+      };
+    };
     const parked = {
       runId,
       name,
@@ -81,7 +125,7 @@ export function waitForEventStep(core: RunnerCore) {
         await core
           .put({
             ...parked,
-            output: waitFloor({ afterMs: hit.publishedAt, afterId: hit.id }),
+            output: waitFloor(refusedFloor(hit)),
             wakeAt: at,
           })
           .catch((unwritten: unknown) =>
@@ -108,6 +152,8 @@ export function waitForEventStep(core: RunnerCore) {
       correlationKey,
       floor?.afterMs ?? startedAt,
       floor?.afterId,
+      floor?.horizon,
+      since,
     );
     if (hit !== undefined) return consume(hit);
 
@@ -155,6 +201,8 @@ export function waitForEventStep(core: RunnerCore) {
         correlationKey,
         floor?.afterMs ?? startedAt,
         floor?.afterId,
+        floor?.horizon,
+        since,
       );
       if (late !== undefined) return consume(late);
     }

package/src/steps.ts

@@ -36,6 +36,7 @@ import { waitForEventStep } from './steps-wait';
 export type {
   CompensateContext,
   EventLookup,
+  EventSince,
   StepApi,
   StepRunOptions,
   WaitForEventOptions,

package/src/subject-jobs.ts

@@ -3,13 +3,15 @@
 // table before a row is touched. Who may call them is the app's action: no route, no MCP tool.
 
 import type { Clock } from '@ultimat3/core';
-import { systemClock } from '@ultimat3/core';
+import { liveClock } from '@ultimat3/core';
 import { registeredEntities } from '@ultimat3/entity';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { DurationInput } from './clock';
 import { nowMs } from './clock';
 import type { ExportFormat } from './export-format';
 import type { ExportSink } from './export-sink';
+import { auditedErase } from './gdpr-audit';
+import { unerasedPersonalData } from './gdpr-coverage';
 import type { JobHandle } from './job';
 import { job } from './job';
 import type { RetryPolicy } from './retry';
@@ -57,6 +59,10 @@ export function plannedSubject<I>(subject: Subject<I>): SubjectPlan {
   });
   const [first] = problems;
   if (first !== undefined) throw first;
+  // A reached table whose treatment would leave a `.personalData()` column standing: refused before
+  // a row is touched, as an untreated table is (`gdpr-coverage.ts`).
+  const [leak] = unerasedPersonalData(plan);
+  if (leak !== undefined) throw leak;
   return plan;
 }
 
@@ -78,14 +84,16 @@ export function subjectErase<I>(definition: SubjectJobDefinition<I>): JobHandle<
     ...common(definition),
     // One live erase per person: a second request while one runs is the same run.
     idempotencyKey: (input) => `${definition.name}:${subject.init.key(input)}`,
-    run: ({ step, input }): Promise<SubjectEraseReport> =>
-      subjectErasePass(step, readerFor(subject, input), subject.init.targets ?? []),
+    run: ({ step, input, ctx, runId }): Promise<SubjectEraseReport> =>
+      auditedErase({ job: definition.name, subject: subject.entity, runId, ctx }, step, () =>
+        subjectErasePass(step, readerFor(subject, input), subject.init.targets ?? []),
+      ),
   });
 }
 
 export function subjectExport<I>(definition: SubjectExportDefinition<I>): JobHandle<I> {
   const { subject } = definition;
-  const clock = definition.clock ?? systemClock;
+  const clock = definition.clock ?? liveClock;
   return job<I>({
     ...common(definition),
     // One live pass per artifact, derived as `exportRows()` derives it.

package/src/webhook.ts

@@ -20,7 +20,7 @@ import {
   finiteOption,
   isCanonicalWebhookField,
   isUltimateError,
-  systemClock,
+  liveClock,
   throwIfAborted,
   WEBHOOK_FIELD_MAX,
 } from '@ultimat3/core';
@@ -189,7 +189,7 @@ export interface WebhookDefinition {
 }
 
 export function webhook(definition: WebhookDefinition): JobHandle<WebhookDeliveryInput> {
-  const clock = definition.clock ?? systemClock;
+  const clock = definition.clock ?? liveClock;
   const disableAfter = finiteOption(
     'webhook()',
     'disableAfter',

package/src/worker-admit.ts

@@ -34,11 +34,14 @@ export type Admission =
   | { readonly kind: 'waiting' }
   | { readonly kind: 'refused'; readonly execution: JobExecution };
 
-/** `behind` is the rest of the claimed batch: handed back before a store failure is rethrown. */
+/**
+ * `behind` is the rest of the claimed batch: handed back before a store failure is rethrown. A
+ * thunk, read only on that failure: a slice per admitted job made a batch O(batch²) to admit.
+ */
 export type Admit = (
   job: ClaimedJob,
   queue: string,
-  behind: readonly ClaimedJob[],
+  behind: () => readonly ClaimedJob[],
 ) => Promise<Admission>;
 
 export function createAdmission(options: AdmissionOptions): Admit {
@@ -79,7 +82,7 @@ export function createAdmission(options: AdmissionOptions): Admit {
         // The nack itself failed, so THIS job went nowhere either: it goes back with the jobs
         // behind it, one more best-effort try, before the round reports. Left out, it sat
         // `running` until its lease lapsed — an attempt spent on a body that never started.
-        await handBack(driver, [job, ...behind], back);
+        await handBack(driver, [job, ...behind()], back);
         throw error;
       }
       return { kind: 'waiting' };
@@ -101,7 +104,7 @@ export function createAdmission(options: AdmissionOptions): Admit {
       lease.abandon();
       // This job and every one behind it go BACK, unburned — rethrowing alone stranded them in
       // `running` with an attempt spent on work that never started.
-      await handBack(driver, [job, ...behind], back);
+      await handBack(driver, [job, ...behind()], back);
       throw error;
     }
     if (grant.outcome === 'granted') return { kind: 'run', lease };
@@ -132,7 +135,7 @@ export function createAdmission(options: AdmissionOptions): Admit {
     } catch (error) {
       // This job too, for the reason above. A refusal that DID settle before throwing is safe to
       // repeat: every nack is fenced on `running` and the claim, so a settled row ignores it.
-      await handBack(driver, [job, ...behind], back);
+      await handBack(driver, [job, ...behind()], back);
       throw error;
     }
     return { kind: 'waiting' };

package/src/worker-drain-cutoff.ts

@@ -51,6 +51,7 @@ export function armDrainCutoff(
     for (const timer of timers.splice(0)) clearTimeout(timer);
   };
   const at = (instant: number, fire: () => void): void => {
+    // Real time, not `liveClock`: this races a real `setTimeout`, and a frozen clock under it never fires.
     const timer = setTimeout(fire, Math.max(0, instant - systemClock.monotonic()));
     timer.unref?.();
     timers.push(timer);

package/src/worker-loop.ts

@@ -42,19 +42,34 @@ export interface ClaimLoop {
   stop(): void;
   /** True once a pass has come back empty. */
   idle(): boolean;
-  /** A pass ended: `found` decides the next wait. */
-  passed(found: boolean): void;
+  /**
+   * A pass ended: `found` decides the next wait. `full` — some ask came back with every row it
+   * asked for — means a backlog is likely, so a slot freeing before the next pass claims at once.
+   */
+  passed(found: boolean, full?: boolean): void;
   /** The wait the loop will arm, or has armed. */
   delayMs(): number;
   /**
    * A slot came free, or a handed-back row is due: one pass NOW if the wait in hand is longer
-   * than the floor — and no reset, so a pass that finds nothing costs one statement, not a ramp.
+   * than the floor, or the last pass came back full — and no reset, so a pass that finds nothing
+   * costs one statement, not a ramp.
    */
   kick(): void;
   /** A row this worker settled back onto the queue is claimable again in `ms`. */
   dueIn(ms: number): void;
 }
 
+/**
+ * Whether one ask came back FULL — every row it asked for STARTED. Counted on what a pass admitted,
+ * never on what it claimed: rows a concurrency or rate cap sent back are not a backlog this worker
+ * can run, and kicking on them is a claim plus N nacks per completion.
+ */
+export function fillsAsk(admitted: ReadonlyMap<string, number>, limit: number): boolean {
+  let ran = 0;
+  for (const count of admitted.values()) ran += count;
+  return ran > 0 && ran >= limit;
+}
+
 /** A due time further out than this is the poll's to find: no timer is held for a 3-day sleep. */
 const DUE_HINT_MAX_MS = 60_000;
 /** After the due time, never on it: the row's `run_at` is the database's clock, not this one. */
@@ -74,6 +89,12 @@ export function createClaimLoop(options: ClaimLoopOptions): ClaimLoop {
   /** The timer's own pass is in flight. A wake landing now asks for ONE more, never a second chain. */
   let passing = false;
   let again = false;
+  /**
+   * The last pass came back full. A pass that found work waits the FLOOR, and a kick shorter than
+   * that did nothing — so a backlog drained at one batch per floor: 8 slots / 250 ms = 32 claims/s,
+   * which `scripts/bench/worker-throughput.bench.ts` measured exactly. Cleared by the next pass.
+   */
+  let backlog = false;
   let unsubscribe: (() => void) | undefined;
   /** One timer per floor-wide bucket of due times, so a burst of retries holds a bounded few. */
   const due = new Map<number, unknown>();
@@ -126,7 +147,7 @@ export function createClaimLoop(options: ClaimLoopOptions): ClaimLoop {
   };
 
   const kick = (): void => {
-    if (delayMs > floor) now();
+    if (delayMs > floor || backlog) now();
   };
 
   return {
@@ -140,6 +161,7 @@ export function createClaimLoop(options: ClaimLoopOptions): ClaimLoop {
     stop() {
       active = false;
       again = false;
+      backlog = false;
       if (timer !== undefined) timers.clear(timer);
       timer = undefined;
       for (const hint of due.values()) timers.clear(hint);
@@ -148,7 +170,8 @@ export function createClaimLoop(options: ClaimLoopOptions): ClaimLoop {
       unsubscribe = undefined;
     },
     idle: () => backoff.idle(),
-    passed(found) {
+    passed(found, full = false) {
+      backlog = full;
       delayMs = backoff.next(found);
     },
     delayMs: () => delayMs,

package/src/worker-registry.ts

@@ -6,7 +6,7 @@
 import type { Clock } from '@ultimat3/core';
 import { logger, renderThrowable } from '@ultimat3/core';
 import { nowMs } from './clock';
-import type { JobDriver } from './driver';
+import { DEFAULT_QUEUE, type JobDriver } from './driver';
 import { MAX_WORKER_IN_FLIGHT } from './introspection';
 import { registeredJobs } from './job';
 import { type IntervalScheduler, startRenewalTimer } from './renewal-timer';
@@ -122,13 +122,15 @@ export function startWorkerRegistry(options: WorkerRegistryOptions): WorkerRegis
 
 /**
  * A queue this worker polls that NO registered job names. Not refused: a per-call
- * `enqueue({ queue })` may still land work there, and an idle pass is one statement however many
- * queues it covers. Said once, at boot, because it is almost always a config leftover — `x new`
- * configures `['<app>-default']` while a `job()` naming no queue lands on `default`.
+ * `enqueue({ queue })` may still land work there — `jobs.queues` exists to name exactly those — and
+ * an idle pass is one statement however many queues it covers. Said once, at boot, because it is
+ * almost always a config leftover (`x new` configured `['<app>-default']` until 31.0.0).
+ * `DEFAULT_QUEUE` is never one: it is where every `job()` naming no queue lands and what a worker
+ * with no list serves, so an app with no such job yet logged this on every boot of every pod.
  */
 export function reportUnregisteredQueues(workerId: string, queues: readonly string[]): void {
   const named = new Set(registeredJobs().map((handle) => handle.queue));
-  const unnamed = queues.filter((queue) => !named.has(queue));
+  const unnamed = queues.filter((queue) => queue !== DEFAULT_QUEUE && !named.has(queue));
   if (unnamed.length === 0) return;
   logger.info('jobs.worker.queue-unregistered', {
     workerId,