@ultimat3/jobs 27.2.3 → 27.4.0

package/CLAUDE.md

@@ -64,8 +64,9 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   what a second call would move.**
 - **No read returns a WHOLE row** — `driver-pg-sql.test.ts` scans every production file here
   (discovered, comments stripped) for `select *`/`returning *`.
-- Drivers implement the six `JobDriver` methods plus optional `introspect`, `backfills`, `leases`. New
-  capabilities go behind the interface. `inspect.ts` returns plain JSON for CLI, `/_x` and MCP.
+- Drivers: the six `JobDriver` methods plus optional `introspect`, `backfills`, `leases`; new
+  capabilities go behind the interface. **`redisJobDriver`** (`@ultimat3/jobs/redis`, off the
+  barrel) is one Lua script per operation: a semantic change lands in memory, pg AND the scripts.
 - Step results are persisted BEFORE the step returns. All time is epoch ms (`nowMs()`, `clock.ts`).
 - **`postgresLeader` is correct only on a DEDICATED connection**; boot uses `postgresLeaseLeader`.
 
@@ -75,8 +76,7 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   `finiteCount()` (a count, caller's minimum); `worker-options.ts` is where `jobWorker` reads them.
   **`bun run finite-bounds` is a floor, never proof**: `concurrencyLimiter`'s five numbers are screened
   with min 0 (zero is a HARD STOP). **A row count is `finiteCount` (min 0)**; `retry.attempts` is one with min 1.
-- **`WorkerOptions.concurrency` is read by OWN key** — a queue named `constructor`
-  (`worker-slots.test.ts`).
+- **`WorkerOptions.concurrency` is read by OWN key** (`worker-slots.test.ts`).
 - **`job.concurrency` is enforced by `JobDriver.leases`** (one row per held slot in `x_job_leases`);
   `limits.ts` is the per-process fast path. No lease store + a declared `concurrency` makes `start()`
   throw `X_JOB_CONCURRENCY_UNENFORCEABLE`.
@@ -110,7 +110,7 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   synchronously with its guard.
 - **A fleet slot is taken INSIDE a `try`, released AWAITED, and HELD, not owned**: `false`, or a TTL
   with no renewal landing, CANCELS the run (`X_JOB_SLOT_LOST`); held per job id as a LIST.
-- **The run's signal is a controller this worker owns** (`run-signal.ts`), never `AbortSignal.any`.
+- **The run's signal is a controller this worker owns** (`run-signal.ts`).
 - **A lease is HELD, not owned** (`heartbeat.ts`): one failed renewal warns; a whole window without
   one landing is `jobs.lease.lost`, on this process's clock, asked both sides of the call.
 - **A renewal is decided against `stopped()`** (`renewal-timer.ts`, re-read after every await); the
@@ -135,7 +135,7 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 - **A lease for a run that never STARTED is `abandon()`ed, never `release()`d** — the rate stamp
   goes with it (`worker-admit.ts`). **A failed pass re-arms at the floor** (`worker-loop.ts`
   catch); `timers` is the test seam.
-- **Every timer body catches before it finalises** (`void work().catch(log).finally(...)`).
+- **Every timer body catches before it finalises.**
 - **Suspension is control flow, and a SHED is not a suspension**: `StepSuspension` →
   `nack({ countsAsAttempt: false, park: true })`; a shed is `countsAsAttempt: false` without `park`,
   stays `ready`, logs `jobs.worker.shed` (no `last_error`). `driver-parity.test.ts`.

package/README.md

@@ -759,10 +759,20 @@ between them — swapping is `setJobDriver(other)`, and there is **no `jobs.driv
 | Driver | Status | Backing | Use |
 |---|---|---|---|
 | `pg` | **default** | `SELECT ... FOR UPDATE SKIP LOCKED`, a partial unique index on `(name, coalesce(tenant_id, ''), idempotency_key)` over live rows (`x_jobs_name_tenant_idempotency_live_idx`), lease-based leader, `x_job_leases` | zero-infra start, most apps |
+| `redis` | complete, `As of 2026-10` | `Bun.redis`; one Lua script per operation, every key in one `{hash tag}` slot | a queue off the database; no `introspect`, `backfills` or `leases` |
 | `memory` | complete | in-process maps | `x dev`, tests |
 
-There is **no NATS or Redis jobs driver**: `createNatsDriver` and `createRedisDriver`, all-throw
-stubs, were deleted in 25.0.0. A real `redisJobDriver()` would arrive as a minor.
+**`redisJobDriver({ client?, prefix?, clock?, doneTtlMs? })`** passes `@ultimat3/testing`'s
+`jobDriverConformance`, the suite the other two pass, and `driver-redis.live.test.ts` runs one
+script of operations on it and on the memory driver and compares every answer. Installed with
+`setJobDriver(redisJobDriver())` (or `ServeOptions.runtime.jobs`), imported from its own entry
+`@ultimat3/jobs/redis` so the barrel every role boots carries none of it; `Bun.redis` reads `REDIS_URL`.
+What it does not carry: `introspect` (so `x jobs show`/`retry`/`cancel` and queue pauses answer
+for Postgres only), `backfills`, and `leases` — a job declaring `concurrency` refuses
+`jobWorker().start()` (`X_JOB_CONCURRENCY_UNENFORCEABLE`). A `done` row and its steps expire
+after `doneTtlMs` (a week; `0` keeps them); `dead` and `failed` rows are kept. The outbox still
+stages in Postgres — the relay publishes committed rows onto it with their ids. The NATS stub
+deleted in 25.0.0 stays deleted.
 
 The pg SQL lives verbatim in `src/driver-pg-*sql.ts` (`SQL_CLAIM`, `SQL_ENQUEUE`, `SQL_NACK`, …)
 so an agent debugging a stuck queue can read and run the exact statement. The barrel exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "27.2.3",
+  "version": "27.4.0",
   "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./redis": "./src/driver-redis.ts"
   },
   "files": [
     "src",
@@ -32,10 +33,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.2.3",
-    "@ultimat3/db": "27.2.3",
-    "@ultimat3/entity": "27.2.3",
-    "@ultimat3/schema": "27.2.3",
-    "@ultimat3/time": "27.2.3"
+    "@ultimat3/core": "27.4.0",
+    "@ultimat3/db": "27.4.0",
+    "@ultimat3/entity": "27.4.0",
+    "@ultimat3/schema": "27.4.0",
+    "@ultimat3/time": "27.4.0"
   }
 }

package/src/driver-redis-scripts.ts

@@ -0,0 +1,231 @@
+// The Redis job driver's statements: one Lua script per queue operation, so each runs atomically
+// on the server the way each `driver-pg-sql.ts` statement runs in one transaction. The TypeScript
+// that binds their arguments, and the key layout they share, is `driver-redis.ts`.
+//
+// Every key a script touches carries the namespace's `{hash tag}`, so all of them live in ONE slot
+// and a script is legal on Redis Cluster and Dragonfly alike: `KEYS[1]` is always a namespaced key,
+// which is what routes the call, and the others are built from `ARGV[1]` inside the slot it named.
+
+import { LEASE_LAPSED_FINAL_ATTEMPT } from './driver';
+
+/**
+ * The live states as a Lua set, the four `LIVE_STATES` names — the idempotency namespace holds a
+ * key only while one of them does, exactly as `x_jobs_name_tenant_idempotency_live_idx` does.
+ */
+const LIVE = `local LIVE = { ready = true, delayed = true, running = true, suspended = true }`;
+
+/**
+ * The claim fence `SQL_ACK` carries: the row is `running`, held by this worker, under this claim.
+ * `ARGV[1]` namespace, `ARGV[2]` id, `ARGV[3]` worker, `ARGV[4]` claim ordinal.
+ */
+const FENCE = `
+local P = ARGV[1]
+local id = ARGV[2]
+local job = P .. ':job:' .. id
+local held = redis.call('HMGET', job, 'state', 'claimedBy', 'claim', 'queue', 'nk', 'runId')
+if held[1] ~= 'running' or held[2] ~= ARGV[3] or held[3] ~= ARGV[4] then return 0 end
+local queue = held[4]
+redis.call('HDEL', job, 'visibleAt', 'claimedBy')
+redis.call('ZREM', P .. ':run:' .. queue, id)
+`;
+
+/**
+ * `ARGV`: namespace, id, name, queue, input, idempotency key, runId, maxAttempts, runAt, now,
+ * tenant, traceparent, enqueuedBy, namespace field. Answers `{ outcome, id, runId }`: `published`
+ * when the caller-allocated id already names a row (`SQL_ENQUEUE`'s `not exists`), `deduped` when
+ * a live row holds the key, `created` otherwise.
+ */
+export const REDIS_ENQUEUE = `
+${LIVE}
+local P = ARGV[1]
+local id = ARGV[2]
+local job = P .. ':job:' .. id
+if redis.call('EXISTS', job) == 1 then
+  return { 'published', id, redis.call('HGET', job, 'runId') }
+end
+local nk = ARGV[14]
+local holder = redis.call('HGET', P .. ':idem', nk)
+if holder then
+  local row = redis.call('HMGET', P .. ':job:' .. holder, 'state', 'runId')
+  if row[1] and LIVE[row[1]] then return { 'deduped', holder, row[2] } end
+end
+local now = tonumber(ARGV[10])
+local runAt = tonumber(ARGV[9])
+local state = 'ready'
+if runAt > now then state = 'delayed' end
+redis.call('HSET', job,
+  'id', id, 'name', ARGV[3], 'queue', ARGV[4], 'input', ARGV[5], 'idempotencyKey', ARGV[6],
+  'runId', ARGV[7], 'attempt', '0', 'maxAttempts', ARGV[8], 'state', state, 'runAt', ARGV[9],
+  'createdAt', ARGV[10], 'updatedAt', ARGV[10], 'claim', '0', 'nk', nk)
+if ARGV[11] ~= '' then redis.call('HSET', job, 'tenantId', ARGV[11]) end
+if ARGV[12] ~= '' then redis.call('HSET', job, 'traceparent', ARGV[12]) end
+if ARGV[13] ~= '' then redis.call('HSET', job, 'enqueuedBy', ARGV[13]) end
+redis.call('ZADD', P .. ':wait:' .. ARGV[4], runAt, id)
+redis.call('SADD', P .. ':queues', ARGV[4])
+redis.call('HSET', P .. ':idem', nk, id)
+return { 'created', id, ARGV[7] }
+`.trim();
+
+/**
+ * `SQL_CLAIM`. `ARGV`: namespace, now, limit, visibility ms, worker, the count of `dropExhausted`
+ * names, those names, then the queues. Candidates are every due row of each queue — ready,
+ * delayed, suspended, or running past its lease — at most `limit` from each source, ordered by
+ * `runAt` and cut at `limit`. A running row on its final attempt is BURIED (`dead`, or `failed`
+ * for a dropped name) and never handed out. Answers one `{ 'c' | 'b', HGETALL… }` per row.
+ */
+export const REDIS_CLAIM = `
+local P = ARGV[1]
+local now = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+local visibility = tonumber(ARGV[4])
+local worker = ARGV[5]
+local dropCount = tonumber(ARGV[6])
+local drop = {}
+for i = 1, dropCount do drop[ARGV[6 + i]] = true end
+local candidates = {}
+if limit > 0 then
+  for i = 7 + dropCount, #ARGV do
+    local queue = ARGV[i]
+    for _, source in ipairs({ 'wait', 'park' }) do
+      local found = redis.call('ZRANGEBYSCORE', P .. ':' .. source .. ':' .. queue, '-inf', now,
+        'WITHSCORES', 'LIMIT', 0, limit)
+      for j = 1, #found, 2 do
+        table.insert(candidates, { id = found[j], runAt = tonumber(found[j + 1]) })
+      end
+    end
+    local lapsed = redis.call('ZRANGEBYSCORE', P .. ':run:' .. queue, '-inf', now, 'LIMIT', 0, limit)
+    for _, id in ipairs(lapsed) do
+      local runAt = tonumber(redis.call('HGET', P .. ':job:' .. id, 'runAt'))
+      if runAt and runAt <= now then table.insert(candidates, { id = id, runAt = runAt }) end
+    end
+  end
+end
+table.sort(candidates, function(a, b)
+  if a.runAt == b.runAt then return a.id < b.id end
+  return a.runAt < b.runAt
+end)
+local out = {}
+for i = 1, math.min(limit, #candidates) do
+  local id = candidates[i].id
+  local job = P .. ':job:' .. id
+  local row = redis.call('HMGET', job, 'state', 'attempt', 'maxAttempts', 'name', 'queue', 'claim', 'nk')
+  local state, attempt, maxAttempts, name, queue = row[1], tonumber(row[2]), tonumber(row[3]), row[4], row[5]
+  if state == 'running' and attempt >= maxAttempts then
+    local final = 'dead'
+    if drop[name] then final = 'failed' end
+    redis.call('ZREM', P .. ':run:' .. queue, id)
+    redis.call('HDEL', job, 'visibleAt', 'claimedBy', 'lastErrorStack')
+    redis.call('HSET', job, 'state', final, 'lastError', '${LEASE_LAPSED_FINAL_ATTEMPT}',
+      'updatedAt', ARGV[2])
+    redis.call('ZADD', P .. ':' .. final .. ':' .. queue, now, id)
+    redis.call('HDEL', P .. ':idem', row[7])
+    table.insert(out, { 'b', redis.call('HGETALL', job) })
+  else
+    redis.call('ZREM', P .. ':wait:' .. queue, id)
+    redis.call('ZREM', P .. ':park:' .. queue, id)
+    local visibleAt = now + visibility
+    redis.call('HSET', job, 'state', 'running', 'attempt', attempt + 1,
+      'claim', tonumber(row[6]) + 1, 'claimedBy', worker, 'claimedAt', ARGV[2],
+      'visibleAt', visibleAt, 'updatedAt', ARGV[2])
+    redis.call('ZADD', P .. ':run:' .. queue, visibleAt, id)
+    table.insert(out, { 'c', redis.call('HGETALL', job) })
+  end
+end
+return out
+`.trim();
+
+/** `SQL_ACK`. `ARGV`: the fence's four, then now, then the done row's time to live (0: none). */
+export const REDIS_ACK = `
+${FENCE}
+redis.call('HSET', job, 'state', 'done', 'updatedAt', ARGV[5])
+redis.call('HDEL', P .. ':idem', held[5])
+local ttl = tonumber(ARGV[6])
+if ttl > 0 then
+  redis.call('PEXPIRE', job, ttl)
+  redis.call('PEXPIRE', P .. ':steps:' .. held[6], ttl)
+end
+return 1
+`.trim();
+
+/**
+ * `SQL_NACK`. `ARGV`: the fence's four, then now, the state `nackState` chose, runAt, `1` when the
+ * attempt counts, `1` when an error is bound, the error, the stack (`''` for none).
+ */
+export const REDIS_NACK = `
+${FENCE}
+local state = ARGV[6]
+local attempt = tonumber(redis.call('HGET', job, 'attempt'))
+if ARGV[8] ~= '1' then attempt = math.max(0, attempt - 1) end
+redis.call('HSET', job, 'state', state, 'runAt', ARGV[7], 'attempt', attempt, 'updatedAt', ARGV[5])
+if ARGV[9] == '1' then
+  redis.call('HSET', job, 'lastError', ARGV[10])
+  if ARGV[11] == '' then redis.call('HDEL', job, 'lastErrorStack')
+  else redis.call('HSET', job, 'lastErrorStack', ARGV[11]) end
+end
+if state == 'ready' then
+  redis.call('ZADD', P .. ':wait:' .. queue, ARGV[7], id)
+elseif state == 'suspended' then
+  redis.call('ZADD', P .. ':park:' .. queue, ARGV[7], id)
+else
+  redis.call('ZADD', P .. ':' .. state .. ':' .. queue, ARGV[5], id)
+  redis.call('HDEL', P .. ':idem', held[5])
+end
+return 1
+`.trim();
+
+/**
+ * `SQL_HEARTBEAT`. `ARGV`: namespace, id, worker (`''`: any), claim (`''`: any), the new lease's
+ * end. Answers 1 when the lease moved.
+ */
+export const REDIS_HEARTBEAT = `
+local P = ARGV[1]
+local id = ARGV[2]
+local job = P .. ':job:' .. id
+local held = redis.call('HMGET', job, 'state', 'claimedBy', 'claim', 'queue')
+if held[1] ~= 'running' then return 0 end
+if ARGV[3] ~= '' and held[2] ~= ARGV[3] then return 0 end
+if ARGV[4] ~= '' and held[3] ~= ARGV[4] then return 0 end
+redis.call('HSET', job, 'visibleAt', ARGV[5])
+redis.call('ZADD', P .. ':run:' .. held[4], ARGV[5], id)
+return 1
+`.trim();
+
+/**
+ * `SQL_STATS`, one consistent read. `ARGV`: namespace, now. Answers one row per queue:
+ * `{ queue, ready, delayed, running, suspended, failed, dead, oldest runAt or -1 }` — due is due
+ * whatever state the row was WRITTEN in, the split `SQL_STATS` makes.
+ */
+export const REDIS_STATS = `
+local P = ARGV[1]
+local now = tonumber(ARGV[2])
+local out = {}
+for _, queue in ipairs(redis.call('SMEMBERS', P .. ':queues')) do
+  local wait = P .. ':wait:' .. queue
+  local oldest = redis.call('ZRANGE', wait, 0, 0, 'WITHSCORES')
+  local first = -1
+  if oldest[2] and tonumber(oldest[2]) <= now then first = oldest[2] end
+  table.insert(out, {
+    queue,
+    redis.call('ZCOUNT', wait, '-inf', now),
+    redis.call('ZCOUNT', wait, '(' .. now, '+inf'),
+    redis.call('ZCARD', P .. ':run:' .. queue),
+    redis.call('ZCARD', P .. ':park:' .. queue),
+    redis.call('ZCARD', P .. ':failed:' .. queue),
+    redis.call('ZCARD', P .. ':dead:' .. queue),
+    first,
+  })
+end
+return out
+`.trim();
+
+/**
+ * `SQL_STEP_PUT` under a claim: the write lands only while that claim still holds the row.
+ * `ARGV`: namespace, job id, worker, claim, runId, step name, the record as JSON.
+ */
+export const REDIS_STEP_PUT_FENCED = `
+local P = ARGV[1]
+local held = redis.call('HMGET', P .. ':job:' .. ARGV[2], 'state', 'claimedBy', 'claim')
+if held[1] ~= 'running' or held[2] ~= ARGV[3] or held[3] ~= ARGV[4] then return 0 end
+redis.call('HSET', P .. ':steps:' .. ARGV[5], ARGV[6], ARGV[7])
+return 1
+`.trim();

package/src/driver-redis-steps.ts

@@ -0,0 +1,64 @@
+// The Redis driver's `StepStore`: one HASH per run (`steps:<runId>`), step name → the record as
+// JSON. Through JSON exactly as the pg store persists it, so a step replays a `Date` as the same
+// string under every driver. A write made under a claim is fenced in one script on the row that
+// claim must still hold (`SQL_STEP_PUT`'s fence) and is `X_JOB_LEASE_LOST` otherwise.
+
+import type { RedisSender } from './driver-redis';
+import { REDIS_STEP_PUT_FENCED } from './driver-redis-scripts';
+import { LeaseLostError } from './errors';
+import type { StepRecord, StepStore } from './steps';
+import { isStepStatus } from './steps';
+
+interface StepStoreSeams {
+  /** The namespace, `{<prefix>}`. */
+  readonly ns: string;
+  /** One script, routed to the namespace's slot. */
+  readonly run: (script: string, args: readonly (string | number)[]) => Promise<unknown>;
+  readonly client: RedisSender;
+}
+
+/** A stored step, or nothing — a value that is not one of ours is never cast onto a record. */
+function parseStep(text: unknown): StepRecord | undefined {
+  if (typeof text !== 'string') return undefined;
+  const record = JSON.parse(text) as StepRecord;
+  return isStepStatus(record.status) ? record : undefined;
+}
+
+export function redisStepStore({ ns, run, client }: StepStoreSeams): StepStore {
+  const key = (runId: string) => `${ns}:steps:${runId}`;
+  return {
+    async get(runId, name) {
+      return parseStep(await client.send('HGET', [key(runId), name]));
+    },
+    async put(record, by) {
+      const text = JSON.stringify({ ...record, output: record.output ?? null });
+      if (by === undefined) {
+        await client.send('HSET', [key(record.runId), record.name, text]);
+        return;
+      }
+      const landed = await run(REDIS_STEP_PUT_FENCED, [
+        by.jobId,
+        by.workerId,
+        by.claim,
+        record.runId,
+        record.name,
+        text,
+      ]);
+      if (Number(landed) !== 1) throw new LeaseLostError({ job: by.job, jobId: by.jobId });
+    },
+    async list(runId) {
+      const values = await client.send('HVALS', [key(runId)]);
+      const records = (Array.isArray(values) ? values : []).flatMap((text: unknown) => {
+        const record = parseStep(text);
+        return record === undefined ? [] : [record];
+      });
+      return records.sort((a, b) => a.startedAt - b.startedAt);
+    },
+    async del(runId, name) {
+      await client.send('HDEL', [key(runId), name]);
+    },
+    async clear(runId) {
+      await client.send('DEL', [key(runId)]);
+    },
+  };
+}

package/src/driver-redis.ts

@@ -0,0 +1,278 @@
+// A Redis queue on `Bun.redis` — no client dependency, the runtime ships one. The same contract as
+// the pg driver, held by `@ultimat3/testing`'s `jobDriverConformance`: every operation is one Lua
+// script (`driver-redis-scripts.ts`), so a claim, a settle and a renewal are each atomic on the
+// server the way a `driver-pg-sql.ts` statement is in one transaction. Its own entry,
+// `@ultimat3/jobs/redis`: the barrel is on every role's boot path, and an app on Postgres loads none
+// of this.
+//
+// Key layout, every key inside ONE hash tag `{<prefix>}` (one slot: legal on Redis Cluster):
+//   job:<id>      HASH   the row                    wait:<queue>  ZSET  ready/delayed, by runAt
+//   park:<queue>  ZSET   suspended, by runAt        run:<queue>   ZSET  running, by lease end
+//   dead:<queue>  ZSET   dead letters, by time      failed:<queue> ZSET failed rows, by time
+//   queues        SET    every queue named          idem          HASH  live key → row id
+//   steps:<runId> HASH   step name → record JSON
+
+import type { Clock } from '@ultimat3/core';
+import { finiteCount, finiteOption, systemClock, uuidV7 } from '@ultimat3/core';
+import { nowMs } from './clock';
+import type {
+  ClaimedJob,
+  EnqueueRequest,
+  EnqueueResult,
+  JobDriver,
+  JobRecord,
+  QueueStats,
+} from './driver';
+import {
+  assertClaimBounds,
+  assertClaimQueues,
+  DEFAULT_QUEUE,
+  isJobState,
+  nackState,
+} from './driver';
+import {
+  REDIS_ACK,
+  REDIS_CLAIM,
+  REDIS_ENQUEUE,
+  REDIS_HEARTBEAT,
+  REDIS_NACK,
+  REDIS_STATS,
+} from './driver-redis-scripts';
+import { redisStepStore } from './driver-redis-steps';
+import { DriverUnavailableError, JobDuplicateError } from './errors';
+import { MAX_ERROR_STACK_LENGTH } from './introspection';
+
+/** The slice of Bun's Redis client this driver uses — `Bun.redis` and `new Bun.RedisClient()`. */
+export interface RedisSender {
+  send(command: string, args: string[]): Promise<unknown>;
+}
+
+/** A finished row's default life: a week, then Redis reclaims it and its steps. */
+export const DEFAULT_REDIS_DONE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+export interface RedisJobDriverOptions {
+  /** Injected in tests and for a second server; production reads `Bun.redis` (`REDIS_URL`). */
+  readonly client?: RedisSender;
+  /** Key namespace, the hash tag every key carries. Default `x:jobs`. */
+  readonly prefix?: string;
+  readonly clock?: Clock;
+  /**
+   * How long a `done` row (and its steps) outlives its ack, in ms; `0` keeps it forever. Default
+   * `DEFAULT_REDIS_DONE_TTL_MS`: a queue in memory that keeps every finished row is a server that
+   * runs out of memory. Dead and failed rows are kept — they are the record of what went wrong.
+   */
+  readonly doneTtlMs?: number;
+}
+
+function resolveClient(injected: RedisSender | undefined): RedisSender {
+  if (injected !== undefined) return injected;
+  const ambient = (Bun as unknown as { redis?: RedisSender }).redis;
+  if (ambient === undefined || typeof ambient.send !== 'function') {
+    throw new DriverUnavailableError({
+      driver: 'redis',
+      cause: 'Bun.redis is not available, and no client was handed to redisJobDriver()',
+      fix: 'REDIS_URL=redis://127.0.0.1:6379 x dev — or hand one in: redisJobDriver({ client: new Bun.RedisClient(url) })',
+    });
+  }
+  return ambient;
+}
+
+/** A Lua reply as an array; anything else is the empty one. */
+const list = (reply: unknown): readonly unknown[] => (Array.isArray(reply) ? reply : []);
+
+/** `HGETALL`'s flat `[field, value, …]` reply as a map. */
+function fieldsOf(flat: readonly unknown[]): ReadonlyMap<string, string> {
+  const fields = new Map<string, string>();
+  for (let i = 0; i + 1 < flat.length; i += 2) fields.set(String(flat[i]), String(flat[i + 1]));
+  return fields;
+}
+
+const num = (fields: ReadonlyMap<string, string>, name: string): number | undefined => {
+  const value = fields.get(name);
+  return value === undefined ? undefined : Number(value);
+};
+
+/** One stored row as the record every driver hands back. Absent fields stay absent. */
+function toRecord(fields: ReadonlyMap<string, string>): JobRecord {
+  const state = fields.get('state') ?? '';
+  const optional = (name: keyof JobRecord & string) => {
+    const value = fields.get(name);
+    return value === undefined ? {} : { [name]: value };
+  };
+  const claim = num(fields, 'claim') ?? 0;
+  const visibleAt = num(fields, 'visibleAt');
+  return {
+    id: fields.get('id') ?? '',
+    name: fields.get('name') ?? '',
+    queue: fields.get('queue') ?? '',
+    input: JSON.parse(fields.get('input') ?? 'null') as unknown,
+    idempotencyKey: fields.get('idempotencyKey') ?? '',
+    runId: fields.get('runId') ?? '',
+    attempt: num(fields, 'attempt') ?? 0,
+    maxAttempts: num(fields, 'maxAttempts') ?? 0,
+    // A state the list does not know is never cast onto a record: it reads as dead, the one state
+    // nothing claims again — the answer `isJobState` gives every driver.
+    state: isJobState(state) ? state : 'dead',
+    runAt: num(fields, 'runAt') ?? 0,
+    createdAt: num(fields, 'createdAt') ?? 0,
+    updatedAt: num(fields, 'updatedAt') ?? 0,
+    ...optional('tenantId'),
+    ...optional('lastError'),
+    ...optional('lastErrorStack'),
+    ...optional('claimedBy'),
+    ...optional('traceparent'),
+    ...optional('enqueuedBy'),
+    ...(claim > 0 ? { claim } : {}),
+    ...(visibleAt === undefined ? {} : { visibleAt }),
+  };
+}
+
+/**
+ * The idempotency namespace field: name, tenant (`''` for none, as the index's `coalesce`) and
+ * key, JSON-joined so no separator inside a value can make two triples one field.
+ */
+const namespaceField = (request: EnqueueRequest): string =>
+  JSON.stringify([request.name, request.tenantId ?? '', request.idempotencyKey]);
+
+export function redisJobDriver(options: RedisJobDriverOptions = {}): JobDriver {
+  const client = resolveClient(options.client);
+  const clock = options.clock ?? systemClock;
+  const ns = `{${options.prefix ?? 'x:jobs'}}`;
+  const doneTtlMs = finiteCount(
+    'redisJobDriver',
+    'doneTtlMs',
+    options.doneTtlMs ?? DEFAULT_REDIS_DONE_TTL_MS,
+  );
+  // `KEYS[1]` routes the call to the namespace's slot; every key a script builds is in it.
+  const run = (script: string, args: readonly (string | number)[]): Promise<unknown> =>
+    client.send('EVAL', [script, '1', `${ns}:queues`, ns, ...args.map(String)]);
+
+  return {
+    name: 'redis',
+    steps: redisStepStore({ ns, run, client }),
+
+    async enqueue(request): Promise<EnqueueResult> {
+      const at = nowMs(clock);
+      const runId = request.runId ?? uuidV7();
+      const [outcome, id, heldRunId] = list(
+        await run(REDIS_ENQUEUE, [
+          request.id ?? uuidV7(),
+          request.name,
+          request.queue || DEFAULT_QUEUE,
+          JSON.stringify(request.input ?? null),
+          request.idempotencyKey,
+          runId,
+          request.maxAttempts,
+          request.runAt ?? at,
+          at,
+          request.tenantId ?? '',
+          request.traceparent ?? '',
+          request.enqueuedBy ?? '',
+          namespaceField(request),
+        ]),
+      ).map(String);
+      if (outcome === 'deduped' && request.onConflict === 'error') {
+        throw new JobDuplicateError({
+          job: request.name,
+          idempotencyKey: request.idempotencyKey,
+          existingId: id ?? '',
+        });
+      }
+      return { id: id ?? '', runId: heldRunId ?? runId, deduped: outcome !== 'created' };
+    },
+
+    async claim(claimOptions): Promise<readonly ClaimedJob[]> {
+      assertClaimQueues('redis', claimOptions);
+      assertClaimBounds('redis', claimOptions);
+      const drop = claimOptions.dropExhausted ?? [];
+      const reply = await run(REDIS_CLAIM, [
+        nowMs(clock),
+        claimOptions.limit,
+        claimOptions.visibilityTimeoutMs,
+        claimOptions.workerId,
+        drop.length,
+        ...drop,
+        ...claimOptions.queues,
+      ]);
+      const claimed: ClaimedJob[] = [];
+      const buried: JobRecord[] = [];
+      for (const entry of list(reply)) {
+        const [kind, flat] = list(entry);
+        const fields = fieldsOf(list(flat));
+        const record = toRecord(fields);
+        if (kind === 'b') {
+          buried.push(record);
+          continue;
+        }
+        claimed.push({
+          ...record,
+          claimedBy: claimOptions.workerId,
+          claim: record.claim ?? 1,
+          claimedAt: num(fields, 'claimedAt') ?? 0,
+          visibleAt: record.visibleAt ?? 0,
+        });
+      }
+      if (buried.length > 0) claimOptions.onExhausted?.(buried);
+      return claimed;
+    },
+
+    async ack(jobId, by): Promise<boolean> {
+      const reply = await run(REDIS_ACK, [jobId, by.workerId, by.claim, nowMs(clock), doneTtlMs]);
+      return Number(reply) === 1;
+    },
+
+    async nack(jobId, nackOptions): Promise<boolean> {
+      finiteOption('the redis driver nack', 'delayMs', nackOptions.delayMs);
+      const at = nowMs(clock);
+      const error = nackOptions.error;
+      const reply = await run(REDIS_NACK, [
+        jobId,
+        nackOptions.workerId,
+        nackOptions.claim,
+        at,
+        nackState(nackOptions),
+        at + nackOptions.delayMs,
+        nackOptions.countsAsAttempt === false ? '0' : '1',
+        error === undefined ? '0' : '1',
+        error ?? '',
+        error === undefined ? '' : (nackOptions.stack ?? '').slice(0, MAX_ERROR_STACK_LENGTH),
+      ]);
+      return Number(reply) === 1;
+    },
+
+    async heartbeat(jobId, heartbeatOptions): Promise<boolean> {
+      finiteOption(
+        'the redis driver heartbeat',
+        'visibilityTimeoutMs',
+        heartbeatOptions.visibilityTimeoutMs,
+      );
+      const reply = await run(REDIS_HEARTBEAT, [
+        jobId,
+        heartbeatOptions.workerId ?? '',
+        heartbeatOptions.claim === undefined ? '' : heartbeatOptions.claim,
+        nowMs(clock) + heartbeatOptions.visibilityTimeoutMs,
+      ]);
+      return Number(reply) === 1;
+    },
+
+    async stats(): Promise<readonly QueueStats[]> {
+      const at = nowMs(clock);
+      const rows = list(await run(REDIS_STATS, [at])).map((row): QueueStats => {
+        const [queue, ready, delayed, running, suspended, failed, dead, oldest] = list(row);
+        const first = Number(oldest);
+        return {
+          queue: String(queue),
+          ready: Number(ready),
+          delayed: Number(delayed),
+          running: Number(running),
+          suspended: Number(suspended),
+          failed: Number(failed),
+          dead: Number(dead),
+          oldestReadyMs: first < 0 ? 0 : at - first,
+        };
+      });
+      // Code units, as `collate "C"` orders `SQL_STATS` — never `localeCompare`.
+      return rows.sort((a, b) => (a.queue < b.queue ? -1 : a.queue > b.queue ? 1 : 0));
+    },
+  };
+}

package/src/driver.ts

@@ -4,9 +4,10 @@
 //
 // There is no config line that picks a backend: boot always builds `postgresJobDriver()`, and a
 // stale `jobs.driver` in `app.config.ts` is refused by `defineConfig` (25.0.0; it was read by
-// nothing since 5.0.0). `postgresJobDriver` and `memoryJobDriver` are the two that exist — 25.0.0
-// deleted the all-throw `redis` and `nats` stubs. Swapping the driver is `setJobDriver(other)` and
-// ZERO job-code change, and that is what the interface buys.
+// nothing since 5.0.0). `postgresJobDriver`, `redisJobDriver` and `memoryJobDriver` are the three
+// that exist — 25.0.0 deleted the all-throw `redis` and `nats` stubs, and #710 built the Redis one
+// for real. Swapping the driver is `setJobDriver(other)` and ZERO job-code change, and that
+// is what the interface buys.
 
 import { finiteCount, finiteOption } from '@ultimat3/core';
 import type { BackfillLedger } from './backfill-ledger';