@12-apps/jobs 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# @12-apps/jobs
+
+Typed background jobs — retries, exponential backoff and cron — behind a
+swappable driver. BullMQ/Redis in production, inline execution in tests.
+
+Framework-free: no Prisma, no Next, no host-app types. The logger is a port.
+
+```ts
+// where the domain lives — the import IS the registration
+export const dispatchNotification = defineJob<{ notificationId: string }>({
+  name: "notifications.dispatch",
+  attempts: 5,
+  backoff: { type: "exponential", delayMs: 5_000 },
+  handle: async ({ notificationId }) => dispatchDeliveries(notificationId),
+});
+
+// a job that only ever runs on a schedule needs no binding at all
+defineJob({
+  name: "notifications.drain",
+  schedule: { pattern: "*/5 * * * *", timezone: "UTC" },
+  handle: async () => drainPending(),
+});
+
+// at an emit site
+await dispatchNotification.enqueue({ notificationId }, { dedupeKey: notificationId });
+
+// at process start
+import { createBullMqJobDriver } from "@12-apps/jobs/bullmq";  // not the barrel
+configureJobs({ driver: createBullMqJobDriver({ redisUrl, logger }), logger });
+await startJobWorkers();   // consumers only
+```
+
+## The two rules
+
+**Payloads carry identifiers, never state.** `{ notificationId }`, not the
+rendered e-mail. The database is the source of truth; the queue only decides
+*when*. A payload that duplicates a row is a second copy that can disagree with
+it, and it is the copy that gets acted on days later.
+
+**Handlers are idempotent.** Delivery is at-least-once — a worker can die
+between the side effect and the acknowledgement. Lean on the database's unique
+constraints, not on the queue.
+
+## Guarantees and non-guarantees
+
+- `enqueue` **never throws**. A queue outage returns `{ enqueued: false }` and
+  logs; it does not fail the request that was deferring work.
+- Bounded Redis memory: completed jobs are kept a day, failed ones a week.
+- Schedules are **reconciled** on start — a cron job deleted from code has its
+  scheduler removed from Redis, instead of firing forever at a handler that no
+  longer exists.
+- The `inline` driver honours `attempts` but not delays or schedules, and both
+  omissions are logged rather than silent. It is refused in production by the
+  host, not by this package.
+
+The BullMQ driver is exported from `@12-apps/jobs/bullmq`, never the barrel, so
+importing `defineJob` at an emit site does not drag Redis into the bundle.
+
+Redis must run with `maxmemory-policy noeviction` — the driver checks and
+complains. See [docs/JOBS.md](../../docs/JOBS.md) for the deployment side.

package/eslint.config.js

@@ -0,0 +1,22 @@
+import { config as baseConfig } from "@12-apps/eslint-config/base";
+import testFlakiness from "eslint-plugin-test-flakiness";
+
+/**
+ * The everyday DX lint for this package. Mirrors `packages/entitlements`:
+ * `eslint-plugin-test-flakiness` is registered with every rule OFF so that
+ * inline disable directives in test files RESOLVE here, while the rules
+ * themselves stay enforced by the repo-root flakiness lane.
+ */
+
+/** @type {import("eslint").Linter.Config[]} */
+export default [
+  ...baseConfig,
+  {
+    files: ["**/__tests__/**", "**/*.test.ts"],
+    plugins: { "test-flakiness": testFlakiness },
+    linterOptions: { reportUnusedDisableDirectives: "off" },
+  },
+  {
+    ignores: ["dist/**", "node_modules/**", "coverage/**"],
+  },
+];

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@12-apps/jobs",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Generic background-job library: a typed job registry with retries, exponential backoff and cron schedules, behind a swappable driver port (BullMQ/Redis in production, inline execution in tests). Framework-free; knows nothing about the host app's domain, ORM or transport.",
+  "exports": {
+    ".": "./src/index.ts",
+    "./bullmq": "./src/drivers/bullmq.ts",
+    "./inline": "./src/drivers/inline.ts"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules coverage",
+    "test": "node ../../scripts/vitest-with-teardown.mjs run",
+    "test:watch": "vitest watch",
+    "lint": "eslint src --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "bullmq": "^5.81.2"
+  },
+  "devDependencies": {
+    "@12-apps/eslint-config": "^1.1.0",
+    "@12-apps/typescript-config": "^1.1.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-test-flakiness": "^1.4.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/12-apps/shared-packages.git",
+    "directory": "packages/jobs"
+  },
+  "files": [
+    "src",
+    "dist",
+    "prisma",
+    "*.js",
+    "*.mjs",
+    "*.md"
+  ]
+}

