@nest-batch/bullmq 0.2.0

package/dist/src/bullmq-runtime.service.d.ts

@@ -0,0 +1,237 @@
+import { OnApplicationBootstrap, OnApplicationShutdown } from '@nestjs/common';
+import { type IExecutionStrategy, type JobDefinition, type BatchObserver, type JobRepository } from '@nest-batch/core';
+import { JobExecutor, JobRegistry } from '@nest-batch/core';
+import { type ResolvedBullMqModuleOptions } from './module-options';
+/**
+ * Payload shape stored in a BullMQ job's `data` field.
+ *
+ * The strategy enqueues one BullMQ job per step (or per partition,
+ * in a future enhancement). The worker reconstructs the
+ * `JobExecution` from the repository via `executionId` and the
+ * `JobDefinition` from the registry via `jobId`.
+ *
+ * Why not store the full `JobDefinition` in the payload?
+ *   - IR is mutable across the host process (decorators / builders
+ *     may swap providers in tests, hot-reload, etc.). The
+ *     repository + registry are the canonical sources; the
+ *     payload carries only the keys needed to look them up.
+ *   - Storage size — IRs can be large (listeners, resolvers).
+ *     Redis is transport, not cache; small payloads are cheaper.
+ */
+export interface BullmqJobPayload {
+    /** JobExecution id, used to load the canonical execution row. */
+    readonly executionId: string;
+    /** Mirrors `executionId` today; kept distinct for forward compat. */
+    readonly jobExecutionId: string;
+    /** JobDefinition id, used to look up the IR from the registry. */
+    readonly jobId: string;
+    /** Step id (the `name` field of the BullMQ job). */
+    readonly stepId: string;
+    /**
+     * Partition index. Reserved for a future enhancement where a
+     * chunk step is split into N partitions and enqueued as N
+     * BullMQ jobs. Today the strategy always enqueues one job
+     * per step (regardless of chunk size), so the field is
+     * `undefined`. Kept in the payload shape so the worker
+     * can distinguish "this is a step" from "this is a partition"
+     * without a separate discriminator.
+     */
+    readonly partitionIndex?: number;
+}
+/**
+ * The single BullMQ queue name used by the strategy + worker +
+ * queue-events. We deliberately do not fan out into per-step
+ * queues — that would force the host to pre-declare every step
+ * name at compile time, which is at odds with the decorator /
+ * builder APIs that discover steps at runtime. A single queue
+ * keyed by the step's `name` field is the standard BullMQ pattern
+ * (the `name` field discriminates the work).
+ *
+ * BullMQ 5 rejects queue names that contain a colon (`:`) because
+ * it is the path separator in the Redis key layout. We use a
+ * hyphen-separated name accordingly.
+ */
+export declare const BULLMQ_QUEUE_NAME = "nest-batch-work";
+/**
+ * Name of the BullMQ strategy. Logged by the bridge for diagnostic
+ * purposes and asserted by tests that need to distinguish the
+ * real implementation from the T17 stub.
+ */
+export declare const BULLMQ_STRATEGY_NAME = "bullmq";
+/**
+ * Bridge between the BullMQ `Queue` / `Worker` / `QueueEvents` and
+ * the `@nest-batch/core` execution pipeline.
+ *
+ * Responsibilities (T18 contract):
+ *   1. Own the producer / worker connection clients with the
+ *      role-specific tuning (fail-fast producer, blocking worker).
+ *   2. Implement the `IExecutionStrategy` contract: `launch()`
+ *      enqueues a single BullMQ job per step, returns
+ *      `{ kind: 'enqueued', queueJobId }`. The launch is
+ *      fire-and-forget — the strategy does NOT block on the
+ *      worker.
+ *   3. Drive the worker lifecycle (`OnApplicationBootstrap` /
+ *      `OnApplicationShutdown`).
+ *   4. Bridge `QueueEvents` `completed` / `failed` / `stalled`
+ *      into the `BatchObserver` (defaulting to `NoopBatchObserver`).
+ *   5. Hand off to `JobExecutor.execute(execution, jobDef)` from
+ *      inside the worker — Batch Core remains the source of truth
+ *      for state transitions, skip/retry, checkpoint, restart.
+ *
+ * Why a single class (not separate `Queue` / `Worker` providers)?
+ *   - The producer and worker share a `connection` record but
+ *     carry *different* `ConnectionOptions` (different
+ *     `maxRetriesPerRequest`, `enableReadyCheck`, ...). Splitting
+ *     them across providers would force the connection-tuning
+ *     logic into two places and risk the worker accidentally
+ *     inheriting the producer's fail-fast config (or vice versa).
+ *   - Lifecycle is a unit: open producer + worker + events
+ *     together, close them together in the documented order
+ *     (workers first, then events, then queues). Centralising
+ *     this in one class makes the close-order a single source
+ *     of truth and a single method (`close()`).
+ */
+export declare class BullmqRuntimeService implements IExecutionStrategy, OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly options;
+    private readonly repository;
+    private readonly registry;
+    private readonly jobExecutor;
+    private readonly observer;
+    /**
+     * Strategy name. Distinct from the T17 stub's `'bullmq-stub'`
+     * so log lines and boundary reports can tell them apart.
+     */
+    readonly name = "bullmq";
+    private readonly logger;
+    /** BullMQ queue (producer side). */
+    private queue;
+    /** BullMQ worker (consumer side). */
+    private worker;
+    /** BullMQ QueueEvents stream listener. */
+    private queueEvents;
+    /**
+     * Promise-chain lock for the close path. We capture the first
+     * `close()` invocation and short-circuit subsequent ones so a
+     * stray double-shutdown (Nest calls `OnApplicationShutdown`
+     * once, but tests sometimes do their own) does not race the
+     * in-flight close.
+     */
+    private closePromise;
+    constructor(options: ResolvedBullMqModuleOptions, repository: JobRepository, registry: JobRegistry, jobExecutor: JobExecutor, observer?: BatchObserver);
+    /**
+     * Nest lifecycle: spin up the queue, worker, and queue-events
+     * after the DI container is fully wired. We do this in
+     * `onApplicationBootstrap` (not `onModuleInit`) so every other
+     * provider — including user-supplied `JobRepository` overrides —
+     * is already instantiated and injectable.
+     *
+     * Worker startup is gated on `options.autoStartWorker`. The
+     * flag exists for launcher-only deployments (e.g. an API
+     * service that only enqueues) and for tests that want to
+     * exercise the producer side in isolation. When the flag is
+     * `false` the queue is still created (so `launch()` can
+     * enqueue), but the worker is not started (no consumer means
+     * the jobs sit in the queue indefinitely).
+     */
+    onApplicationBootstrap(): void;
+    /**
+     * Nest lifecycle: close every BullMQ resource in the documented
+     * order — workers first (let in-flight jobs finish or be
+     * returned to the queue), then events (no new events can
+     * arrive once the worker is closed), then queues (the producer
+     * is closed last so any pending `add()` calls had a chance to
+     * land).
+     *
+     * Idempotent: a second call to `onApplicationShutdown` (which
+     * can happen in tests) short-circuits to the first close's
+     * promise rather than racing.
+     */
+    onApplicationShutdown(): Promise<void>;
+    /**
+     * Enqueue a single BullMQ job per step. Returns
+     * `{ kind: 'enqueued', queueJobId }` after the producer has
+     * acknowledged the enqueue. The execution is fire-and-forget:
+     * the launcher resolves the latest persisted `JobExecution`
+     * (which is still in `STARTING`/`STARTED` because the executor
+     * has not run yet).
+     *
+     * The canonical `JobExecution` row is created by the launcher
+     * via `repository.createExecutionAtomic` BEFORE this method is
+     * called (the `executionId` in `ctx` is the result). This
+     * strategy does NOT re-create it; doing so would race the
+     * launcher's atomic create and break the `SELECT ... FOR
+     * UPDATE SKIP LOCKED` invariant.
+     *
+     * Throws if the producer cannot enqueue (Redis down, key
+     * collision, etc.). The launcher re-throws the error to its
+     * caller; the `JobExecution` row remains in `STARTING` —
+     * the host's recovery path (or a manual cleanup) is
+     * responsible for transitioning it.
+     */
+    launch(job: JobDefinition, _params: Record<string, unknown>, ctx: {
+        executionId: string;
+        jobExecutionId: string;
+    }): Promise<{
+        kind: 'enqueued';
+        queueJobId: string;
+    }>;
+    private buildQueue;
+    private buildWorker;
+    private buildQueueEvents;
+    /**
+     * Wire the `QueueEvents` listeners to the configured
+     * `BatchObserver`. Each listener swallows observer errors so
+     * a slow / failing observer cannot poison the BullMQ event
+     * stream.
+     */
+    private attachQueueEventsBridge;
+    private bridgeEvent;
+    /**
+     * Worker entry point. Loads the canonical `JobExecution` from
+     * the repository and the `JobDefinition` from the registry, then
+     * hands the work to `JobExecutor.execute`. All batch semantics
+     * (step dispatch, chunk loop, skip/retry, checkpoint) live in
+     * the executor — this method is a thin bridge.
+     */
+    private processJob;
+    /**
+     * Producer-side connection tuning. The two flags below are
+     * the contract the T18 "Redis-down" test depends on:
+     *
+     *   - `enableOfflineQueue: false`  — a `Queue.add()` against a
+     *     dead Redis MUST throw synchronously rather than buffer
+     *     the command. Without this, BullMQ keeps the command in
+     *     memory and `add()` returns success, breaking the
+     *     "fail fast" guarantee.
+     *   - `maxRetriesPerRequest: 1`    — keep the first `add`
+     *     fast; subsequent reconnects are handled by ioredis
+     *     itself (we do not want BullMQ to block on retries
+     *     during the launcher call).
+     *
+     * BullMQ specifically warns against `maxRetriesPerRequest: null`
+     * on the producer, because the producer does not use blocking
+     * commands. We use `1` for the same reason.
+     */
+    private producerConnectionOptions;
+    /**
+     * Worker-side connection tuning. Two flags that BullMQ
+     * *requires* for blocking workers (per the BullMQ docs):
+     *
+     *   - `maxRetriesPerRequest: null` — the worker's
+     *     `BLPOP` / `BRPOPLPUSH` / `XREADGROUP` commands MUST NOT
+     *     retry per request. A stalled worker surfaces as a
+     *     stall, not a connection error.
+     *   - `enableReadyCheck: false`   — the worker should not
+     *     refuse to start when Redis is in the middle of a
+     *     failover; ioredis reconnects on its own.
+     */
+    private workerConnectionOptions;
+    /**
+     * Close all BullMQ resources in the documented order:
+     * worker → events → queue. Each step is best-effort: a close
+     * error on one resource does not prevent the others from
+     * being closed.
+     */
+    private close;
+}
+//# sourceMappingURL=bullmq-runtime.service.d.ts.map

