@ultimat3/jobs 25.2.0 → 26.1.0

package/README.md

@@ -293,7 +293,7 @@ report a different number:
 | Surface | Shows |
 |---|---|
 | `x db backfill --list` | the whole ledger, `--name` / `--status` / `--limit`, and `--json` |
-| `x jobs ls` | the passes **in flight** — rows so far and cursor, beside the queue depth |
+| `x jobs list` | the passes **in flight** — rows so far and cursor, beside the queue depth |
 | `x jobs show <id>` | the ledger row for that run, under `backfill` (`null` for any other job) |
 | `/_x` → jobs | the whole ledger plus a live count, alongside the queues and the step traces |
 
@@ -568,7 +568,7 @@ re-exports (`X_HELPER_COPY`). Same argument `timing-safe-equal.ts` makes for its
 **Upgrading a webhook to `tenant: ({ orgId }) => orgId`.** Deliveries already queued without an
 `orgId` dead-letter on their next attempt with `X_JOB_TENANT_MISMATCH`, and a retry cannot add the
 field. Drain the queue before deploying the new declaration, or re-enqueue what dead-letters with its
-org: `x jobs ls --state dead --name partner.webhooks --json`, then `deliver.enqueue({ endpointId, eventId, orgId })` for each.
+org: `x jobs list --state dead --name partner.webhooks --json`, then `deliver.enqueue({ endpointId, eventId, orgId })` for each.
 
 **Set `timeout` below the drain budget.** A webhook has no timeout unless you declare one, and a
 POST on the wire when SIGTERM lands runs until the receiver answers. With a `timeout`, a drained
@@ -1195,7 +1195,7 @@ export const syncAccountWatched = job({
 |---|---|
 | a retry, a `step.sleep` / `waitForEvent`, a drain | nobody: the run has not ended |
 | `cancelJob()` / `x jobs cancel` on a queued or running row | the caller of the cancel — the worker's own settle then matches nothing |
-| `x jobs retry`, `rm`, `promote`, `drain` | the operator; a retried run settles again, and is told again |
+| `x jobs retry`, `delete`, `promote`, `drain` | the operator; a retried run settles again, and is told again |
 | a settle that did not land — the lease lapsed and the queue re-delivered | the claim that holds the row now |
 
 | Guarantee | Stated plainly |
@@ -1254,13 +1254,13 @@ FOR a user takes that user's id in its input and re-authorises it in the body.
 | `X_JOB_LEASE_LOST` | the job was cancelled, or its lease lapsed and the queue re-delivered it, while this worker was still running it |
 | `X_JOB_SLOT_LOST` | the fleet `concurrency` slot this run held was taken by another worker — a different row on a different clock from the lease above |
 | `X_JOB_NOT_CANCELLABLE` | `cancelJob` reached a job that is not live — done, failed, dead or already cancelled — an id no queue holds, or a driver with no `cancel` |
-| `X_JOB_NOT_FOUND` | `requeue` was asked for an id the queue does not hold — one answer on both drivers. Fix: `x jobs ls --json` |
+| `X_JOB_NOT_FOUND` | `requeue` was asked for an id the queue does not hold — one answer on both drivers. Fix: `x jobs list --json` |
 | `X_JOB_CONCURRENCY_UNENFORCEABLE` | a registered job declares `concurrency`, plain or keyed, and the driver has no lease store |
-| `X_JOB_KEY_BUSY` | a run claimed under `whenBusy: 'fail'` while its key already held `limit` runs. Classified `terminal`. Fix: `x jobs ls --name <job> --state running --json` |
+| `X_JOB_KEY_BUSY` | a run claimed under `whenBusy: 'fail'` while its key already held `limit` runs. Classified `terminal`. Fix: `x jobs list --name <job> --state running --json` |
 | `X_JOB_DECLARATION_INVALID` | `job()` is missing a required field, declares a `concurrency` no worker can honour (plain or keyed), or its `concurrency.key` answered an empty, non-string or over-long key at enqueue |
 | `X_JOB_NOT_REMOVABLE` | `remove` / `removeMany` reached a running job. Fix: `x jobs cancel <id> --json` |
 | `X_JOB_NOT_PROMOTABLE` | `promote` reached a job not waiting on its run time |
-| `X_JOB_PAGE_INVALID` | `list()` was asked for more than `MAX_JOB_PAGE` rows, or handed a cursor no page produced. The cause names which cursor (`after` / `before`). Fix: `x jobs ls --limit 200 --json` |
+| `X_JOB_PAGE_INVALID` | `list()` was asked for more than `MAX_JOB_PAGE` rows, or handed a cursor no page produced. The cause names which cursor (`after` / `before`). Fix: `x jobs list --limit 200 --json` |
 | `X_JOB_ON_SETTLED_FAILED` | a declared `onSettled` threw on every one of its tries; logged and reported, never thrown |
 | `X_NOT_IMPLEMENTED` | introspection or the operator surface on a driver with no `introspect` (a hand-rolled one) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "25.2.0",
+  "version": "26.1.0",
   "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
   "license": "MIT",
   "type": "module",
@@ -32,10 +32,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.2.0",
-    "@ultimat3/db": "25.2.0",
-    "@ultimat3/entity": "25.2.0",
-    "@ultimat3/schema": "25.2.0",
-    "@ultimat3/time": "25.2.0"
+    "@ultimat3/core": "26.1.0",
+    "@ultimat3/db": "26.1.0",
+    "@ultimat3/entity": "26.1.0",
+    "@ultimat3/schema": "26.1.0",
+    "@ultimat3/time": "26.1.0"
   }
 }