package/src/core/__tests__/registry.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createInlineJobDriver } from "../../drivers/inline";
+import { clearJobs, defineJob, DuplicateJobError, findJob, listJobs } from "../registry";
+import { configureJobs, enqueueJob, resetJobRuntime, startJobWorkers } from "../runtime";
+
+afterEach(() => {
+  clearJobs();
+  resetJobRuntime();
+});
+
+describe("defineJob", () => {
+  it("registers the definition under its name", () => {
+    const job = defineJob({ name: "a.job", handle: () => Promise.resolve() });
+
+    expect(job.name).toBe("a.job");
+    expect(findJob("a.job")).toBe(job.definition);
+    expect(listJobs()).toHaveLength(1);
+  });
+
+  it("refuses a duplicate name rather than replacing the handler", () => {
+    defineJob({ name: "a.job", handle: () => Promise.resolve() });
+
+    expect(() => defineJob({ name: "a.job", handle: () => Promise.resolve() })).toThrow(
+      DuplicateJobError,
+    );
+  });
+});
+
+describe("enqueue", () => {
+  it("runs the handler through the installed driver", async () => {
+    const handle = vi.fn().mockResolvedValue(undefined);
+    const job = defineJob<{ id: string }>({ name: "a.job", handle });
+    configureJobs({ driver: createInlineJobDriver({ logger: silentLogger() }) });
+
+    const result = await job.enqueue({ id: "x" });
+
+    expect(result).toEqual({ enqueued: true });
+    expect(handle).toHaveBeenCalledWith(
+      { id: "x" },
+      expect.objectContaining({ attempt: 1, maxAttempts: 1 }),
+    );
+  });
+
+  it("reports rather than throws when no driver is configured", async () => {
+    const job = defineJob({ name: "a.job", handle: () => Promise.resolve() });
+
+    await expect(job.enqueue()).resolves.toEqual({
+      enqueued: false,
+      reason: "no-driver",
+    });
+  });
+
+  it("reports rather than throws when the driver itself fails", async () => {
+    const definition = { name: "a.job", handle: () => Promise.resolve() };
+    configureJobs({
+      logger: silentLogger(),
+      driver: {
+        kind: "broken",
+        enqueue: () => Promise.reject(new Error("redis is down")),
+        start: () => Promise.resolve(),
+        stop: () => Promise.resolve(),
+      },
+    });
+
+    await expect(enqueueJob(definition, undefined, {})).resolves.toEqual({
+      enqueued: false,
+      reason: "error",
+    });
+  });
+});
+
+describe("startJobWorkers", () => {
+  it("starts every registered job once, ignoring a second call", async () => {
+    defineJob({ name: "a.job", handle: () => Promise.resolve() });
+    const start = vi.fn().mockResolvedValue(undefined);
+    configureJobs({
+      logger: silentLogger(),
+      driver: {
+        kind: "spy",
+        enqueue: () => Promise.resolve({ enqueued: true }),
+        start,
+        stop: () => Promise.resolve(),
+      },
+    });
+
+    await startJobWorkers();
+    await startJobWorkers();
+
+    expect(start).toHaveBeenCalledTimes(1);
+    expect(start.mock.calls[0]?.[0]).toHaveLength(1);
+  });
+
+  it("refuses to start with no driver configured", async () => {
+    await expect(startJobWorkers()).rejects.toThrow("no driver configured");
+  });
+});
+
+function silentLogger() {
+  return { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+}

package/src/core/registry.ts

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+
+import type {
+  AnyJobDefinition,
+  EnqueueOptions,
+  EnqueueResult,
+  JobDefinition,
+} from "./types";
+
+/** A defined job: its declaration, plus the typed way to enqueue one. */
+export interface RegisteredJob<TPayload> {
+  readonly name: string;
+  readonly definition: JobDefinition<TPayload>;
+  /** Defer one run. Never throws — see {@link EnqueueResult}. */
+  enqueue(payload: TPayload, options?: EnqueueOptions): Promise<EnqueueResult>;
+}
+
+const registry = new Map<string, AnyJobDefinition>();
+
+/** Raised for a duplicate job name — always a programming error. */
+export class DuplicateJobError extends Error {
+  constructor(name: string) {
+    super(`A job named "${name}" is already defined.`);
+    this.name = "DuplicateJobError";
+  }
+}
+
+/**
+ * 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*.)
+ */
+export function defineJob<TPayload = void>(
+  definition: JobDefinition<TPayload>,
+): RegisteredJob<TPayload> {
+  if (registry.has(definition.name)) throw new DuplicateJobError(definition.name);
+  registry.set(definition.name, definition as unknown as AnyJobDefinition);
+
+  return {
+    name: definition.name,
+    definition,
+    async enqueue(payload, options = {}) {
+      // Imported lazily: the runtime imports this module, and a static cycle
+      // would leave one of the two half-initialized at first use.
+      const { enqueueJob } = await import("./runtime");
+      return enqueueJob(definition as unknown as AnyJobDefinition, payload, options);
+    },
+  };
+}
+
+/** Every registered definition, in declaration order. */
+export function listJobs(): readonly AnyJobDefinition[] {
+  return [...registry.values()];
+}
+
+/** One definition by name, or `undefined`. */
+export function findJob(name: string): AnyJobDefinition | undefined {
+  return registry.get(name);
+}
+
+/** Test-only: drop every registration (isolation between suites). */
+export function clearJobs(): void {
+  registry.clear();
+}

package/src/core/runtime.ts

@@ -0,0 +1,116 @@
+/**
+ * The process-wide job runtime: which driver is installed, and the enqueue /
+ * start / stop entry points that everything else goes through.
+ *
+ * A process is either a PRODUCER (the web server: it enqueues, it does not
+ * 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.
+ */
+
+import { listJobs } from "./registry";
+import type {
+  AnyJobDefinition,
+  EnqueueOptions,
+  EnqueueResult,
+  JobDriver,
+  JobLogger,
+} from "./types";
+
+/** Fallback logger — used until the host installs its own. */
+const consoleLogger: JobLogger = {
+  info: (message, ...meta) => console.info(`[jobs] ${message}`, ...meta),
+  warn: (message, ...meta) => console.warn(`[jobs] ${message}`, ...meta),
+  error: (message, ...meta) => console.error(`[jobs] ${message}`, ...meta),
+};
+
+let driver: JobDriver | null = null;
+let logger: JobLogger = consoleLogger;
+let started = false;
+
+/** Install the driver (and optionally the host's logger) for this process. */
+export function configureJobs(options: {
+  driver: JobDriver;
+  logger?: JobLogger;
+}): void {
+  driver = options.driver;
+  if (options.logger) logger = options.logger;
+  logger.info(`runtime configured with the "${options.driver.kind}" driver`);
+}
+
+/** The installed driver, or `null` in a process that never configured one. */
+export function getJobDriver(): JobDriver | null {
+  return driver;
+}
+
+/** The logger the runtime and drivers write through. */
+export function getJobLogger(): JobLogger {
+  return logger;
+}
+
+/**
+ * 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.
+ */
+export async function enqueueJob(
+  definition: AnyJobDefinition,
+  payload: unknown,
+  options: EnqueueOptions = {},
+): Promise<EnqueueResult> {
+  if (!driver) {
+    logger.warn(
+      `"${definition.name}" was not enqueued: no driver is configured in this process.`,
+    );
+    return { enqueued: false, reason: "no-driver" };
+  }
+  try {
+    return await driver.enqueue(definition, payload, options);
+  } catch (error) {
+    logger.error(`enqueue of "${definition.name}" failed:`, error);
+    return { enqueued: false, reason: "error" };
+  }
+}
+
+/**
+ * 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.
+ */
+export async function startJobWorkers(): Promise<void> {
+  if (!driver) throw new Error("startJobWorkers(): no driver configured.");
+  if (started) {
+    logger.warn("startJobWorkers() called twice; ignoring the second call.");
+    return;
+  }
+  started = true;
+
+  const definitions = listJobs();
+  await driver.start(definitions);
+  const scheduled = definitions.filter((job) => job.schedule).length;
+  logger.info(
+    `workers started: ${definitions.length} job(s), ${scheduled} on a schedule.`,
+  );
+}
+
+/** Stop consuming and release the driver's connections. */
+export async function stopJobs(): Promise<void> {
+  if (!driver) return;
+  await driver.stop();
+  started = false;
+  logger.info("workers stopped.");
+}
+
+/** Test-only: forget the installed driver and the started flag. */
+export function resetJobRuntime(): void {
+  driver = null;
+  logger = consoleLogger;
+  started = false;
+}

package/src/core/types.ts

@@ -0,0 +1,171 @@
+/**
+ * Core types of the background-job library.
+ *
+ * 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.
+ *   - 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.
+ */
+
+/**
+ * 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.
+ */
+export interface JobLogger {
+  info(message: string, ...meta: unknown[]): void;
+  warn(message: string, ...meta: unknown[]): void;
+  error(message: string, ...meta: unknown[]): void;
+}
+
+/** Retry spacing after a failed attempt. */
+export interface JobBackoff {
+  /**
+   * `exponential` doubles `delayMs` per attempt (5s → 10s → 20s → …), which is
+   * what a flaky provider call wants. `fixed` waits `delayMs` every time.
+   */
+  type: "exponential" | "fixed";
+  delayMs: number;
+}
+
+/** A cron schedule for a repeatable job. */
+export interface JobSchedule {
+  /** Standard 5-field cron expression. */
+  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.
+   */
+  timezone?: string;
+}
+
+/** What a handler is told about the attempt it is running in. */
+export interface JobContext {
+  /** The driver's id for this run. Useful in logs; never a business key. */
+  runId: string;
+  /** 1-based. `attempt === maxAttempts` means this is the last chance. */
+  attempt: number;
+  maxAttempts: number;
+  logger: JobLogger;
+}
+
+/** The unit of work itself. Throwing schedules a retry; returning succeeds. */
+export type JobHandler<TPayload> = (
+  payload: TPayload,
+  context: JobContext,
+) => Promise<void>;
+
+/**
+ * A job's declaration.
+ *
+ * ## 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:
+ *
+ *   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.
+ *
+ * ## Idempotency
+ *
+ * At-least-once delivery is the contract. A handler MUST tolerate running
+ * twice on the same payload — the driver can redeliver after a worker dies
+ * between the side effect and the acknowledgement, and a retry after a
+ * timeout may race the original. Lean on the database's unique constraints
+ * for this, not on the queue.
+ */
+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
+   * dashboard. Move a noisy or slow job onto its own queue when it starts
+   * starving the others; no call site changes when you do.
+   */
+  queue?: string;
+  /** Total attempts including the first. Defaults to 1 (no retry). */
+  attempts?: number;
+  backoff?: JobBackoff;
+  /** Present ⇒ the job also runs on a schedule, with no payload. */
+  schedule?: JobSchedule;
+  /**
+   * Per-queue worker concurrency. Set it on any job in the queue; the highest
+   * STATED value wins, and the driver's default applies only when no job on
+   * the queue states one — so `concurrency: 1` really does mean single-flight
+   * rather than being raised back to the default.
+   */
+  concurrency?: number;
+  handle: JobHandler<TPayload>;
+}
+
+/** A definition with its payload type erased — what registries and drivers hold. */
+export type AnyJobDefinition = JobDefinition<never>;
+
+/** Per-enqueue overrides. */
+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>`.
+   *
+   * 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,
+   * not double-processing across days. Business idempotency stays in the
+   * database.
+   */
+  dedupeKey?: string;
+  /** Run no earlier than this many milliseconds from now. */
+  delayMs?: number;
+}
+
+/** Why an enqueue did not reach a queue. */
+export type EnqueueSkipReason = "no-driver" | "duplicate" | "error";
+
+/**
+ * The result of an enqueue.
+ *
+ * Enqueueing NEVER throws (see `enqueueJob`): a queue outage must not take
+ * down the request that was merely trying to defer some work. The caller has
+ * already committed the durable row; a sweep will find it.
+ */
+export interface EnqueueResult {
+  enqueued: boolean;
+  reason?: EnqueueSkipReason;
+}
+
+/**
+ * The driver port. `inline` and `bullmq` implement it; a third (SQS, pg-boss)
+ * would need no change above this line.
+ */
+export interface JobDriver {
+  readonly kind: string;
+  /** Hand one unit of work to the backend. Throws only on a real backend fault. */
+  enqueue(
+    definition: AnyJobDefinition,
+    payload: unknown,
+    options: EnqueueOptions,
+  ): Promise<EnqueueResult>;
+  /**
+   * Begin consuming, and install the cron schedules of every definition that
+   * declares one. Idempotent: calling it twice must not double-consume or
+   * duplicate a schedule.
+   */
+  start(definitions: readonly AnyJobDefinition[]): Promise<void>;
+  /** Stop consuming and release connections, letting in-flight jobs finish. */
+  stop(): Promise<void>;
+}

package/src/drivers/__tests__/concurrency.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+
+import type { AnyJobDefinition } from "../../core/types";
+import { __testables } from "../bullmq";
+
+/**
+ * The queue-concurrency rule. Pinned on its own because getting it wrong is
+ * SILENT: a job that asked for single-flight would simply run concurrently,
+ * and nothing would fail — the sweeps would just start racing each other again.
+ */
+const { resolveConcurrency, DEFAULT_CONCURRENCY } = __testables;
+
+function job(overrides: Partial<AnyJobDefinition> = {}): AnyJobDefinition {
+  return { name: "a.job", handle: () => Promise.resolve(), ...overrides };
+}
+
+describe("resolveConcurrency", () => {
+  it("falls back to the default when no job on the queue states one", () => {
+    expect(resolveConcurrency([job(), job({ name: "b.job" })])).toBe(DEFAULT_CONCURRENCY);
+  });
+
+  it("honours a stated 1 instead of raising it to the default", () => {
+    // The regression this exists for: `Math.max(DEFAULT, ...)` silently turns
+    // single-flight back into the default and undoes the guarantee.
+    expect(resolveConcurrency([job({ concurrency: 1 })])).toBe(1);
+  });
+
+  it("takes the highest STATED value when several are given", () => {
+    expect(
+      resolveConcurrency([job({ concurrency: 1 }), job({ name: "b.job", concurrency: 4 })]),
+    ).toBe(4);
+  });
+
+  it("ignores a stated value alongside unstated ones rather than averaging in the default", () => {
+    expect(resolveConcurrency([job({ concurrency: 2 }), job({ name: "b.job" })])).toBe(2);
+  });
+
+  it("ignores a nonsensical value", () => {
+    expect(resolveConcurrency([job({ concurrency: 0 })])).toBe(DEFAULT_CONCURRENCY);
+    expect(resolveConcurrency([job({ concurrency: -3 })])).toBe(DEFAULT_CONCURRENCY);
+  });
+});

package/src/drivers/__tests__/inline.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { AnyJobDefinition } from "../../core/types";
+import { createInlineJobDriver } from "../inline";
+
+function silentLogger() {
+  return { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+}
+
+function definition(overrides: Partial<AnyJobDefinition> = {}): AnyJobDefinition {
+  return { name: "a.job", handle: () => Promise.resolve(), ...overrides };
+}
+
+describe("inline driver", () => {
+  it("awaits the handler so a test sees the side effect", async () => {
+    const seen: string[] = [];
+    const driver = createInlineJobDriver({ logger: silentLogger() });
+
+    await driver.enqueue(
+      definition({ handle: (payload) => {
+        seen.push(payload as string);
+        return Promise.resolve();
+      } }),
+      "one",
+      {},
+    );
+
+    expect(seen).toEqual(["one"]);
+  });
+
+  it("retries up to `attempts` and records the run", async () => {
+    const handle = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("transient"))
+      .mockResolvedValueOnce(undefined);
+    const driver = createInlineJobDriver({ logger: silentLogger() });
+
+    await driver.enqueue(definition({ attempts: 3, handle }), undefined, {});
+
+    expect(handle).toHaveBeenCalledTimes(2);
+    expect(driver.runs).toEqual([
+      { name: "a.job", payload: undefined, attempts: 2, error: undefined },
+    ]);
+  });
+
+  it("swallows a handler that fails every attempt, logging it once", async () => {
+    const logger = silentLogger();
+    const handle = vi.fn().mockRejectedValue(new Error("permanent"));
+    const driver = createInlineJobDriver({ logger });
+
+    await expect(
+      driver.enqueue(definition({ attempts: 2, handle }), undefined, {}),
+    ).resolves.toEqual({ enqueued: true });
+
+    expect(handle).toHaveBeenCalledTimes(2);
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    expect(driver.runs[0]?.error).toBeInstanceOf(Error);
+  });
+
+  it("warns that a delay is ignored instead of silently dropping it", async () => {
+    const logger = silentLogger();
+    const driver = createInlineJobDriver({ logger });
+
+    await driver.enqueue(definition(), undefined, { delayMs: 3_000 });
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("ignored a 3000ms delay"),
+    );
+  });
+
+  it("warns that registered schedules will never fire", async () => {
+    const logger = silentLogger();
+    const driver = createInlineJobDriver({ logger });
+
+    await driver.start([definition({ schedule: { pattern: "0 * * * *" } })]);
+
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("a.job"));
+  });
+});

package/src/drivers/__tests__/redis-url.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+
+import { InvalidRedisUrlError, parseRedisUrl } from "../redis-url";
+
+describe("parseRedisUrl", () => {
+  it("defaults host, port and database", () => {
+    expect(parseRedisUrl("redis://localhost")).toEqual({
+      host: "localhost",
+      port: 6379,
+      username: undefined,
+      password: undefined,
+      db: undefined,
+      tls: undefined,
+      maxRetriesPerRequest: null,
+      enableReadyCheck: false,
+    });
+  });
+
+  it("reads credentials, port and database from the URL", () => {
+    const parsed = parseRedisUrl("redis://user:p%40ss@redis:6380/3");
+
+    expect(parsed).toMatchObject({
+      host: "redis",
+      port: 6380,
+      username: "user",
+      password: "p@ss",
+      db: 3,
+    });
+  });
+
+  it("enables TLS for rediss://", () => {
+    expect(parseRedisUrl("rediss://redis:6379").tls).toEqual({});
+  });
+
+  it("always pins the two options BullMQ requires", () => {
+    const parsed = parseRedisUrl("redis://redis:6379/1");
+
+    expect(parsed.maxRetriesPerRequest).toBeNull();
+    expect(parsed.enableReadyCheck).toBe(false);
+  });
+
+  it("rejects a non-Redis protocol", () => {
+    expect(() => parseRedisUrl("http://redis:6379")).toThrow(InvalidRedisUrlError);
+  });
+
+  it("rejects a malformed URL", () => {
+    expect(() => parseRedisUrl("not a url")).toThrow(InvalidRedisUrlError);
+  });
+
+  it("never puts the URL (which can carry a password) in the error message", () => {
+    expect(() => parseRedisUrl("http://user:hunter2@redis:6379")).toThrow(
+      expect.objectContaining({
+        message: expect.not.stringContaining("hunter2") as unknown as string,
+      }),
+    );
+  });
+});

package/src/drivers/bullmq.ts

@@ -0,0 +1,302 @@
+/**
+ * The BULLMQ driver — the production path.
+ *
+ * ## What Redis is, and is not
+ *
+ * It is the EXECUTOR: what runs next, how many at once, when to retry. It is
+ * never the ledger. Payloads carry ids (see `JobDefinition`'s payload rule),
+ * every handler re-reads its row, and every job is paired with a durable table
+ * a sweep can re-derive the work from. Losing Redis therefore costs a delayed
+ * run — not a lost charge, and not a double one.
+ *
+ * That split is what makes the enqueue-outside-the-transaction problem
+ * survivable. A Prisma commit followed by an enqueue is not atomic: crash in
+ * between and the job never lands. The paired sweep is the answer — the row is
+ * committed, so the next tick finds it.
+ *
+ * ## Redis configuration this driver depends on
+ *
+ * `maxmemory-policy` MUST be `noeviction`. Under any `allkeys-*` policy Redis
+ * will evict live queue keys under pressure and BullMQ loses jobs silently.
+ * The driver checks on start and complains loudly rather than trusting it.
+ * Persistence (AOF) should be on: a restart otherwise drops delayed jobs, and
+ * the schedules are re-installed on boot but pending retries are not.
+ */
+
+import { Queue, UnrecoverableError, Worker, type JobsOptions } from "bullmq";
+
+import type {
+  AnyJobDefinition,
+  EnqueueOptions,
+  EnqueueResult,
+  JobContext,
+  JobDriver,
+  JobLogger,
+} from "../core/types";
+
+import { parseRedisUrl, type RedisConnectionOptions } from "./redis-url";
+
+/** The queue a definition lands on when it does not name one. */
+const DEFAULT_QUEUE = "default";
+/** Worker concurrency when no definition in the queue asks for more. */
+const DEFAULT_CONCURRENCY = 5;
+
+/**
+ * Retention. Bounded on purpose: an unbounded completed-set is the classic way
+ * a small Redis fills up and starts refusing writes. A day of successes is
+ * enough to answer "did it run?"; a week of failures is enough to debug one.
+ */
+const RETENTION: Pick<JobsOptions, "removeOnComplete" | "removeOnFail"> = {
+  removeOnComplete: { age: 24 * 3600, count: 1_000 },
+  removeOnFail: { age: 7 * 24 * 3600, count: 5_000 },
+};
+
+/** The one ioredis command this driver reads outside BullMQ's own surface. */
+interface RedisConfigReader {
+  config(command: "GET", parameter: string): Promise<unknown>;
+}
+
+export interface BullMqJobDriverOptions {
+  /** `redis://[user:pass@]host:port[/db]`. */
+  redisUrl: string;
+  logger: JobLogger;
+  /**
+   * Key prefix, so one Redis can carry several environments without a staging
+   * worker consuming production's jobs.
+   */
+  prefix?: string;
+}
+
+/** Everything the driver's helpers need, threaded instead of closed over. */
+interface DriverState {
+  connection: RedisConnectionOptions;
+  logger: JobLogger;
+  prefix?: string;
+  queues: Map<string, Queue>;
+  workers: Worker[];
+}
+
+/** Turn a definition's retry policy into BullMQ's per-job options. */
+function jobOptionsFor(
+  definition: AnyJobDefinition,
+  enqueueOptions: EnqueueOptions,
+): JobsOptions {
+  const options: JobsOptions = {
+    attempts: Math.max(1, definition.attempts ?? 1),
+    ...RETENTION,
+  };
+  if (definition.backoff) {
+    options.backoff = {
+      type: definition.backoff.type,
+      delay: definition.backoff.delayMs,
+    };
+  }
+  if (enqueueOptions.delayMs) options.delay = enqueueOptions.delayMs;
+  if (enqueueOptions.dedupeKey) {
+    // BullMQ's own deduplication (not a hijacked `jobId`): the entry is
+    // released when the job finishes, so a later, legitimately-identical run
+    // is not swallowed by a retained completed job.
+    options.deduplication = { id: enqueueOptions.dedupeKey };
+  }
+  return options;
+}
+
+function queueFor(state: DriverState, name: string): Queue {
+  const existing = state.queues.get(name);
+  if (existing) return existing;
+
+  const queue = new Queue(name, {
+    connection: state.connection,
+    ...(state.prefix ? { prefix: state.prefix } : {}),
+    defaultJobOptions: RETENTION,
+  });
+  // Without a listener an emitted 'error' is an unhandled exception that takes
+  // the process down — a Redis blip must not kill the web server.
+  queue.on("error", (error) => state.logger.error(`queue "${name}" error:`, error));
+  state.queues.set(name, queue);
+  return queue;
+}
+
+/**
+ * Warn when Redis is configured to evict. Best-effort: managed providers
+ * routinely forbid `CONFIG GET`, and an unanswerable check is not a reason to
+ * refuse to start.
+ */
+async function checkEvictionPolicy(state: DriverState, queue: Queue): Promise<void> {
+  try {
+    // `CONFIG` is an ioredis command BullMQ's narrower client type does not
+    // advertise. Reached through a structural type rather than a blanket cast,
+    // and guarded — this is a diagnostic, not a dependency.
+    const client = (await queue.client) as unknown as Partial<RedisConfigReader>;
+    if (typeof client.config !== "function") return;
+    const config = await client.config("GET", "maxmemory-policy");
+    const policy = Array.isArray(config) ? String(config[1]) : "";
+    if (policy && policy !== "noeviction") {
+      state.logger.error(
+        `Redis maxmemory-policy is "${policy}", not "noeviction" — queued jobs CAN be evicted and lost. Fix the Redis config.`,
+      );
+    }
+  } catch {
+    state.logger.info(
+      "could not read Redis maxmemory-policy (provider restricts CONFIG).",
+    );
+  }
+}
+
+/**
+ * Install every cron schedule and REMOVE the ones no longer declared in code.
+ *
+ * Without the removal half, a renamed or deleted cron job keeps firing forever
+ * from Redis — the schedule outlives the deploy that created it, and lands on a
+ * handler that no longer exists.
+ */
+async function reconcileSchedules(
+  state: DriverState,
+  queue: Queue,
+  definitions: readonly AnyJobDefinition[],
+): Promise<void> {
+  const wanted = new Map(
+    definitions.filter((job) => job.schedule).map((job) => [job.name, job]),
+  );
+
+  for (const [name, job] of wanted) {
+    const schedule = job.schedule;
+    if (!schedule) continue;
+    await queue.upsertJobScheduler(
+      name,
+      { pattern: schedule.pattern, tz: schedule.timezone ?? "UTC" },
+      { name, data: {}, opts: jobOptionsFor(job, {}) },
+    );
+    state.logger.info(
+      `schedule installed: ${name} (${schedule.pattern} ${schedule.timezone ?? "UTC"})`,
+    );
+  }
+
+  for (const scheduler of await queue.getJobSchedulers()) {
+    if (wanted.has(scheduler.key)) continue;
+    await queue.removeJobScheduler(scheduler.key);
+    state.logger.warn(
+      `removed stale schedule "${scheduler.key}" (no longer defined in code).`,
+    );
+  }
+}
+
+/**
+ * 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.
+ */
+function resolveConcurrency(group: readonly AnyJobDefinition[]): 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) : DEFAULT_CONCURRENCY;
+}
+
+/** Consume one queue, dispatching by job name to the definitions it carries. */
+function startWorker(
+  state: DriverState,
+  queueName: string,
+  group: readonly AnyJobDefinition[],
+): Worker {
+  const byName = new Map(group.map((definition) => [definition.name, definition]));
+  const concurrency = resolveConcurrency(group);
+
+  const worker = new Worker(
+    queueName,
+    async (job) => {
+      const definition = byName.get(job.name);
+      if (!definition) {
+        // A job left in Redis by a previous deploy whose handler is gone.
+        // Retrying cannot help, so fail it terminally instead of burning every
+        // attempt on it.
+        throw new UnrecoverableError(`No handler registered for job "${job.name}".`);
+      }
+      const context: JobContext = {
+        runId: job.id ?? `${job.name}:unknown`,
+        attempt: job.attemptsMade + 1,
+        maxAttempts: definition.attempts ?? 1,
+        logger: state.logger,
+      };
+      await definition.handle(job.data as never, context);
+    },
+    {
+      connection: state.connection,
+      concurrency,
+      ...(state.prefix ? { prefix: state.prefix } : {}),
+    },
+  );
+
+  worker.on("failed", (job, error) => {
+    const attempts = job ? `${job.attemptsMade}/${job.opts.attempts ?? 1}` : "?";
+    state.logger.error(
+      `job "${job?.name ?? queueName}" failed (attempt ${attempts}):`,
+      error,
+    );
+  });
+  worker.on("error", (error) =>
+    state.logger.error(`worker "${queueName}" error:`, error),
+  );
+  return worker;
+}
+
+/** Definitions bucketed by the queue that carries them. */
+function groupByQueue(
+  definitions: readonly AnyJobDefinition[],
+): Map<string, AnyJobDefinition[]> {
+  const byQueue = new Map<string, AnyJobDefinition[]>();
+  for (const definition of definitions) {
+    const name = definition.queue ?? DEFAULT_QUEUE;
+    const group = byQueue.get(name);
+    if (group) group.push(definition);
+    else byQueue.set(name, [definition]);
+  }
+  return byQueue;
+}
+
+export function createBullMqJobDriver(options: BullMqJobDriverOptions): JobDriver {
+  const state: DriverState = {
+    connection: parseRedisUrl(options.redisUrl),
+    logger: options.logger,
+    prefix: options.prefix,
+    queues: new Map(),
+    workers: [],
+  };
+
+  return {
+    kind: "bullmq",
+
+    async enqueue(definition, payload, enqueueOptions): Promise<EnqueueResult> {
+      const queue = queueFor(state, definition.queue ?? DEFAULT_QUEUE);
+      await queue.add(definition.name, payload, jobOptionsFor(definition, enqueueOptions));
+      return { enqueued: true };
+    },
+
+    async start(definitions): Promise<void> {
+      for (const [queueName, group] of groupByQueue(definitions)) {
+        state.workers.push(startWorker(state, queueName, group));
+        const queue = queueFor(state, queueName);
+        await checkEvictionPolicy(state, queue);
+        await reconcileSchedules(state, queue, group);
+      }
+    },
+
+    async stop(): Promise<void> {
+      // Workers first: `close()` waits for in-flight jobs, and closing the
+      // queues underneath a running handler would fail its final update.
+      await Promise.all(state.workers.map((worker) => worker.close()));
+      state.workers.length = 0;
+      await Promise.all([...state.queues.values()].map((queue) => queue.close()));
+      state.queues.clear();
+    },
+  };
+}
+
+/**
+ * Internals exposed for tests only — the concurrency rule is silent when
+ * wrong, so it is pinned directly rather than inferred from a live Worker.
+ */
+export const __testables = { resolveConcurrency, DEFAULT_CONCURRENCY };