package/dist/src/bullmq-runtime.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq-runtime.service.d.ts","sourceRoot":"","sources":["../../src/bullmq-runtime.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,sBAAsB,EACtB,qBAAqB,EAEtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAElB,KAAK,aAAa,EAInB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,WAAW,EAAkC,MAAM,kBAAkB,CAAC;AAE5F,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBACa,oBACX,YAAW,kBAAkB,EAAE,sBAAsB,EAAE,qBAAqB;IA2B1E,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAE5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IA/B3B;;;OAGG;IACH,QAAQ,CAAC,IAAI,YAAwB;IAErC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAEhE,oCAAoC;IACpC,OAAO,CAAC,KAAK,CAAsB;IACnC,qCAAqC;IACrC,OAAO,CAAC,MAAM,CAAyC;IACvD,0CAA0C;IAC1C,OAAO,CAAC,WAAW,CAA4B;IAC/C;;;;;;OAMG;IACH,OAAO,CAAC,YAAY,CAA8B;gBAI/B,OAAO,EAAE,2BAA2B,EAEpC,UAAU,EAAE,aAAa,EACzB,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,WAAW,EAExB,QAAQ,GAAE,aAAwD;IAGrF;;;;;;;;;;;;;;OAcG;IACH,sBAAsB,IAAI,IAAI;IAmB9B;;;;;;;;;;;OAWG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5C;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CACV,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GACnD,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAwEpD,OAAO,CAAC,UAAU;IAiClB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,gBAAgB;IAOxB;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;YAiBjB,WAAW;IAsBzB;;;;;;OAMG;YACW,UAAU;IAyBxB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,yBAAyB;IAajC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;OAKG;YACW,KAAK;CAgCpB"}