package/src/backfill-inspect.ts

@@ -44,7 +44,7 @@ export function toBackfillProgress(run: BackfillRun): BackfillProgress {
 
 /**
  * Every pass the ledger holds, newest first. An EMPTY list on a driver that ships no ledger, and
- * deliberately not a throw: `x jobs ls` and the jobs panel report the queue, and a queue that
+ * deliberately not a throw: `x jobs list` and the jobs panel report the queue, and a queue that
  * answers everything except "no backfills recorded" is a broken command for a fact nobody asked
  * about. `x db backfill --list` says so in its own summary instead, where it IS the question.
  */

package/src/driver-pg-jobs-sql.ts

@@ -1,7 +1,7 @@
 // Every statement returning a WHOLE `x_jobs` row, and the one column list they share. They ask
 // Postgres for epoch ms because `select *` left the decoding to the client's type map: one with
 // none decodes `timestamptz` as TEXT, so `toJobRecord` read `Number('2026-01-01 00:00:00+00')`
-// and `x jobs ls` / `show` / `cancel` printed `NaN` for every timestamp.
+// and `x jobs list` / `show` / `cancel` printed `NaN` for every timestamp.
 
 import { JOBS_WAKE_CHANNEL } from './driver-pg-wake-sql';
 

package/src/driver.ts

@@ -389,7 +389,7 @@ export const assertClaimQueues = (driver: string, options: ClaimOptions): void =
  * both drivers already answer it identically. `visibilityTimeoutMs` is a DURATION, so it is
  * screened for finiteness alone, the same rule `worker-options.ts` applies to the same knob: it is
  * on this list because `visibleAt = at + NaN` is never `<= now`, which turns at-least-once into
- * never on a row `x jobs ls` still prints as `running`.
+ * never on a row `x jobs list` still prints as `running`.
  */
 export const assertClaimBounds = (driver: string, options: ClaimOptions): void => {
   finiteCount(`the ${driver} driver claim`, 'limit', options.limit);

package/src/errors-concurrency.ts

@@ -67,8 +67,8 @@ export class JobKeyBusyError extends UltimateError {
       // still goes through `renderFixShellArg` — the screen `bun run error-render` looks for —
       // whose placeholder the guard above makes unreachable.
       fix: isFixShellSafe(input.job)
-        ? `x jobs ls --name ${renderFixShellArg(input.job, 'job')} --state running --json`
-        : 'x jobs ls --state running --json',
+        ? `x jobs list --name ${renderFixShellArg(input.job, 'job')} --state running --json`
+        : 'x jobs list --state running --json',
       meta: { job: input.job, key: input.key, limit: input.limit },
     });
   }

