@12-apps/jobs 1.20.0 → 3.0.0

package/ADOPTING.md

@@ -3,14 +3,17 @@
 This package is a **plug-and-play background-job runtime**: one library,
 reusable across repositories, exposing standardized surfaces. A host repo only
 *points* at these surfaces — when the library updates, every host updates with
-**no app changes**. The contract below is the same one `@12-apps/report-builder`
-and `@12-apps/payments-backend` established.
+**no app changes**.
+
+It contains no job of its own. Not one name, not one schedule, not one retry
+policy, not one queue tuned to a product's SLA — those are the host's, and they
+arrive as config. What the package owns is the RUNNING of them.
 
 ## The standardized plugin surfaces
 
 | Surface | Export | What the host does |
 |---|---|---|
-| **Core library** | `@12-apps/jobs` | `defineJob` next to the domain each job belongs to (the import IS the registration), `enqueue` at emit sites, `SWEEP_QUEUE` + `createSweepLease` for scheduled sweeps. Never drags Redis into a bundle. |
+| **Core library** | `@12-apps/jobs` | `defineJob` next to the domain each job belongs to (the import IS the registration), `enqueue` at emit sites, `DEFAULT_QUEUE` / `SWEEP_QUEUE` + `createSweepLease` for scheduled sweeps. Never drags Redis into a bundle. |
 | **Server** | `@12-apps/jobs/server` | Call `createApiJobs(config)` once at process start: driver resolution (with the inline zero-config default and the production refusals), job registration, the `JOBS_WORKER` producer/consumer switch, graceful drain on `SIGTERM`/`SIGINT`, the bound sweep lease, and the health endpoint as framework-neutral route descriptors. |
 | **Hono** | `@12-apps/jobs/hono` | `app.route(prefix, jobsRouter(jobsApi))`. A one-call mount for hosts on Hono; `hono` is an OPTIONAL peer, so importing the root or `/server` never resolves it. |
 | **Drivers** | `@12-apps/jobs/bullmq`, `@12-apps/jobs/inline` | Nothing, usually — `createApiJobs` resolves them. Import directly only to hand a pre-built instance in (`driver: createInlineJobDriver({ await: true })` in a test). |
@@ -34,7 +37,7 @@ it reads the same health endpoint every other probe reads.
 1. **The host owns the handlers; this package owns the running of them.**
    Job definitions, their retry policies and their schedules are host domain —
    they stay in the host, declared with `defineJob` next to the code they
-   belong to. What moved here is everything operational: which driver runs,
+   belong to. What lives here is everything operational: which driver runs,
    when workers start, how they drain, who may run a sweep.
 2. **Payloads carry identifiers, never state**, and every handler is
    idempotent — delivery is at-least-once. Both rules are documented on
@@ -51,22 +54,39 @@ it reads the same health endpoint every other probe reads.
    host with no `REDIS_URL` must boot green: `createApiJobs` resolves the
    inline driver outside production (handlers in-process, schedules off and
    logged). Do not "fix" that by demanding Redis in dev.
-5. **Fail closed, never fail loud.** In production every misconfiguration
-   (no `REDIS_URL`, `inline` requested, a bad URL) resolves to NO driver plus
-   a loud error log and a 503 from `/health`. Enqueues then report
-   `no-driver`; the durable rows still get written. A queue must never take
-   the host app down.
-6. **Auth for the health endpoint is the host's.** Mount `jobsRouter` under
-   whatever guard the deployment's internal probes live behind (future-pay
-   answers `/api/internal/*` only machine-to-machine). The package holds zero
-   authorization logic.
-7. **Sweeps: one queue, one flight, one lease.** Declare scheduled sweeps
+5. **Fail closed, never fail loud — about the QUEUE.** In production every
+   misconfiguration (no `REDIS_URL`, `inline` requested, a bad URL) resolves to
+   NO driver plus a loud error log and a 503 from `/health`. Enqueues then
+   report `no-driver`; the durable rows still get written. A queue must never
+   take the host app down.
+6. **But the WIRING fails loud, on purpose.** A `jobs` that names nothing, a
+   definition that cannot run, an enqueue of a job the registry does not hold:
+   each of those is refused with a throw or a refused result. They are not
+   queue outages, they are programming errors, and every one of them is
+   otherwise completely silent. See "What it refuses" below.
+7. **Auth for the health endpoint is the host's.** Mount `jobsRouter` under
+   whatever guard the deployment's internal probes live behind. The package
+   holds zero authorization logic.
+8. **Sweeps: one queue, one flight, one lease.** Declare scheduled sweeps
    with `queue: SWEEP_QUEUE, concurrency: 1` and take
    `withSweepLease(name, ttlMs, work)` inside the handler. The TTL must
    comfortably exceed the sweep's own duration — a lease expiring mid-sweep
    is the one way two workers can still overlap. Only a lost race is silent;
    a real store fault throws, so a stopped sweep has a failed job to notice.
 