package/dist/src/bullmq-runtime.service.js

@@ -0,0 +1,441 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get BULLMQ_QUEUE_NAME () {
+        return BULLMQ_QUEUE_NAME;
+    },
+    get BULLMQ_STRATEGY_NAME () {
+        return BULLMQ_STRATEGY_NAME;
+    },
+    get BullmqRuntimeService () {
+        return BullmqRuntimeService;
+    }
+});
+const _common = require("@nestjs/common");
+const _bullmq = require("bullmq");
+const _core = require("@nest-batch/core");
+const _moduleoptions = require("./module-options");
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+const BULLMQ_QUEUE_NAME = 'nest-batch-work';
+const BULLMQ_STRATEGY_NAME = 'bullmq';
+let BullmqRuntimeService = class BullmqRuntimeService {
+    options;
+    repository;
+    registry;
+    jobExecutor;
+    observer;
+    /**
+   * Strategy name. Distinct from the T17 stub's `'bullmq-stub'`
+   * so log lines and boundary reports can tell them apart.
+   */ name = BULLMQ_STRATEGY_NAME;
+    logger = new _common.Logger(BullmqRuntimeService.name);
+    /** BullMQ queue (producer side). */ queue = null;
+    /** BullMQ worker (consumer side). */ worker = null;
+    /** BullMQ QueueEvents stream listener. */ queueEvents = null;
+    /**
+   * Promise-chain lock for the close path. We capture the first
+   * `close()` invocation and short-circuit subsequent ones so a
+   * stray double-shutdown (Nest calls `OnApplicationShutdown`
+   * once, but tests sometimes do their own) does not race the
+   * in-flight close.
+   */ closePromise = null;
+    constructor(options, repository, registry, jobExecutor, observer = new _core.NoopBatchObserver()){
+        this.options = options;
+        this.repository = repository;
+        this.registry = registry;
+        this.jobExecutor = jobExecutor;
+        this.observer = observer;
+    }
+    /**
+   * Nest lifecycle: spin up the queue, worker, and queue-events
+   * after the DI container is fully wired. We do this in
+   * `onApplicationBootstrap` (not `onModuleInit`) so every other
+   * provider — including user-supplied `JobRepository` overrides —
+   * is already instantiated and injectable.
+   *
+   * Worker startup is gated on `options.autoStartWorker`. The
+   * flag exists for launcher-only deployments (e.g. an API
+   * service that only enqueues) and for tests that want to
+   * exercise the producer side in isolation. When the flag is
+   * `false` the queue is still created (so `launch()` can
+   * enqueue), but the worker is not started (no consumer means
+   * the jobs sit in the queue indefinitely).
+   */ onApplicationBootstrap() {
+        this.queue = this.buildQueue();
+        this.queueEvents = this.buildQueueEvents();
+        this.attachQueueEventsBridge();
+        if (this.options.autoStartWorker) {
+            this.worker = this.buildWorker();
+            this.logger.log(`BullmqRuntimeService started: queue="${BULLMQ_QUEUE_NAME}" ` + `worker=auto, keyPrefix="${this.options.connection.keyPrefix}"`);
+        } else {
+            this.logger.log(`BullmqRuntimeService started: queue="${BULLMQ_QUEUE_NAME}" ` + `worker=manual (autoStartWorker=false)`);
+        }
+    }
+    /**
+   * Nest lifecycle: close every BullMQ resource in the documented
+   * order — workers first (let in-flight jobs finish or be
+   * returned to the queue), then events (no new events can
+   * arrive once the worker is closed), then queues (the producer
+   * is closed last so any pending `add()` calls had a chance to
+   * land).
+   *
+   * Idempotent: a second call to `onApplicationShutdown` (which
+   * can happen in tests) short-circuits to the first close's
+   * promise rather than racing.
+   */ async onApplicationShutdown() {
+        if (this.closePromise !== null) {
+            return this.closePromise;
+        }
+        this.closePromise = this.close();
+        return this.closePromise;
+    }
+    // -----------------------------------------------------------------------
+    // IExecutionStrategy
+    // -----------------------------------------------------------------------
+    /**
+   * Enqueue a single BullMQ job per step. Returns
+   * `{ kind: 'enqueued', queueJobId }` after the producer has
+   * acknowledged the enqueue. The execution is fire-and-forget:
+   * the launcher resolves the latest persisted `JobExecution`
+   * (which is still in `STARTING`/`STARTED` because the executor
+   * has not run yet).
+   *
+   * The canonical `JobExecution` row is created by the launcher
+   * via `repository.createExecutionAtomic` BEFORE this method is
+   * called (the `executionId` in `ctx` is the result). This
+   * strategy does NOT re-create it; doing so would race the
+   * launcher's atomic create and break the `SELECT ... FOR
+   * UPDATE SKIP LOCKED` invariant.
+   *
+   * Throws if the producer cannot enqueue (Redis down, key
+   * collision, etc.). The launcher re-throws the error to its
+   * caller; the `JobExecution` row remains in `STARTING` —
+   * the host's recovery path (or a manual cleanup) is
+   * responsible for transitioning it.
+   */ async launch(job, _params, ctx) {
+        if (this.queue === null) {
+            throw new Error(`[BullmqRuntimeService] launch() called before onApplicationBootstrap — ` + 'module is not initialized. Did you forget to import BullmqBatchModule?');
+        }
+        // T8 (partition orchestration): when the start step declares
+        // `partitions.count >= 2`, the strategy enqueues one BullMQ job
+        // per partition (each carrying a distinct `partitionIndex`).
+        // Otherwise (default, `count === 1`, or absent) it preserves
+        // the 0.1.0 "one job per step" behaviour. The validate call
+        // surfaces a misconfiguration (e.g. `count <= 0`) at the
+        // launcher's boundary so the host's caller sees the failure
+        // before the worker is ever asked to process the job.
+        const stepId = job.startStepId;
+        const startStep = job.steps[stepId];
+        const partitions = startStep?.kind === 'chunk' ? startStep.partitions : undefined;
+        (0, _core.validatePartitions)(partitions);
+        const partitionCount = partitions?.count ?? 1;
+        const partitionOrdinals = partitionCount >= 2 ? Array.from({
+            length: partitionCount
+        }, (_, i)=>i) : [
+            undefined
+        ];
+        const jobOpts = {
+            attempts: 3,
+            backoff: {
+                type: 'exponential',
+                delay: 100,
+                jitter: 0.5
+            },
+            removeOnComplete: {
+                count: 100,
+                age: 3600
+            },
+            removeOnFail: {
+                count: 1000
+            }
+        };
+        let lastQueueJobId = null;
+        for (const partitionIndex of partitionOrdinals){
+            const payload = {
+                executionId: ctx.executionId,
+                jobExecutionId: ctx.jobExecutionId,
+                jobId: job.id,
+                stepId,
+                ...partitionIndex !== undefined ? {
+                    partitionIndex
+                } : {}
+            };
+            const enqueued = await this.queue.add(stepId, payload, jobOpts);
+            if (enqueued.id === undefined) {
+                // BullMQ returns a job with `id` undefined only when the
+                // producer cannot reach Redis and the in-memory buffer
+                // (which is disabled by `enableOfflineQueue: false`) is
+                // not available. Surface this as a hard error so the
+                // launcher propagates the failure.
+                throw new Error(`[BullmqRuntimeService] enqueue returned undefined job id (Redis down?)`);
+            }
+            const qid = String(enqueued.id);
+            lastQueueJobId = qid;
+            this.logger.debug(`Enqueued step "${stepId}" for execution ${ctx.executionId}` + (partitionIndex !== undefined ? ` (partition ${partitionIndex}/${partitionCount})` : '') + ` as BullMQ job ${qid}`);
+        }
+        if (lastQueueJobId === null) {
+            // Defensive: the loop above always runs at least once
+            // (partitionOrdinals has length >= 1), so this branch is
+            // unreachable in practice. Keep the explicit throw so a
+            // future refactor cannot quietly enqueue zero jobs.
+            throw new Error(`[BullmqRuntimeService] enqueued zero jobs for execution ${ctx.executionId}`);
+        }
+        return {
+            kind: 'enqueued',
+            queueJobId: lastQueueJobId
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Construction
+    // -----------------------------------------------------------------------
+    buildQueue() {
+        return new _bullmq.Queue(BULLMQ_QUEUE_NAME, {
+            connection: this.producerConnectionOptions(),
+            // `defaultJobOptions` is a defence-in-depth measure. The
+            // strategy already passes per-call `JobsOptions` (with
+            // the T18 retry / remove policy) so this is the fallback
+            // for any code path that calls `queue.add` without
+            // explicit options. Today the only caller is the strategy.
+            defaultJobOptions: {
+                attempts: 3,
+                backoff: {
+                    type: 'exponential',
+                    delay: 100,
+                    jitter: 0.5
+                },
+                removeOnComplete: {
+                    count: 100,
+                    age: 3600
+                },
+                removeOnFail: {
+                    count: 1000
+                }
+            },
+            prefix: this.options.connection.keyPrefix,
+            // Skip waiting for the producer connection to become ready
+            // before returning from `add`. The fail-fast producer
+            // options (see `producerConnectionOptions`) make a dead
+            // Redis surface as a synchronous error on the first `add`,
+            // which is exactly what the "Redis-down" test asserts.
+            skipWaitingForReady: true,
+            // BullMQ 5 calls `client.info()` to discover the server
+            // version + database type at `Queue` construction time. With
+            // `enableOfflineQueue: false` and the ioredis client not
+            // yet ready, the call throws `Stream isn't writeable`.
+            // `skipVersionCheck: true` short-circuits that probe — the
+            // strategy never depends on the version, and a dead Redis
+            // still surfaces synchronously on the first `add()` (per
+            // the fail-fast contract above).
+            skipVersionCheck: true
+        });
+    }
+    buildWorker() {
+        return new _bullmq.Worker(BULLMQ_QUEUE_NAME, async (job)=>this.processJob(job.data), {
+            connection: this.workerConnectionOptions(),
+            prefix: this.options.connection.keyPrefix,
+            concurrency: 1
+        });
+    }
+    buildQueueEvents() {
+        return new _bullmq.QueueEvents(BULLMQ_QUEUE_NAME, {
+            connection: this.workerConnectionOptions(),
+            prefix: this.options.connection.keyPrefix
+        });
+    }
+    /**
+   * Wire the `QueueEvents` listeners to the configured
+   * `BatchObserver`. Each listener swallows observer errors so
+   * a slow / failing observer cannot poison the BullMQ event
+   * stream.
+   */ attachQueueEventsBridge() {
+        if (this.queueEvents === null) return;
+        this.queueEvents.on('completed', ({ jobId })=>{
+            void this.bridgeEvent(_core.BATCH_EVENT.JOB_COMPLETED, {
+                queueJobId: jobId,
+                kind: 'completed'
+            });
+        });
+        this.queueEvents.on('failed', ({ jobId, failedReason })=>{
+            void this.bridgeEvent(_core.BATCH_EVENT.JOB_FAILED, {
+                queueJobId: jobId,
+                kind: 'failed',
+                reason: failedReason
+            });
+        });
+        this.queueEvents.on('stalled', ({ jobId })=>{
+            void this.bridgeEvent(_core.BATCH_EVENT.JOB_FAILED, {
+                queueJobId: jobId,
+                kind: 'stalled'
+            });
+        });
+    }
+    async bridgeEvent(type, data) {
+        try {
+            await this.observer.onEvent({
+                type,
+                timestamp: new Date(),
+                jobExecutionId: String(data['queueJobId'] ?? '<unknown>'),
+                data: data
+            });
+        } catch (err) {
+            this.logger.warn(`BatchObserver threw on event ${type}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Worker processor — delegated to JobExecutor
+    // -----------------------------------------------------------------------
+    /**
+   * Worker entry point. Loads the canonical `JobExecution` from
+   * the repository and the `JobDefinition` from the registry, then
+   * hands the work to `JobExecutor.execute`. All batch semantics
+   * (step dispatch, chunk loop, skip/retry, checkpoint) live in
+   * the executor — this method is a thin bridge.
+   */ async processJob(payload) {
+        const execution = await this.repository.getJobExecution(payload.executionId);
+        if (execution === null) {
+            // The DB row is gone. The launcher pre-created it via
+            // `createExecutionAtomic`; if it's missing now, the host
+            // either deleted it or restored a DB without the row.
+            // Surface as a BullMQ-level failure so the technical
+            // retry / dead-letter path handles it.
+            throw new Error(`[BullmqRuntimeService] JobExecution ${payload.executionId} not found in repository`);
+        }
+        const jobDef = this.registry.get(payload.jobId);
+        // `JobRegistry.get` throws `JobNotFoundError` if the
+        // definition is missing. We let it propagate so BullMQ
+        // records the failure and the dead-letter queue catches
+        // it (a missing job definition is a misconfiguration that
+        // should be loud, not silent).
+        await this.jobExecutor.execute(execution, jobDef);
+    }
+    // -----------------------------------------------------------------------
+    // Connection options
+    // -----------------------------------------------------------------------
+    /**
+   * Producer-side connection tuning. The two flags below are
+   * the contract the T18 "Redis-down" test depends on:
+   *
+   *   - `enableOfflineQueue: false`  — a `Queue.add()` against a
+   *     dead Redis MUST throw synchronously rather than buffer
+   *     the command. Without this, BullMQ keeps the command in
+   *     memory and `add()` returns success, breaking the
+   *     "fail fast" guarantee.
+   *   - `maxRetriesPerRequest: 1`    — keep the first `add`
+   *     fast; subsequent reconnects are handled by ioredis
+   *     itself (we do not want BullMQ to block on retries
+   *     during the launcher call).
+   *
+   * BullMQ specifically warns against `maxRetriesPerRequest: null`
+   * on the producer, because the producer does not use blocking
+   * commands. We use `1` for the same reason.
+   */ producerConnectionOptions() {
+        return {
+            host: this.options.connection.host,
+            port: this.options.connection.port,
+            password: this.options.connection.password,
+            username: this.options.connection.username,
+            db: this.options.connection.db,
+            ...this.options.connection.tls ? {
+                tls: true
+            } : {},
+            enableOfflineQueue: false,
+            maxRetriesPerRequest: 1
+        };
+    }
+    /**
+   * Worker-side connection tuning. Two flags that BullMQ
+   * *requires* for blocking workers (per the BullMQ docs):
+   *
+   *   - `maxRetriesPerRequest: null` — the worker's
+   *     `BLPOP` / `BRPOPLPUSH` / `XREADGROUP` commands MUST NOT
+   *     retry per request. A stalled worker surfaces as a
+   *     stall, not a connection error.
+   *   - `enableReadyCheck: false`   — the worker should not
+   *     refuse to start when Redis is in the middle of a
+   *     failover; ioredis reconnects on its own.
+   */ workerConnectionOptions() {
+        return {
+            host: this.options.connection.host,
+            port: this.options.connection.port,
+            password: this.options.connection.password,
+            username: this.options.connection.username,
+            db: this.options.connection.db,
+            ...this.options.connection.tls ? {
+                tls: true
+            } : {},
+            maxRetriesPerRequest: null,
+            enableReadyCheck: false
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Close
+    // -----------------------------------------------------------------------
+    /**
+   * Close all BullMQ resources in the documented order:
+   * worker → events → queue. Each step is best-effort: a close
+   * error on one resource does not prevent the others from
+   * being closed.
+   */ async close() {
+        if (this.worker !== null) {
+            try {
+                await this.worker.close();
+            } catch (err) {
+                this.logger.warn(`Worker close failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            this.worker = null;
+        }
+        if (this.queueEvents !== null) {
+            try {
+                await this.queueEvents.close();
+            } catch (err) {
+                this.logger.warn(`QueueEvents close failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            this.queueEvents = null;
+        }
+        if (this.queue !== null) {
+            try {
+                await this.queue.close();
+            } catch (err) {
+                this.logger.warn(`Queue close failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            this.queue = null;
+        }
+    }
+};
+BullmqRuntimeService = _ts_decorate([
+    (0, _common.Injectable)(),
+    _ts_param(0, (0, _common.Inject)(_moduleoptions.BULLMQ_MODULE_OPTIONS)),
+    _ts_param(1, (0, _common.Inject)(_core.JOB_REPOSITORY_TOKEN)),
+    _ts_param(4, (0, _common.Optional)()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof ResolvedBullMqModuleOptions === "undefined" ? Object : ResolvedBullMqModuleOptions,
+        typeof JobRepository === "undefined" ? Object : JobRepository,
+        typeof _core.JobRegistry === "undefined" ? Object : _core.JobRegistry,
+        typeof _core.JobExecutor === "undefined" ? Object : _core.JobExecutor,
+        typeof BatchObserver === "undefined" ? Object : BatchObserver
+    ])
+], BullmqRuntimeService);
+
+//# sourceMappingURL=bullmq-runtime.service.js.map