package/src/errors-operator.ts

@@ -9,7 +9,7 @@ import { isFixShellSafe, renderFixShellArg, renderThrowable, UltimateError } fro
 const jobCommand = (verb: string, jobId: string): string =>
   isFixShellSafe(jobId)
     ? `x jobs ${verb} ${renderFixShellArg(jobId, 'id')} --json`
-    : 'x jobs ls --state running --json';
+    : 'x jobs list --state running --json';
 
 /** `remove()` / `removeMany()` reached a job a worker holds. Cancel stops the body; then remove. */
 export class JobNotRemovableError extends UltimateError {
@@ -22,7 +22,7 @@ export class JobNotRemovableError extends UltimateError {
           : `job ${input.jobId} is running, and deleting the row under its body would not stop the body`,
       fix:
         input.jobId === undefined
-          ? 'x jobs ls --state running --json'
+          ? 'x jobs list --state running --json'
           : jobCommand('cancel', input.jobId),
       meta: { ...(input.jobId === undefined ? {} : { jobId: input.jobId }) },
     });
@@ -92,7 +92,7 @@ export class JobPageInvalidError extends UltimateError {
         input.limit === undefined
           ? `${input.subject} was handed ${cursor === 'after' ? 'an after' : 'a before'} cursor that no page produced — ${cursor}: ${source} of a page this driver answered is the only one it reads; omit it for the first page`
           : `${input.subject} limit is ${input.limit}, over MAX_JOB_PAGE (${input.maxPage}) — the rows one page may answer; walk further with after: jobCursor(lastRow), and stop at a page shorter than its limit`,
-      fix: `x jobs ls --limit ${renderFixShellArg(String(input.maxPage), '200')} --json`,
+      fix: `x jobs list --limit ${renderFixShellArg(String(input.maxPage), '200')} --json`,
       meta: {
         maxPage: input.maxPage,
         ...(input.limit === undefined ? {} : { limit: input.limit }),

package/src/errors-requeue.ts

@@ -31,7 +31,7 @@ export class JobNotFoundError extends UltimateError {
     super({
       code: 'X_JOB_NOT_FOUND',
       cause: `the "${input.driver}" queue holds no job with id ${renderCauseValue(input.jobId)} — a mistyped id, a job removed since, or an id from another environment`,
-      fix: 'x jobs ls --json',
+      fix: 'x jobs list --json',
       meta: { jobId: input.jobId },
     });
   }

package/src/errors.ts

@@ -196,7 +196,7 @@ export class JobNameTakenError extends UltimateError {
     super({
       code: 'X_JOB_DUPLICATE',
       cause: `two ${input.kind}s claim the name "${input.name}"`,
-      fix: `x jobs ls --json names the one already seated; rename the other's export, or its "name:" if it declares one — a ${input.kind} name is a durable queue key and is globally unique`,
+      fix: `x jobs list --json names the one already seated; rename the other's export, or its "name:" if it declares one — a ${input.kind} name is a durable queue key and is globally unique`,
     });
   }
 }
@@ -434,7 +434,7 @@ export class JobNotCancellableError extends UltimateError {
         input.state === 'missing'
           ? `no job ${input.jobId} exists in this queue`
           : `job ${input.jobId} is "${input.state}" and only a job that has not finished can be cancelled`,
-      fix: `x jobs ls --state running --json`,
+      fix: `x jobs list --state running --json`,
     });
   }
 }

package/src/inspect-operator.ts

