@ultimat3/jobs 3.0.0 → 4.1.0

package/src/driver.ts

@@ -17,15 +17,22 @@ import type { StepStore } from './steps';
  * a cancellation is work an operator stopped on purpose and `x jobs retry` must not resurrect by
  * accident. It appears in no claim predicate, so the queue never hands a cancelled row out again.
  */
-export type JobState =
-  | 'ready'
-  | 'delayed'
-  | 'running'
-  | 'suspended'
-  | 'done'
-  | 'failed'
-  | 'dead'
-  | 'cancelled';
+export const JOB_STATES = [
+  'ready',
+  'delayed',
+  'running',
+  'suspended',
+  'done',
+  'failed',
+  'dead',
+  'cancelled',
+] as const;
+
+export type JobState = (typeof JOB_STATES)[number];
+
+/** Narrows a state read back off a queue row. Never a cast — the list decides. */
+export const isJobState = (value: string): value is JobState =>
+  (JOB_STATES as readonly string[]).includes(value);
 
 export interface JobRecord {
   readonly id: string;
@@ -114,10 +121,23 @@ export interface NackOptions {
   readonly delayMs: number;
   readonly error?: string;
   /**
-   * False for a suspension (`step.sleep`): parking a run is not a failure and must not burn
-   * a retry attempt, or a 3-day sleep would dead-letter the job.
+   * The ATTEMPT COUNTER, and nothing else. False for a suspension and for a shed alike: neither is
+   * a failure, and a 3-day sleep that burned an attempt would dead-letter the job.
    */
   readonly countsAsAttempt?: boolean;
+  /**
+   * True for a SUSPENSION — `step.sleep`, or a name this deploy does not know — which leaves the
+   * ready bucket and is counted `suspended`. Absent for a limiter or `job.concurrency` shed, which
+   * is a job still WAITING to run.
+   *
+   * The two were one flag until 2026-08: `countsAsAttempt: false` decided the state as well as the
+   * counter, so a shed was filed beside a 3-day sleep and `stats()` excluded it from `ready` and
+   * from `oldestReadyMs` — the two numbers the worker publishes as `queue_depth` and
+   * `queue_oldest_ready_seconds`. Under sustained overload the shed fraction approaches 100%, so
+   * the HPA signal and the "oldest job older than 5 minutes" page both went quiet exactly when the
+   * queue was saturated.
+   */
+  readonly park?: boolean;
   readonly deadLetter?: boolean;
 }
 
@@ -128,7 +148,11 @@ export interface QueueStats {
   readonly running: number;
   readonly suspended: number;
   readonly dead: number;
-  /** Age in ms of the oldest claimable job — the number that decides autoscaling. */
+  /**
+   * Age in ms of the oldest job that is READY and due — the number that decides autoscaling.
+   * Not "claimable": a `suspended` row is claimable once its `runAt` passes and is deliberately
+   * excluded here, which is exactly why a limiter shed may not be filed as a suspension.
+   */
   readonly oldestReadyMs: number;
 }
 

package/src/errors.ts

@@ -23,6 +23,8 @@ export const JOB_OWNED_ERROR_CODES = [
   'X_BACKFILL_RUNNING',
   'X_BACKFILL_STALLED',
   'X_BACKFILL_UNKNOWN',
+  'X_JOB_ROW_STATUS_UNKNOWN',
+  'X_ACTION_JOB_UNBRIDGED',
 ] as const;
 
 /**
@@ -58,6 +60,8 @@ export const JOB_ERROR_TITLES: Readonly<Record<JobOwnedErrorCode, string>> = {
   X_BACKFILL_RUNNING: 'a pass under this name is already live',
   X_BACKFILL_STALLED: 'the sweep ended with rows its own count still matches',
   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',
 };
 
 // One unconditional call, so a second package claiming one of jobs' codes throws
@@ -89,7 +93,8 @@ registerErrorRetry({
   X_BACKFILL_APPLIED: 'terminal',
 });
 
-const docsFor = (code: JobErrorCode): string => `https://ultimate.dev/errors/${code}`;
+/** Shared with `backfill-errors.ts`, which holds the seven `X_BACKFILL_*` classes. */
+export const docsFor = (code: JobErrorCode): string => `https://ultimate.dev/errors/${code}`;
 
 /** An enqueue collided with a live job holding the same idempotency key under `onConflict: 'error'`. */
 export class JobDuplicateError extends UltimateError {
@@ -124,6 +129,57 @@ export class JobNameTakenError extends UltimateError {
   }
 }
 
+/**
+ * A `text` status column holds a value outside the vocabulary this build compiled.
+ *
+ * Refused rather than passed through, because the alternative is what used to happen: the three
+ * decoders in `driver-pg-rows.ts` cast the column, and `stepRun`'s `existing?.status ===
+ * 'completed'` then read false for the laundered value and RE-EXECUTED the step. A second charge
+ * is a worse answer than a failed attempt, and "an unrecognised fact is never a satisfied one" is
+ * the rule the rest of the framework already follows.
+ *
+ * Almost always a NEWER deploy's row, not corruption: a status string only reaches the table
+ * because some version of this framework wrote it. A rolling deploy that only ADDS a status is
+ * safe in the normal direction — the new build knows every old value — and it is the old build
+ * reading the new build's row that lands here, on that one job, loudly.
+ */
+export class JobRowStatusUnknownError extends UltimateError {
+  constructor(input: { table: string; column: string; value: string; known: readonly string[] }) {
+    super({
+      code: 'X_JOB_ROW_STATUS_UNKNOWN',
+      cause:
+        `${input.table}.${input.column} holds "${input.value}", which this build does not know — ` +
+        `it reads ${input.known.join(', ')}`,
+      fix: `x jobs show --json   # then drain the older workers: a status this build cannot read was almost certainly written by a newer deploy`,
+      docs: docsFor('X_JOB_ROW_STATUS_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * `registerJobs()` was handed `someAction.job()`.
+ *
+ * That call answers an `ActionJobHandle` — `kind: 'action-job'`, deliberately a different literal
+ * from `'job'` — which is the four fields `job()` takes, not a job. It cannot be one: `action` and
+ * `jobs` are both tier 3, so neither may import the other, and only `job()` seats a handle the
+ * queue, the worker and the manifest accept.
+ *
+ * Refused BY NAME rather than skipped, which is what used to happen. `registerJobs(module)` is
+ * handed a whole module namespace, so silently ignoring a constant or a helper exported beside a
+ * job is right — but ignoring this one meant `registerJobs({ publishPost: publishPost.job() })`
+ * registered nothing, returned `[]`, and the job never ran, with nothing failing anywhere.
+ */
+export class ActionJobUnbridgedError extends UltimateError {
+  constructor(input: { export: string; job: string }) {
+    super({
+      code: 'X_ACTION_JOB_UNBRIDGED',
+      cause: `export "${input.export}" is the action projection "${input.job}", which is not a job handle and cannot be registered as one`,
+      fix: `wrap it: agentJob(${input.export}, { name: '${input.export}', tenant, retry }) from @ultimat3/ai — that composes job() and returns a handle the queue accepts`,
+      docs: docsFor('X_ACTION_JOB_UNBRIDGED'),
+    });
+  }
+}
+
 /** Two steps in one run share a name, so replay cannot tell their persisted results apart. */
 export class StepDuplicateError extends UltimateError {
   constructor(input: { job: string; step: string }) {
@@ -299,7 +355,7 @@ export class CancelUnsupportedError extends UltimateError {
     super({
       code: 'X_JOB_NOT_CANCELLABLE',
       cause: `the "${input.driver}" jobs driver cannot cancel a single job`,
-      fix: "set jobs: { driver: 'postgres' } in app.config.ts, then: x jobs cancel <id> --json",
+      fix: 'call setJobDriver(createPgDriver()) at boot — only the pg driver implements introspect.cancel — then: x jobs cancel <id> --json',
       docs: docsFor('X_JOB_NOT_CANCELLABLE'),
     });
   }
@@ -316,7 +372,7 @@ export class ConcurrencyUnenforceableError extends UltimateError {
     super({
       code: 'X_JOB_CONCURRENCY_UNENFORCEABLE',
       cause: `${input.jobs.join(', ')} declare concurrency and the "${input.driver}" jobs driver has no lease store, so the cap would hold per process and the fleet would run concurrency x replicas`,
-      fix: `remove concurrency from job("${input.jobs[0] ?? 'the job'}"), or set jobs: { driver: 'postgres' } in app.config.ts`,
+      fix: `remove concurrency from job("${input.jobs[0] ?? 'the job'}"), or call setJobDriver(createPgDriver()) at boot — the pg driver is the one with a lease store`,
       docs: docsFor('X_JOB_CONCURRENCY_UNENFORCEABLE'),
     });
   }
@@ -334,134 +390,6 @@ export class OutboxNoTxError extends UltimateError {
   }
 }
 
-/**
- * The seven backfill codes below all answer one question — "why is this sweep not running?" — and
- * each is here because it sends the reader somewhere different: run it, force it, change
- * environment, migrate first, wait, fix the predicates, or fix the name. A code that shared a fix
- * line with another one would be code inflation, which is why `X_BACKFILL_WRITE_UNCONFIRMED` was
- * considered and rejected: a dry run that wrote nothing did exactly what it was asked to.
- *
- * Every `fix` below is ONE line something can execute — a shell command, or the edit to make.
- * Never a command with prose appended: a `fix:` is copied and run verbatim, so a trailing clause
- * turns a working command into a syntax error at the one moment the reader is following it
- * literally. Explanations belong in `cause`, which is read and never run.
- */
-
-/**
- * Declared and never completed. The alarm the framework did not have: an author could
- * `x g backfill`, merge and deploy, and nothing anywhere said the pass had not run.
- */
-export class BackfillPendingError extends UltimateError {
-  constructor(input: { backfill: string; environment: string }) {
-    super({
-      code: 'X_BACKFILL_PENDING',
-      cause: `backfill "${input.backfill}" is declared and x_backfills holds no completed pass for it in ${input.environment}`,
-      fix: `x db backfill ${input.backfill} --write --json`,
-      docs: docsFor('X_BACKFILL_PENDING'),
-    });
-  }
-}
-
-/** Already swept. A rerun is legitimate, so this names the flag rather than refusing outright. */
-export class BackfillAppliedError extends UltimateError {
-  constructor(input: { backfill: string; runId: string; completedAt: string }) {
-    super({
-      code: 'X_BACKFILL_APPLIED',
-      cause: `backfill "${input.backfill}" completed as run ${input.runId} at ${input.completedAt}; a forced rerun writes a NEW ledger row and never edits that one`,
-      fix: `x db backfill ${input.backfill} --write --force --json`,
-      docs: docsFor('X_BACKFILL_APPLIED'),
-    });
-  }
-}
-
-/**
- * The declaration names the environments it belongs to and this is not one. Declared DATA, never a
- * hardcoded "cleanups are production": a staging rehearsal is correct practice, so which
- * environments a sweep belongs to is the app's convention and this is only the mechanism carrying
- * it (axiom 8).
- */
-export class BackfillEnvironmentError extends UltimateError {
-  constructor(input: { backfill: string; environment: string; declared: readonly string[] }) {
-    // The first declared environment, because the fix has to be ONE runnable line and the list is
-    // ordered by the author. The empty case cannot arise from `checkBackfillEnvironment`, which
-    // treats an empty list as "every environment" — but this constructor is public, so it answers
-    // with the command that lists what IS declared rather than an `ULTIMATE_ENV=undefined`.
-    const target = input.declared[0];
-    super({
-      code: 'X_BACKFILL_ENVIRONMENT',
-      cause: `backfill "${input.backfill}" declares environments: ${input.declared.join(', ')} and this process resolved ${input.environment} — add "${input.environment}" to that list if this deploy should sweep too`,
-      fix:
-        target === undefined
-          ? 'x db backfill --pending --json'
-          : `ULTIMATE_ENV=${target} x db backfill ${input.backfill} --write --json`,
-      docs: docsFor('X_BACKFILL_ENVIRONMENT'),
-    });
-  }
-}
-
-/**
- * `requires` names a migration the ledger has not applied. Checked where `x_migrations` is
- * readable — this package holds no `@ultimat3/db` dependency and growing one to read a ledger
- * would put the migration engine on the tier-3 queue's import graph.
- */
-export class BackfillMigrationPendingError extends UltimateError {
-  constructor(input: { backfill: string; migration: string }) {
-    super({
-      code: 'X_BACKFILL_MIGRATION_PENDING',
-      cause: `backfill "${input.backfill}" requires migration ${input.migration}, which x_migrations does not record as applied`,
-      fix: 'x db migrate --json',
-      docs: docsFor('X_BACKFILL_MIGRATION_PENDING'),
-    });
-  }
-}
-
-/**
- * The enqueue deduped: one live pass per name, so this run is the one already going. Distinct from
- * `X_BACKFILL_APPLIED`, which is a pass that finished — the response there is `--force`, and the
- * response here is to look at the run that is holding the key.
- */
-export class BackfillRunningError extends UltimateError {
-  constructor(input: { backfill: string; jobId: string }) {
-    super({
-      code: 'X_BACKFILL_RUNNING',
-      cause: `backfill "${input.backfill}" already has a live pass queued as ${input.jobId}, and one name holds one live pass; its step trace names the batch it is on, and a pass that is not advancing is a worker that lost its lease`,
-      fix: `x jobs show ${input.jobId} --json`,
-      docs: docsFor('X_BACKFILL_RUNNING'),
-    });
-  }
-}
-
-/**
- * The source ran out of rows and the declaration's own `count()` still matches some. Two
- * predicates that disagree is an authoring bug in any business — the sweep reported success over
- * rows it never visited — so the pass fails rather than writing a completed row nobody can trust.
- */
-export class BackfillStalledError extends UltimateError {
-  constructor(input: { backfill: string; remaining: number; swept: number }) {
-    super({
-      code: 'X_BACKFILL_STALLED',
-      cause: `backfill "${input.backfill}" swept ${input.swept} rows, exhausted its source, and count() still matches ${input.remaining} — a WHERE the sweep narrows and the count does not is what leaves rows behind`,
-      fix: `make count() select on exactly what source() selects on in backfill("${input.backfill}")`,
-      docs: docsFor('X_BACKFILL_STALLED'),
-    });
-  }
-}
-
-/** A name no declaration in this app carries — a typo, or a backfill whose module was deleted. */
-export class BackfillUnknownError extends UltimateError {
-  constructor(input: { backfill: string; known: readonly string[] }) {
-    super({
-      code: 'X_BACKFILL_UNKNOWN',
-      cause:
-        input.known.length === 0
-          ? `no backfill named "${input.backfill}" is declared, and this app declares none at all`
-          : `no backfill named "${input.backfill}" is declared (declared: ${input.known.join(', ')})`,
-      fix: 'x db backfill --pending --json',
-      docs: docsFor('X_BACKFILL_UNKNOWN'),
-    });
-  }
-}
-
 export class JobsNotImplementedError extends UltimateError {
   constructor(input: { feature: string; fix: string }) {
     super({

package/src/execute.ts

@@ -1,5 +1,7 @@
 // One claimed job run to completion, suspension or failure and settled with the driver — the
-// single execution path the worker loop and `x jobs run` share. It owns the run's deadline, and
+// single execution path, shared by the worker loop (`worker-run.ts`) and by the one caller outside
+// this package, `@ultimat3/testing`'s job fixture. There is no `x jobs run` to share it with: the
+// subcommands are `ls`, `show`, `retry`, `cancel`, `drain`. It owns the run's deadline, and
 // a deadline here means CANCEL: the nack that follows makes the job claimable again, so a body
 // still running past it would be a second copy of one job, racing the attempt that replaced it.
 
@@ -87,7 +89,8 @@ export interface ExecuteJobOptions {
 
 /**
  * Run one claimed job to completion, suspension or failure, and settle it with the driver.
- * Shared by the worker loop and `x jobs run` so both take exactly the same code path.
+ * Shared by the worker loop and by `@ultimat3/testing`'s job fixture, so a job under test takes
+ * exactly the code path the worker takes.
  */
 export async function executeJob(options: ExecuteJobOptions): Promise<JobExecution> {
   const { driver, claimed, handle } = options;
@@ -159,8 +162,10 @@ export async function executeJob(options: ExecuteJobOptions): Promise<JobExecuti
   } catch (error) {
     if (isStepSuspension(error)) {
       const delayMs = Math.max(0, error.resumeAt - nowMs(options.clock));
-      // countsAsAttempt: false — parking a run is not a failure.
-      await driver.nack(claimed.id, { delayMs, countsAsAttempt: false });
+      // `park: true` is the suspension itself — the row leaves the ready bucket — and
+      // `countsAsAttempt: false` only says not to burn an attempt on it. A limiter shed passes the
+      // second and not the first: it is a job still waiting, and it belongs in `queue_depth`.
+      await driver.nack(claimed.id, { delayMs, countsAsAttempt: false, park: true });
       return settle({
         outcome: 'suspended',
         jobId: claimed.id,
@@ -200,8 +205,8 @@ export async function executeJob(options: ExecuteJobOptions): Promise<JobExecuti
     // This package's ONE error-reporting call site, and it is here rather than in the loop because
     // this is the only frame that still holds the thrown value — the loop sees a message string.
     // A retry is a failure the framework recovered from, so it is a `warning`; a dead letter is
-    // one nobody recovered from. `x jobs run` takes this path too, which is the point: one
-    // execution path means one place a failed job can become visible.
+    // one nobody recovered from. A job driven by `@ultimat3/testing`'s fixture takes this path
+    // too, which is the point: one execution path means one place a failed job becomes visible.
     reportError(error, {
       source: 'job',
       severity: decision.retry ? 'warning' : 'error',

package/src/index.ts

@@ -17,6 +17,15 @@ export type {
   BackfillReport,
 } from './backfill';
 export { backfill, DEFAULT_BACKFILL_BATCH } from './backfill';
+export {
+  BackfillAppliedError,
+  BackfillEnvironmentError,
+  BackfillMigrationPendingError,
+  BackfillPendingError,
+  BackfillRunningError,
+  BackfillStalledError,
+  BackfillUnknownError,
+} from './backfill-errors';
 export type { BackfillGate, BackfillGateInput } from './backfill-gate';
 export { checkBackfillEnvironment, gateBackfill } from './backfill-gate';
 export type { BackfillProgress } from './backfill-inspect';
@@ -77,11 +86,13 @@ export type {
 export {
   DEFAULT_QUEUE,
   DEFAULT_VISIBILITY_TIMEOUT_MS,
+  isJobState,
+  JOB_STATES,
   jobDriver,
   resetJobDriver,
   setJobDriver,
 } from './driver';
-export type { MemoryDriverOptions } from './driver-memory';
+export type { MemoryDriverOptions, MemoryJobDriver } from './driver-memory';
 export { createMemoryDriver } from './driver-memory';
 export type { NatsDriverOptions } from './driver-nats';
 export { createNatsDriver } from './driver-nats';
@@ -121,13 +132,7 @@ export type { RedisDriverOptions } from './driver-redis';
 export { createRedisDriver } from './driver-redis';
 export type { JobErrorCode } from './errors';
 export {
-  BackfillAppliedError,
-  BackfillEnvironmentError,
-  BackfillMigrationPendingError,
-  BackfillPendingError,
-  BackfillRunningError,
-  BackfillStalledError,
-  BackfillUnknownError,
+  ActionJobUnbridgedError,
   CancelUnsupportedError,
   ConcurrencyUnenforceableError,
   DriverUnavailableError,
@@ -139,6 +144,7 @@ export {
   JobMaxAttemptsError,
   JobNameTakenError,
   JobNotCancellableError,
+  JobRowStatusUnknownError,
   JobSlotLostError,
   JobsNotImplementedError,
   JobTenantRequiredError,
@@ -248,8 +254,10 @@ export type {
 export {
   createMemoryStepStore,
   createStepRunner,
+  isStepStatus,
   isStepSuspension,
   MAX_TRACE_NAMES,
+  STEP_STATUSES,
   StepSuspension,
 } from './steps';
 export type {

package/src/inspect.ts

@@ -91,7 +91,7 @@ function requireIntrospection(driver: JobDriver): NonNullable<JobDriver['introsp
   if (driver.introspect === undefined) {
     throw new JobsNotImplementedError({
       feature: `introspection for the "${driver.name}" jobs driver`,
-      fix: "set jobs: { driver: 'postgres' } in app.config.ts, then: x jobs ls --json",
+      fix: 'call setJobDriver(createPgDriver()) at boot — only the pg driver implements introspect — then: x jobs ls --json',
     });
   }
   return driver.introspect;

package/src/metrics.ts

@@ -18,7 +18,7 @@ import { gauge } from '@ultimat3/core';
 /** Seconds and not milliseconds: every Prometheus duration is seconds, and the alert is `> 300`. */
 export const queueOldestReady: Gauge = gauge('queue_oldest_ready_seconds', {
   unit: 's',
-  description: 'Age of the oldest claimable job, by queue — 0 when the queue is empty',
+  description: 'Age of the oldest job that is ready and due, by queue — 0 when none is',
 });
 
 export const queueDeadJobs: Gauge = gauge('queue_dead_jobs', {

package/src/outbox.ts

@@ -338,7 +338,7 @@ export function jobsFacade(): JobsFacade {
           throw new DriverUnavailableError({
             driver: 'none',
             cause: 'no queue driver is installed in this process',
-            fix: 'call setJobDriver(createMemoryDriver()) before enqueuing — or set jobs.driver in app.config.ts and run `x dev`',
+            fix: 'call setJobDriver(createMemoryDriver()) before enqueuing, or setJobDriver(createPgDriver()) for a real queue',
           });
         }
         return installed;

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/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),

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);
   }

package/src/worker.ts

@@ -161,6 +161,26 @@ export function createWorker(options: WorkerOptions): Worker {
       ...(options.events === undefined ? {} : { events: options.events }),
     });
 
+  /**
+   * A claimed job handed straight back over a cap. It is NOT a suspension and NOT a failure: no
+   * `park`, so the row stays where `queue_depth` and `queue_oldest_ready_seconds` can see it, and
+   * no `error`, so `x jobs show` does not report a `lastError` for a job that never ran. It was
+   * both of those until 2026-08 — parked beside a 3-day `step.sleep`, and stamped with a failure
+   * it never had — which is why the two sheds go through one function now.
+   */
+  const shed = async (
+    claimed: ClaimedJob,
+    detail: { readonly queue: string; readonly reason: string },
+  ): Promise<void> => {
+    logger.debug('jobs.worker.shed', {
+      workerId,
+      job: claimed.name,
+      jobId: claimed.id,
+      ...detail,
+    });
+    await options.driver.nack(claimed.id, { delayMs: pollIntervalMs, countsAsAttempt: false });
+  };
+
   /** The drain's one question: may this worker still take work off the queue? */
   const claiming = (): boolean => state !== 'draining' && state !== 'stopped';
 
@@ -196,11 +216,17 @@ export function createWorker(options: WorkerOptions): Worker {
           ...(job.tenantId === undefined ? {} : { tenantId: job.tenantId }),
         });
         if (lease === undefined) {
-          // Over a tenant/queue/global cap: hand it straight back for another worker.
-          await options.driver.nack(job.id, {
-            delayMs: pollIntervalMs,
-            countsAsAttempt: false,
-            error: `limited: ${limiter.blockedBy({ queue, ...(job.tenantId === undefined ? {} : { tenantId: job.tenantId }) }) ?? 'unknown'}`,
+          // Over a tenant/queue/global cap: hand it straight back for another worker. No `park`
+          // and no `error` — the row stays in the ready bucket the depth gauge reads, and nothing
+          // about this job failed, so `x jobs show` must not report a `lastError` for it. The
+          // reason is a log FIELD instead, where it costs nothing when nobody is asking.
+          await shed(job, {
+            queue,
+            reason:
+              limiter.blockedBy({
+                queue,
+                ...(job.tenantId === undefined ? {} : { tenantId: job.tenantId }),
+              }) ?? 'unknown',
           });
           continue;
         }
@@ -223,10 +249,9 @@ export function createWorker(options: WorkerOptions): Worker {
         }
         if (!granted) {
           lease.release();
-          await options.driver.nack(job.id, {
-            delayMs: pollIntervalMs,
-            countsAsAttempt: false,
-            error: `limited: job concurrency (${getJob(job.name)?.concurrency ?? 0})`,
+          await shed(job, {
+            queue,
+            reason: `job concurrency (${getJob(job.name)?.concurrency ?? 0})`,
           });
           continue;
         }