@ultimat3/jobs 29.3.2 → 30.0.0

package/src/driver-redis-scripts.ts

@@ -30,40 +30,70 @@ 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.
+ * One enqueue, as a Lua function both enqueue scripts call, so the single and the batch insert are
+ * ONE body. `a[o]` onwards, `ENQUEUE_ARITY` fields: 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 = `
+const ENQUEUE_ONE = `
 ${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') }
+local function enqueue_one(P, a, o)
+  local id = a[o]
+  local job = P .. ':job:' .. id
+  if redis.call('EXISTS', job) == 1 then
+    return { 'published', id, redis.call('HGET', job, 'runId') }
+  end
+  local nk = a[o + 12]
+  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(a[o + 8])
+  local runAt = tonumber(a[o + 7])
+  local state = 'ready'
+  if runAt > now then state = 'delayed' end
+  local queue = a[o + 2]
+  redis.call('HSET', job,
+    'id', id, 'name', a[o + 1], 'queue', queue, 'input', a[o + 3], 'idempotencyKey', a[o + 4],
+    'runId', a[o + 5], 'attempt', '0', 'maxAttempts', a[o + 6], 'state', state,
+    'runAt', a[o + 7], 'createdAt', a[o + 8], 'updatedAt', a[o + 8], 'claim', '0', 'nk', nk)
+  if a[o + 9] ~= '' then redis.call('HSET', job, 'tenantId', a[o + 9]) end
+  if a[o + 10] ~= '' then redis.call('HSET', job, 'traceparent', a[o + 10]) end
+  if a[o + 11] ~= '' then redis.call('HSET', job, 'enqueuedBy', a[o + 11]) end
+  redis.call('ZADD', P .. ':wait:' .. queue, runAt, id)
+  redis.call('SADD', P .. ':queues', queue)
+  redis.call('HSET', P .. ':idem', nk, id)
+  return { 'created', id, a[o + 5] }
 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
+`;
+
+/** Fields one request binds, after the namespace — what `ENQUEUE_ONE` reads from `a[o]` on. */
+export const ENQUEUE_ARITY = 13;
+
+/** `SQL_ENQUEUE`. `ARGV`: namespace, then one request's `ENQUEUE_ARITY` fields. */
+export const REDIS_ENQUEUE = `
+${ENQUEUE_ONE}
+return enqueue_one(ARGV[1], ARGV, 2)
+`.trim();
+
+/**
+ * `SQL_ENQUEUE_MANY`: every request in ONE script, so the batch is atomic on the server and a key
+ * twice in it is one job — the second request meets the first's `idem` entry. `ARGV`: namespace,
+ * then `ENQUEUE_ARITY` fields per request, in request order. Answers the three fields
+ * `enqueue_one` answers, per request, flat and in order.
+ */
+export const REDIS_ENQUEUE_MANY = `
+${ENQUEUE_ONE}
+local out = {}
+for o = 2, #ARGV, ${ENQUEUE_ARITY} do
+  local answer = enqueue_one(ARGV[1], ARGV, o)
+  table.insert(out, answer[1])
+  table.insert(out, answer[2])
+  table.insert(out, answer[3])
 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] }
+return out
 `.trim();
 
 /**
@@ -221,6 +251,25 @@ end
 return out
 `.trim();
 