@@ -12,7 +12,7 @@ function operatorOf(driver: JobDriver): JobIntrospection {
   if (driver.introspect === undefined) {
     throw new NotImplementedError({
       cause: `the operator surface of the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
-      fix: 'call setJobDriver(postgresJobDriver()) at boot — the pg driver implements introspect — then: x jobs ls --json',
+      fix: 'call setJobDriver(postgresJobDriver()) at boot — the pg driver implements introspect — then: x jobs list --json',
     });
   }
   return driver.introspect;

package/src/inspect.ts

@@ -114,7 +114,7 @@ function requireIntrospection(driver: JobDriver): NonNullable<JobDriver['introsp
   if (driver.introspect === undefined) {
     throw new NotImplementedError({
       cause: `introspection for the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
-      fix: 'call setJobDriver(postgresJobDriver()) at boot — only the pg driver implements introspect — then: x jobs ls --json',
+      fix: 'call setJobDriver(postgresJobDriver()) at boot — only the pg driver implements introspect — then: x jobs list --json',
     });
   }
   return driver.introspect;

package/src/metrics.ts

@@ -22,7 +22,7 @@ import type { JobOutcome } from './execute';
  * `step.sleep` read as a finished job and make the failure ratio meaningless. `interrupted` for
  * the same reason: a deploy cutting a job short is the process's doing, and a failure ratio that
  * spikes on every rollout is a page nobody answers. `refused` is `failed` because the ROW is: the
- * counter says what `x jobs ls --state failed` says, and never `dead` — a key refusal is not in
+ * counter says what `x jobs list --state failed` says, and never `dead` — a key refusal is not in
  * the dead-letter queue, so it must not move the gauge beside this one. Read by the worker's
  * `recordJob` sites.
  */

package/src/scheduler-pg.ts

@@ -146,7 +146,7 @@ export function postgresLeaseLeader(options: PostgresLeaseLeaderOptions): Leader
   };
 }
 
-/** Exposed so a test — and `x jobs ls` — can say which node currently holds the lease. */
+/** Exposed so a test — and `x jobs list` — can say which node currently holds the lease. */
 export async function currentLeader(
   executor: PgExecutor,
   lockKey = 'scheduler',

package/src/webhook-errors.ts

@@ -122,7 +122,7 @@ export class WebhookDeliveryFailedError extends UltimateError {
     super({
       code: 'X_WEBHOOK_DELIVERY_FAILED',
       cause: `webhook "${input.webhook}" delivery to ${webhookTarget(input.url)} ${answer}: ${input.detail}`,
-      fix: 'no edit here — the job retries on its declared backoff; watch the endpoint with x jobs ls --json and fix the receiver before it reaches disableAfter',
+      fix: 'no edit here — the job retries on its declared backoff; watch the endpoint with x jobs list --json and fix the receiver before it reaches disableAfter',
       meta: { endpointId: input.endpointId, status: input.status },
     });
   }

package/src/worker-options.ts

@@ -7,7 +7,7 @@
 // value arrives at a lease deadline, a claim limit and a timer interval intact, and every
 // comparison against it reads FALSE — measured on `memoryJobDriver`: `visibleAt = at + NaN`,
 // the reclaim scan asks `visibleAt <= at`, and a job whose worker died is never claimable again.
-// At-least-once becomes never, with no error and a row `x jobs ls` still prints as `running`.
+// At-least-once becomes never, with no error and a row `x jobs list` still prints as `running`.
 // `slice(0, NaN)` is `[]`, so a `concurrency: NaN` worker claims nothing and reports healthy.
 // Same shape as `concurrencyLimiter`'s `maxTenants` and `backfill()`'s `batch`, refused the same way.
 

package/src/worker-registry.ts

@@ -113,6 +113,6 @@ export function reportUnregisteredQueues(workerId: string, queues: readonly stri
   logger.info('jobs.worker.queue-unregistered', {
     workerId,
     queues: unnamed,
-    fix: 'remove the queue from jobs.queues in app.config.ts, or set queue on the job that should run there — x jobs ls --json shows what each queue holds',
+    fix: 'remove the queue from jobs.queues in app.config.ts, or set queue on the job that should run there — x jobs list --json shows what each queue holds',
   });
 }