package/src/drivers/inline.ts

@@ -0,0 +1,130 @@
+/**
+ * The INLINE driver: run the handler in the calling process, immediately.
+ *
+ * For unit and integration tests (which boot PGlite and must not need a Redis
+ * container) and for local development without `docker compose up`. It is a
+ * real driver, not a stub — `attempts` are honoured so retry behaviour stays
+ * testable — but three things it deliberately does NOT do:
+ *
+ *   - **No delay.** `delayMs` is ignored and logged. A test asserting a
+ *     three-day dunning gap should assert on the enqueue, not the clock.
+ *   - **No schedules.** A cron job is registered but never fires; drive it
+ *     directly in a test by calling the handler.
+ *   - **No backoff waits.** Retries happen back-to-back so suites stay fast.
+ *
+ * Which is why it must never reach production: work would run inside the
+ * request that scheduled it, and a crash between the two would lose it. The
+ * host's driver factory is responsible for refusing it there.
+ */
+
+import type {
+  AnyJobDefinition,
+  EnqueueOptions,
+  EnqueueResult,
+  JobContext,
+  JobDriver,
+  JobLogger,
+} from "../core/types";
+
+export interface InlineJobDriverOptions {
+  logger?: JobLogger;
+  /**
+   * Await the handler inside `enqueue` (the default) instead of letting it run
+   * detached. Awaiting is what a test wants: the assertion after `enqueue`
+   * sees the side effect.
+   */
+  await?: boolean;
+}
+
+/** A record of what ran, for assertions. */
+export interface InlineJobRun {
+  name: string;
+  payload: unknown;
+  attempts: number;
+  error?: unknown;
+}
+
+export interface InlineJobDriver extends JobDriver {
+  /** Every run since the driver was created, in order. */
+  readonly runs: readonly InlineJobRun[];
+  /** Forget the recorded runs. */
+  clearRuns(): void;
+}
+
+export function createInlineJobDriver(
+  options: InlineJobDriverOptions = {},
+): InlineJobDriver {
+  const logger = options.logger ?? console;
+  const awaitHandlers = options.await ?? true;
+  const runs: InlineJobRun[] = [];
+
+  async function run(
+    definition: AnyJobDefinition,
+    payload: unknown,
+  ): Promise<void> {
+    const maxAttempts = Math.max(1, definition.attempts ?? 1);
+    const record: InlineJobRun = { name: definition.name, payload, attempts: 0 };
+    runs.push(record);
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      record.attempts = attempt;
+      const context: JobContext = {
+        runId: `inline:${definition.name}:${runs.length}:${attempt}`,
+        attempt,
+        maxAttempts,
+        logger,
+      };
+      try {
+        await definition.handle(payload as never, context);
+        record.error = undefined;
+        return;
+      } catch (error) {
+        record.error = error;
+        if (attempt === maxAttempts) {
+          logger.error(
+            `"${definition.name}" failed after ${attempt} attempt(s):`,
+            error,
+          );
+          return;
+        }
+      }
+    }
+  }
+
+  return {
+    kind: "inline",
+    runs,
+    clearRuns() {
+      runs.length = 0;
+    },
+    async enqueue(
+      definition: AnyJobDefinition,
+      payload: unknown,
+      enqueueOptions: EnqueueOptions,
+    ): Promise<EnqueueResult> {
+      if (enqueueOptions.delayMs) {
+        logger.warn(
+          `inline driver ignored a ${enqueueOptions.delayMs}ms delay on "${definition.name}".`,
+        );
+      }
+      const execution = run(definition, payload);
+      if (awaitHandlers) await execution;
+      else void execution;
+      return { enqueued: true };
+    },
+    start(definitions: readonly AnyJobDefinition[]): Promise<void> {
+      const scheduled = definitions.filter((job) => job.schedule);
+      if (scheduled.length > 0) {
+        logger.warn(
+          `inline driver does not run schedules; ${scheduled.length} cron job(s) will never fire: ${scheduled
+            .map((job) => job.name)
+            .join(", ")}`,
+        );
+      }
+      return Promise.resolve();
+    },
+    stop(): Promise<void> {
+      return Promise.resolve();
+    },
+  };
+}

