@12-apps/jobs 2.0.0 → 4.0.0

package/src/core/registry.ts

@@ -1,9 +1,14 @@
 /**
  * The job registry: `defineJob` at module scope, jobs collected by import.
  *
- * Same open/closed seam as the notification generators — a domain module
- * declares its jobs next to the code they belong to, and the worker bootstrap
- * only has to import those modules. Nothing central lists them.
+ * An open/closed seam — a domain module declares its jobs next to the code
+ * they belong to, and the worker bootstrap only has to import those modules.
+ * Nothing central lists them.
+ *
+ * The registry is also THE GATE. `resolveRegisteredJob` is the one question
+ * both halves of the system ask — the enqueue side before it writes, the
+ * execution side before it runs — so the two cannot drift into a state where
+ * a write is accepted that the run side will refuse.
  */
 
 import type {
@@ -31,18 +36,140 @@ export class DuplicateJobError extends Error {
   }
 }
 
+/**
+ * Raised for a definition that cannot run as written — a blank name, an empty
+ * queue, a cron pattern no scheduler will ever fire.
+ *
+ * Every one of these fails SILENTLY if it is let through: an empty queue name
+ * creates a queue nobody consumes, `attempts: 0` means one attempt in one
+ * driver and none in another, and a blank pattern installs a scheduler that
+ * never fires — a sweep that simply stops happening, with nothing logged and
+ * nothing failed. So they are refused at assembly, where the stack trace still
+ * points at the declaration.
+ */
+export class InvalidJobDefinitionError extends Error {
+  constructor(name: string, detail: string) {
+    super(`Job "${name}" is not valid: ${detail}`);
+    this.name = "InvalidJobDefinitionError";
+  }
+}
+
+/**
+ * Raised when a process is asked to run jobs and NOT ONE is registered.
+ *
+ * "Declare nothing" must not resolve to "accept anything": with an empty
+ * registry a worker starts, consumes no queue, installs no schedule and
+ * reports itself healthy — every scheduled sweep in the deployment silently
+ * stops, and nothing fails to show it. A host with no jobs has no use for this
+ * package at all, so an empty registry is always a wiring mistake.
+ */
+export class NoJobsRegisteredError extends Error {
+  constructor(where: string) {
+    super(
+      `${where}: no jobs are registered. Import the modules that call defineJob ` +
+        "(the import IS the registration), or list them in `jobs`.",
+    );
+    this.name = "NoJobsRegisteredError";
+  }
+}
+
+function assertText(name: string, field: string, value: unknown): void {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new InvalidJobDefinitionError(name, `\`${field}\` must be a non-empty string.`);
+  }
+}
+
+function assertPositiveInteger(name: string, field: string, value: unknown): void {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new InvalidJobDefinitionError(
+      name,
+      `\`${field}\` must be a positive integer, got ${JSON.stringify(value)}.`,
+    );
+  }
+}
+
+/**
+ * Structural cron validation: five fields (or six, with seconds), none blank.
+ *
+ * Deliberately not a full cron parser — the driver's scheduler owns what a
+ * field may contain. What this catches is the class that is invisible at
+ * runtime: `""`, `"   "`, `"@daily"` and `"0 *"` all satisfy a `string` type
+ * and all produce a schedule that never fires.
+ */
+function assertCron(name: string, pattern: string): void {
+  assertText(name, "schedule.pattern", pattern);
+  const fields = pattern.trim().split(/\s+/);
+  if (fields.length !== 5 && fields.length !== 6) {
+    throw new InvalidJobDefinitionError(
+      name,
+      `\`schedule.pattern\` needs 5 fields (or 6 with seconds), got ${fields.length} in "${pattern}".`,
+    );
+  }
+}
+
+function assertBackoff(name: string, backoff: JobDefinition<never>["backoff"]): void {
+  if (!backoff) return;
+  const { type, delayMs } = backoff;
+  if (type !== "exponential" && type !== "fixed") {
+    throw new InvalidJobDefinitionError(
+      name,
+      `\`backoff.type\` must be "exponential" or "fixed", got ${JSON.stringify(type)}.`,
+    );
+  }
+  if (typeof delayMs !== "number" || !Number.isFinite(delayMs) || delayMs < 1) {
+    throw new InvalidJobDefinitionError(
+      name,
+      `\`backoff.delayMs\` must be a positive number of milliseconds, got ${JSON.stringify(delayMs)}.`,
+    );
+  }
+}
+
+/**
+ * Refuse a definition that cannot run. Every check here guards a failure that
+ * is otherwise silent — see {@link InvalidJobDefinitionError}.
+ */
+function assertValidDefinition(definition: JobDefinition<never>): void {
+  if (typeof definition !== "object" || definition === null) {
+    throw new InvalidJobDefinitionError("<unnamed>", "a definition object is required.");
+  }
+  assertText(String(definition.name), "name", definition.name);
+  const { name } = definition;
+  if (typeof definition.handle !== "function") {
+    throw new InvalidJobDefinitionError(name, "`handle` must be a function.");
+  }
+  // `queue: ""` is the sharp one: it is not nullish, so it never falls back to
+  // the default queue — it creates a queue named "" that no worker consumes.
+  if (definition.queue !== undefined) assertText(name, "queue", definition.queue);
+  if (definition.attempts !== undefined) {
+    assertPositiveInteger(name, "attempts", definition.attempts);
+  }
+  if (definition.concurrency !== undefined) {
+    assertPositiveInteger(name, "concurrency", definition.concurrency);
+  }
+  assertBackoff(name, definition.backoff);
+  if (definition.schedule !== undefined) {
+    assertCron(name, definition.schedule.pattern);
+    if (definition.schedule.timezone !== undefined) {
+      assertText(name, "schedule.timezone", definition.schedule.timezone);
+    }
+  }
+}
+
 /**
  * Declare a job and register it under its name.
  *
  * Throws on a duplicate name rather than replacing: two modules quietly
  * claiming one name means one of them never runs, and a schedule installed
- * under that name would fire the wrong handler. (The notification registry
- * replaces on re-register, which is right for *content* generators and wrong
- * for *execution*.)
+ * under that name would fire the wrong handler.
+ *
+ * Throws on an unusable definition too, for the same reason — both are silent
+ * if let through, and both are programming errors a deployment cannot recover
+ * from on its own.
  */
 export function defineJob<TPayload = void>(
   definition: JobDefinition<TPayload>,
 ): RegisteredJob<TPayload> {
+  assertValidDefinition(definition as unknown as JobDefinition<never>);
   if (registry.has(definition.name)) throw new DuplicateJobError(definition.name);
   registry.set(definition.name, definition as unknown as AnyJobDefinition);
 
@@ -68,6 +195,41 @@ export function findJob(name: string): AnyJobDefinition | undefined {
   return registry.get(name);
 }
 
+/**
+ * THE GATE — "may this job run in this deployment?" — and the answer both
+ * sides of the queue key on.
+ *
+ * The enqueue path asks it before a write; the execution path asks it before a
+ * run. One function on purpose: restating the rule on each side is how a write
+ * comes to be accepted that the run side then refuses, which is the shape of a
+ * silent drop — the job lands in the backend, no handler claims it, it
+ * dead-letters, and the caller was told `enqueued: true`.
+ *
+ * Passing a DEFINITION checks identity, not just the name: an impostor object
+ * carrying a registered name would ship a payload the real handler never
+ * agreed to, and it is not the object a worker holds. Passing a NAME is what
+ * the execution side has — a wire key read back off the queue.
+ */
+export function resolveRegisteredJob(
+  job: AnyJobDefinition | string,
+): AnyJobDefinition | undefined {
+  const name = typeof job === "string" ? job : job.name;
+  const registered = registry.get(name);
+  if (!registered) return undefined;
+  if (typeof job !== "string" && registered !== job) return undefined;
+  return registered;
+}
+
+/**
+ * Refuse an empty registry at the point of use. It takes the caller's name so
+ * the message says WHICH entry point was asked — the root `startJobWorkers`
+ * and the server factory both reach this, and an operator reading the log
+ * needs to know which of the two they wired.
+ */
+export function assertJobsRegistered(where: string): void {
+  if (registry.size === 0) throw new NoJobsRegisteredError(where);
+}
+
 /** Test-only: drop every registration (isolation between suites). */
 export function clearJobs(): void {
   registry.clear();

package/src/core/retention.ts

@@ -0,0 +1,68 @@
+import type { JobRetention, JobRetentionWindow } from "./types";
+
+/**
+ * Validation for the retention window a host may now configure.
+ *
+ * It lives in `core` rather than beside the BullMQ driver that consumes it so
+ * that the root entry point can re-export the error without dragging `bullmq`
+ * — and therefore ioredis — into a bundle that only ever enqueues. Nothing
+ * here imports a driver; it is arithmetic on four numbers.
+ */
+
+/**
+ * Raised for a retention window that cannot bound anything.
+ *
+ * The negative case is the one worth the class. BullMQ's count trim runs
+ * `ZREMRANGEBYRANK` derived from the number it is given, so a NEGATIVE count
+ * removes one job per completion instead of holding the set at a ceiling —
+ * which is not "less retention", it is the UNBOUNDED completed-set that the
+ * default exists to prevent, arrived at by way of a config knob. Nothing
+ * throws, no probe reddens, and the symptom is a Redis that fills up weeks
+ * later and starts refusing writes.
+ *
+ * `NaN` is the likelier way in: `ageSeconds: Number(process.env.JOBS_KEEP_H)`
+ * with the variable unset is `NaN`, which every comparison in the trim silently
+ * answers false for.
+ */
+export class InvalidJobRetentionError extends Error {
+  constructor(field: string, value: unknown) {
+    super(
+      `retention.${field} must be a positive finite number, got ${JSON.stringify(value)}. ` +
+        "A non-positive or NaN window does not shrink retention — it stops bounding the set.",
+    );
+    this.name = "InvalidJobRetentionError";
+  }
+}
+
+function assertWindow(half: string, window: JobRetentionWindow | undefined): void {
+  if (typeof window !== "object" || window === null) {
+    throw new InvalidJobRetentionError(half, window);
+  }
+  for (const field of ["ageSeconds", "count"] as const) {
+    const value = window[field];
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+      throw new InvalidJobRetentionError(`${half}.${field}`, value);
+    }
+  }
+}
+
+/**
+ * Refuse a retention that cannot bound the backend.
+ *
+ * Held to the same standard as every sibling numeric input — `attempts` and
+ * `concurrency` go through `assertPositiveInteger`, `backoff.delayMs` through
+ * a finite check, and the driver's `defaultConcurrency` is sanitised with a
+ * `> 0` guard. Retention was the one configurable number with no check on any
+ * path, and it is the only one whose failure is invisible.
+ *
+ * `undefined` is fine and means "use the package default"; it is the values a
+ * host actually spells out that are checked.
+ */
+export function assertValidRetention(retention: JobRetention | undefined): void {
+  if (retention === undefined) return;
+  if (typeof retention !== "object" || retention === null) {
+    throw new InvalidJobRetentionError("<root>", retention);
+  }
+  assertWindow("completed", retention.completed);
+  assertWindow("failed", retention.failed);
+}

package/src/core/runtime.ts

@@ -6,9 +6,15 @@
  * consume), a CONSUMER (the worker: it does both), or neither (a unit test).
  * `configureJobs` installs the driver; `startJobWorkers` is the extra step a
  * consumer takes.