+/**
+ * `SQL_QUEUE_DEMAND`, one consistent read. `ARGV`: namespace, now. Answers `{ queue, demand }` per
+ * queue with some: every running row plus every due wait or park row. This driver keeps no worker
+ * registry and no pause, so no claimer is known to drain and no queue is paused: the rule
+ * `SQL_QUEUE_DEMAND` applies to a claimer with no live row, which counts.
+ */
+export const REDIS_DEMAND = `
+local P = ARGV[1]
+local now = tonumber(ARGV[2])
+local out = {}
+for _, queue in ipairs(redis.call('SMEMBERS', P .. ':queues')) do
+  local demand = redis.call('ZCARD', P .. ':run:' .. queue)
+    + redis.call('ZCOUNT', P .. ':wait:' .. queue, '-inf', now)
+    + redis.call('ZCOUNT', P .. ':park:' .. queue, '-inf', now)
+  if demand > 0 then table.insert(out, { queue, demand }) end
+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.

package/src/driver-redis.ts

@@ -1,7 +1,7 @@
-// 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,
+// A Redis queue on core's `redisClient()` — 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.
 //
@@ -14,6 +14,7 @@
 
 import type { Clock } from '@ultimat3/core';
 import { finiteCount, finiteOption, systemClock, uuidV7 } from '@ultimat3/core';
+import { redisClient } from '@ultimat3/core/redis';
 import { nowMs } from './clock';
 import type {
   ClaimedJob,
@@ -21,28 +22,33 @@ import type {
   EnqueueResult,
   JobDriver,
   JobRecord,
+  QueueDemand,
   QueueStats,
 } from './driver';
 import {
   assertClaimBounds,
   assertClaimQueues,
+  assertEnqueueMany,
   DEFAULT_QUEUE,
   isJobState,
   nackState,
 } from './driver';
+import { typedRefusals } from './driver-redis-refusal';
 import {
   REDIS_ACK,
   REDIS_CLAIM,
+  REDIS_DEMAND,
   REDIS_ENQUEUE,
+  REDIS_ENQUEUE_MANY,
   REDIS_HEARTBEAT,
   REDIS_NACK,
   REDIS_STATS,
 } from './driver-redis-scripts';
 import { redisStepStore } from './driver-redis-steps';
-import { DriverUnavailableError, JobDuplicateError } from './errors';
+import { 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()`. */
+/** The slice of Bun's Redis client this driver uses — `redisClient()` and `new Bun.RedisClient()`. */
 export interface RedisSender {
   send(command: string, args: string[]): Promise<unknown>;
 }
