ts-server-lib 0.0.48

package/db/TSRQW.js

@@ -0,0 +1,1204 @@
+"use strict";
+/**
+ * TSRQW — Redis Queue Worker (standalone / sentinel / cluster).
+ *
+ * R = Redis · Q = Queue · W = Worker
+ *
+ * Single class unifying queue storage (Redis Streams) + worker lifecycle
+ * (events, retry, dead-letter, cron schedule, thread pool).
+ *
+ * Backend: Redis Streams (XADD / XREADGROUP / XAUTOCLAIM / XACK).
+ *   - All keys hash-tagged → zero CROSSSLOT on any topology.
+ *   - No Lua scripts, no EVALSHA, no SCRIPT LOAD broadcast.
+ *   - Consumer-group model: crashed consumers recovered automatically via XAUTOCLAIM.
+ *   - Built-in dead-letter stream (`{ns:name}:dlq`).
+ *
+ * Performance:
+ *   - send:    1 roundtrip (XADD MAXLEN ~)
+ *   - receive: 1 roundtrip (XREADGROUP); XAUTOCLAIM throttled to reclaimIntervalMs
+ *   - node-redis v5 auto-pipelines concurrent callers → linear throughput scaling
+ *   - XAUTOCLAIM sweeps the PEL cursor-to-cursor (`nextId` fed back as the next `start`),
+ *     per Redis docs — never resets to '0-0' mid-sweep, so a bounded-per-call PEL scan can
+ *     never leave a static, unreachable tail of stale/repeatedly-failing entries behind
+ *     while brand-new messages (a separate XREADGROUP '>' path) keep flowing fine.
+ *
+ * Events: new · ready · completed · retry · exceeded · failed · deleted · error
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSRQW = exports.TSRQWPool = exports.TSRQWEvents = exports.TSRQW_OFFLINE_BUFFER_MAX = void 0;
+exports.applyWorkerDataUpdate = applyWorkerDataUpdate;
+const events_1 = require("events");
+const async_hooks_1 = require("async_hooks");
+const cron_1 = require("cron");
+const os_1 = require("os");
+const worker_threads_1 = require("worker_threads");
+const TSRedis_1 = require("./TSRedis");
+const TSRedisTB_1 = require("./TSRedisTB");
+const TSFifo_1 = require("../utils/TSFifo");
+/**
+ * Ceiling on sends buffered while disconnected, per queue instance.
+ *
+ * Chosen against what it protects, not as a round number: these entries hold the caller's message STRING,
+ * so a few hundred thousand of them is real heap, and the buffer only grows while the broker is unreachable
+ * — precisely when the process has no way to shed it. 10,000 covers any realistic reconnect (seconds to
+ * minutes at normal send rates) while keeping the worst case bounded and observable rather than fatal.
+ * Overflow is counted by {@link TSFifo.dropped} and logged once per drain.
+ */
+exports.TSRQW_OFFLINE_BUFFER_MAX = 10_000;
+/**
+ * Apply a workerData update — the ONE implementation, run identically by the pool and by every worker.
+ *
+ * ## Why it lives here and is stringified into the worker
+ *
+ * The pool keeps `this.wd` (the template every new worker is spawned from) and each worker keeps its own
+ * structured-clone. Both must apply an update the same way, and they used to do it via two hand-written copies
+ * of the same branching — one in TypeScript, one as a concatenated eval string. That is the worst possible
+ * place for a duplicate: a divergence produces workers that disagree with the pool *intermittently*, only for
+ * workers spawned after the drift, which is far harder to find than a plain bug. So the worker embeds this
+ * function's own source via `toString()`, exactly as it already does for the bootstrap callback.
+ *
+ * MUST stay self-contained — no closure over module scope, no imports, nothing from `this`. It is serialised
+ * and evaluated in another realm, so anything it does not receive as an argument does not exist there. The
+ * `__name` shim the worker preamble defines covers the tsx/esbuild wrapper.
+ *
+ * ## Semantics
+ *
+ * - `_wd_merge`: two-level merge — `target[k][sk]` gains `patch[sk]`'s fields when both are plain objects,
+ *   otherwise `target[k]` is assigned outright.
+ * - `_wd_delete`: two-level prune — removes each listed field from `target[k][sk]`.
+ * - Neither present: FULL REPLACE, which is why this returns the (possibly new) target instead of mutating.
+ *   A function cannot rebind its caller's variable, and the worker's `workerData` needs rebinding on replace.
+ * - With either present, remaining non-special keys are copied over as plain assignments.
+ */
+function applyWorkerDataUpdate(target, task) {
+    // Helpers are NESTED, not module-level, so `toString()` carries them into the worker realm with the rest of
+    // the function. Extracting them upward would compile fine and then throw at runtime in the worker only.
+    function mergeNamespaces(out, merge) {
+        for (const k in merge) {
+            const patch = merge[k];
+            const bothObjects = patch && typeof patch === 'object' && out[k] && typeof out[k] === 'object';
+            if (bothObjects) {
+                for (const sk in patch)
+                    out[k][sk] = Object.assign(out[k][sk] || {}, patch[sk]);
+            }
+            else if (patch !== undefined) {
+                out[k] = patch;
+            }
+        }
+    }
+    function pruneNamespaces(out, del) {
+        for (const k in del) {
+            const nsPatch = del[k];
+            if (!nsPatch || typeof nsPatch !== 'object' || !out[k] || typeof out[k] !== 'object')
+                continue;
+            for (const sk in nsPatch) {
+                const fields = nsPatch[sk];
+                if (!Array.isArray(fields) || !out[k][sk] || typeof out[k][sk] !== 'object')
+                    continue;
+                for (const field of fields)
+                    delete out[k][sk][field];
+            }
+        }
+    }
+    const merge = task._wd_merge;
+    const del = task._wd_delete;
+    // Neither present = full replace. A fresh object, so the caller rebinding to the return value cannot alias
+    // the task it was handed.
+    if (!merge && !del)
+        return { ...task };
+    const out = target && typeof target === 'object' ? target : {};
+    if (merge)
+        mergeNamespaces(out, merge);
+    if (del)
+        pruneNamespaces(out, del);
+    for (const k in task) {
+        if (k !== '_wd_updated' && k !== '_wd_merge' && k !== '_wd_delete')
+            out[k] = task[k];
+    }
+    return out;
+}
+// ─── Events ──────────────────────────────────────────────────────────────────
+var TSRQWEvents;
+(function (TSRQWEvents) {
+    TSRQWEvents["new"] = "new";
+    TSRQWEvents["ready"] = "ready";
+    TSRQWEvents["deleted"] = "deleted";
+    TSRQWEvents["completed"] = "completed";
+    TSRQWEvents["retry"] = "retry";
+    TSRQWEvents["exceeded"] = "exceeded";
+    TSRQWEvents["failed"] = "failed";
+    TSRQWEvents["error"] = "error";
+})(TSRQWEvents || (exports.TSRQWEvents = TSRQWEvents = {}));
+// ─── Shared error-detection helpers ─────────────────────────────────────────
+/** Compute derived snapshot fields and health from raw Streams data. */
+function buildSnapshot(raw) {
+    const { msgs, hiddenmsgs, totalrecv, totalsentExact, lag, consumers, dlqDepth, lastDeliveredMs, oldestPendingMs, lastAddedMs } = raw;
+    const backpressure = lag + hiddenmsgs;
+    const consumptionRate = totalsentExact > 0 ? (totalrecv / totalsentExact) * 100 : 100;
+    const dlqRate = totalsentExact > 0 ? (dlqDepth / totalsentExact) * 100 : 0;
+    let health;
+    if (totalsentExact === 0 && dlqDepth === 0)
+        health = 'empty';
+    else if (oldestPendingMs > 0 && Date.now() - oldestPendingMs > 120_000)
+        health = 'stuck';
+    else if (lag > 0)
+        health = 'lagging';
+    else
+        health = 'healthy';
+    return {
+        msgs, hiddenmsgs, totalsent: msgs, totalrecv,
+        lag, consumers, dlqDepth, totalsentExact,
+        lastDeliveredMs, oldestPendingMs, lastAddedMs,
+        backpressure, consumptionRate, dlqRate, health
+    };
+}
+/** True for any error indicating the stream or consumer group no longer exists. */
+function isStreamMissingError(msg) {
+    return msg.includes('NOGROUP') || msg.includes('no such key') || msg.includes('ERR no such key') || msg.includes('WRONGTYPE');
+}
+/** True specifically for NOGROUP (group wiped) — self-heal by resetting `ensured`. */
+function isNoGroupError(msg) {
+    return msg.includes('NOGROUP') || msg.includes('no such key');
+}
+/** Read a Redis info field that may be returned as kebab-case or camelCase. */
+function xField(obj, kebab, camel, fallback) {
+    const o = obj;
+    const v = o?.[kebab] ?? o?.[camel];
+    return (v !== undefined && v !== null ? v : fallback);
+}
+/** Parse the entries array out of an xReadGroup result (first stream only). */
+function parseXReadGroupEntries(result) {
+    return result?.[0]?.messages ?? [];
+}
+// ─── Thread pool ──────────────────────────────────────────────────────────────
+const kTaskInfo = Symbol('kTaskInfo');
+const kWorkerFreedEvent = Symbol('kWorkerFreedEvent');
+/** Set once a worker has been retired, so `error` + `exit` for the same death replace it only once. */
+const kRetired = Symbol('kRetired');
+class TSRQWPoolTask extends async_hooks_1.AsyncResource {
+    callback;
+    timer = null;
+    /** Retry bookkeeping — the payload is retained so a worker fault can re-run it on a fresh thread. */
+    payload = undefined;
+    attempt = 0;
+    /**
+     * A task settles EXACTLY once.
+     *
+     * Without this, a timeout followed by a late worker reply calls `done` twice, and the second
+     * `emitDestroy()` throws from inside a worker `message` handler — turning a recoverable slow parse into
+     * an uncaught exception. The promise in `work()` would ignore the second settle; `AsyncResource` does not.
+     */
+    settled = false;
+    constructor(callback) {
+        super('TSRQWPoolTask');
+        this.callback = callback;
+    }
+    /** Arm the per-task ceiling. `unref` so a pending timeout never keeps the process alive. */
+    arm(timeoutMs, onTimeout) {
+        if (!(timeoutMs > 0))
+            return;
+        this.timer = setTimeout(onTimeout, timeoutMs);
+        this.timer.unref?.();
+    }
+    done(err, result) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.runInAsyncScope(this.callback, null, err, result);
+        this.emitDestroy();
+    }
+    /**
+     * Retire this attempt WITHOUT settling the caller — the payload is being re-run on a fresh worker.
+     *
+     * The callback is deliberately not invoked: it belongs to the retry, not to this attempt. Still tears the
+     * AsyncResource down, or every retried task would leak an async id.
+     */
+    abandon() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.emitDestroy();
+    }
+}
+class TSRQWPool extends events_1.EventEmitter {
+    factor;
+    callback;
+    wd;
+    opts;
+    workers = [];
+    freeWorkers = [];
+    /**
+     * Tasks re-run after a worker fault (see {@link TSRQWPoolOptions.maxTaskRetries}).
+     *
+     * Exposed because a retry is invisible to the caller by design — it resolves normally — so without this a
+     * pool silently masking repeated worker deaths looks identical to a healthy one. Rising here means threads
+     * are dying under load even though nothing is failing.
+     */
+    taskRetries = 0;
+    /**
+     * Accepted-but-unstarted tasks. An O(1) FIFO, not an array: this was drained with `shift()`, which
+     * re-indexes every remaining entry, so a pool that fell behind paid O(N) per completion — quadratic over
+     * the backlog, and worst exactly when the backlog is deepest. Read the depth via `.size`.
+     */
+    tasks = new TSFifo_1.TSFifo();
+    closed = false;
+    constructor(factor = 1, callback, wd, opts) {
+        super();
+        this.factor = factor;
+        this.callback = callback;
+        this.wd = wd;
+        this.opts = opts;
+        // `factor` is a DIVISOR of the core count, NOT a thread count — see TSRQWPoolOptions.threads for
+        // why that distinction has already cost real memory, and prefer `threads` when you want a number.
+        const threads = Math.max(1, Math.floor(opts?.threads ?? (0, os_1.availableParallelism)() / factor));
+        for (let i = 0; i < threads; i++)
+            this._addWorker();
+        this.on(kWorkerFreedEvent, () => {
+            const item = this.tasks.shift();
+            if (item)
+                this._runTask(item.task, item.callback, item.attempt ?? 0);
+        });
+    }
+    work = (data) => {
+        if (this.closed) {
+            return Promise.reject(new Error('TSRQWPool closed'));
+        }
+        return new Promise((resolve, reject) => this._runTask(data, (err, result) => err ? reject(err) : resolve(result)));
+    };
+    /**
+     * Broadcast a workerData update to every live worker AND record it on the pool.
+     *
+     * 🔴 The pool record is the whole point. This used to only `postMessage` to `this.workers`, so an update
+     * reached the workers alive at that instant and nothing else — while new workers are spawned from `this.wd`
+     * (see {@link _addWorker}), which was never touched. The pool grows LAZILY, so any worker created after an
+     * update started with pre-update state and could never catch up.
+     *
+     * Measured in sports-service on 2026-08-10: the AMQP catalog id maps were loaded into the pool exactly once
+     * at boot (5,486 entries across `b`/`o`/`ems`), the parse pool then grew to 5 workers under load, and **100 %
+     * of odds messages arrived with unresolved wire market keys** (mean 112 per message) because the workers
+     * doing the parsing had an empty map. That forced the downstream FIG-3 fallback — a synchronous walk over
+     * every market plus two Redis round trips plus a full per-market object rebuild — on EVERY message, on the
+     * money path, for what is documented as a rare boot-window fallback. It is also self-sustaining: the reload
+     * is fingerprinted on hash length, so with a static catalog it never fires again (466 skips observed).
+     */
+    update(data) {
+        if (this.closed)
+            return;
+        data._wd_updated = Date.now();
+        // Pool first, then live workers: if the broadcast throws, future workers still get the state, and a worker
+        // spawned DURING this call reads an already-updated `this.wd` rather than a stale one.
+        this.wd = applyWorkerDataUpdate(this.wd, data);
+        this.workers.forEach(w => w.postMessage(data));
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const err = new Error('TSRQWPool closed');
+        while (this.tasks.size > 0) {
+            this.tasks.shift().callback(err, null);
+        }
+        for (const w of this.workers) {
+            // QUEUED tasks were already rejected above, but IN-FLIGHT ones were not: closing terminated the
+            // worker and left every caller mid-parse waiting on a reply that could no longer arrive. Shutdown
+            // hung on exactly the work it was waiting to finish.
+            const task = w[kTaskInfo];
+            w[kTaskInfo] = null;
+            w[kRetired] = true;
+            if (task)
+                task.done(err, null);
+            void w.terminate();
+        }
+        this.workers = [];
+        this.freeWorkers = [];
+    }
+    _finishWorkerMessage(worker, result) {
+        const task = worker[kTaskInfo];
+        if (!task)
+            return;
+        const payload = result;
+        if (payload && typeof payload === 'object' && payload.error != null) {
+            const err = payload.error instanceof Error
+                ? payload.error
+                : new Error(String(payload.error));
+            task.done(err, null);
+        }
+        else {
+            task.done(null, result);
+        }
+        worker[kTaskInfo] = null;
+        if (!this.closed) {
+            this.freeWorkers.push(worker);
+            this.emit(kWorkerFreedEvent);
+        }
+    }
+    _runTask(task, callback, attempt = 0) {
+        if (this.closed) {
+            callback(new Error('TSRQWPool closed'), null);
+            return;
+        }
+        if (this.freeWorkers.length === 0) {
+            this.tasks.push({ task, callback, attempt });
+            return;
+        }
+        const worker = this.freeWorkers.pop();
+        const info = new TSRQWPoolTask(callback);
+        // Retained so `_retireWorker` can re-run this exact payload on a replacement thread.
+        info.payload = task;
+        info.attempt = attempt;
+        worker[kTaskInfo] = info;
+        info.arm(this.opts?.taskTimeoutMs ?? 0, () => this._retireWorker(worker, new Error('TSRQWPool task timeout')));
+        // `postMessage` throws on a non-cloneable task. Left unguarded it threw out of the Promise executor in
+        // `work()` — which rejected that one caller, but leaked the worker: still holding `kTaskInfo`, already
+        // popped off `freeWorkers`, never returned. Retiring settles the task and replaces the worker instead.
+        try {
+            worker.postMessage(task);
+        }
+        catch (err) {
+            // `retriable: false` — the payload could not be cloned, and it will not clone any better on a fresh
+            // thread. Retrying here would burn the whole budget re-proving the same failure.
+            this._retireWorker(worker, err, false);
+        }
+    }
+    /**
+     * Settle a worker's in-flight task, drop the worker, and spawn a replacement — exactly once per worker.
+     *
+     * `error` and `exit` both fire for a single death (the error handler terminates, which then emits exit),
+     * so without {@link kRetired} the pool would replace one dead worker twice and grow without bound.
+     */
+    _retireWorker(worker, err, retriable = true) {
+        if (worker[kRetired])
+            return;
+        worker[kRetired] = true;
+        const task = worker[kTaskInfo];
+        worker[kTaskInfo] = null;
+        // Decided BEFORE the worker is torn down, so the branch cannot depend on pool state that teardown
+        // mutates. `closed` blocks a retry outright: close() is already rejecting everything.
+        //
+        // Written as a nested `if` rather than one boolean expression on purpose: `!!task && … && task.attempt`
+        // compiles, but `eslint --fix` rewrites the cast to `Boolean(task)`, which is a CALL and narrows nothing,
+        // so the build then fails on `task` being possibly null. This form cannot be broken by that fix.
+        const maxRetries = this.opts?.maxTaskRetries ?? 0;
+        let willRetry = false;
+        if (task) {
+            willRetry = retriable && !this.closed && task.attempt < maxRetries;
+            // `abandon`, not `done`: the caller is not being settled, this attempt is being replaced by another.
+            if (willRetry)
+                task.abandon();
+            else
+                task.done(err, null);
+        }
+        else if (this.listenerCount('error') > 0) {
+            // Guarded: `EventEmitter.emit('error')` with no listener THROWS. An idle worker dying would then take
+            // the process down from inside an event handler — strictly worse than the failure it reports, and no
+            // caller is waiting on it. Pools that care can subscribe.
+            this.emit('error', err);
+        }
+        const fwIdx = this.freeWorkers.indexOf(worker);
+        if (fwIdx >= 0)
+            this.freeWorkers.splice(fwIdx, 1);
+        const wIdx = this.workers.indexOf(worker);
+        if (wIdx >= 0)
+            this.workers.splice(wIdx, 1);
+        void worker.terminate();
+        // `_addWorker` emits `kWorkerFreedEvent`, which drains whatever queued behind the dead worker.
+        if (!this.closed)
+            this._addWorker();
+        // Re-queued AFTER the replacement exists, so it runs immediately instead of sitting in `tasks` waiting
+        // for a `kWorkerFreedEvent` that has already fired.
+        if (task && willRetry) {
+            this.taskRetries++;
+            this._runTask(task.payload, task.callback, task.attempt + 1);
+        }
+    }
+    _addWorker() {
+        // ONE implementation, embedded by source — see applyWorkerDataUpdate. This replaced ~20 lines of
+        // concatenated eval that duplicated the pool's TypeScript branch-for-branch; the two could drift and the
+        // symptom would be workers disagreeing with the pool only after a respawn. Reassigns `workerData` because
+        // a full replace must rebind it, which a called function cannot do for its caller.
+        let ep = `if (task?._wd_updated) { workerData = (${applyWorkerDataUpdate.toString()})(workerData, task); }`;
+        ep += `else { if (workerData?.debug) { console.log('TSRQWPool:tick', threadId); } fn(task).then(data => pp.postMessage({ data, threadId })).catch(err => { try { pp.postMessage({ error: err }); } catch (_) {} }); }`;
+        let em = `import('worker_threads').then(({ threadId, isMainThread, parentPort: pp, workerData}) => { if(!isMainThread) {`;
+        // tsx/esbuild inject __name() when callback.toString() is embedded in eval workers (e.g. atfeed betradar AMQP).
+        em += `const __name=(t,n)=>t;`;
+        em += `const cb = ${this.callback.toString()};`;
+        em += `cb(workerData).then(fn => pp.on('message', task => {${ep}} )).catch(err => { pp.on('message', task => { try { pp.postMessage({ error: err }); } catch (_) {} }); });`;
+        em += `} });`;
+        if (this.wd?._debug)
+            console.log('TSRQWPool:worker', em);
+        const worker = new worker_threads_1.Worker(em, {
+            eval: true,
+            workerData: this.wd,
+            // Unset means an unbounded worker heap — see TSRQWPoolOptions.resourceLimits.
+            ...(this.opts?.resourceLimits ? { resourceLimits: this.opts.resourceLimits } : {})
+        });
+        worker.on('message', result => {
+            this._finishWorkerMessage(worker, result);
+        });
+        worker.on('error', (err) => {
+            this._retireWorker(worker, err);
+        });
+        // A worker can die WITHOUT emitting `error` — `process.exit()` inside the worker, an OS kill, or an
+        // abrupt termination. That path had no handler at all, so the in-flight task was never settled and the
+        // worker was never replaced: one such death wedged the pool permanently. `exit` also fires after the
+        // `error` handler's own `terminate()`, which `kRetired` absorbs.
+        worker.on('exit', (code) => {
+            if (this.closed)
+                return;
+            this._retireWorker(worker, new Error(`TSRQWPool worker exited unexpectedly (code ${code})`));
+        });
+        this.workers.push(worker);
+        this.freeWorkers.push(worker);
+        this.emit(kWorkerFreedEvent);
+    }
+}
+exports.TSRQWPool = TSRQWPool;
+// ─── TSRQW ────────────────────────────────────────────────────────────────────
+class TSRQW extends events_1.EventEmitter {
+    redis;
+    qname;
+    rawNs;
+    ns;
+    group;
+    consumer;
+    maxLen;
+    attempts;
+    reclaimIntervalMs;
+    /**
+     * Shared cross-process consumption cap for the handler receive paths (see {@link TSRQWOptions.rateLimit}); null
+     * when unconfigured. A {@link TSRedisTBReservation} — the reusable batch/reserve/coalesce layer over `TSRedisTB`.
+     */
+    rlReservation;
+    connected = false;
+    closed = false;
+    /**
+     * Sends accepted while disconnected, replayed on reconnect.
+     *
+     * `TSFifo`, not an array, and BOUNDED — this was the sixth instance of the drain defect this class exists
+     * to remove. It was drained with `shift()` inside `while (length > 0)`, so replaying N buffered messages
+     * cost O(N²) at exactly the worst moment: a reconnect after a long outage is when the buffer is deepest.
+     *
+     * The cap matters more than the drain. It had none, and `send()` pushes unconditionally while the
+     * connection is down, so a broker outage grew this without limit until the process died — trading a
+     * recoverable outage for an unrecoverable one. `reject-new` keeps the OLDEST work: this is a work queue,
+     * so the messages that have already waited longest are the ones a consumer is most likely still waiting
+     * on, and dropping the tail at least preserves ordering of what survives.
+     */
+    offlineBuffer = new TSFifo_1.TSFifo({
+        maxSize: exports.TSRQW_OFFLINE_BUFFER_MAX,
+        overflow: 'reject-new'
+    });
+    delayedTimers = new Map();
+    delaySeq = 0;
+    ensured = false;
+    ensurePromise = null;
+    lastReclaimAt = 0;
+    /**
+     * XAUTOCLAIM scan cursor — persisted across calls. Redis docs: to sweep an entire PEL you
+     * must feed each call's returned `nextId` back in as the next `start` argument; resetting to
+     * '0-0' every call re-scans the same bounded prefix of the PEL forever, so any stale entries
+     * beyond that prefix (or any that keep failing and get re-claimed) are never reached even
+     * though brand-new messages (read via a separate XREADGROUP '>' path) keep flowing fine.
+     * '0-0' here means "start of PEL" — Redis itself returns '0-0' as nextId once a full sweep
+     * completes, so this naturally resets when the PEL is fully covered or empty.
+     */
+    reclaimCursor = '0-0';
+    /** Resolves when the consumer group is ready and the first offline drain completes. */
+    initialized;
+    /** Max delivery attempts before dead-lettering (see {@link TSRQWOptions.attempts}). */
+    get maxAttempts() {
+        return this.attempts;
+    }
+    constructor(redis, options = {}) {
+        super();
+        this.redis = redis;
+        this.qname = options.name ?? 'queue';
+        this.rawNs = options.ns ?? 'tsq';
+        this.ns = this.rawNs + ':';
+        this.group = options.group ?? this.rawNs;
+        this.consumer = options.consumer ?? `${this.rawNs}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+        this.maxLen = options.maxLen ?? 100_000;
+        this.attempts = options.attempts ?? 3;
+        this.reclaimIntervalMs = options.reclaimIntervalMs ?? 2_000;
+        // The reservation derives its own batch from the configured rate; unset ⇒ null ⇒ no throttle.
+        this.rlReservation = options.rateLimit ? new TSRedisTB_1.TSRedisTBReservation(new TSRedisTB_1.TSRedisTB(redis, options.rateLimit)) : null;
+        this.connected = true;
+        this.initialized = this._init();
+    }
+    // ─── Key helpers ─────────────────────────────────────────────────────────────
+    static streamKey(rawNs, name) { return `{${rawNs}:${name}}:stream`; }
+    static dlqKey(rawNs, name) { return `{${rawNs}:${name}}:dlq`; }
+    _streamKey() { return TSRQW.streamKey(this.rawNs, this.qname); }
+    _dlqKey() { return TSRQW.dlqKey(this.rawNs, this.qname); }
+    /** Wrap stream commands with transient cluster retry (TRYAGAIN / CLUSTERDOWN / LOADING). */
+    _cmd(fn) {
+        return (0, TSRedis_1.executeWithClusterRetry)(fn);
+    }
+    // ─── Lifecycle ────────────────────────────────────────────────────────────────
+    async _init() {
+        await this._ensureGroup();
+        if (this.listenerCount(TSRQWEvents.ready) > 0)
+            this.emit(TSRQWEvents.ready);
+        await this._drainOffline();
+    }
+    _ensureGroup() {
+        if (this.ensured)
+            return Promise.resolve();
+        if (!this.ensurePromise) {
+            this.ensurePromise = this._createGroup().finally(() => { this.ensurePromise = null; });
+        }
+        return this.ensurePromise;
+    }
+    async _createGroup() {
+        try {
+            await this._cmd(() => this.redis.xGroupCreate(this._streamKey(), this.group, '$', { MKSTREAM: true }));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes('BUSYGROUP'))
+                throw err;
+        }
+        // Register in the namespace discovery index every time the group is (re)created —
+        // including NOGROUP self-heal after Redis flush. SADD is idempotent so this is safe
+        // to call repeatedly. Swallowed on error so a transient Redis hiccup cannot block startup.
+        await this.redis.sAdd(`{${this.rawNs}:QUEUES}`, this.qname).catch(() => { });
+        this.ensured = true;
+    }
+    /** Reset the ensured flag so the next receive call recreates stream+group.
+     *  Call this when XREADGROUP returns NOGROUP (stream/group wiped, e.g. after Redis flush). */
+    resetEnsured() {
+        this.ensured = false;
+    }
+    /** True after {@link close} — further send/receive calls are no-ops or throw. */
+    isClosed() {
+        return this.closed;
+    }
+    /**
+     * Graceful shutdown: stop delayed sends, optionally remove this consumer from the group.
+     * Does not delete stream data — use {@link purge} for admin reset.
+     */
+    async close(opts) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.connected = false;
+        for (const timer of this.delayedTimers.values())
+            clearTimeout(timer);
+        this.delayedTimers.clear();
+        if (opts?.removeConsumer !== false) {
+            await this.redis.xGroupDelConsumer(this._streamKey(), this.group, this.consumer).catch(() => { });
+        }
+    }
+    _assertOpen() {
+        if (this.closed)
+            throw new Error('TSRQW closed');
+    }
+    // ─── Send — 1 roundtrip ───────────────────────────────────────────────────────
+    /**
+     * Append a message. Returns the stream entry ID for immediate sends;
+     * `delay:{token}` for delayed sends (pass token to {@link cancelDelayedSend});
+     * undefined for buffered (pre-connect) sends.
+     */
+    async send(message, delay = 0) {
+        if (this.closed)
+            return undefined;
+        if (!this.connected) {
+            this.offlineBuffer.push({ message, delay });
+            return;
+        }
+        await this._ensureGroup();
+        if (delay > 0) {
+            const token = ++this.delaySeq;
+            const timer = setTimeout(() => {
+                this.delayedTimers.delete(token);
+                if (!this.closed)
+                    void this._xadd(message);
+            }, delay * 1000);
+            timer.unref?.();
+            this.delayedTimers.set(token, timer);
+            return `delay:${token}`;
+        }
+        const id = await this._xadd(message);
+        if (this.listenerCount(TSRQWEvents.new) > 0)
+            this.emit(TSRQWEvents.new, message);
+        return id;
+    }
+    /**
+     * Cancel a pending delayed send created by {@link send} (token from `delay:{n}` return value).
+     * Returns true when a timer was found and cleared.
+     */
+    cancelDelayedSend(token) {
+        const id = typeof token === 'string'
+            ? Number(token.startsWith('delay:') ? token.slice(6) : token)
+            : token;
+        if (!Number.isFinite(id))
+            return false;
+        const timer = this.delayedTimers.get(id);
+        if (!timer)
+            return false;
+        clearTimeout(timer);
+        this.delayedTimers.delete(id);
+        return true;
+    }
+    _xadd(message) {
+        return this._cmd(() => this.redis.xAdd(this._streamKey(), '*', { p: message }, { TRIM: { strategy: 'MAXLEN', strategyModifier: '~', threshold: this.maxLen } }));
+    }
+    // ─── Receive with handler (hot path) ─────────────────────────────────────────
+    /**
+     * When a shared consumption cap is configured ({@link TSRQWOptions.rateLimit}), block until a token is free
+     * before the message reaches its handler. The message stays in the PEL during the wait (its visibility timeout
+     * still protects it against a crash), so the cap holds fleet-wide: N consumers on the same `scope` collectively
+     * never exceed `perSecond`. No-op — and never allocates — when no limiter is configured.
+     */
+    async _acquireToken() {
+        const r = this.rlReservation;
+        if (r === null)
+            return; // no cap configured — never a blocker
+        for (;;) {
+            if (this.closed)
+                return;
+            const { admitted, retryAfterMs } = await r.acquire();
+            if (admitted)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, Math.max(1, Math.min(retryAfterMs || 100, 1_000))));
+        }
+    }
+    async receiveWithStatus({ handle, visibility: vt = 30 }) {
+        if (this.closed)
+            return { status: 'idle' };
+        await this._ensureGroup();
+        const raw = (await this._tryReclaim(vt)) ?? (await this._readOne());
+        if (!raw)
+            return { status: 'idle' };
+        const { id, message, rc } = raw;
+        const meta = { id, rc, fr: this._msFromId(id) };
+        await this._acquireToken();
+        const ok = await handle(message, meta);
+        if (ok) {
+            await this._ack(id);
+            if (this.listenerCount(TSRQWEvents.completed) > 0)
+                this.emit(TSRQWEvents.completed, { message, meta });
+            if (this.listenerCount(TSRQWEvents.deleted) > 0)
+                this.emit(TSRQWEvents.deleted, { message, meta });
+            return { status: 'completed', message, meta };
+        }
+        if (rc > this.attempts) {
+            await this._moveToDeadLetter(id, message, rc);
+            await this._ack(id);
+            if (this.listenerCount(TSRQWEvents.exceeded) > 0)
+                this.emit(TSRQWEvents.exceeded, { message, meta });
+            if (this.listenerCount(TSRQWEvents.failed) > 0)
+                this.emit(TSRQWEvents.failed, { message, meta });
+            if (this.listenerCount(TSRQWEvents.deleted) > 0)
+                this.emit(TSRQWEvents.deleted, { message, meta });
+            return { status: 'failed', message, meta };
+        }
+        if (this.listenerCount(TSRQWEvents.retry) > 0)
+            this.emit(TSRQWEvents.retry, { message, meta });
+        return { status: 'retry', message, meta };
+    }
+    async receive(opts) {
+        await this.receiveWithStatus(opts);
+    }
+    /**
+     * Blocking receive — XREADGROUP with BLOCK so the connection sleeps until a message
+     * arrives, then wakes immediately. Zero polling overhead vs CronJob polling.
+     *
+     * Preferred consumer pattern for durable/recovery consumers (e.g. integration event
+     * streams). Each call blocks for up to `blockMs` ms. On timeout: returns null (no
+     * message). On message: calls `handler`, ACKs on success, leaves in PEL on failure.
+     *
+     * Run in a `while (running) { await q.receiveBlocking(handler) }` loop per channel.
+     * The loop is woken by Redis as soon as a message is written — no polling overhead.
+     *
+     * @param handler   - Return true to ACK, false to leave in PEL (retry after vt).
+     * @param vt        - Visibility timeout seconds.
+     * @param blockMs   - Max ms to wait for a message (Redis BLOCK option). Default 2 000.
+     *                   Keep short (≤5s) when using a shared cluster client — BLOCK holds
+     *                   the master socket and prevents other commands from executing on it.
+     */
+    async receiveBlocking(handler, vt = 30, blockMs = 2_000) {
+        if (this.closed)
+            return;
+        try {
+            await this._ensureGroup();
+        }
+        catch {
+            return; // group creation failed — caller loop will retry
+        }
+        const reclaimed = await this._tryReclaim(vt);
+        if (reclaimed) {
+            const { id, message, rc } = reclaimed;
+            const meta = { id, rc, fr: this._msFromId(id) };
+            await this._acquireToken();
+            const ok = await handler(message, meta).catch(() => false);
+            if (ok) {
+                await this._ack(id).catch(() => { });
+                return;
+            }
+            if (rc > this.attempts) {
+                await this._moveToDeadLetter(id, message, rc).catch(() => { });
+                await this._ack(id).catch(() => { });
+            }
+            return;
+        }
+        let result;
+        try {
+            result = await this._cmd(() => this.redis.xReadGroup(this.group, this.consumer, [{ key: this._streamKey(), id: '>' }], { COUNT: 1, BLOCK: blockMs }));
+        }
+        catch (err) {
+            if (isNoGroupError((0, TSRedis_1.errMsg)(err)))
+                this.ensured = false; // stream/group wiped — recreate on next call
+            return; // transient error — caller loop will retry
+        }
+        const entries = parseXReadGroupEntries(result);
+        if (!entries.length)
+            return; // BLOCK timeout — no message
+        const e = entries[0];
+        const fr = this._msFromId(e.id);
+        const message = String(e.message['p'] ?? '');
+        await this._acquireToken();
+        const ok = await handler(message, { id: e.id, rc: 1, fr }).catch(() => false);
+        if (ok) {
+            await this._ack(e.id).catch(() => { });
+        }
+    }
+    // ─── Low-level API (adaptive consumers owning their own ack cycle) ────────────
+    /** Pull one raw message without calling a handler or auto-acking. */
+    async receiveRaw(vt = 30) {
+        if (this.closed)
+            return null;
+        await this._ensureGroup();
+        const raw = (await this._tryReclaim(vt)) ?? (await this._readOne());
+        if (!raw)
+            return null;
+        const fr = this._msFromId(raw.id);
+        return { id: raw.id, message: raw.message, rc: raw.rc, fr, sent: fr };
+    }
+    /**
+     * Look up ONE queued message by its stream id WITHOUT consuming it (XRANGE id id) — a non-destructive peek so a
+     * caller can pick one specific queued entry on demand (reconcile/verify a known id) instead of draining FIFO.
+     * O(1): a direct single-entry range read on the stream's radix tree. Returns null when the id is not on the stream
+     * (already acked-and-trimmed, or never existed). Touches neither the consumer group, the PEL, nor delivery order —
+     * existing send/receive/ack behavior is completely unchanged. `rc` is 0 (a peek observes no delivery attempt).
+     */
+    async lookupById(id) {
+        if (this.closed)
+            return null;
+        const rows = await this.redis.xRange(this._streamKey(), id, id, { COUNT: 1 });
+        const row = rows?.[0];
+        if (!row)
+            return null;
+        const fr = this._msFromId(row.id);
+        return { id: row.id, message: String(row.message?.p ?? ''), rc: 0, fr, sent: fr };
+    }
+    /**
+     * Take ONE specific queued message by id OUT of the queue: read it, then remove it — XACK (clears the group PEL if
+     * it was pending; a no-op otherwise) and XDEL (removes it from the stream) — so the normal FIFO consumers will
+     * never deliver or process it. The destructive sibling of {@link lookupById}, for picking a known entry on demand
+     * (cancel a queued item, hand one off, settle it early). O(1). Returns the message, or null if the id is not on the
+     * stream (already taken / acked-and-trimmed). Only the named entry is touched — send/receive/ack for every other
+     * message is unchanged.
+     */
+    async claimById(id) {
+        this._assertOpen();
+        const found = await this.lookupById(id);
+        if (!found)
+            return null;
+        await this._ack(id);
+        await this.redis.xDel(this._streamKey(), id);
+        return found;
+    }
+    /** XACK a message by ID. Returns true when the PEL entry was removed. */
+    async ack(id) {
+        return (await this._ack(id)) > 0;
+    }
+    /**
+     * XACK multiple messages in one roundtrip.
+     * All IDs must belong to this stream — guaranteed by the caller holding them from receiveRaw/receiveRawBatch.
+     * Returns the number of entries removed from the PEL.
+     */
+    async ackBatch(ids) {
+        if (ids.length === 0)
+            return 0;
+        return Number(await this.redis.xAck(this._streamKey(), this.group, ids)) || 0;
+    }
+    /**
+     * Pull up to `count` messages in one roundtrip (XREADGROUP COUNT N).
+     * Reclaim path uses a single XPENDING RANGE for all stale entries — no per-message round-trips.
+     * Returns an empty array when the queue is idle. Caller owns ack/deadLetter for each message.
+     */
+    async receiveRawBatch(vt = 30, count = 10) {
+        if (this.closed)
+            return [];
+        try {
+            return await this._receiveRawBatchImpl(vt, count);
+        }
+        catch (err) {
+            if (isNoGroupError((0, TSRedis_1.errMsg)(err))) {
+                // Stream or consumer group was wiped (e.g. Redis flush). Reset and retry once.
+                this.ensured = false;
+                this.reclaimCursor = '0-0';
+                return this._receiveRawBatchImpl(vt, count);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Build a message from a stream entry. `fr` and `sent` both derive from the id's timestamp — the two
+     * receive paths (reclaim and fresh read) previously restated this mapping independently.
+     */
+    _toMessage(id, payload, rc) {
+        const fr = this._msFromId(id);
+        return { id, message: String(payload ?? ''), rc, fr, sent: fr };
+    }
+    /** One XPENDING RANGE covering every reclaimed id — a single roundtrip for delivery counts. */
+    async _reclaimDeliveryCounts(messages) {
+        const deliveryMap = new Map();
+        const sortedIds = messages.map(m => m.id).sort();
+        try {
+            const details = await this._cmd(() => this.redis.xPendingRange(this._streamKey(), this.group, sortedIds[0], sortedIds[sortedIds.length - 1], messages.length));
+            for (const d of details) {
+                deliveryMap.set(String(d.id ?? ''), Number(d.deliveriesCounter ?? 2));
+            }
+        }
+        catch { /* caller defaults to 2 */ }
+        return deliveryMap;
+    }
+    /** Throttled reclaim — one XAUTOCLAIM COUNT N for all stale entries. Empty until the interval elapses. */
+    async _reclaimStaleBatch(vt, count) {
+        const now = Date.now();
+        if (now - this.lastReclaimAt < this.reclaimIntervalMs)
+            return [];
+        this.lastReclaimAt = now;
+        const claimed = await this._cmd(() => this.redis.xAutoClaim(this._streamKey(), this.group, this.consumer, vt * 1000, this.reclaimCursor, { COUNT: count }));
+        this.reclaimCursor = String(claimed?.nextId ?? '0-0');
+        // XAUTOCLAIM can return null entries for PEL ids whose underlying stream entry was
+        // already trimmed/deleted (see node-redis XAutoClaimRawReply — messages: (Null | Stream)[]).
+        // Redis auto-acks these from the PEL; skip rather than crash on null.id.
+        const messages = (claimed?.messages ?? []).filter((m) => m != null);
+        if (messages.length === 0)
+            return [];
+        const deliveryMap = await this._reclaimDeliveryCounts(messages);
+        return messages.map(e => this._toMessage(e.id, e.message?.['p'], deliveryMap.get(e.id) ?? 2));
+    }
+    /** XREADGROUP COUNT (remaining) for new messages — one roundtrip. */
+    async _readNewBatch(count) {
+        if (count <= 0)
+            return [];
+        const readResult = await this._cmd(() => this.redis.xReadGroup(this.group, this.consumer, [{ key: this._streamKey(), id: '>' }], { COUNT: count }));
+        return parseXReadGroupEntries(readResult).map(e => this._toMessage(e.id, e.message['p'], 1));
+    }
+    async _receiveRawBatchImpl(vt = 30, count = 10) {
+        await this._ensureGroup();
+        // Reclaim first, then top up with fresh messages so one call never exceeds `count`.
+        const results = await this._reclaimStaleBatch(vt, count);
+        results.push(...(await this._readNewBatch(count - results.length)));
+        return results;
+    }
+    /** Move a message to the `:dlq` stream and XACK the source. */
+    async deadLetter(id, message, rc) {
+        this._assertOpen();
+        await this._moveToDeadLetter(id, message, rc);
+        await this._ack(id);
+    }
+    /**
+     * Read dead-letter entries (oldest first). Does not remove them — use {@link replayDlq}
+     * or {@link purgeDlq} for ops.
+     */
+    async receiveDlqBatch(count = 10) {
+        const rows = await this.redis.xRange(this._dlqKey(), '-', '+', { COUNT: count });
+        if (!rows?.length)
+            return [];
+        return rows.map((row) => ({
+            id: row.id,
+            message: String(row.message?.p ?? ''),
+            srcId: String(row.message?.src ?? ''),
+            rc: Number(row.message?.rc ?? 0)
+        }));
+    }
+    /** Re-enqueue one DLQ entry onto the main stream and remove it from the DLQ. */
+    async replayDlq(dlqId) {
+        this._assertOpen();
+        const rows = await this.redis.xRange(this._dlqKey(), dlqId, dlqId, { COUNT: 1 });
+        const row = rows?.[0];
+        if (!row)
+            return undefined;
+        const id = await this._xadd(String(row.message?.p ?? ''));
+        await this.redis.xDel(this._dlqKey(), dlqId);
+        return id;
+    }
+    /** Delete all entries from the dead-letter stream. Returns number of entries removed. */
+    async purgeDlq() {
+        const len = Number(await this.redis.xLen(this._dlqKey()).catch(() => 0)) || 0;
+        if (len > 0)
+            await this.redis.del(this._dlqKey()).catch(() => { });
+        return len;
+    }
+    /**
+     * Admin reset — delete main stream + DLQ keys. Consumer group must be recreated on next use.
+     * Calls {@link resetEnsured} automatically.
+     */
+    async purge() {
+        this._assertOpen();
+        await Promise.all([
+            this.redis.del(this._streamKey()).catch(() => { }),
+            this.redis.del(this._dlqKey()).catch(() => { })
+        ]);
+        this.resetEnsured();
+    }
+    /**
+     * Approximate trim of the main stream (Redis MAXLEN ~). Does not affect the DLQ.
+     */
+    async trimStream(approxMaxLen = 0) {
+        this._assertOpen();
+        await this.redis.xTrim(this._streamKey(), 'MAXLEN', approxMaxLen, { strategyModifier: '~' });
+    }
+    // ─── Internal primitives ─────────────────────────────────────────────────────
+    /** Handle a NOGROUP error: reset ensured flag, re-create group, return null so the caller retries. */
+    async _handleNoGroup() {
+        this.ensured = false;
+        // Stream/group was wiped and is being recreated — the old scan cursor refers to PEL
+        // state that no longer exists; restart the sweep from the beginning.
+        this.reclaimCursor = '0-0';
+        await this._ensureGroup();
+        return null;
+    }
+    /** Throttled reclaim — runs at most once per reclaimIntervalMs. Returns null when skipped or idle. */
+    async _tryReclaim(vt) {
+        const now = Date.now();
+        if (now - this.lastReclaimAt < this.reclaimIntervalMs)
+            return null;
+        this.lastReclaimAt = now;
+        return this._reclaimOne(vt);
+    }
+    async _readOne() {
+        try {
+            const result = await this._cmd(() => this.redis.xReadGroup(this.group, this.consumer, [{ key: this._streamKey(), id: '>' }], { COUNT: 1 }));
+            const entries = parseXReadGroupEntries(result);
+            if (!entries.length)
+                return null;
+            const e = entries[0];
+            return { id: e.id, message: String(e.message['p'] ?? ''), rc: 1 };
+        }
+        catch (err) {
+            if (isNoGroupError((0, TSRedis_1.errMsg)(err)))
+                return this._handleNoGroup();
+            throw err;
+        }
+    }
+    async _reclaimOne(vt) {
+        try {
+            const result = await this._cmd(() => this.redis.xAutoClaim(this._streamKey(), this.group, this.consumer, vt * 1000, this.reclaimCursor, { COUNT: 1 }));
+            this.reclaimCursor = String(result?.nextId ?? '0-0');
+            const messages = result?.messages;
+            const e = messages?.find((m) => m != null);
+            if (!e)
+                return null;
+            const rc = await this._deliveryCount(e.id);
+            return { id: e.id, message: String(e.message?.['p'] ?? ''), rc };
+        }
+        catch (err) {
+            if (isNoGroupError((0, TSRedis_1.errMsg)(err)))
+                return this._handleNoGroup();
+            throw err;
+        }
+    }
+    async _deliveryCount(id) {
+        try {
+            const detail = (await this._cmd(() => this.redis.xPendingRange(this._streamKey(), this.group, id, id, 1)));
+            return Number(detail?.[0]?.deliveriesCounter ?? 2);
+        }
+        catch {
+            return 2;
+        }
+    }
+    _ack(id) {
+        return this._cmd(() => this.redis.xAck(this._streamKey(), this.group, id));
+    }
+    _moveToDeadLetter(id, message, rc) {
+        return this._cmd(() => this.redis.xAdd(this._dlqKey(), '*', { p: message, src: id, rc: String(rc) }, { TRIM: { strategy: 'MAXLEN', strategyModifier: '~', threshold: this.maxLen } }));
+    }
+    _msFromId(id) { return TSRQW._msFromId(id); }
+    // ─── Attributes ──────────────────────────────────────────────────────────────
+    async attributes() {
+        try {
+            const [len, groups] = await Promise.all([
+                this.redis.xLen(this._streamKey()),
+                this.redis.xInfoGroups(this._streamKey())
+            ]);
+            const g = groups.find((x) => x.name === this.group);
+            const totalsent = Number(len) || 0;
+            return {
+                msgs: totalsent,
+                hiddenmsgs: Number(g?.pending ?? 0),
+                totalsent,
+                totalrecv: Number(xField(g, 'entries-read', 'entriesRead', 0))
+            };
+        }
+        catch (err) {
+            if (isStreamMissingError((0, TSRedis_1.errMsg)(err)))
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Rich Streams-native snapshot — for dashboards, platform stats, admin UI.
+     * 4–5 parallel roundtrips (XLEN×2 + XINFO STREAM + XINFO GROUPS + optional XPENDING).
+     * Do NOT call on the hot message path — use attributes() there.
+     */
+    async snapshot() {
+        try {
+            const [len, dlqLen, info, groups] = await Promise.all([
+                this.redis.xLen(this._streamKey()),
+                this.redis.xLen(this._dlqKey()).catch(() => 0),
+                this.redis.xInfoStream(this._streamKey()),
+                this.redis.xInfoGroups(this._streamKey())
+            ]);
+            const g = groups.find((x) => x.name === this.group);
+            const msgs = Number(len) || 0;
+            const dlqDepth = Number(dlqLen) || 0;
+            const totalsentExact = Number(xField(info, 'entries-added', 'entriesAdded', msgs)) || 0;
+            const totalrecv = Number(xField(g, 'entries-read', 'entriesRead', 0));
+            const pendingCount = Number(g?.pending ?? 0);
+            const lag = Number(g?.lag ?? Math.max(0, msgs - totalrecv));
+            const lastDeliveredMs = TSRQW._msFromId(String(xField(g, 'last-delivered-id', 'lastDeliveredId', '0-0')));
+            const lastAddedMs = TSRQW._msFromId(String(xField(info, 'last-generated-id', 'lastGeneratedId', '0-0')));
+            // oldest pending: one extra roundtrip only when there's something in the PEL
+            let oldestPendingMs = 0;
+            if (pendingCount > 0) {
+                try {
+                    const oldest = await this.redis.xPendingRange(this._streamKey(), this.group, '-', '+', 1);
+                    if (oldest?.length > 0)
+                        oldestPendingMs = TSRQW._msFromId(String(oldest[0]?.id ?? '0'));
+                }
+                catch { /* non-fatal — oldest stays 0 */ }
+            }
+            return buildSnapshot({
+                msgs, hiddenmsgs: pendingCount, totalrecv, totalsentExact,
+                lag, consumers: Number(g?.consumers ?? 0), dlqDepth,
+                lastDeliveredMs, oldestPendingMs, lastAddedMs
+            });
+        }
+        catch (err) {
+            if (isStreamMissingError((0, TSRedis_1.errMsg)(err)))
+                return null;
+            throw err;
+        }
+    }
+    // ─── Offline buffer ───────────────────────────────────────────────────────────
+    /**
+     * Replay buffered sends after a reconnect.
+     *
+     * Drains a SNAPSHOT rather than looping on the live buffer, which is a correctness fix, not a tidy-up.
+     * `send()` re-buffers whenever `connected` is false, so the previous `while (length > 0) { shift(); send() }`
+     * livelocked if the connection dropped mid-drain: shift removed an item, send pushed the same item back,
+     * length never reached zero, and the loop span forever re-queueing one message without progress. Taking
+     * the snapshot bounds the work to what was pending when the drain began.
+     *
+     * On a mid-drain disconnect the untried remainder is pushed back IN ORDER and the drain returns; the next
+     * reconnect picks it up. Re-buffering can hit the cap, which is why the drop count is checked here.
+     */
+    async _drainOffline() {
+        const pending = this.offlineBuffer.drain(this.offlineBuffer.size);
+        const droppedBefore = this.offlineBuffer.dropped;
+        for (let i = 0; i < pending.length; i++) {
+            if (!this.connected || this.closed) {
+                for (let j = i; j < pending.length; j++)
+                    this.offlineBuffer.push(pending[j]);
+                break;
+            }
+            await this.send(pending[i].message, pending[i].delay);
+        }
+        const dropped = this.offlineBuffer.dropped - droppedBefore;
+        if (dropped > 0) {
+            // Loud, because it is silent data loss otherwise: `send()` returns undefined for a buffered send, so
+            // a caller cannot tell a queued message from a discarded one.
+            console.error(`[TSRQW] offline buffer overflow — ${dropped} message(s) dropped (cap ${exports.TSRQW_OFFLINE_BUFFER_MAX}). ` +
+                'The broker was unreachable for longer than the buffer covers.');
+        }
+    }
+    // ─── Statics: schedule + thread pool ─────────────────────────────────────────
+    /** List all queue names registered in a namespace (reads from `{ns:QUEUES}` index set). */
+    static async listQueues(redis, ns) {
+        return ((await redis.sMembers(`{${ns}:QUEUES}`)) ?? []).sort();
+    }
+    /**
+     * Read-only aggregate snapshot across ALL consumer groups on a stream — no XGROUP CREATE.
+     * Use from dashboards instead of `new TSRQW(...).snapshot()` to avoid creating phantom groups.
+     *
+     * Aggregation rules (correct for fan-out / multi-group topologies):
+     *  - lag        : max across groups (worst consumer defines backpressure)
+     *  - consumers  : sum across groups (total workers active)
+     *  - totalrecv  : max entries-read across groups (how far the fastest consumer has reached)
+     *  - lastDeliveredMs: max last-delivered-id ms (most-recently-delivered across groups)
+     *  - dlqRate    : dlqDepth / totalsentExact capped at entries-read by the most-advanced group
+     *                 (avoids 100% false-positive when DLQ accumulated across stream recreations)
+     *
+     * Returns null when the stream does not exist.
+     */
+    static async snapshotFromGroups(redis, ns, name) {
+        try {
+            const [len, dlqLen, info, groups] = await Promise.all([
+                redis.xLen(TSRQW.streamKey(ns, name)),
+                redis.xLen(TSRQW.dlqKey(ns, name)).catch(() => 0),
+                redis.xInfoStream(TSRQW.streamKey(ns, name)),
+                redis.xInfoGroups(TSRQW.streamKey(ns, name)).catch(() => [])
+            ]);
+            const gs = groups;
+            const msgs = Number(len) || 0;
+            const dlqDepth = Number(dlqLen) || 0;
+            const totalsentExact = Number(xField(info, 'entries-added', 'entriesAdded', msgs)) || 0;
+            const lastAddedMs = TSRQW._msFromId(String(xField(info, 'last-generated-id', 'lastGeneratedId', '0-0')));
+            // Exclude zero-activity groups from aggregate — phantom/producer-only groups that
+            // never consumed would inflate lag to the full stream length.
+            const activeGs = gs.filter(g => Number(xField(g, 'entries-read', 'entriesRead', 0)) > 0 || Number(g.pending ?? 0) > 0);
+            const effectiveGs = activeGs.length > 0 ? activeGs : gs;
+            let lag = 0, consumers = 0, totalrecv = 0, lastDeliveredMs = 0, hiddenmsgs = 0;
+            for (const g of effectiveGs) {
+                const gEntriesRead = Number(xField(g, 'entries-read', 'entriesRead', 0));
+                lag = Math.max(lag, Number(g.lag ?? Math.max(0, msgs - gEntriesRead)));
+                consumers += Number(g.consumers ?? 0);
+                totalrecv = Math.max(totalrecv, gEntriesRead);
+                lastDeliveredMs = Math.max(lastDeliveredMs, TSRQW._msFromId(String(xField(g, 'last-delivered-id', 'lastDeliveredId', '0-0'))));
+                hiddenmsgs += Number(g.pending ?? 0);
+            }
+            // dlqRate against entries-read by the most-advanced group to avoid false 100% when
+            // DLQ accumulated across stream recreations (entries-added resets, DLQ does not).
+            const dlqBase = totalrecv > 0 ? totalrecv : totalsentExact;
+            const snap = buildSnapshot({ msgs, hiddenmsgs, totalrecv, totalsentExact, lag, consumers, dlqDepth, lastDeliveredMs, oldestPendingMs: 0, lastAddedMs });
+            return { ...snap, consumptionRate: totalsentExact > 0 ? (totalrecv / totalsentExact) * 100 : 100, dlqRate: dlqBase > 0 ? (dlqDepth / dlqBase) * 100 : 0 };
+        }
+        catch (err) {
+            if (isStreamMissingError((0, TSRedis_1.errMsg)(err)))
+                return null;
+            throw err;
+        }
+    }
+    static _msFromId(id) {
+        const ms = parseInt(id.split('-')[0] ?? '0', 10);
+        return isNaN(ms) ? 0 : ms;
+    }
+    static schedule({ onTick = () => { }, onComplete = null, runOnInit = false, cronTime = '*/9 * * * * *', context = null, start = false, timeZone = 'utc' }) {
+        return new cron_1.CronJob(cronTime, onTick, onComplete, start, timeZone, context, runOnInit);
+    }
+    /**
+     * Create a worker pool.
+     *
+     * `factor` is a DIVISOR of the core count, not a thread count — `factor: 1` (the default) means one
+     * worker PER CORE. Pass `opts.threads` when you want an absolute number, and `opts.resourceLimits`
+     * to bound each worker's heap. See {@link TSRQWPoolOptions}.
+     */
+    static worker(cb, factor = 1, wd, opts) {
+        return new TSRQWPool(factor, cb, wd, opts);
+    }
+}
+exports.TSRQW = TSRQW;