+## What it refuses
+
+Each of these produces, if let through, a deployment that starts, probes green
+and quietly does nothing.
+
+| Refused | Where | Why it is not "a choice" |
+|---|---|---|
+| `defineJob({ name: "" })`, `queue: ""`, `attempts: 0`, `concurrency: 0`, `backoff.delayMs: 0`, `schedule.pattern: "@daily"` / `""` / `"0 *"` | `defineJob`, at declaration | `InvalidJobDefinitionError`. `queue: ""` is not nullish, so it never falls back to `DEFAULT_QUEUE` — it makes a queue no worker is started for. A non-5/6-field cron installs a scheduler that never fires. |
+| `createApiJobs({ jobs: [] })` | the factory, at assembly | `JobsConfigError`. Declaring nothing is not how jobs are turned off — `JOBS_DRIVER=off` is, and it reports `status: "disabled"` rather than a green `ok` over an empty runtime. |
+| a `jobs` thunk that registers nothing | `start()` | `NoJobsRegisteredError`. This is the common one: a dropped import in the host's jobs barrel. Both roles are checked — a producer that registered nothing enqueues nothing. |
+| `startJobWorkers()` with an empty registry | the root entry point | `NoJobsRegisteredError`, the same guard. A host that wires the runtime by hand is not a host with fewer checks. |
+| `enqueue` of a definition the registry does not hold under that name | `enqueueJob`, and the BullMQ driver's own `enqueue` | `{ enqueued: false, reason: "unregistered" }`. It is the SAME `resolveRegisteredJob` call the worker's dispatch makes, so a write cannot be accepted that the run side then refuses. Identity, not just the name: an impostor object would ship a payload the real handler never agreed to. |
+
 ## Configuration
 
 `createApiJobs(config)` — every field optional except `jobs`; unset fields
@@ -74,16 +94,72 @@ default from the environment, which is what makes the mount one line:
 
 | Config | Env default | Meaning |
 |---|---|---|
-| `jobs` | — | An import thunk (`() => import("./jobs")`) or an array of `defineJob` returns. Registration. |
+| `jobs` | — | **Required, and may not be empty.** An import thunk (`() => import("./jobs")`) or a non-empty array of `defineJob` returns. Registration. |
 | `driver` | `JOBS_DRIVER` | `bullmq` \| `inline` \| `off`, or a `JobDriver` instance. Unset → `bullmq` when a Redis URL exists, else `off` in production, `inline` elsewhere. |
 | `redisUrl` | `REDIS_URL` | Setting it turns the queue on. |
 | `worker` | `JOBS_WORKER` (`1`/`true`) | This process consumes and runs schedules, not just enqueues. |
 | `production` | `NODE_ENV === "production"` | Refuses `inline`, makes "no queue" loud. |
 | `queuePrefix` | `JOBS_QUEUE_PREFIX` | Share one Redis across environments. |
-| `logger` | console | Structurally a winston logger or `console`. |
+| `logger` | console | Structurally a winston-style logger or `console`. |
+| `events` | — | `JobEvents` — dead-letters, completions and removed schedules, for the host to wire to its own notifier / audit / realtime. See below. |
+| `retention` | package default | How long finished jobs are kept: a day of successes, a week of failures. Override for a longer support window. All four numbers must be positive and finite — see the warning below. |
+| `defaultConcurrency` | `5` | Per-queue concurrency when no job on the queue states one. A stated `concurrency: 1` still wins. |
 | `db` | — | `() => SweepLeaseDb` — enables `withSweepLease`. Without it the lease throws on first use (loud, never a silent skip). |
 | `installShutdownHooks` | `true` | `SIGTERM`/`SIGINT` drain in-flight jobs (workers only). Off in tests. |
 
