ts-server-lib 0.0.48

package/db/TSRQW.d.ts

@@ -0,0 +1,625 @@
+/**
+ * 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
+ */
+import { EventEmitter } from 'events';
+import { AsyncResource } from 'async_hooks';
+import { CronJob } from 'cron';
+import { Worker } from 'worker_threads';
+import { type TSRedisClient } from './TSRedis';
+import { TSRedisTBReservation, type TSRedisTBOptions } from './TSRedisTB';
+import { TSFifo } from '../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.
+ */
+export declare const TSRQW_OFFLINE_BUFFER_MAX = 10000;
+/**
+ * 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.
+ */
+export declare function applyWorkerDataUpdate(target: Record<string, any>, task: Record<string, any>): Record<string, any>;
+export declare enum TSRQWEvents {
+    new = "new",
+    ready = "ready",
+    deleted = "deleted",
+    completed = "completed",
+    retry = "retry",
+    exceeded = "exceeded",
+    failed = "failed",
+    error = "error"
+}
+export type TSRQWStatus = 'idle' | 'completed' | 'retry' | 'failed';
+export type TSRQWHandler = (message: string, meta: {
+    id: string;
+    rc: number;
+    fr: number;
+}) => Promise<boolean | void> | boolean | void;
+export type TSRQWCallback = (data?: unknown) => Promise<(data?: unknown) => Promise<unknown>>;
+/** Payload for {@link TSRQWPool.update} — full replace, {@link _wd_merge} patch, or {@link _wd_delete} prune. */
+export type TSRQWWorkerDataUpdate = Record<string, unknown> & {
+    _wd_updated?: number;
+    /**
+     * Two-level in-worker merge: for each key `k`, merges `patch[sk]` into `workerData[k][sk]`
+     * when both sides are plain objects; otherwise assigns `workerData[k] = patch`.
+     */
+    _wd_merge?: Record<string, Record<string, unknown>>;
+    /**
+     * Two-level in-worker delete: for each key `k` and nested namespace `sk`, removes
+     * `workerData[k][sk][field]` for every `field` in the array. No-op when absent.
+     */
+    _wd_delete?: Record<string, Record<string, string[]>>;
+};
+export interface TSRQWReceiveResult {
+    status: TSRQWStatus;
+    message?: string;
+    meta?: {
+        id: string;
+        rc: number;
+        fr: number;
+    };
+}
+export interface TSRQWAttributes {
+    msgs: number;
+    hiddenmsgs: number;
+    totalsent: number;
+    totalrecv: number;
+}
+/** Raw message shape returned by receiveRaw() and the adaptive consumer API. */
+export interface TSRQWMessage {
+    id: string;
+    message: string;
+    rc: number;
+    fr: number;
+    sent: number;
+}
+/** Dead-letter stream entry — fields written by {@link TSRQW.deadLetter}. */
+export interface TSRQWDlqMessage {
+    id: string;
+    message: string;
+    srcId: string;
+    rc: number;
+}
+/** Queue health state — derived from snapshot fields, no extra Redis calls. */
+export type TSRQWHealth = 'empty' | 'healthy' | 'lagging' | 'stuck';
+/**
+ * Rich Streams-native snapshot — call from dashboards / platform stats.
+ * Extends TSRQWAttributes with fields only Redis Streams can provide.
+ * NOT for the hot path — use attributes() there (2 roundtrips).
+ */
+export interface TSRQWSnapshot extends TSRQWAttributes {
+    /** Messages in stream not yet delivered to this group — real queue backlog. */
+    lag: number;
+    /** Active consumers in this group (0 = no worker connected). */
+    consumers: number;
+    /** Dead-letter queue depth — poison messages accumulating. */
+    dlqDepth: number;
+    /** Exact total-sent counter, unaffected by MAXLEN trim (entries-added, Redis 7.2+). */
+    totalsentExact: number;
+    /** Unix ms of last message delivered to this group (0 = never). */
+    lastDeliveredMs: number;
+    /** Unix ms of oldest in-flight (PEL) message (0 = nothing pending). */
+    oldestPendingMs: number;
+    /** Unix ms of last XADD — 0 if stream has no entries. Idle indicator. */
+    lastAddedMs: number;
+    /** lag + hiddenmsgs — total messages in the system not yet completed. */
+    backpressure: number;
+    /** (totalrecv / totalsentExact) * 100 — % of sent messages consumed. 100 = fully drained. */
+    consumptionRate: number;
+    /** (dlqDepth / totalsentExact) * 100 — % of messages dead-lettered. */
+    dlqRate: number;
+    /**
+     * empty   — no messages ever sent.
+     * healthy — no lag, nothing stuck.
+     * lagging — lag > 0 (messages waiting to be delivered to this group).
+     * stuck   — oldest pending entry has been in-flight > 2 min.
+     */
+    health: TSRQWHealth;
+}
+export interface TSRQWOptions {
+    /** Logical queue name (default: 'queue'). */
+    name?: string;
+    /** Redis key namespace prefix (default: 'tsq'). */
+    ns?: string;
+    /** Max delivery attempts before dead-lettering (default: 3). */
+    attempts?: number;
+    /** Consumer group name (default: ns). One group per service. */
+    group?: string;
+    /** Consumer name (default: auto-generated per process). */
+    consumer?: string;
+    /** Approximate stream MAXLEN (default: 100_000). */
+    maxLen?: number;
+    /** How often to run XAUTOCLAIM for stale-consumer recovery (ms, default: 2_000). */
+    reclaimIntervalMs?: number;
+    /**
+     * Optional SHARED consumption cap for the HANDLER-based receive paths ({@link TSRQW.receive} /
+     * {@link TSRQW.receiveWithStatus} / {@link TSRQW.receiveBlocking}). When set, a token is drawn from one
+     * cross-process {@link TSRedisTB} (keyed by `scope`) before each message reaches its handler, so N consumers on
+     * the same `scope` collectively never exceed `perSecond` — the fleet-wide equivalent of a per-process limiter,
+     * the place to encode an upstream provider's per-operator cap. Tokens are claimed in batches and reserved
+     * locally (concurrent acquirers coalesce onto one round trip), so most messages are admitted with NO round trip.
+     *
+     * The LOW-LEVEL raw API ({@link TSRQW.receiveRaw} / {@link TSRQW.receiveRawBatch}) does NOT apply this — those
+     * consumers own their own ack cycle AND their own pacing (e.g. the adaptive per-driver limiter). Unset ⇒ no
+     * throttle (unchanged behavior). Fail-open: with no Redis or `perSecond <= 0` the bucket grants freely, so the
+     * queue never stalls on it — the limiter is never a blocker when unset.
+     */
+    rateLimit?: TSRedisTBOptions;
+}
+declare const kTaskInfo: unique symbol;
+/** Set once a worker has been retired, so `error` + `exit` for the same death replace it only once. */
+declare const kRetired: unique symbol;
+interface WorkerWithTaskInfo extends Worker {
+    [kTaskInfo]?: TSRQWPoolTask | null;
+    [kRetired]?: boolean;
+}
+declare class TSRQWPoolTask extends AsyncResource {
+    callback: (err: Error | null, result: unknown) => void;
+    private timer;
+    /** Retry bookkeeping — the payload is retained so a worker fault can re-run it on a fresh thread. */
+    payload: unknown;
+    attempt: number;
+    /**
+     * 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.
+     */
+    private settled;
+    constructor(callback: (err: Error | null, result: unknown) => void);
+    /** Arm the per-task ceiling. `unref` so a pending timeout never keeps the process alive. */
+    arm(timeoutMs: number, onTimeout: () => void): void;
+    done(err: Error | null, result: unknown): void;
+    /**
+     * 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(): void;
+}
+/**
+ * Explicit pool sizing and per-worker memory ceiling.
+ *
+ * ### Why `threads` exists (a measured incident, 2026-08-05)
+ *
+ * `factor` is a DIVISOR: `threads = availableParallelism() / factor`. So `factor: 1` — which reads like
+ * "one worker" and is also the DEFAULT — means "one worker per core". On a 20-core host that is 20
+ * threads. `TSRequest`'s XML parse pool passed `1` with the comment "the pool below is size 1" and got
+ * 20 workers, each with an unbounded V8 heap, each parsing ~1 MB schedule documents: RSS climbed
+ * 1065 MB → 2015 MB while the main-thread heap stayed flat and GC'd normally.
+ *
+ * That signature is easy to misread as a leak in the wrong place, because `process.memoryUsage().heapUsed`
+ * covers the MAIN thread only — a worker's heap shows up exclusively in RSS.
+ *
+ * Pass `threads` when you want a count. `factor` stays for callers that genuinely want to scale with the
+ * host (`sports-betting`'s system-combination pool, atfeed's AMQP parse pool) and those pass a real
+ * divisor deliberately.
+ */
+export interface TSRQWPoolOptions {
+    /** Absolute worker count. Takes precedence over `factor`. Use this unless you mean "per N cores". */
+    threads?: number;
+    /**
+     * Per-worker V8 limits, forwarded to `new Worker`. Unset means UNBOUNDED: V8 grows the worker's old
+     * generation and does not return pages to the OS, so a long-lived pool ratchets RSS for the process
+     * lifetime.
+     *
+     * Deliberately NOT defaulted here. A blanket ceiling would silently apply to pools whose workloads
+     * were never measured (combinatorial bet-system generation can legitimately want hundreds of MB), and
+     * exceeding it terminates the worker. Opt in per pool, with a number you can justify.
+     *
+     * Exceeding the limit is survivable by design: Node emits `ERR_WORKER_OUT_OF_MEMORY` as a worker
+     * `error`, which rejects the in-flight task and replaces the worker (see `_addWorker`'s error handler).
+     * Callers that fall back on task failure — `parseXmlDocument` re-parses inline — degrade rather than
+     * break.
+     */
+    resourceLimits?: {
+        maxOldGenerationSizeMb?: number;
+        maxYoungGenerationSizeMb?: number;
+        codeRangeSizeMb?: number;
+        stackSizeMb?: number;
+    };
+    /**
+     * Per-task ceiling in ms. Unset (or 0) keeps the original behaviour: a task waits forever.
+     *
+     * ### Why this exists (2026-08-16)
+     *
+     * A task settled only on a worker `message` or a worker `error`. Any path that produced NEITHER left the
+     * caller's promise pending forever, the worker permanently marked busy, and — because `_runTask` pops the
+     * worker off `freeWorkers` — the pool stuck at zero free workers, queueing every later task on a
+     * `kWorkerFreedEvent` that could no longer fire. Silent and unrecoverable.
+     *
+     * At least one such path is reachable from the worker entry point itself: the reply is posted as
+     * `fn(task).then(d => pp.postMessage(...)).catch(err => { try { pp.postMessage({error: err}) } catch (_) {} })`,
+     * so a non-cloneable RESULT falls into the catch, and a non-cloneable ERROR is then swallowed by the empty
+     * inner catch — nothing is ever posted back.
+     *
+     * A timeout converts that into an ordinary task failure, which callers already handle:
+     * `parseXmlDocument` re-parses inline. Set it to a value comfortably above the worst legitimate task, since
+     * firing it also RETIRES the worker — a worker that missed a deadline has unknown state.
+     */
+    taskTimeoutMs?: number;
+    /**
+     * How many times to re-run a task whose WORKER faulted. Default 0 — the historical behaviour, where such a
+     * task is rejected and the work item is lost.
+     *
+     * ### The distinction this relies on
+     *
+     * The pool already separates two unrelated failures, and only one of them is worth retrying:
+     *
+     * - **worker fault** — the thread died, timed out, or vanished. The payload was never the problem, so the
+     *   same input on a fresh worker is expected to succeed. Routed through `_retireWorker`. RETRIABLE.
+     * - **task error** — the handler rejected, or returned something that could not be cloned. The worker is
+     *   alive and reports it as a `{ error }` message. Re-running it fails identically. NOT retriable, and it
+     *   never reaches the retry path.
+     *
+     * ### Leave it at 0 unless the task is idempotent
+     *
+     * A retry re-executes the handler. For a pure function — XML parsing, combinatorial generation — that is
+     * strictly better than dropping the item. For anything with side effects it can double them, which is worse
+     * than the loss it prevents. That is why this is opt-in per pool rather than a default.
+     *
+     * Bounded on purpose: a task that faults every time (a payload that reliably OOMs the worker) would
+     * otherwise respawn threads forever. After the last attempt the task rejects exactly as it does today.
+     */
+    maxTaskRetries?: number;
+}
+export declare class TSRQWPool extends EventEmitter {
+    factor: number;
+    callback: TSRQWCallback;
+    wd?: unknown;
+    opts?: TSRQWPoolOptions | undefined;
+    workers: WorkerWithTaskInfo[];
+    freeWorkers: WorkerWithTaskInfo[];
+    /**
+     * 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: number;
+    /**
+     * 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: TSFifo<{
+        task: unknown;
+        callback: (err: Error | null, result: unknown) => void;
+        attempt?: number;
+    }>;
+    private closed;
+    constructor(factor: number | undefined, callback: TSRQWCallback, wd?: unknown, opts?: TSRQWPoolOptions | undefined);
+    work: (data: unknown) => Promise<unknown>;
+    /**
+     * 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: TSRQWWorkerDataUpdate): void;
+    close(): void;
+    private _finishWorkerMessage;
+    private _runTask;
+    /**
+     * 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.
+     */
+    private _retireWorker;
+    private _addWorker;
+}
+export declare class TSRQW extends EventEmitter {
+    protected readonly redis: TSRedisClient;
+    protected readonly qname: string;
+    protected readonly rawNs: string;
+    protected readonly ns: string;
+    protected readonly group: string;
+    protected readonly consumer: string;
+    protected readonly maxLen: number;
+    protected readonly attempts: number;
+    protected readonly reclaimIntervalMs: number;
+    /**
+     * 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`.
+     */
+    protected readonly rlReservation: TSRedisTBReservation | null;
+    connected: boolean;
+    private closed;
+    /**
+     * 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.
+     */
+    private offlineBuffer;
+    private delayedTimers;
+    private delaySeq;
+    private ensured;
+    private ensurePromise;
+    private lastReclaimAt;
+    /**
+     * 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.
+     */
+    private reclaimCursor;
+    /** Resolves when the consumer group is ready and the first offline drain completes. */
+    readonly initialized: Promise<void>;
+    /** Max delivery attempts before dead-lettering (see {@link TSRQWOptions.attempts}). */
+    get maxAttempts(): number;
+    constructor(redis: TSRedisClient, options?: TSRQWOptions);
+    static streamKey(rawNs: string, name: string): string;
+    static dlqKey(rawNs: string, name: string): string;
+    private _streamKey;
+    private _dlqKey;
+    /** Wrap stream commands with transient cluster retry (TRYAGAIN / CLUSTERDOWN / LOADING). */
+    private _cmd;
+    private _init;
+    private _ensureGroup;
+    private _createGroup;
+    /** 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(): void;
+    /** True after {@link close} — further send/receive calls are no-ops or throw. */
+    isClosed(): boolean;
+    /**
+     * Graceful shutdown: stop delayed sends, optionally remove this consumer from the group.
+     * Does not delete stream data — use {@link purge} for admin reset.
+     */
+    close(opts?: {
+        removeConsumer?: boolean;
+    }): Promise<void>;
+    private _assertOpen;
+    /**
+     * 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.
+     */
+    send(message: string, delay?: number): Promise<string | undefined>;
+    /**
+     * 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: number | string): boolean;
+    private _xadd;
+    /**
+     * 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.
+     */
+    private _acquireToken;
+    receiveWithStatus({ handle, visibility: vt }: {
+        handle: TSRQWHandler;
+        visibility?: number;
+    }): Promise<TSRQWReceiveResult>;
+    receive(opts: {
+        handle: TSRQWHandler;
+        visibility?: number;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    receiveBlocking(handler: (message: string, meta: {
+        id: string;
+        rc: number;
+        fr: number;
+    }) => Promise<boolean>, vt?: number, blockMs?: number): Promise<void>;
+    /** Pull one raw message without calling a handler or auto-acking. */
+    receiveRaw(vt?: number): Promise<TSRQWMessage | null>;
+    /**
+     * 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).
+     */
+    lookupById(id: string): Promise<TSRQWMessage | null>;
+    /**
+     * 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.
+     */
+    claimById(id: string): Promise<TSRQWMessage | null>;
+    /** XACK a message by ID. Returns true when the PEL entry was removed. */
+    ack(id: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    ackBatch(ids: string[]): Promise<number>;
+    /**
+     * 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.
+     */
+    receiveRawBatch(vt?: number, count?: number): Promise<TSRQWMessage[]>;
+    /**
+     * 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.
+     */
+    private _toMessage;
+    /** One XPENDING RANGE covering every reclaimed id — a single roundtrip for delivery counts. */
+    private _reclaimDeliveryCounts;
+    /** Throttled reclaim — one XAUTOCLAIM COUNT N for all stale entries. Empty until the interval elapses. */
+    private _reclaimStaleBatch;
+    /** XREADGROUP COUNT (remaining) for new messages — one roundtrip. */
+    private _readNewBatch;
+    private _receiveRawBatchImpl;
+    /** Move a message to the `:dlq` stream and XACK the source. */
+    deadLetter(id: string, message: string, rc: number): Promise<void>;
+    /**
+     * Read dead-letter entries (oldest first). Does not remove them — use {@link replayDlq}
+     * or {@link purgeDlq} for ops.
+     */
+    receiveDlqBatch(count?: number): Promise<TSRQWDlqMessage[]>;
+    /** Re-enqueue one DLQ entry onto the main stream and remove it from the DLQ. */
+    replayDlq(dlqId: string): Promise<string | undefined>;
+    /** Delete all entries from the dead-letter stream. Returns number of entries removed. */
+    purgeDlq(): Promise<number>;
+    /**
+     * Admin reset — delete main stream + DLQ keys. Consumer group must be recreated on next use.
+     * Calls {@link resetEnsured} automatically.
+     */
+    purge(): Promise<void>;
+    /**
+     * Approximate trim of the main stream (Redis MAXLEN ~). Does not affect the DLQ.
+     */
+    trimStream(approxMaxLen?: number): Promise<void>;
+    /** Handle a NOGROUP error: reset ensured flag, re-create group, return null so the caller retries. */
+    private _handleNoGroup;
+    /** Throttled reclaim — runs at most once per reclaimIntervalMs. Returns null when skipped or idle. */
+    private _tryReclaim;
+    private _readOne;
+    private _reclaimOne;
+    private _deliveryCount;
+    private _ack;
+    private _moveToDeadLetter;
+    private _msFromId;
+    attributes(): Promise<TSRQWAttributes | null>;
+    /**
+     * 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.
+     */
+    snapshot(): Promise<TSRQWSnapshot | null>;
+    /**
+     * 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.
+     */
+    private _drainOffline;
+    /** List all queue names registered in a namespace (reads from `{ns:QUEUES}` index set). */
+    static listQueues(redis: TSRedisClient, ns: string): Promise<string[]>;
+    /**
+     * 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 snapshotFromGroups(redis: TSRedisClient, ns: string, name: string): Promise<TSRQWSnapshot | null>;
+    static _msFromId(id: string): number;
+    static schedule({ onTick, onComplete, runOnInit, cronTime, context, start, timeZone }: {
+        onTick?: () => void;
+        onComplete?: (() => void) | null;
+        runOnInit?: boolean;
+        cronTime?: string;
+        context?: unknown;
+        start?: boolean;
+        timeZone?: string;
+    }): CronJob;
+    /**
+     * 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: TSRQWCallback, factor?: number, wd?: unknown, opts?: TSRQWPoolOptions): TSRQWPool;
+}
+export {};