@@ -51,7 +57,11 @@ export interface RedisSender {
 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`). */
+  /**
+   * Injected in tests and for a second server; production takes `redisClient()` from
+   * `@ultimat3/core/redis` (`REDIS_URL`): while it is down every command refuses at once, as
+   * `X_DRIVER_UNAVAILABLE`. No deadline here: a stuck command has the request's.
+   */
   readonly client?: RedisSender;
   /** Key namespace, the hash tag every key carries. Default `x:jobs`. */
   readonly prefix?: string;
@@ -64,19 +74,6 @@ export interface RedisJobDriverOptions {
   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 : []);
 
@@ -134,8 +131,33 @@ function toRecord(fields: ReadonlyMap<string, string>): JobRecord {
 const namespaceField = (request: EnqueueRequest): string =>
   JSON.stringify([request.name, request.tenantId ?? '', request.idempotencyKey]);
 
+/** One request as `ENQUEUE_ONE` reads it: `ENQUEUE_ARITY` fields, in its order. */
+function enqueueArgs(request: EnqueueRequest, runId: string, at: number): (string | number)[] {
+  return [
+    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),
+  ];
+}
+
+/** The `{ outcome, id, runId }` triple at `at` in a reply, as the result `enqueue` answers. */
+function answerOf(reply: readonly unknown[], at: number, runId: string): EnqueueResult {
+  const [outcome, id, heldRunId] = reply.slice(at, at + 3).map(String);
+  return { id: id ?? '', runId: heldRunId ?? runId, deduped: outcome !== 'created' };
+}
+
 export function redisJobDriver(options: RedisJobDriverOptions = {}): JobDriver {
-  const client = resolveClient(options.client);
+  const client = typedRefusals(options.client ?? redisClient());
   const clock = options.clock ?? systemClock;
   const ns = `{${options.prefix ?? 'x:jobs'}}`;
   const doneTtlMs = finiteCount(
@@ -152,33 +174,31 @@ export function redisJobDriver(options: RedisJobDriverOptions = {}): JobDriver {
     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') {
+      const reply = list(await run(REDIS_ENQUEUE, enqueueArgs(request, runId, nowMs(clock))));
+      const answer = answerOf(reply, 0, runId);
+      if (reply[0] === 'deduped' && request.onConflict === 'error') {
         throw new JobDuplicateError({
           job: request.name,
           idempotencyKey: request.idempotencyKey,
-          existingId: id ?? '',
+          existingId: answer.id,
         });
       }
-      return { id: id ?? '', runId: heldRunId ?? runId, deduped: outcome !== 'created' };
+      return answer;
+    },
+
+    // ONE script for the batch (`REDIS_ENQUEUE_MANY`), the body `enqueue` runs once per request:
+    // atomic on the server, and a key twice in it meets its own first request.
+    async enqueueMany(requests): Promise<readonly EnqueueResult[]> {
+      assertEnqueueMany('redis', requests);
+      if (requests.length === 0) return [];
+      const at = nowMs(clock);
+      const runIds = requests.map((request) => request.runId ?? uuidV7());
+      const args = requests.flatMap((request, index) =>
+        enqueueArgs(request, runIds[index] ?? uuidV7(), at),
+      );
+      const reply = list(await run(REDIS_ENQUEUE_MANY, args));
+      return runIds.map((runId, index) => answerOf(reply, index * 3, runId));
     },
 
     async claim(claimOptions): Promise<readonly ClaimedJob[]> {
@@ -274,5 +294,13 @@ export function redisJobDriver(options: RedisJobDriverOptions = {}): JobDriver {
       // 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));
     },
+
+    async demand(): Promise<readonly QueueDemand[]> {
+      const rows = list(await run(REDIS_DEMAND, [nowMs(clock)])).map((row): QueueDemand => {
+        const [queue, demand] = list(row);
+        return { queue: String(queue), demand: Number(demand) };
+      });
+      return rows.sort((a, b) => (a.queue < b.queue ? -1 : a.queue > b.queue ? 1 : 0));
+    },
   };
 }

package/src/driver.ts

@@ -9,7 +9,7 @@
 // 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 { assert, finiteCount, finiteOption } from '@ultimat3/core';
 import type { BackfillLedger } from './backfill-ledger';
 import { ClaimQueuesEmptyError } from './errors';
 import type { JobIntrospection, JobProgress } from './introspection';
@@ -305,6 +305,12 @@ export interface QueueStats {
   readonly oldestReadyMs: number;
 }
 
+/** What one queue's fleet must hold: `JobDriver.demand`. */
+export interface QueueDemand {
+  readonly queue: string;
+  readonly demand: number;
+}
+
 export interface HeartbeatOptions {
   readonly visibilityTimeoutMs: number;
   /** Renew only if this worker is still the claimant. Omit and any claimant matches. */
@@ -318,6 +324,13 @@ export interface JobDriver {
   /** Step persistence lives with the queue: one store, one transaction boundary. */
   readonly steps: StepStore;
   enqueue(request: EnqueueRequest): Promise<EnqueueResult>;
+  /**
+   * `enqueue` for every request in ONE round trip — a statement on Postgres, a script on Redis —
+   * answered in request order with what `enqueue` would have answered each: a repeat of an `id` or
+   * a live key is `deduped: true`, a key twice in the batch is one job. REQUIRED, the one batch
+   * path `handle.enqueueMany` and the outbox relay take. Opens with `assertEnqueueMany`.
+   */
+  enqueueMany(requests: readonly EnqueueRequest[]): Promise<readonly EnqueueResult[]>;
   claim(options: ClaimOptions): Promise<readonly ClaimedJob[]>;
   /**
    * Both settles are fenced on `state = 'running'` AND on the claimer, and both answer whether
@@ -336,6 +349,14 @@ export interface JobDriver {
    */
   heartbeat(jobId: string, options: HeartbeatOptions): Promise<boolean>;
   stats(): Promise<readonly QueueStats[]>;
+  /**
+   * The jobs a live worker of this fleet must hold, per queue: running on a worker that still
+   * serves, plus every due row of an unpaused queue. Only a queue with some is listed. What
+   * `queue_demand` publishes and an autoscaler sizes by. Required since 30.0.0: `ready + running`
+   * off `stats()` cannot tell a draining worker's runs from a serving one's, and the HPA sized on it.
+   * A claimer no live registry row says drains is counted, so a driver with no registry counts all.
+   */
+  demand(): Promise<readonly QueueDemand[]>;
   /**
    * Optional, like `introspect`: `x_backfills` records what a `backfill()` pass has already swept,
    * and a driver without one runs backfills with no bookkeeping rather than refusing them. It
@@ -395,6 +416,22 @@ export const assertClaimQueues = (driver: string, options: ClaimOptions): void =
   if (options.queues.length === 0) throw new ClaimQueuesEmptyError(driver);
 };
 
+/**
+ * Every driver's `enqueueMany` opens with this, so a batch is refused ONE way. `onConflict:
+ * 'error'` has no batch meaning the drivers could share: Postgres inserts every other row of the
+ * statement before the refusal is known, a loop only the rows before it — two different sets of
+ * jobs left behind by one refused call. A request that must refuse a duplicate is a single
+ * `enqueue`; `handle.enqueueMany` never sets it.
+ */
+export const assertEnqueueMany = (driver: string, requests: readonly EnqueueRequest[]): void => {
+  const at = requests.findIndex((request) => request.onConflict === 'error');
+  assert(
+    at === -1,
+    `the ${driver} driver's enqueueMany was handed onConflict: 'error' on request ${at}, and a batch that refuses a duplicate would leave a different set of jobs behind on every driver`,
+    "drop onConflict from the batch — a duplicate is answered deduped: true — or send that request alone: driver.enqueue({ ...request, onConflict: 'error' })",
+  );
+};
+
 /**
  * The two NUMBERS of a claim, screened for both drivers in one place for the reason above: a value
  * neither of them refuses is answered two ways. `limit: -1` sliced every ready row but the newest

package/src/enqueue-record.ts

@@ -0,0 +1,137 @@
+// What one enqueue WRITES, built once for every path: the staged `OutboxRecord` and the direct
+// `EnqueueRequest`, for `enqueue` and `enqueueMany` alike. Split from `outbox.ts` so the batch path
+// builds the identical row the single one does, instead of a second spelling of it.
+
+import { currentSpanContext, describeValue, traceparent, UltimateError } from '@ultimat3/core';
+import type { EnqueueRequest } from './driver';
+import { DEFAULT_QUEUE } from './driver';
+import type { JobHandle } from './job';
+import type { EnqueueOptions, OutboxRecord } from './outbox';
+import { enqueuedAttempts } from './retry';
+
+/**
+ * The W3C `traceparent` of the span this enqueue is happening inside, or `undefined` outside a
+ * trace. This is the ONE place the link is minted: `docs/idea/04-jobs.md` promises a job trace
+ * linked to the enqueuing request, and before this there was no field to carry the link, so a
+ * checkout's `chargeCard` opened a fresh root two seconds later with nothing pointing back.
+ *
+ * A context recovered from a `Ctx` has an empty `spanId` (`currentSpanContext`), which renders as
+ * an all-zero parent that every collector rejects — so that case carries no header rather than a
+ * malformed one, and the job opens a root as it did before.
+ */
+export function ambientTraceparent(): string | undefined {
+  const context = currentSpanContext();
+  if (context === undefined || context.spanId === '') return undefined;
+  return traceparent(context);
+}
+
+/** What Postgres prints for a `uuid`, and so the only spelling both drivers store identically. */
+const RUN_ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/**
+ * `EnqueueOptions.runId`, refused HERE when it is not a uuid — the one screen both enqueue paths
+ * read. `run_id` is a `uuid` column: the memory driver took any string, Postgres raised a raw
+ * `22P02`, and on the staged path that was the caller's whole transaction failing at the outbox
+ * insert. Any version, lowercase: an uppercase one would come back from Postgres re-spelled.
+ */
+export function namedRunId(job: string, runId: unknown): string | undefined {
+  if (runId === undefined) return undefined;
+  if (typeof runId === 'string' && RUN_ID_SHAPE.test(runId)) return runId;
+  throw new UltimateError({
+    code: 'X_ID_INVALID',
+    // `describeValue`, never the value: what arrives here wrong is as often a key as a typo.
+    cause: `enqueue of job "${job}" was given runId ${describeValue(runId)}, and a run id is a lowercase uuid (8-4-4-4-12 hex) — the queue stores it in a uuid column`,
+    fix: "pass { runId: uuidV7() } to enqueue(), with import { uuidV7 } from '@ultimat3/core'",
+    meta: { job, option: 'runId' },
+  });
+}
+
+/** The parts of one row the caller of the builders decides: its key, its clock, its ids. */
+export interface RowFacts {
+  readonly idempotencyKey: string;
+  readonly at: number;
+  readonly trace: string | undefined;
+  readonly id?: string;
+  readonly runId?: string;
+}
+
+/**
+ * The org the row is queued for: the one stated, else the one the payload names. Without the
+ * default a plain `enqueue(input)` queued for nobody, so org B's `invoice:1` deduped onto org A's
+ * job (the namespace is `(name, tenant, key)`) and `perTenant` counted every such row as no org's.
+ * The facade's `refuseEnqueueTenant` has already refused the two disagreeing.
+ */
+function queuedFor<I>(handle: JobHandle<I>, input: I, options: EnqueueOptions): string | undefined {
+  return options.tenantId ?? handle.tenantFor(input);
+}
+
+const optional = (
+  tenantId: string | undefined,
+  options: EnqueueOptions,
+  trace: string | undefined,
+) => ({
+  ...(tenantId === undefined ? {} : { tenantId }),
+  ...(trace === undefined ? {} : { traceparent: trace }),
+  ...(options.enqueuedBy === undefined ? {} : { enqueuedBy: options.enqueuedBy }),
+});
+
+/** The row a staged enqueue writes to the outbox; its `id` and `runId` are the job's to be. */
+export function stagedRecord<I>(
+  handle: JobHandle<I>,
+  input: I,
+  options: EnqueueOptions,
+  facts: RowFacts & { readonly id: string; readonly runId: string },
+): OutboxRecord {
+  return {
+    id: facts.id,
+    runId: facts.runId,
+    job: handle.name,
+    queue: options.queue ?? handle.queue ?? DEFAULT_QUEUE,
+    input,
+    idempotencyKey: facts.idempotencyKey,
+    maxAttempts: enqueuedAttempts(handle.retry, handle.compensates),
+    runAt: options.runAt ?? facts.at,
+    stagedAt: facts.at,
+    // Stamped at STAGE time and not at publish time: the relay runs after commit, in its own
+    // timer, with no request span in scope — a trace read there would be nobody's.
+    ...optional(queuedFor(handle, input, options), options, facts.trace),
+  };
+}
+
+/** The request a direct enqueue hands the driver. Ids only when the caller allocated them. */
+export function directRequest<I>(
+  handle: JobHandle<I>,
+  input: I,
+  options: EnqueueOptions,
+  facts: RowFacts,
+): EnqueueRequest {
+  return {
+    ...(facts.id === undefined ? {} : { id: facts.id }),
+    name: handle.name,
+    queue: options.queue ?? handle.queue,
+    input,
+    idempotencyKey: facts.idempotencyKey,
+    maxAttempts: enqueuedAttempts(handle.retry, handle.compensates),
+    runAt: options.runAt ?? facts.at,
+    ...(facts.runId === undefined ? {} : { runId: facts.runId }),
+    ...optional(queuedFor(handle, input, options), options, facts.trace),
+  };
+}
+
+/** The request the relay publishes a staged row as — under the ids the stage answered. */
+export function publishRequest(record: OutboxRecord): EnqueueRequest {
+  return {
+    // A repeat of this publish — a crash before the mark — meets the job this one made.
+    id: record.id,
+    runId: record.runId,
+    name: record.job,
+    queue: record.queue,
+    input: record.input,
+    idempotencyKey: record.idempotencyKey,
+    maxAttempts: record.maxAttempts,
+    runAt: record.runAt,
+    ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
+    ...(record.traceparent === undefined ? {} : { traceparent: record.traceparent }),
+    ...(record.enqueuedBy === undefined ? {} : { enqueuedBy: record.enqueuedBy }),
+  };
+}