+### ⚠️ A non-positive `retention` does not shrink retention
+
+It stops bounding the backend altogether. BullMQ derives its count trim from
+the number it is handed, so a NEGATIVE `count` removes one job per completion
+instead of holding the set at a ceiling — which is the unbounded completed-set
+the default exists to prevent, arrived at through a config knob. Nothing
+throws at the queue, no probe reddens, and the symptom is a Redis that fills up
+weeks later and starts refusing writes.
+
+`NaN` is the likelier way in:
+
+```ts
+// ✗ With JOBS_KEEP_H unset this is NaN, and every comparison in the trim
+//   silently answers false.
+retention: { completed: { ageSeconds: Number(process.env.JOBS_KEEP_H), count: 1_000 }, … }
+```
+
+So all four numbers are validated — `createApiJobs` refuses at ASSEMBLY with
+`InvalidJobRetentionError`, and `createBullMqJobDriver` refuses again for a
+host that builds the driver off `@12-apps/jobs/bullmq` itself. Omitting
+`retention` is always fine and means "use the package default".
+
+### `events` — what this package will not do for you
+
+It notifies nobody, audits nothing and publishes no realtime event. It owns
+the MOMENT and exports it; the consequence is the host's, wired with the
+host's own packages:
+
+```ts
+createApiJobs({
+  jobs: () => import("./lib/jobs"),
+  events: {
+    onJobFailed: ({ name, error, terminal }) => {
+      // `terminal` is the whole point: no attempt is left. A non-terminal
+      // failure is ordinary retry noise and must not page anyone.
+      if (terminal) void notifyOperators(name, error);
+    },
+    onJobCompleted: ({ name, runId }) => void publishRealtime(name, runId),
+    onScheduleRemoved: ({ name, queue }) =>
+      void audit("schedule.removed", { name, queue }),
+  },
+});
+```
+
+An observer that throws or rejects is logged and swallowed — somebody else's
+code must never be able to fail the job it is watching, nor the reconcile that
+was cleaning up a stale schedule.
+
+`onScheduleRemoved` fires only for REMOVAL, not installation. Installation is
+an idempotent upsert that runs on every boot of every worker, so auditing it
+would write one row per schedule per deploy; removal is a deploy permanently
+cancelling a recurring job, which is the half worth a record.
+
 ## The endpoints
 
 Mounted under whatever prefix the host chooses (recommended: wherever its
@@ -102,9 +178,8 @@ packages/jobs/prisma/jobs.prisma          # the model partial
 packages/jobs/prisma/migrations/          # its migration
 ```
 
-A host adopts them by COPY (the entity-lifecycle / shift precedent — in this
-repo, `packages/shared-helpers/scripts/sync-jobs-schema.mjs` plus the
-structural migration sync in `sync-prisma-plugins.mjs`):
+A host adopts them by COPY, from a sync script in whichever of its packages
+owns the schema folder:
 
 - **Migrations are copied, never symlinked.** Prisma enumerates the
   migrations folder with `lstat`, so a symlinked migration reports
@@ -118,17 +193,21 @@ structural migration sync in `sync-prisma-plugins.mjs`):
   is the CI gate against drift.
 - **The migration's timestamp (`20260727190000`) may sort before migrations
   your host has already applied.** That is deliberate: the directory is a
-  byte-identical copy of the one future-pay already has in production, so a
-  rename would make that host's sync try to create a second table. For every
-  other host the out-of-order arrival is safe — `prisma migrate dev` may
-  grumble, but the SQL is `CREATE TABLE IF NOT EXISTS`, so even a double
-  apply is inert.
+  byte-identical copy of one already applied in production, so a rename would
+  make that host's sync try to create a second table. For every other host the
+  out-of-order arrival is safe — `prisma migrate dev` may grumble, but the SQL
+  is `CREATE TABLE IF NOT EXISTS`, so even a double apply is inert.
+- **Those bytes are frozen, comment and all.** Prisma checksums an applied
+  migration; changing so much as a comment makes `migrate deploy` refuse the
+  next deploy of every host that already ran it. That is why the packed-artifact
+  sweep carries exactly one exemption, scoped to one literal on that one path
+  (`src/__tests__/packed-artifact.test.ts`), rather than editing the file.
 
 ## Porting to another repo
 
 1. Add the package and sync the partial + migration into your schema-owning
-   package (adjust the two paths in your copy of the sync script); declare
-   `@12-apps/jobs` as that package's dependency; `prisma generate`.
+   package; declare `@12-apps/jobs` as that package's dependency;
+   `prisma generate`.
 2. Declare your jobs with `defineJob` and collect the modules behind one
    import (`lib/jobs/index.ts` importing each for its side effect).
 3. Mount: `createApiJobs({ jobs: () => import("./lib/jobs"), db: () => yourClient })`,
@@ -137,3 +216,97 @@ structural migration sync in `sync-prisma-plugins.mjs`):
    needs `maxmemory-policy noeviction` (the driver checks and complains) and
    AOF persistence. More than one worker is safe for sweeps that take the
    lease.
+
+---
+
+# Migrating to 3.0.0 — the app-agnostic release
+
+3.0.0 does two things: it removes the origin application from a package
+published as generic, and it closes three fail-open paths that were invisible
+by construction.
+
+## What changed in behaviour
+
+Nothing was **removed** from the API — every 2.0.0 export still exists with the
+same signature. What changed is that four things that used to be accepted are
+now refused, and one union grew a member.
+
+| Was accepted | Now | Where |
+|---|---|---|
+| a definition with a blank `name`, an empty `queue`, `attempts: 0`, `concurrency: 0`, `backoff.delayMs: 0`, or a cron pattern that is not 5/6 fields | throws `InvalidJobDefinitionError` | `defineJob` |
+| `createApiJobs({ jobs: [] })` | throws `JobsConfigError` at the factory | `@12-apps/jobs/server` |
+| a `jobs` thunk that registers nothing | `start()` rejects with `NoJobsRegisteredError`; `/health` stays 503 | `@12-apps/jobs/server` |
+| `startJobWorkers()` with an empty registry | rejects with `NoJobsRegisteredError` | `@12-apps/jobs` (root) |
+| `enqueue` of an unregistered definition — written to the backend, then dead-lettered by the consumer | `{ enqueued: false, reason: "unregistered" }`, nothing written | `enqueueJob`, `RegisteredJob.enqueue`, and the BullMQ driver |
+
+**`EnqueueSkipReason` gained `"unregistered"`.** An exhaustive `switch` over it
+will not compile until the new arm is handled. That is the intended failure:
+the reason exists precisely because the outcome used to be indistinguishable
+from success.
+
+## What is new
+
+| Added | What for |
+|---|---|
+| `events?: JobEvents` on `createApiJobs`, and on both driver factories | Dead-letters (`onJobFailed` with `terminal`), completions (`onJobCompleted`) and removed schedules (`onScheduleRemoved`). The package still notifies/audits/publishes nothing itself. |
+| `retention?: JobRetention`, `defaultConcurrency?: number` | The two operational numbers that were hardcoded. The defaults are unchanged (a day / a week; concurrency 5), so omitting them is a no-op. `retention` is validated at assembly and again in the driver — a non-positive window stops bounding the backend rather than shrinking it. |
+| `assertValidRetention`, `InvalidJobRetentionError` | The retention check, exported so a host that assembles its own window can run it. Lives in `core`, so importing it never pulls `bullmq` into a bundle that only enqueues. |
+| `DEFAULT_QUEUE` | The queue name a definition falls back to, exported instead of duplicated as a literal in every host. |
+| `resolveRegisteredJob`, `InvalidJobDefinitionError`, `NoJobsRegisteredError`, `JobsConfigError` | The gate and the three refusals, so a host can catch them by type. |
+
+## Host vocabulary that left the tarball
+
+`files` publishes `src` (minus tests), `prisma` and every top-level `*.md`, so
+all of this was shipping to every adopter:
+
+- the origin application was named 19 times, across four published source files
+  and this one;
+- **its job identifiers were the examples** — in the README, the root module
+  header, the payload rule on `JobDefinition`, the inline driver's docs, the
+  runtime's own comments and the `SweepLease` schema annotation. A jobs
+  package's examples ARE job identifiers, which is exactly what made this the
+  easiest leak to read straight past: they look like documentation and they are
+  another product's schedule names.
+- its billing vocabulary and its own timezone sat in the payload rule and in
+  the `JobSchedule` docs, so an adopter's night job inherited a zone chosen for
+  somebody else.
+
+`src/__tests__/packed-artifact.test.ts` now asks `npm pack --dry-run --json`
+what would be uploaded, reads every entry off disk and greps it, with a plant
+test so a green run means something.
+
+### The two strings that have NOT left, and why
+
+Both are in files whose BYTES are pinned to something outside this package, so
+neither is fixable by editing the string. The sweep exempts exactly those two
+literals on exactly those two paths — never the file, never the word
+elsewhere — and the suite proves the scoping.
+
+- `prisma/migrations/.../migration.sql` keeps a ticket reference in its header
+  comment. Prisma checksums an applied migration; changing a comment makes
+  `migrate deploy` refuse the next deploy of every host that already ran it.
+  This one is permanent.
+- `prisma/jobs.prisma` still uses a host's job name as the example value of the
+  `name` column, and still names a pre-2.0.0 path for the sync script. That
+  file is byte-compared against a **committed copy in the schema-host package**
+  (`sync-jobs-schema.mjs --check`, wired into that package's `build` and
+  `prisma:generate`), so a one-byte edit here turns the workspace's
+  `check-types` red until the copy is re-synced — a write in another package's
+  directory, which the release tooling reads as a release of that package. It
+  is a two-line comment fix that must ride the commit which can also carry
+  `prisma:sync-jobs`, and it is the one item this release deliberately left.
+
+## Upgrading a host that is on 1.20.0
+
+Two majors, and 2.0.0's break is not in this package's own API — it was cut by
+the commit that moved the Prisma host out of `@12-apps/shared-helpers` into
+`@12-apps/prisma`, so `@12-apps/shared-helpers/prisma` is gone and the
+reference sync script moved with it. `packages/jobs`'s own diff for that
+release was a single path in this file.
+
+The concrete, anchored upgrade for this repo's own consumer — the pins, the
+partial re-sync and the generated copy it invalidates, the health endpoint that
+was never mounted, and the cross-package seams now available — is in
+`packages/jobs/docs/host-upgrade.md`. It is deliberately NOT published: it
+names one application throughout, which is the whole thing this release was
+about.

package/README.md

@@ -4,36 +4,38 @@ Typed background jobs — retries, exponential backoff and cron — behind a
 swappable driver. BullMQ/Redis in production, inline execution in tests and
 zero-config development.
 
-Framework-free: no Prisma import, no Next, no host-app types. The logger is a
-port, the lease's database is a structural seam, and the one web framework in
-sight (`hono`) is an optional peer behind its own subpath.
+Framework-free and domain-free: no ORM import, no host-app types, no job names
+of its own. The logger is a port, the lease's database is a structural seam,
+observation is a port, and the one web framework in sight (`hono`) is an
+optional peer behind its own subpath.
 
 ```ts
 // where the domain lives — the import IS the registration
-export const dispatchNotification = defineJob<{ notificationId: string }>({
-  name: "notifications.dispatch",
+export const renderReport = defineJob<{ reportId: string }>({
+  name: "reports.render",
   attempts: 5,
   backoff: { type: "exponential", delayMs: 5_000 },
-  handle: async ({ notificationId }) => dispatchDeliveries(notificationId),
+  handle: async ({ reportId }) => renderAndStore(reportId),
 });
 
 // a job that only ever runs on a schedule needs no binding at all
 defineJob({
-  name: "notifications.drain",
+  name: "reports.purge",
   schedule: { pattern: "*/5 * * * *", timezone: "UTC" },
-  handle: async () => drainPending(),
+  handle: async () => purgeExpired(),
 });
 
 // at an emit site
-await dispatchNotification.enqueue({ notificationId }, { dedupeKey: notificationId });
+await renderReport.enqueue({ reportId }, { dedupeKey: reportId });
 
 // at process start — ONE call wires driver, workers, drain, lease and health
 import { createApiJobs } from "@12-apps/jobs/server";
 import { jobsRouter } from "@12-apps/jobs/hono";
 
 const jobsApi = createApiJobs({
-  jobs: () => import("./lib/jobs"),   // the defineJob modules
+  jobs: () => import("./lib/jobs"),   // the defineJob modules — required
   db: () => getPrismaClient(),        // the sweep_leases table (optional)
+  events: { onJobFailed: pageOnDeadLetter },   // yours, if you want one
 });
 await jobsApi.start();
 app.route("/api/internal/jobs", jobsRouter(jobsApi));
@@ -47,32 +49,63 @@ never a crash, never a silent fake. `JOBS_WORKER=1` is what turns a process
 from producer (enqueue only) into consumer (workers + schedules); the worker
 is the same image, not a second build.
 
-The full adoption contract — config seam, env variables, the sweep lease, the
-Prisma partial and why there is no `createWebJobs` — is in
+The full adoption contract — config seam, env variables, the events port, the
+sweep lease, the Prisma partial and why there is no `createWebJobs` — is in
 [ADOPTING.md](./ADOPTING.md).
 
 ## 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.
+**Payloads carry identifiers, never state.** `{ reportId }`, not the rendered
+report. 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.
 
+## What it refuses
+
+Three wiring mistakes are refused rather than absorbed, because each of them
+is otherwise **silent** — the process starts, the probe is green, and work
+simply stops happening:
+
+- **A job that cannot run.** `defineJob` throws on a blank name, an empty
+  `queue` (which never falls back to the default — it creates a queue nobody
+  consumes), a non-positive `attempts`/`concurrency`, a backoff with no delay,
+  and a cron pattern that is not 5 or 6 fields. `"@daily"` and `""` both
+  install a scheduler that never fires.
+- **A deployment with no jobs.** `createApiJobs({ jobs: [] })` throws at the
+  factory; a `jobs` thunk that registers nothing throws from `start()`; and
+  `startJobWorkers()` throws on an empty registry, so the hand-wired root path
+  is guarded identically. Declaring nothing is not a way to turn jobs off —
+  `JOBS_DRIVER=off` is.
+- **An enqueue no worker could ever claim.** `enqueue` returns
+  `{ enqueued: false, reason: "unregistered" }` for a definition the registry
+  does not hold under that name (identity, not just the name). The alternative
+  is a write the backend accepts, no handler claims, and the consumer
+  dead-letters — after the caller was told `enqueued: true`.
+- **A `retention` window that bounds nothing.** Every number must be positive
+  and finite. A negative `count` does not keep fewer jobs, it trims one per
+  completion instead of holding a ceiling; `NaN` (an unset env var read through
+  `Number()`) disables the comparison entirely. Refused at the factory and
+  again in the driver.
+
 ## 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.
+- Bounded backend memory: completed jobs are kept a day, failed ones a week,
+  and a host with a different support window passes its own `retention` — whose
+  four numbers are validated, because a negative or `NaN` window stops bounding
+  the backend rather than shrinking it.
 - 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.
+  longer exists. That removal is reported to `events.onScheduleRemoved`,
+  because it is destructive and a deploy did it.
 - 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.
+  omissions are logged rather than silent. It is refused in production —
+  by name, by env var and by instance.
 
 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.
@@ -82,6 +115,30 @@ only in a process whose resolution actually picked it.
 Redis must run with `maxmemory-policy noeviction` — the driver checks and
 complains.
 
+## Telling somebody else what happened
+
+This package notifies nobody, audits nothing and publishes no events. What it
+owns is the MOMENT, and the moments are a port:
+
+```ts
+createApiJobs({
+  jobs: () => import("./lib/jobs"),
+  events: {
+    // The dead-letter. `terminal` is the whole point — a non-terminal failure
+    // is ordinary retry noise.
+    onJobFailed: ({ name, error, terminal }) => {
+      if (terminal) void notifyOperators(name, error);
+    },
+    onJobCompleted: ({ name, runId }) => void publishRealtime(name, runId),
+    // A deploy just cancelled a recurring job, permanently.
+    onScheduleRemoved: ({ name, queue }) => void audit("schedule.removed", { name, queue }),
+  },
+});
+```
+
+An observer that throws or rejects is logged and swallowed: somebody else's
+code must not be able to fail the job it is watching.
+
 ## The sweep lease
 
 Scheduled sweeps declare `queue: SWEEP_QUEUE, concurrency: 1`, which makes
@@ -91,13 +148,13 @@ named, time-bounded claim in the DATABASE — `createSweepLease` (or the bound
 
 ```ts
 defineJob({
-  name: "billing.tick",
+  name: "reports.purge",
   queue: SWEEP_QUEUE,
   concurrency: 1,
   schedule: { pattern: "0 * * * *" },
   handle: async () => {
-    const { ran } = await jobsApi.withSweepLease("billing.tick", 10 * 60_000, () =>
-      runBillingTick(),
+    const { ran } = await jobsApi.withSweepLease("reports.purge", 10 * 60_000, () =>
+      purgeExpired(),
     );
     if (!ran) return; // another worker holds this tick
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/jobs",
-  "version": "1.20.0",
+  "version": "3.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 and zero-config dev). The runtime half (./server) is one factory — createApiJobs: driver resolution, worker bootstrap, graceful drain, the single-writer sweep lease and a health endpoint — with a Hono adapter (./hono) and the package-owned SweepLease Prisma partial + migrations. Knows nothing about the host app's domain, ORM or transport.",
   "exports": {
@@ -59,6 +59,7 @@
     "*.js",
     "*.mjs",
     "*.md",
+    "!docs/**",
     "!eslint.config.js",
     "!**/__tests__/**",
     "!**/tests/**",

package/src/core/events.ts

@@ -0,0 +1,34 @@
+import type { JobEvents, JobLogger } from "./types";
+
+/**
+ * The observer plumbing, in ONE place because both drivers need it and the
+ * rule is easy to get subtly wrong twice: a `JobEvents` hook is somebody
+ * else's code, and it must never be able to fail the job it is watching, nor
+ * the reconcile that was cleaning up a stale schedule.
+ *
+ * Both failure modes are covered, and they are not the same one: a hook can
+ * THROW synchronously, and an async hook can REJECT later. Catching only the
+ * first leaves an unhandled rejection that some Node configurations turn into
+ * a process exit — a notifier outage taking the worker down with it, which is
+ * exactly backwards.
+ *
+ * Fire-and-forget by design: the job's own latency must not include whatever
+ * a host's notifier decides to do.
+ */
+export type EmitJobEvent = (emit: (events: JobEvents) => void | Promise<void>) => void;
+
+export function createEventEmitter(
+  events: JobEvents | undefined,
+  logger: JobLogger,
+): EmitJobEvent {
+  if (!events) return () => undefined;
+  return (emit) => {
+    try {
+      void Promise.resolve(emit(events)).catch((error: unknown) =>
+        logger.error("a jobs event observer rejected:", error),
+      );
+    } catch (error) {
+      logger.error("a jobs event observer threw:", error);
+    }
+  };
+}

package/src/core/queues.ts

@@ -1,26 +1,36 @@
 /**
- * Well-known queue names.
+ * Well-known queue names — this package's own vocabulary, exported so a host
+ * composes them rather than re-typing string literals that have to match.
  *
- * The scheduled sweeps run SINGLE-FLIGHT: their own queue at concurrency 1,
- * so a tick that outlives its interval makes the next one WAIT rather than run
- * alongside it.
+ * `DEFAULT_QUEUE` is where a definition lands when it names no queue. One
+ * queue for everything is the right shape at most scales: one worker, one pair
+ * of connections, one dashboard.
  *
- * That is a correctness property, not tuning. Every sweep walks a work list
- * and decides "has this already been handled?" by reading a row it is about
- * to write; two ticks interleaved on the same row both read the old answer.
- * Durable markers in the host's tables make that safe rather than corrupting
- * — the worst case is duplicate work, and the ledger is protected by the
- * database — but single-flight is what keeps it from happening at all, and it
- * costs nothing: sweeps run hourly and daily, and none of them is
- * latency-sensitive.
+ * `SWEEP_QUEUE` is the other one, and it exists for a correctness property
+ * rather than for tuning. The scheduled sweeps run SINGLE-FLIGHT — their own
+ * queue at concurrency 1 — so a tick that outlives its interval makes the next
+ * one WAIT rather than run alongside it.
  *
- * Keeping them off the DEFAULT queue matters too, in the other direction: a
- * sweep grinding through a few hundred tenants must not occupy the workers
- * that handle a user-facing job.
+ * Every sweep walks a work list and decides "has this already been handled?"
+ * by reading a row it is about to write; two ticks interleaved on the same row
+ * both read the old answer. Durable markers in the host's tables make that
+ * safe rather than corrupting — the worst case is duplicate work, and the
+ * ledger is protected by the database — but single-flight is what keeps it
+ * from happening at all, and it costs nothing: sweeps are periodic and none of
+ * them is latency-sensitive.
+ *
+ * Keeping them off the default queue matters too, in the other direction: a
+ * sweep grinding through a long work list must not occupy the workers that
+ * handle a user-facing job.
  *
  * Declare a sweep with `queue: SWEEP_QUEUE, concurrency: 1` and take a
  * {@link ../lease/sweep-lease!createSweepLease | sweep lease} inside the
  * handler when more than one worker can run — the queue serializes ticks
  * within one worker, the lease serializes them across the deployment.
  */
+
+/** The queue a definition lands on when it names none. */
+export const DEFAULT_QUEUE = "default";
+
+/** The single-flight queue the scheduled sweeps share. */
 export const SWEEP_QUEUE = "sweeps";