package/src/drivers/redis-url.ts

@@ -0,0 +1,77 @@
+/**
+ * `REDIS_URL` → the connection options BullMQ hands to ioredis.
+ *
+ * Parsed here rather than passed through as a string so the two settings a
+ * BullMQ deployment cannot get wrong are applied in ONE place:
+ *
+ *   - `maxRetriesPerRequest: null` — required by BullMQ's blocking commands.
+ *     ioredis' default (20) makes a worker throw on a brief Redis blip
+ *     instead of waiting it out.
+ *   - `enableReadyCheck: false` — the ready check trips on providers that
+ *     restrict `INFO`, and BullMQ does not need it.
+ */
+
+/** The subset of ioredis options this library sets. */
+export interface RedisConnectionOptions {
+  host: string;
+  port: number;
+  username?: string;
+  password?: string;
+  db?: number;
+  tls?: Record<string, never>;
+  maxRetriesPerRequest: null;
+  enableReadyCheck: false;
+}
+
+/** Raised for a `REDIS_URL` that cannot be used. */
+export class InvalidRedisUrlError extends Error {
+  constructor(url: string, detail: string) {
+    // The URL can carry a password — report the failure, never the value.
+    super(`REDIS_URL is not usable (${detail}). Expected redis:// or rediss://.`);
+    this.name = "InvalidRedisUrlError";
+    void url;
+  }
+}
+
+function toUrl(url: string): URL {
+  try {
+    return new URL(url);
+  } catch {
+    throw new InvalidRedisUrlError(url, "it is not a valid URL");
+  }
+}
+
+/** An empty URL component means "not given", not "the empty string". */
+function optional(value: string): string | undefined {
+  return value === "" ? undefined : decodeURIComponent(value);
+}
+
+/** `/0`, `/1`, … selects the database; an empty path means the default. */
+function parseDatabase(url: string, pathname: string): number | undefined {
+  const path = pathname.replace(/^\//, "");
+  if (path === "") return undefined;
+  const db = Number(path);
+  if (!Number.isInteger(db)) {
+    throw new InvalidRedisUrlError(url, "the path is not a database number");
+  }
+  return db;
+}
+
+export function parseRedisUrl(url: string): RedisConnectionOptions {
+  const parsed = toUrl(url);
+  const secure = parsed.protocol === "rediss:";
+  if (!secure && parsed.protocol !== "redis:") {
+    throw new InvalidRedisUrlError(url, `unsupported protocol "${parsed.protocol}"`);
+  }
+
+  return {
+    host: parsed.hostname || "127.0.0.1",
+    port: parsed.port === "" ? 6379 : Number(parsed.port),
+    username: optional(parsed.username),
+    password: optional(parsed.password),
+    db: parseDatabase(url, parsed.pathname),
+    tls: secure ? {} : undefined,
+    maxRetriesPerRequest: null,
+    enableReadyCheck: false,
+  };
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * `@12-apps/jobs` — typed background jobs with retries, backoff and cron, behind
+ * a swappable driver.
+ *
+ *     // where the domain lives
+ *     export const dispatchNotification = defineJob<{ notificationId: string }>({
+ *       name: "notifications.dispatch",
+ *       attempts: 5,
+ *       backoff: { type: "exponential", delayMs: 5_000 },
+ *       handle: async ({ notificationId }) => dispatchDeliveries(notificationId),
+ *     });
+ *
+ *     // at an emit site
+ *     await dispatchNotification.enqueue({ notificationId }, { dedupeKey: notificationId });
+ *
+ *     // at process start
+ *     configureJobs({ driver: createBullMqJobDriver({ redisUrl, logger }), logger });
+ *     await startJobWorkers();   // consumers only
+ *
+ * The two rules that keep this safe are documented on `JobDefinition`:
+ * payloads carry identifiers rather than state, and every handler is
+ * idempotent because delivery is at-least-once.
+ *
+ * The BullMQ driver is deliberately NOT re-exported here — it is imported
+ * from `@12-apps/jobs/bullmq`, so that pulling in `defineJob` at an emit site
+ * never drags Redis into a bundle that only ever enqueues.
+ */
+
+export { defineJob, findJob, listJobs, clearJobs, DuplicateJobError } from "./core/registry";
+export type { RegisteredJob } from "./core/registry";
+
+export {
+  configureJobs,
+  enqueueJob,
+  getJobDriver,
+  getJobLogger,
+  resetJobRuntime,
+  startJobWorkers,
+  stopJobs,
+} from "./core/runtime";
+
+export type {
+  AnyJobDefinition,
+  EnqueueOptions,
+  EnqueueResult,
+  EnqueueSkipReason,
+  JobBackoff,
+  JobContext,
+  JobDefinition,
+  JobDriver,
+  JobHandler,
+  JobLogger,
+  JobSchedule,
+} from "./core/types";
+
+export { createInlineJobDriver } from "./drivers/inline";
+export type { InlineJobDriver, InlineJobRun } from "./drivers/inline";
+
+export { parseRedisUrl, InvalidRedisUrlError } from "./drivers/redis-url";
+export type { RedisConnectionOptions } from "./drivers/redis-url";