+ *
+ * This is a PUBLIC entry point, not merely `createApiJobs`'s plumbing: the
+ * package root exports all of it, and a host that wires the runtime by hand
+ * reaches every hazard the factory does. So the guards live HERE and the
+ * factory inherits them, rather than the newest surface owning a second copy
+ * the older path never got.
  */
 
-import { listJobs } from "./registry";
+import { assertJobsRegistered, listJobs, resolveRegisteredJob } from "./registry";
 import type {
   AnyJobDefinition,
   EnqueueOptions,
@@ -51,18 +57,31 @@ export function getJobLogger(): JobLogger {
 /**
  * Defer one run of `definition`.
  *
- * **Never throws.** Every caller of this has just committed a durable row —
- * a notification delivery, a due subscription cycle, a stock movement — and
- * the enqueue is only the fast path to acting on it. Redis being down must
- * degrade that to "a sweep will pick it up in a few minutes", not fail the
- * checkout or the webhook that triggered it. The failure is logged loudly and
- * reported in the result for callers that care.
+ * **Never throws.** Every caller of this has just committed a durable row, and
+ * the enqueue is only the fast path to acting on it. The backend being down
+ * must degrade that to "a sweep will pick it up in a few minutes", not fail
+ * the request that triggered it. The failure is logged loudly and reported in
+ * the result for callers that care.
+ *
+ * It does REFUSE an unregistered definition, through the same
+ * `resolveRegisteredJob` gate the execution side calls. Without that, a write
+ * is accepted no worker can ever claim: the job lands in the backend, the
+ * consumer finds no handler for the name, the run dead-letters, and the caller
+ * was told `enqueued: true`. Refusing at the write is louder, and loses
+ * nothing that was not already lost.
  */
 export async function enqueueJob(
   definition: AnyJobDefinition,
   payload: unknown,
   options: EnqueueOptions = {},
 ): Promise<EnqueueResult> {
+  if (!resolveRegisteredJob(definition)) {
+    logger.error(
+      `"${definition.name}" was not enqueued: it is not the job registered under that ` +
+        "name. Enqueue the value defineJob() returned, and import its module first.",
+    );
+    return { enqueued: false, reason: "unregistered" };
+  }
   if (!driver) {
     logger.warn(
       `"${definition.name}" was not enqueued: no driver is configured in this process.`,
@@ -80,9 +99,14 @@ export async function enqueueJob(
 /**
  * Start consuming every registered job and install their cron schedules.
  *
- * Idempotent: a second call is a no-op, so a bootstrap that runs twice (Next
- * can evaluate `instrumentation.ts` more than once in dev) cannot double-
- * consume.
+ * Idempotent: a second call is a no-op, so a bootstrap that runs twice cannot
+ * double-consume.
+ *
+ * Refuses an EMPTY registry. A worker that consumes nothing is not a degraded
+ * deployment but a broken one that looks fine: no queue is read, no schedule
+ * is installed, and the process reports itself started. "The host declared no
+ * jobs" and "the host's job modules were never imported" are the same fact
+ * from here, and the second is the common one.
  */
 export async function startJobWorkers(): Promise<void> {
   if (!driver) throw new Error("startJobWorkers(): no driver configured.");
@@ -90,6 +114,7 @@ export async function startJobWorkers(): Promise<void> {
     logger.warn("startJobWorkers() called twice; ignoring the second call.");
     return;
   }
+  assertJobsRegistered("startJobWorkers()");
   started = true;
 
   const definitions = listJobs();

package/src/core/types.ts

@@ -4,20 +4,18 @@
  * Three layers, each replaceable without touching the others:
  *   - DEFINITIONS describe a unit of deferred work: its name, its retry
  *     policy, its optional cron schedule, and the handler that runs it.
- *   - The REGISTRY collects definitions at import time (the same open/closed
- *     seam the notification generators use) so a worker process can start
- *     every job by importing the modules that define them.
+ *   - The REGISTRY collects definitions at import time so a worker process can
+ *     start every job by importing the modules that define them.
  *   - A DRIVER executes them. BullMQ/Redis in production, inline in tests.
  *
- * Nothing here imports Redis, Prisma, or the host app. A job handler receives
- * a plain payload and is expected to re-read whatever it needs from the
- * database — see the payload rule below.
+ * Nothing here imports Redis, an ORM, or an application's domain. A job
+ * handler receives a plain payload and is expected to re-read whatever it
+ * needs from the database — see the payload rule below.
  */
 
 /**
- * The logging port. Structurally satisfied by a winston logger (what the host
- * app has) and by `console` (what a test wants), so the library needs no
- * logging dependency of its own.
+ * The logging port. Structurally satisfied by a winston-style logger and by
+ * `console`, so the library needs no logging dependency of its own.
  */
 export interface JobLogger {
   info(message: string, ...meta: unknown[]): void;
@@ -37,12 +35,17 @@ export interface JobBackoff {
 
 /** A cron schedule for a repeatable job. */
 export interface JobSchedule {
-  /** Standard 5-field cron expression. */
+  /**
+   * Standard 5-field cron expression (a 6-field form carrying seconds is
+   * accepted too). Validated when the job is defined: a blank or malformed
+   * pattern installs a scheduler that never fires, which is a sweep that
+   * silently never runs.
+   */
   pattern: string;
   /**
    * IANA timezone the pattern is evaluated in. Defaults to UTC — a schedule
-   * that means "03:00 in São Paulo" must say so, because a server's local
-   * zone is not a product decision.
+   * that means "03:00 local" must say WHICH local, because a server's own zone
+   * is not a product decision.
    */
   timezone?: string;
 }
@@ -68,17 +71,17 @@ export type JobHandler<TPayload> = (
  *
  * ## The payload rule
  *
- * A payload carries IDENTIFIERS, never state. `{ notificationId }`, not the
- * rendered e-mail; `{ subscriptionId, periodStart }`, not the amount to
- * charge. Two reasons, and both are load-bearing:
+ * A payload carries IDENTIFIERS, never state. `{ documentId }`, not the
+ * rendered document; `{ accountId, periodStart }`, not the amount to charge.
+ * Two reasons, and both are load-bearing:
  *
- *   1. **Redis is not the source of truth.** The database is. A payload that
- *      duplicates a row's contents is a second copy that can disagree with it
- *      — and the copy is the one that gets acted on, days later, after the row
- *      changed. Re-reading inside the handler is always correct.
- *   2. **Redis can be lost.** A flushed or evicted queue must cost a delayed
- *      run, not a lost or corrupted business fact. Every job here is paired
- *      with a durable row that a sweep can find again.
+ *   1. **The queue is not the source of truth.** The database is. A payload
+ *      that duplicates a row's contents is a second copy that can disagree
+ *      with it — and the copy is the one that gets acted on, days later, after
+ *      the row changed. Re-reading inside the handler is always correct.
+ *   2. **The queue can be lost.** A flushed or evicted backend must cost a
+ *      delayed run, not a lost or corrupted business fact. Pair every job with
+ *      a durable row a sweep can find again.
  *
  * ## Idempotency
  *
@@ -92,8 +95,8 @@ export interface JobDefinition<TPayload = void> {
   /** Dot-namespaced and stable: it is the wire key and the scheduler id. */
   name: string;
   /**
-   * Which queue carries it. One queue ("default") for everything is the right
-   * shape at this scale — one worker, one pair of Redis connections, one
+   * Which queue carries it. One queue (`DEFAULT_QUEUE`) for everything is the
+   * right shape at most scales — one worker, one pair of connections, one
    * dashboard. Move a noisy or slow job onto its own queue when it starts
    * starving the others; no call site changes when you do.
    */
@@ -121,7 +124,8 @@ export interface EnqueueOptions {
   /**
    * Collapses duplicates: while a job with this key is waiting, delayed or
    * active, enqueueing it again is a no-op. Scope it to the work, not the
-   * caller — `notification:<id>`, `low-stock:<itemId>:<date>`.
+   * caller — `<job>:<entity id>`, or `<job>:<entity id>:<date>` for a job that
+   * may legitimately repeat daily.
    *
    * NOT a durability mechanism. The key is forgotten once the job completes
    * and is cleaned up, so it stops accidental double-sends within a window,
@@ -133,8 +137,15 @@ export interface EnqueueOptions {
   delayMs?: number;
 }
 
-/** Why an enqueue did not reach a queue. */
-export type EnqueueSkipReason = "no-driver" | "duplicate" | "error";
+/**
+ * Why an enqueue did not reach a queue.
+ *
+ * `unregistered` is the one that is a PROGRAMMING error rather than an
+ * operational one: the definition handed in is not the one the registry holds
+ * under that name, so no worker in this deployment could ever run it. See
+ * `enqueueJob`.
+ */
+export type EnqueueSkipReason = "no-driver" | "duplicate" | "error" | "unregistered";
 
 /**
  * The result of an enqueue.
@@ -148,6 +159,88 @@ export interface EnqueueResult {
   reason?: EnqueueSkipReason;
 }
 
+/** What happened to one attempt of one job. */
+export interface JobRunEvent {
+  name: string;
+  /** The queue that carried it, already resolved — never `undefined`. */
+  queue: string;
+  /** The driver's id for the run, matching {@link JobContext.runId}. */
+  runId: string;
+  /** 1-based attempt number. */
+  attempt: number;
+  maxAttempts: number;
+}
+
+/** A job that finished successfully. */
+export type JobCompletedEvent = JobRunEvent;
+
+/** A job attempt that threw. */
+export interface JobFailedEvent extends JobRunEvent {
+  error: unknown;
+  /**
+   * No further attempt will be made — the attempt budget is spent, or the
+   * failure was unrecoverable. This is the DEAD-LETTER signal, and the one
+   * moment a host may want to notify someone, open a ticket or page an
+   * operator. A non-terminal failure is ordinary retry noise.
+   */
+  terminal: boolean;
+}
+
+/** A cron schedule that existed in the backend and no longer exists in code. */
+export interface ScheduleRemovedEvent {
+  /** The scheduler key, which is the name of the job that installed it. */
+  name: string;
+  queue: string;
+}
+
+/**
+ * The observation port — how the rest of a system finds out what the queue did.
+ *
+ * This package deliberately does NOT notify, audit or publish anything itself:
+ * it has no opinion about who should hear that a job dead-lettered, and
+ * reaching for a notification package here would make every host inherit that
+ * opinion (and that dependency). What it owns is the MOMENT, so the moment is
+ * exported and the host wires the consequence.
+ *
+ * Every hook is optional, and a hook that throws is logged and swallowed — an
+ * observer must never fail the job it is observing, nor the reconcile that
+ * removed a stale schedule.
+ */
+export interface JobEvents {
+  /** A job finished successfully. The seam for a realtime "it is done" event. */
+  onJobCompleted?(event: JobCompletedEvent): void | Promise<void>;
+  /**
+   * An attempt failed. Check `terminal` — that is the dead-letter, and the
+   * only one of the two most hosts want to act on.
+   */
+  onJobFailed?(event: JobFailedEvent): void | Promise<void>;
+  /**
+   * A schedule was removed from the backend because no code declares it any
+   * more. Destructive and unrecoverable from the queue's side, which is why it
+   * is the schedule event worth auditing; installation is an idempotent upsert
+   * that happens on every boot, so auditing that would write noise per deploy.
+   */
+  onScheduleRemoved?(event: ScheduleRemovedEvent): void | Promise<void>;
+}
+
+/** How long finished jobs are kept in the backend before they are trimmed. */
+export interface JobRetentionWindow {
+  ageSeconds: number;
+  count: number;
+}
+
+/**
+ * Retention for finished jobs. Bounded on purpose: an unbounded completed-set
+ * is the classic way a small queue backend fills up and starts refusing
+ * writes. The package default keeps a day of successes (enough to answer "did
+ * it run?") and a week of failures (enough to debug one); a host whose support
+ * window is longer says so rather than forking the driver.
+ */
+export interface JobRetention {
+  completed: JobRetentionWindow;
+  failed: JobRetentionWindow;
+}
+
 /**
  * The driver port. `inline` and `bullmq` implement it; a third (SQS, pg-boss)
  * would need no change above this line.

package/src/drivers/bullmq-policy.ts

@@ -0,0 +1,86 @@
+import { UnrecoverableError, type JobsOptions } from "bullmq";
+
+import { assertValidRetention } from "../core/retention";
+import type { AnyJobDefinition, JobRetention } from "../core/types";
+
+/**
+ * The BullMQ driver's three policy decisions, kept together and out of the
+ * driver body — retention, concurrency and what counts as a dead-letter.
+ *
+ * All three share a property that makes them worth their own file and their
+ * own tests: each is SILENT when it is wrong. Nothing throws, no probe turns
+ * red, and the only symptom is behaviour nobody is watching — a queue that
+ * filled up, a sweep that quietly stopped being single-flight, a pager that
+ * never went off.
+ */
+
+/** Worker concurrency when no definition on the queue asks for a specific one. */
+export const DEFAULT_CONCURRENCY = 5;
+
+/**
+ * The package's retention default: a day of successes is enough to answer "did
+ * it run?", a week of failures is enough to debug one. Bounded on purpose — an
+ * unbounded completed-set is the classic way a small Redis fills up and starts
+ * refusing writes. A host with a different support window passes its own
+ * {@link JobRetention} rather than forking the driver.
+ */
+export const DEFAULT_JOB_RETENTION: JobRetention = {
+  completed: { ageSeconds: 24 * 3600, count: 1_000 },
+  failed: { ageSeconds: 7 * 24 * 3600, count: 5_000 },
+};
+
+/**
+ * Validated HERE, at the single funnel both paths cross, rather than only at
+ * the server factory: `@12-apps/jobs/bullmq` is a published entry point, so a
+ * host that builds the driver itself would otherwise reach BullMQ with an
+ * unchecked window. `createApiJobs` checks the same thing at assembly so the
+ * failure lands on the line that wrote it, and this is the backstop that makes
+ * the check a property of the driver rather than of the newest caller.
+ */
+export function retentionOptions(
+  retention: JobRetention,
+): Pick<JobsOptions, "removeOnComplete" | "removeOnFail"> {
+  assertValidRetention(retention);
+  return {
+    removeOnComplete: {
+      age: retention.completed.ageSeconds,
+      count: retention.completed.count,
+    },
+    removeOnFail: { age: retention.failed.ageSeconds, count: retention.failed.count },
+  };
+}
+
+/**
+ * A queue's worker concurrency.
+ *
+ * The default applies only when NO definition on the queue asked for a
+ * specific number. A stated `concurrency: 1` means single-flight and must be
+ * honoured — taking `max(default, …)` would quietly raise it back to the
+ * default and undo the very property the caller asked for.
+ */
+export function resolveConcurrency(
+  group: readonly AnyJobDefinition[],
+  fallback: number = DEFAULT_CONCURRENCY,
+): number {
+  const stated = group
+    .map((definition) => definition.concurrency)
+    .filter((value): value is number => typeof value === "number" && value > 0);
+  return stated.length > 0 ? Math.max(...stated) : fallback;
+}
+
+/**
+ * Is this the last thing that will happen to the job?
+ *
+ * The whole value of `onJobFailed` rests on this bit: a host pages someone on
+ * a dead-letter and must not page them on every retry. Two ways to be
+ * terminal — the attempt budget is spent, or the failure was declared
+ * unrecoverable (a name no handler claims is the common one, and BullMQ never
+ * retries it).
+ */
+export function isTerminalFailure(
+  attemptsMade: number,
+  maxAttempts: number,
+  error: unknown,
+): boolean {
+  return attemptsMade >= maxAttempts || error instanceof UnrecoverableError;
+}