@daloyjs/core 1.2.0 → 1.3.0

package/dist/jobs.js

@@ -0,0 +1,1102 @@
+/**
+ * Queue-agnostic background jobs for DaloyJS.
+ *
+ * Where {@link Scheduler} answers *“run this work in this process, on this
+ * clock”*, this module answers *“run this work somewhere,
+ * eventually”* — the three things a production job interface needs:
+ *
+ * - **A durable record.** {@link JobStore.put} persists a named JSON payload
+ *   so the work survives the HTTP request and the process that accepted it.
+ *   {@link MemoryJobStore} is correct for tests and single-process apps;
+ *   production supplies a shared adapter (Redis, Postgres, SQS) that
+ *   implements the same SPI. Core stays zero-dependency.
+ * - **At-least-once execution.** {@link createJobWorker} claims a lease,
+ *   runs an allowlisted handler, and completes or fails with bounded
+ *   retries (exponential backoff, full jitter) and a dead-letter status.
+ *   If the process dies after the side effect but before complete, the
+ *   lease expires and another worker may run it again — handlers must be
+ *   idempotent. {@link EnqueueOptions.idempotencyKey} collapses duplicate
+ *   producers (same key + same payload) the way HTTP `idempotency()`
+ *   collapses duplicate POSTs.
+ * - **A clean split from workflows.** This is not Temporal, Inngest, or
+ *   Vercel Workflow: there is no replay of TypeScript, no “world”,
+ *   and no `await sleep("7 days")` inside a function body. Delayed jobs and
+ *   retries are *new attempts of the same record*, not continuations.
+ *
+ * Pair `App.useJobs` to attach a queue (and optionally a worker that
+ * drains on graceful shutdown) and `App.cronEnqueue` when a cron tick
+ * should create a job instead of running the side effect in-process.
+ *
+ * @example
+ * ```ts
+ * import { createJobQueue, createJobWorker, MemoryJobStore } from "@daloyjs/core/jobs";
+ *
+ * const store = new MemoryJobStore();
+ * const queue = createJobQueue({ store });
+ * const worker = createJobWorker({
+ *   queue,
+ *   handlers: {
+ *     "email.welcome": async ({ job, signal }) => {
+ *       await sendEmail(job.payload, { signal });
+ *     },
+ *   },
+ * });
+ * await queue.enqueue({ name: "email.welcome", payload: { to: "a@b.c" } });
+ * await worker.runOnce();
+ * ```
+ *
+ * @module
+ * @since 1.3.0
+ */
+import { isForbiddenObjectKey, safeJsonParse } from "./security.js";
+const enc = new TextEncoder();
+/**
+ * Enqueue validation, unknown names at define-time, and bad options. An
+ * ordinary `Error` subclass (like `CronParseError`), not an `HttpError` —
+ * the jobs engine is a library, not a mounted route; map it to `400`/`422`
+ * in your own contract route if you expose enqueue over HTTP.
+ *
+ * @since 1.3.0
+ */
+export class JobConfigError extends Error {
+    /** Machine-readable failure reason; see {@link JobConfigErrorCode}. */
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "JobConfigError";
+        this.code = code;
+    }
+}
+/**
+ * Same idempotency key, different payload fingerprint. A key is permanently
+ * bound to the first payload it was enqueued with — mirroring the `422`
+ * key-reuse rule of the HTTP `idempotency()` middleware.
+ *
+ * @since 1.3.0
+ */
+export class JobIdempotencyConflictError extends Error {
+    /** Machine-readable failure reason. */
+    code = "idempotency_conflict";
+    /** The idempotency key that was reused. */
+    key;
+    /** The id of the job that already holds the key. */
+    existingJobId;
+    constructor(key, existingJobId) {
+        super(`Job idempotency key "${key}" was already used with a different payload ` +
+            `(existing job "${existingJobId}").`);
+        this.name = "JobIdempotencyConflictError";
+        this.key = key;
+        this.existingJobId = existingJobId;
+    }
+}
+/**
+ * Thrown by a handler (or the worker, for an unknown job name) to signal
+ * “do not retry” — the job is dead-lettered on the spot, however
+ * many attempts remain. Analogous to a webhook SSRF / permanent-4xx failure.
+ *
+ * @since 1.3.0
+ */
+export class JobFatalError extends Error {
+    /** Machine-readable failure reason. */
+    code = "fatal";
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "JobFatalError";
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+/**
+ * A claimed job exceeded its `timeoutMs`; the worker aborted the handler's
+ * signal and failed the job as retryable (unless the attempt budget is
+ * already exhausted).
+ *
+ * @since 1.3.0
+ */
+export class JobTimeoutError extends Error {
+    /** Machine-readable failure reason. */
+    code = "timeout";
+    /** The per-attempt timeout that elapsed, in ms. */
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Job exceeded its timeoutMs of ${timeoutMs}ms and was aborted.`);
+        this.name = "JobTimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+// ── internal helpers ────────────────────────────────────────────────
+// Anchored, bounded character-class allowlists — linear-time, ReDoS-free.
+const JOB_NAME_RE = /^[a-zA-Z][a-zA-Z0-9._:-]{0,127}$/;
+const QUEUE_NAME_RE = /^[a-zA-Z0-9_:-]{1,64}$/;
+// Printable ASCII only (no control chars / whitespace), 1–255 chars — the
+// same grammar as the HTTP Idempotency-Key header.
+const IDEMPOTENCY_KEY_RE = /^[\x21-\x7e]{1,255}$/;
+// Tenant ids share the tenancy() default grammar: lowercase DNS-label-like,
+// safe to embed in keys and log lines.
+const TENANT_RE = /^[a-z0-9](?:[a-z0-9_-]{0,61}[a-z0-9])?$/;
+function assertJobName(name) {
+    if (typeof name !== "string" || !JOB_NAME_RE.test(name)) {
+        throw new JobConfigError("invalid_name", `Invalid job name ${JSON.stringify(String(name))}: must match ^[a-zA-Z][a-zA-Z0-9._:-]{0,127}$.`);
+    }
+    return name;
+}
+function assertQueueName(queue) {
+    if (typeof queue !== "string" || !QUEUE_NAME_RE.test(queue)) {
+        throw new JobConfigError("invalid_name", `Invalid queue name ${JSON.stringify(String(queue))}: must match ^[a-zA-Z0-9_:-]{1,64}$.`);
+    }
+    return queue;
+}
+function assertIdempotencyKey(key) {
+    if (typeof key !== "string" || !IDEMPOTENCY_KEY_RE.test(key)) {
+        throw new JobConfigError("invalid_option", "Job idempotencyKey must be 1-255 printable ASCII characters (no whitespace or control characters).");
+    }
+    return key;
+}
+function assertTenant(tenant) {
+    if (typeof tenant !== "string" || !TENANT_RE.test(tenant)) {
+        throw new JobConfigError("invalid_option", `Invalid tenant ${JSON.stringify(String(tenant))}: must match the tenancy() id grammar ` +
+            `^[a-z0-9](?:[a-z0-9_-]{0,61}[a-z0-9])?$.`);
+    }
+    return tenant;
+}
+/**
+ * Serialize a payload (or completion result) to JSON under the same rules:
+ * plain JSON only, prototype-pollution keys rejected (never stripped —
+ * silent key dropping is how `__proto__` smuggles past a review), byte size
+ * capped. A `JSON.stringify` replacer throws on forbidden keys, so the
+ * check rides the one traversal the serialization already performs.
+ */
+function serializePayload(payload, maxBytes, what) {
+    if (payload === undefined ||
+        typeof payload === "function" ||
+        typeof payload === "symbol" ||
+        typeof payload === "bigint") {
+        throw new JobConfigError("invalid_payload", `Job ${what} must be a JSON-serializable value; got ${payload === undefined ? "undefined" : typeof payload}.`);
+    }
+    if (payload !== null && typeof payload === "object" && !Array.isArray(payload)) {
+        // Reject class instances at the top level (Date, Map, Uint8Array, …):
+        // they stringify by silently dropping or reshaping data. Nested values
+        // follow ordinary JSON.stringify semantics (Date -> ISO string, …).
+        const proto = Object.getPrototypeOf(payload);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new JobConfigError("invalid_payload", `Job ${what} must be a plain JSON object, array, or primitive; got a non-plain object.`);
+        }
+    }
+    let json;
+    try {
+        json = JSON.stringify(payload, (key, value) => {
+            if (key !== "" && isForbiddenObjectKey(key)) {
+                throw new JobConfigError("invalid_payload", `Job ${what} contains forbidden key "${key}" (prototype pollution).`);
+            }
+            return value;
+        });
+    }
+    catch (error) {
+        if (error instanceof JobConfigError)
+            throw error;
+        throw new JobConfigError("invalid_payload", `Job ${what} is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const bytes = enc.encode(json);
+    if (bytes.byteLength > maxBytes) {
+        throw new JobConfigError("payload_too_large", `Job ${what} is ${bytes.byteLength} bytes serialized; the limit is ${maxBytes} bytes. ` +
+            "Jobs are not a blob store — put large payloads in object storage and enqueue the URL.");
+    }
+    return { json, bytes };
+}
+function getSubtle() {
+    const c = globalThis.crypto;
+    if (!c?.subtle) {
+        throw new Error("jobs: Web Crypto (crypto.subtle) is required for idempotency fingerprints. " +
+            "Provide a polyfill in environments without it.");
+    }
+    return c.subtle;
+}
+const HEX = "0123456789abcdef";
+function bytesToHex(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i];
+        out += HEX[b >> 4] + HEX[b & 0x0f];
+    }
+    return out;
+}
+/** SHA-256 hex of already-serialized payload bytes (idempotency fingerprint). */
+async function sha256Hex(bytes) {
+    const digest = new Uint8Array(await getSubtle().digest("SHA-256", bytes));
+    return bytesToHex(digest);
+}
+function isPromiseLike(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+/** Await a store result that may be sync or async (the SPI allows both). */
+async function settle(value) {
+    return isPromiseLike(value) ? await value : value;
+}
+function randomId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    // Web-Crypto is mandatory on every runtime Daloy supports; this is an
+    // unreachable last-resort guard so a missing global never throws.
+    throw new Error("WebCrypto unavailable: cannot generate a job id");
+}
+/** Cap persisted error strings so a huge stack cannot bloat the store. */
+const MAX_ERROR_CHARS = 2_000;
+function errorMessage(error) {
+    const raw = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    return raw.length > MAX_ERROR_CHARS ? `${raw.slice(0, MAX_ERROR_CHARS)}…` : raw;
+}
+// ── backoff ─────────────────────────────────────────────────────────
+/**
+ * Exponential backoff with full jitter, in ms — the same math as webhook
+ * delivery: `min(max, base * 2^(attempt-1))` scaled by a uniform random
+ * factor in `[0, 1)`. Exported for deterministic tests (inject
+ * `random: () => 1` for the unfuzzed ceiling).
+ *
+ * @param attempt - The attempt number that just failed (1-based; attempts
+ *   were already incremented at claim time).
+ * @param base - Base delay for the first retry, in ms.
+ * @param max - Upper bound on the un-jittered delay, in ms.
+ * @param random - Uniform source in `[0, 1)`.
+ * @returns The delay before the next attempt, in ms.
+ * @since 1.3.0
+ */
+export function computeBackoffMs(attempt, base, max, random) {
+    const exp = Math.min(max, base * 2 ** Math.max(0, attempt - 1));
+    return Math.floor(random() * exp); // full jitter
+}
+// ── memory store ────────────────────────────────────────────────────
+/** Default cap on jobs (all statuses) held by {@link MemoryJobStore}. */
+const DEFAULT_CAPACITY = 10_000;
+/** Default retention for `completed` / `cancelled` records: 24 hours. */
+const DEFAULT_RETENTION_MS = 86_400_000;
+/** Default retention for `dead` records (kept longer for inspection): 7 days. */
+const DEFAULT_DEAD_RETENTION_MS = 604_800_000;
+/** Higher priority first, then earliest runAt, then oldest, then id. */
+function compareRunnable(a, b) {
+    if (a.priority !== b.priority)
+        return b.priority - a.priority;
+    if (a.runAt !== b.runAt)
+        return a.runAt - b.runAt;
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt - b.createdAt;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/**
+ * In-memory {@link JobStore}. Correct for tests and single-process apps —
+ * a full implementation of the SPI, not a fake. **Not durable across
+ * processes** and invisible to other replicas: production deployments must
+ * supply a shared store (Redis, Postgres, SQS) through the same interface.
+ * `app.useJobs()` warns when it sees this store with production config.
+ *
+ * Payloads are held serialized and re-parsed with the prototype-pollution-safe
+ * `safeJsonParse` on every read, and every read returns a deep copy, so
+ * callers can never mutate store state.
+ *
+ * @since 1.3.0
+ */
+export class MemoryJobStore {
+    #jobs = new Map();
+    #idem = new Map(); // `${queue}\0${idempotencyKey}` -> job id
+    #capacity;
+    #now;
+    #retentionMs;
+    #deadRetentionMs;
+    /**
+     * @param opts - Capacity, clock, and retention knobs.
+     * @throws {RangeError} when a numeric option is out of bounds.
+     */
+    constructor(opts = {}) {
+        const capacity = opts.capacity ?? DEFAULT_CAPACITY;
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new RangeError("MemoryJobStore: capacity must be a positive integer.");
+        }
+        const retentionMs = opts.retentionMs ?? DEFAULT_RETENTION_MS;
+        if (!Number.isInteger(retentionMs) || retentionMs < 0) {
+            throw new RangeError("MemoryJobStore: retentionMs must be a non-negative integer.");
+        }
+        const deadRetentionMs = opts.deadRetentionMs ?? DEFAULT_DEAD_RETENTION_MS;
+        if (!Number.isInteger(deadRetentionMs) || deadRetentionMs < 0) {
+            throw new RangeError("MemoryJobStore: deadRetentionMs must be a non-negative integer.");
+        }
+        this.#capacity = capacity;
+        this.#now = opts.now ?? Date.now;
+        this.#retentionMs = retentionMs;
+        this.#deadRetentionMs = deadRetentionMs;
+    }
+    /** The number of jobs currently held (all statuses). */
+    get size() {
+        return this.#jobs.size;
+    }
+    /**
+     * @inheritDoc
+     * `_fingerprint` is part of the {@link JobStore} contract but unused here:
+     * the in-memory store compares serialized payloads directly.
+     */
+    put(job, _fingerprint) {
+        const now = this.#now();
+        const payloadJson = JSON.stringify(job.payload);
+        if (job.idempotencyKey !== null) {
+            const idemKey = `${job.queue}\0${job.idempotencyKey}`;
+            const existingId = this.#idem.get(idemKey);
+            if (existingId !== undefined) {
+                const existing = this.#jobs.get(existingId);
+                if (existing !== undefined) {
+                    if (existing.payloadJson !== payloadJson) {
+                        throw new JobIdempotencyConflictError(job.idempotencyKey, existingId);
+                    }
+                    return { job: this.#clone(existing), duplicate: true };
+                }
+                // Stale index entry (record was swept): fall through and re-insert.
+            }
+            if (this.#jobs.size >= this.#capacity) {
+                this.#purgeExpiredTerminal(now);
+                if (this.#jobs.size >= this.#capacity) {
+                    throw new JobConfigError("store_full", `MemoryJobStore is at capacity (${this.#capacity} jobs); refusing to drop queued work. ` +
+                        "Supply a durable JobStore for production volumes.");
+                }
+            }
+            this.#insert(job, payloadJson, now);
+            this.#idem.set(idemKey, job.id);
+            return { job: this.#clone(this.#jobs.get(job.id)), duplicate: false };
+        }
+        if (this.#jobs.size >= this.#capacity) {
+            this.#purgeExpiredTerminal(now);
+            if (this.#jobs.size >= this.#capacity) {
+                throw new JobConfigError("store_full", `MemoryJobStore is at capacity (${this.#capacity} jobs); refusing to drop queued work. ` +
+                    "Supply a durable JobStore for production volumes.");
+            }
+        }
+        this.#insert(job, payloadJson, now);
+        return { job: this.#clone(this.#jobs.get(job.id)), duplicate: false };
+    }
+    /** @inheritDoc */
+    claim(queue, workerId, now) {
+        this.#reapLeases(now);
+        let best;
+        for (const job of this.#jobs.values()) {
+            if (job.queue !== queue)
+                continue;
+            const runnable = job.status === "queued" || (job.status === "delayed" && job.runAt <= now);
+            if (!runnable)
+                continue;
+            if (best === undefined || compareRunnable(job, best) < 0)
+                best = job;
+        }
+        if (best === undefined)
+            return null;
+        best.status = "running";
+        best.lockedBy = workerId;
+        best.leaseUntil = now + best.leaseMs;
+        // Attempts increment at claim: a crashed worker that never reports back
+        // still spends one attempt, so a poison handler cannot loop forever.
+        best.attempts += 1;
+        best.updatedAt = now;
+        return this.#clone(best);
+    }
+    /** @inheritDoc */
+    heartbeat(id, workerId, leaseUntil, now) {
+        const job = this.#jobs.get(id);
+        if (job === undefined || job.status !== "running" || job.lockedBy !== workerId) {
+            return false;
+        }
+        if (job.leaseUntil !== null && job.leaseUntil < now)
+            return false; // already lost
+        job.leaseUntil = leaseUntil;
+        job.updatedAt = now;
+        return true;
+    }
+    /** @inheritDoc */
+    complete(id, workerId, now, result) {
+        const job = this.#jobs.get(id);
+        if (job === undefined || job.status !== "running" || job.lockedBy !== workerId) {
+            return false;
+        }
+        job.status = "completed";
+        job.completedAt = now;
+        job.resultJson = result === null || result === undefined ? null : JSON.stringify(result);
+        job.lockedBy = null;
+        job.leaseUntil = null;
+        job.updatedAt = now;
+        return true;
+    }
+    /** @inheritDoc */
+    fail(id, workerId, error, next, now) {
+        const job = this.#jobs.get(id);
+        if (job === undefined || job.status !== "running" || job.lockedBy !== workerId) {
+            return false;
+        }
+        job.lastError = error;
+        job.lockedBy = null;
+        job.leaseUntil = null;
+        if (job.attempts >= job.maxAttempts) {
+            job.status = "dead";
+            job.runAt = now;
+        }
+        else {
+            job.status = next.status;
+            job.runAt = next.status === "delayed" ? next.runAt : now;
+        }
+        job.updatedAt = now;
+        return true;
+    }
+    /** @inheritDoc */
+    cancel(id, now) {
+        const job = this.#jobs.get(id);
+        if (job === undefined)
+            return false;
+        if (job.status === "completed" || job.status === "dead" || job.status === "cancelled") {
+            return false;
+        }
+        job.status = "cancelled";
+        job.lockedBy = null;
+        job.leaseUntil = null;
+        job.updatedAt = now;
+        return true;
+    }
+    /** @inheritDoc */
+    get(id, now) {
+        this.#reapLeases(now);
+        const job = this.#jobs.get(id);
+        return job === undefined ? null : this.#clone(job);
+    }
+    /** @inheritDoc */
+    list(filter) {
+        this.#reapLeases(this.#now());
+        const statuses = filter?.status === undefined
+            ? undefined
+            : new Set(Array.isArray(filter.status) ? filter.status : [filter.status]);
+        const out = [];
+        for (const job of this.#jobs.values()) {
+            if (filter?.queue !== undefined && job.queue !== filter.queue)
+                continue;
+            if (statuses !== undefined && !statuses.has(job.status))
+                continue;
+            if (filter?.name !== undefined && job.name !== filter.name)
+                continue;
+            if (filter?.tenant !== undefined && job.tenant !== filter.tenant)
+                continue;
+            out.push(this.#clone(job));
+        }
+        // Deterministic inspection order: oldest first, id as tiebreak.
+        out.sort((a, b) => a.createdAt !== b.createdAt ? a.createdAt - b.createdAt : a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+        return out;
+    }
+    /** Test helper: every job, including terminal records. */
+    dump() {
+        return this.list();
+    }
+    #insert(job, payloadJson, now) {
+        this.#jobs.set(job.id, {
+            id: job.id,
+            queue: job.queue,
+            name: job.name,
+            payloadJson,
+            // The store decides the initial status from its own clock: a job with
+            // a future runAt starts delayed, anything else is immediately claimable.
+            status: job.runAt > now ? "delayed" : "queued",
+            attempts: job.attempts,
+            maxAttempts: job.maxAttempts,
+            runAt: job.runAt,
+            createdAt: job.createdAt,
+            updatedAt: now,
+            leaseUntil: null,
+            lockedBy: null,
+            leaseMs: job.leaseMs,
+            idempotencyKey: job.idempotencyKey,
+            priority: job.priority,
+            timeoutMs: job.timeoutMs,
+            lastError: null,
+            completedAt: null,
+            resultJson: null,
+            tenant: job.tenant,
+        });
+    }
+    /** Expired leases return to `queued`; attempts stay spent. */
+    #reapLeases(now) {
+        for (const job of this.#jobs.values()) {
+            if (job.status === "running" && job.leaseUntil !== null && job.leaseUntil < now) {
+                job.status = "queued";
+                job.lockedBy = null;
+                job.leaseUntil = null;
+                job.updatedAt = now;
+            }
+        }
+    }
+    /** Sweep terminal records past their retention; also drops index entries. */
+    #purgeExpiredTerminal(now) {
+        for (const job of this.#jobs.values()) {
+            const retention = job.status === "dead"
+                ? this.#deadRetentionMs
+                : job.status === "completed" || job.status === "cancelled"
+                    ? this.#retentionMs
+                    : undefined;
+            if (retention === undefined)
+                continue;
+            if (now - job.updatedAt <= retention)
+                continue;
+            if (job.idempotencyKey !== null)
+                this.#idem.delete(`${job.queue}\0${job.idempotencyKey}`);
+            this.#jobs.delete(job.id);
+        }
+    }
+    /** Deep copy: callers can never mutate store state through a snapshot. */
+    #clone(job) {
+        return {
+            id: job.id,
+            queue: job.queue,
+            name: job.name,
+            payload: safeJsonParse(job.payloadJson),
+            status: job.status,
+            attempts: job.attempts,
+            maxAttempts: job.maxAttempts,
+            runAt: job.runAt,
+            createdAt: job.createdAt,
+            updatedAt: job.updatedAt,
+            leaseUntil: job.leaseUntil,
+            lockedBy: job.lockedBy,
+            leaseMs: job.leaseMs,
+            idempotencyKey: job.idempotencyKey,
+            priority: job.priority,
+            timeoutMs: job.timeoutMs,
+            lastError: job.lastError,
+            completedAt: job.completedAt,
+            result: job.resultJson === null ? null : safeJsonParse(job.resultJson),
+            tenant: job.tenant,
+        };
+    }
+}
+/**
+ * Create a {@link JobQueue} over a {@link JobStore}. Validates all options
+ * eagerly (fail-fast config): numeric bounds throw `RangeError`, bad names
+ * throw {@link JobConfigError}, a missing store throws
+ * {@link JobConfigError} (`store_required`).
+ *
+ * @param opts - Queue configuration; see {@link JobQueueOptions}.
+ * @returns The producer façade.
+ * @since 1.3.0
+ */
+export function createJobQueue(opts) {
+    if (opts === undefined || opts.store === undefined || opts.store === null) {
+        throw new JobConfigError("store_required", "createJobQueue(): a JobStore is required (MemoryJobStore for tests, a durable adapter in production).");
+    }
+    const store = opts.store;
+    const logger = opts.logger;
+    const now = opts.now ?? Date.now;
+    const payloadMaxBytes = opts.payloadMaxBytes ?? 64 * 1024;
+    if (!Number.isInteger(payloadMaxBytes) || payloadMaxBytes < 1) {
+        throw new RangeError("createJobQueue(): payloadMaxBytes must be a positive integer.");
+    }
+    const defaultQueue = opts.defaultQueue === undefined ? "default" : assertQueueName(opts.defaultQueue);
+    const defaultMaxAttempts = opts.defaultMaxAttempts ?? 5;
+    if (!Number.isInteger(defaultMaxAttempts) || defaultMaxAttempts < 1) {
+        throw new RangeError("createJobQueue(): defaultMaxAttempts must be a positive integer.");
+    }
+    const defaultTimeoutMs = opts.defaultTimeoutMs ?? 30_000;
+    if (!Number.isInteger(defaultTimeoutMs) || defaultTimeoutMs < 0) {
+        throw new RangeError("createJobQueue(): defaultTimeoutMs must be a non-negative integer.");
+    }
+    const defaultLeaseMs = opts.defaultLeaseMs ?? 30_000;
+    if (!Number.isInteger(defaultLeaseMs) || defaultLeaseMs < 1) {
+        throw new RangeError("createJobQueue(): defaultLeaseMs must be a positive integer.");
+    }
+    const baseDelayMs = opts.backoff?.baseDelayMs ?? 200;
+    if (!Number.isInteger(baseDelayMs) || baseDelayMs < 0) {
+        throw new RangeError("createJobQueue(): backoff.baseDelayMs must be a non-negative integer.");
+    }
+    const maxDelayMs = opts.backoff?.maxDelayMs ?? 60_000;
+    if (!Number.isInteger(maxDelayMs) || maxDelayMs < baseDelayMs) {
+        throw new RangeError("createJobQueue(): backoff.maxDelayMs must be an integer >= backoff.baseDelayMs.");
+    }
+    const backoff = {
+        baseDelayMs,
+        maxDelayMs,
+        // Backoff jitter spreads load; it is not a security primitive.
+        random: opts.backoff?.random ?? Math.random, // daloy-allow-weak-random: backoff jitter is not a security primitive
+    };
+    return {
+        store,
+        defaultQueue,
+        payloadMaxBytes,
+        backoff,
+        async enqueue(enqueueOpts) {
+            const name = assertJobName(enqueueOpts.name);
+            const queueName = enqueueOpts.queue === undefined ? defaultQueue : assertQueueName(enqueueOpts.queue);
+            const idempotencyKey = enqueueOpts.idempotencyKey === undefined
+                ? null
+                : assertIdempotencyKey(enqueueOpts.idempotencyKey);
+            const tenant = enqueueOpts.tenant === undefined ? null : assertTenant(enqueueOpts.tenant);
+            const enqueueNow = now();
+            let runAt;
+            if (enqueueOpts.runAt !== undefined) {
+                runAt =
+                    enqueueOpts.runAt instanceof Date
+                        ? enqueueOpts.runAt.getTime()
+                        : enqueueOpts.runAt;
+                if (!Number.isFinite(runAt)) {
+                    throw new JobConfigError("invalid_option", "enqueue(): runAt must be a finite epoch ms or a Date.");
+                }
+            }
+            else {
+                const delayMs = enqueueOpts.delayMs ?? 0;
+                if (!Number.isInteger(delayMs) || delayMs < 0) {
+                    throw new JobConfigError("invalid_option", "enqueue(): delayMs must be a non-negative integer.");
+                }
+                runAt = enqueueNow + delayMs;
+            }
+            const priority = enqueueOpts.priority ?? 0;
+            if (!Number.isInteger(priority)) {
+                throw new JobConfigError("invalid_option", "enqueue(): priority must be an integer.");
+            }
+            const maxAttempts = enqueueOpts.maxAttempts ?? defaultMaxAttempts;
+            if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+                throw new JobConfigError("invalid_option", "enqueue(): maxAttempts must be a positive integer.");
+            }
+            const timeoutMs = enqueueOpts.timeoutMs ?? defaultTimeoutMs;
+            if (!Number.isInteger(timeoutMs) || timeoutMs < 0) {
+                throw new JobConfigError("invalid_option", "enqueue(): timeoutMs must be a non-negative integer (0 disables the per-attempt timeout).");
+            }
+            const leaseMs = enqueueOpts.leaseMs ?? defaultLeaseMs;
+            if (!Number.isInteger(leaseMs) || leaseMs < 1) {
+                throw new JobConfigError("invalid_option", "enqueue(): leaseMs must be a positive integer.");
+            }
+            const { json, bytes } = serializePayload(enqueueOpts.payload, payloadMaxBytes, "payload");
+            // The fingerprint rides only idempotent enqueues; without a key the
+            // store never compares payloads, so skip the hash.
+            const fingerprint = idempotencyKey === null ? null : await sha256Hex(bytes);
+            // A clean, plain-JSON clone: key order and values are exactly what was
+            // serialized, so two enqueues of the same logical payload compare equal.
+            const payload = safeJsonParse(json);
+            const job = {
+                id: randomId(),
+                queue: queueName,
+                name,
+                payload,
+                status: runAt > enqueueNow ? "delayed" : "queued",
+                attempts: 0,
+                maxAttempts,
+                runAt,
+                createdAt: enqueueNow,
+                updatedAt: enqueueNow,
+                leaseUntil: null,
+                lockedBy: null,
+                leaseMs,
+                idempotencyKey,
+                priority,
+                timeoutMs,
+                lastError: null,
+                completedAt: null,
+                result: null,
+                tenant,
+            };
+            logger?.debug({ event: "jobs.enqueue", queue: queueName, name, jobId: job.id, delayed: runAt > enqueueNow }, `Enqueued job "${name}" (${job.id})`);
+            const result = await settle(store.put(job, fingerprint));
+            return { job: result.job, duplicate: result.duplicate };
+        },
+        async get(id) {
+            return settle(store.get(id, now()));
+        },
+        async cancel(id) {
+            return settle(store.cancel(id, now()));
+        },
+    };
+}
+const defaultWorkerTimers = {
+    set(callback, delayMs) {
+        const handle = setTimeout(callback, delayMs);
+        handle.unref?.();
+        return handle;
+    },
+    clear(handle) {
+        clearTimeout(handle);
+    },
+};
+/**
+ * Create a {@link JobWorker}. The handler registry is frozen into a
+ * null-prototype map at construction: unknown job names dead-letter as
+ * poison pills instead of spinning, and no code path resolves a handler by
+ * dynamic lookup or import.
+ *
+ * @param opts - Worker configuration; see {@link JobWorkerOptions}.
+ * @returns The worker.
+ * @throws {RangeError} on out-of-bounds numeric options.
+ * @throws {@link JobConfigError} on a missing/empty registry or invalid
+ *   handler names.
+ * @since 1.3.0
+ */
+export function createJobWorker(opts) {
+    if (opts === undefined || opts.queue === undefined || opts.queue === null) {
+        throw new JobConfigError("store_required", "createJobWorker(): a JobQueue is required.");
+    }
+    const queue = opts.queue;
+    const store = queue.store;
+    const logger = opts.logger;
+    const now = opts.now ?? Date.now;
+    const timers = opts.timers ?? defaultWorkerTimers;
+    if (opts.handlers === undefined || opts.handlers === null || typeof opts.handlers !== "object") {
+        throw new JobConfigError("unknown_handler", "createJobWorker(): a handlers registry is required.");
+    }
+    const handlers = Object.create(null);
+    for (const [name, handler] of Object.entries(opts.handlers)) {
+        assertJobName(name);
+        if (typeof handler !== "function") {
+            throw new JobConfigError("invalid_option", `createJobWorker(): handler "${name}" must be a function.`);
+        }
+        handlers[name] = handler;
+    }
+    const handlerNames = Object.keys(handlers);
+    if (handlerNames.length === 0) {
+        throw new JobConfigError("unknown_handler", "createJobWorker(): the handlers registry is empty; every claimed job would dead-letter.");
+    }
+    Object.freeze(handlers);
+    const queues = (opts.queues ?? [queue.defaultQueue]).map(assertQueueName);
+    const concurrency = opts.concurrency ?? 1;
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        throw new RangeError("createJobWorker(): concurrency must be a positive integer.");
+    }
+    if (concurrency > 1000) {
+        throw new RangeError("createJobWorker(): concurrency above 1000 is not a supported posture.");
+    }
+    if (concurrency > 32) {
+        logger?.warn({ event: "jobs.worker.high_concurrency", concurrency }, `Job worker concurrency ${concurrency} is unusually high; bound it to downstream capacity.`);
+    }
+    const pollIntervalMs = opts.pollIntervalMs ?? 200;
+    if (!Number.isInteger(pollIntervalMs) || pollIntervalMs < 1) {
+        throw new RangeError("createJobWorker(): pollIntervalMs must be a positive integer.");
+    }
+    const workerId = opts.workerId ?? randomId();
+    const backoff = queue.backoff;
+    let started = false;
+    let stopped = false;
+    let pollTimer;
+    let draining = false;
+    let drainAgain = false;
+    const inFlight = new Set();
+    function arm() {
+        if (stopped || !started)
+            return;
+        pollTimer = timers.set(() => {
+            pollTimer = undefined;
+            void tick();
+        }, pollIntervalMs);
+    }
+    async function tick() {
+        if (stopped)
+            return;
+        // Re-arm first (fixed cadence), then claim. Overlapping drains are
+        // collapsed by the single-flight drain flag.
+        arm();
+        await drainAvailable();
+    }
+    async function drainAvailable() {
+        if (draining) {
+            drainAgain = true;
+            return;
+        }
+        draining = true;
+        try {
+            do {
+                drainAgain = false;
+                while (!stopped && inFlight.size < concurrency) {
+                    let job;
+                    try {
+                        job = await claimNext();
+                    }
+                    catch (error) {
+                        // A throwing store must not kill the loop; the next poll retries.
+                        logger?.error({ event: "jobs.worker.claim_failed", err: errorMessage(error), workerId }, "Job worker: claim failed");
+                        break;
+                    }
+                    if (job === null)
+                        break;
+                    launch(job);
+                }
+            } while (drainAgain && !stopped);
+        }
+        finally {
+            draining = false;
+        }
+    }
+    async function claimNext() {
+        for (const queueName of queues) {
+            const job = await settle(store.claim(queueName, workerId, now()));
+            if (job !== null) {
+                logger?.debug({ event: "jobs.claim", queue: job.queue, name: job.name, jobId: job.id, attempt: job.attempts, workerId }, `Claimed job "${job.name}" (${job.id})`);
+                return job;
+            }
+        }
+        return null;
+    }
+    /** Track and run a claimed job without awaiting it (concurrency > 1). */
+    function launch(job) {
+        const controller = new AbortController();
+        const entry = { controller, promise: Promise.resolve(), jobId: job.id };
+        entry.promise = execute(job, controller)
+            .catch((error) => {
+            // The run algorithm handles every expected failure; this catch is the
+            // last-resort guard that keeps a defect from crashing the loop.
+            logger?.error({ event: "jobs.worker.run_crashed", jobId: job.id, err: errorMessage(error), workerId }, "Job worker: unexpected runner error");
+        })
+            .finally(() => {
+            inFlight.delete(entry);
+        });
+        inFlight.add(entry);
+        return entry;
+    }
+    async function execute(job, controller) {
+        let timedOut = false;
+        let lostLease = false;
+        let settled = false;
+        let timeoutTimer;
+        let heartbeatTimer;
+        const clearJobTimers = () => {
+            if (timeoutTimer !== undefined) {
+                timers.clear(timeoutTimer);
+                timeoutTimer = undefined;
+            }
+            if (heartbeatTimer !== undefined) {
+                timers.clear(heartbeatTimer);
+                heartbeatTimer = undefined;
+            }
+        };
+        const beat = async () => {
+            if (settled || lostLease)
+                return;
+            const ok = await settle(store.heartbeat(job.id, workerId, now() + job.leaseMs, now()));
+            if (!ok && !settled) {
+                // Another worker owns the job now: unwind locally, touch nothing.
+                lostLease = true;
+                logger?.warn({ event: "jobs.lease_lost", queue: job.queue, name: job.name, jobId: job.id, workerId }, `Lost lease for job "${job.name}" (${job.id}); aborting local run`);
+                controller.abort();
+            }
+        };
+        const scheduleBeat = () => {
+            if (settled)
+                return;
+            heartbeatTimer = timers.set(() => {
+                heartbeatTimer = undefined;
+                void (async () => {
+                    await beat();
+                    if (!settled && !lostLease && !controller.signal.aborted)
+                        scheduleBeat();
+                })();
+            }, Math.max(1, Math.floor(job.leaseMs / 3)));
+        };
+        if (job.timeoutMs > 0) {
+            timeoutTimer = timers.set(() => {
+                timedOut = true;
+                controller.abort();
+            }, job.timeoutMs);
+        }
+        // Auto-heartbeat so handlers that forget ctx.heartbeat() still hold the
+        // lease while they run; long jobs should also call ctx.heartbeat().
+        scheduleBeat();
+        const jobLog = {
+            debug: (obj, msg) => logger?.debug(typeof obj === "string"
+                ? obj
+                : { jobId: job.id, name: job.name, queue: job.queue, attempt: job.attempts, ...obj }, msg),
+            info: (obj, msg) => logger?.info(typeof obj === "string"
+                ? obj
+                : { jobId: job.id, name: job.name, queue: job.queue, attempt: job.attempts, ...obj }, msg),
+            warn: (obj, msg) => logger?.warn(typeof obj === "string"
+                ? obj
+                : { jobId: job.id, name: job.name, queue: job.queue, attempt: job.attempts, ...obj }, msg),
+            error: (obj, msg) => logger?.error(typeof obj === "string"
+                ? obj
+                : { jobId: job.id, name: job.name, queue: job.queue, attempt: job.attempts, ...obj }, msg),
+        };
+        try {
+            const handler = handlers[job.name];
+            if (handler === undefined) {
+                // Poison pill: no code is registered for this name. Dead-letter
+                // immediately instead of retrying a record that can never succeed.
+                throw new JobFatalError(`Unknown job handler: "${job.name}".`);
+            }
+            const returned = await handler({
+                job,
+                signal: controller.signal,
+                attempt: job.attempts,
+                heartbeat: beat,
+                log: jobLog,
+            });
+            if (controller.signal.aborted) {
+                if (lostLease)
+                    return; // the other worker owns the outcome
+                if (timedOut)
+                    throw new JobTimeoutError(job.timeoutMs);
+                throw new Error("Job aborted: worker is stopping.");
+            }
+            const resultValue = returned === undefined ? null : returned;
+            if (resultValue !== null) {
+                // Same rules as payloads: plain JSON, pollution keys rejected, size cap.
+                serializePayload(resultValue, queue.payloadMaxBytes, "result");
+            }
+            const ok = await settle(store.complete(job.id, workerId, now(), resultValue));
+            if (!ok) {
+                logger?.warn({ event: "jobs.complete_lost", queue: job.queue, name: job.name, jobId: job.id, workerId }, `Complete for job "${job.name}" (${job.id}) was rejected: lease lost`);
+                return;
+            }
+            logger?.debug({ event: "jobs.complete", queue: job.queue, name: job.name, jobId: job.id, attempt: job.attempts }, `Completed job "${job.name}" (${job.id})`);
+            await safeHook(() => opts.onComplete?.(job));
+        }
+        catch (error) {
+            if (lostLease)
+                return; // the other worker owns the outcome
+            // A handler that unwound because of the timeout abort reports the
+            // timeout, not whatever the abort made it throw.
+            const effectiveError = timedOut
+                ? error instanceof JobTimeoutError
+                    ? error
+                    : new JobTimeoutError(job.timeoutMs)
+                : error;
+            const fatal = effectiveError instanceof JobFatalError;
+            const message = errorMessage(effectiveError);
+            const willRetry = !fatal && job.attempts < job.maxAttempts;
+            const delayMs = willRetry
+                ? computeBackoffMs(job.attempts, backoff.baseDelayMs, backoff.maxDelayMs, backoff.random)
+                : 0;
+            const nextRunAt = now() + delayMs;
+            const ok = await settle(store.fail(job.id, workerId, message, willRetry
+                ? { status: "delayed", runAt: nextRunAt }
+                : { status: "dead", runAt: now() }, now()));
+            if (!ok) {
+                logger?.warn({ event: "jobs.fail_lost", queue: job.queue, name: job.name, jobId: job.id, workerId }, `Fail for job "${job.name}" (${job.id}) was rejected: lease lost`);
+                return;
+            }
+            if (willRetry) {
+                logger?.warn({
+                    event: "jobs.retry",
+                    queue: job.queue,
+                    name: job.name,
+                    jobId: job.id,
+                    attempt: job.attempts,
+                    delayMs,
+                    err: message,
+                }, `Job "${job.name}" (${job.id}) failed; retrying in ${delayMs}ms`);
+                await safeHook(() => opts.onFail?.(job, message, true, delayMs));
+            }
+            else {
+                logger?.error({
+                    event: "jobs.dead",
+                    queue: job.queue,
+                    name: job.name,
+                    jobId: job.id,
+                    attempt: job.attempts,
+                    fatal,
+                    err: message,
+                }, `Job "${job.name}" (${job.id}) dead-lettered`);
+                await safeHook(() => opts.onFail?.(job, message, false));
+                await safeHook(() => opts.onDead?.(job, message));
+            }
+        }
+        finally {
+            settled = true;
+            clearJobTimers();
+        }
+    }
+    async function safeHook(hook) {
+        try {
+            await hook();
+        }
+        catch (error) {
+            // Hooks observe; they must never change the job's outcome.
+            logger?.error({ event: "jobs.hook_failed", err: errorMessage(error) }, "Job worker: lifecycle hook threw");
+        }
+    }
+    return {
+        start() {
+            if (stopped) {
+                throw new JobConfigError("invalid_option", "Job worker cannot be restarted after stop(); create a new worker.");
+            }
+            if (started) {
+                throw new JobConfigError("invalid_option", "Job worker is already started.");
+            }
+            started = true;
+            logger?.info({ event: "jobs.worker.started", workerId, queues, concurrency }, "Job worker started");
+            arm();
+        },
+        async stop(graceMs = 5_000) {
+            if (!Number.isInteger(graceMs) || graceMs < 0) {
+                throw new RangeError("Job worker stop(): graceMs must be a non-negative integer.");
+            }
+            if (stopped)
+                return;
+            stopped = true;
+            if (pollTimer !== undefined) {
+                timers.clear(pollTimer);
+                pollTimer = undefined;
+            }
+            if (inFlight.size === 0) {
+                logger?.info({ event: "jobs.worker.stopped", workerId }, "Job worker stopped");
+                return;
+            }
+            let timedOut = false;
+            let deadlineTimer;
+            const deadline = new Promise((resolve) => {
+                deadlineTimer = timers.set(() => {
+                    timedOut = true;
+                    resolve();
+                }, graceMs);
+            });
+            const settledAll = Promise.all([...inFlight].map((entry) => entry.promise)).then(() => undefined);
+            await Promise.race([settledAll, deadline]);
+            if (deadlineTimer !== undefined)
+                timers.clear(deadlineTimer);
+            if (timedOut && inFlight.size > 0) {
+                logger?.warn({ event: "jobs.worker.stop_timeout", workerId, inFlight: inFlight.size }, `Job worker grace period elapsed; aborting ${inFlight.size} in-flight job(s)`);
+                for (const entry of inFlight)
+                    entry.controller.abort();
+                // Wait for the aborted runs to unwind (they fail back to the queue).
+                await Promise.all([...inFlight].map((entry) => entry.promise)).catch(() => undefined);
+            }
+            logger?.info({ event: "jobs.worker.stopped", workerId }, "Job worker stopped");
+        },
+        getState() {
+            return { running: started && !stopped, inFlight: inFlight.size, workerId };
+        },
+        async runOnce() {
+            const job = await claimNext();
+            if (job === null)
+                return false;
+            const entry = launch(job);
+            await entry.promise;
+            return true;
+        },
+    };
+}
+// ── tenancy helper ──────────────────────────────────────────────────
+/**
+ * Build a tenant-safe idempotency key of the form `t/{tenant}/{name}/{key}`
+ * (or `g/{name}/{key}` when no tenant applies). Segments are validated so a
+ * key can never smuggle whitespace/control characters, newlines, or `..`
+ * into store keys or log lines, and tenant ids follow the `tenancy()`
+ * grammar — one tenant's keys can never collide with another's.
+ *
+ * @param parts - `name` is the job name; `key` is the caller's dedupe id
+ *   (user id, provider event id, order id, …); `tenant` scopes the key.
+ * @returns The composed key, at most 255 chars.
+ * @throws {@link JobConfigError} when a segment fails validation.
+ * @since 1.3.0
+ */
+export function jobIdempotencyKey(parts) {
+    const name = assertJobName(parts.name);
+    const key = parts.key;
+    if (typeof key !== "string" || key.length === 0) {
+        throw new JobConfigError("invalid_option", "jobIdempotencyKey(): key must be a non-empty string.");
+    }
+    if (!/^[\x21-\x7e]+$/.test(key)) {
+        throw new JobConfigError("invalid_option", "jobIdempotencyKey(): key must be printable ASCII (no whitespace or control characters).");
+    }
+    if (key.includes("..")) {
+        throw new JobConfigError("invalid_option", 'jobIdempotencyKey(): key must not contain "..".');
+    }
+    const scope = parts.tenant === undefined ? "g" : `t/${assertTenant(parts.tenant)}`;
+    const out = `${scope}/${name}/${key}`;
+    if (out.length > 255) {
+        throw new JobConfigError("invalid_option", `jobIdempotencyKey(): composed key is ${out.length} chars; the limit is 255.`);
+    }
+    return out;
+}