@babelqueue/redis 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,102 +1,372 @@
-import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
 
 /**
  * Redis adapter for BabelQueue.
  *
- * A canonical-envelope **publisher** and a URN-routed **consumer** over the §1 reliable-queue
- * pattern (`RPUSH` to produce, `BRPOPLPUSH` the head to a `<queue>:processing` list to reserve so
- * an in-flight message survives a crash, `LREM` to acknowledge), so a Redis-based Node service
- * speaks the same wire contract as the PHP, Python and Go SDKs.
+ * A canonical-envelope **publisher** and a URN-routed **consumer** over two Redis layouts
+ * (broker-bindings §1, ADR-0033):
+ *
+ * - **`legacy`** (default) — the reliable-queue pattern: `RPUSH` to produce, `LMOVE` the head of
+ *   `<queue>` to `<queue>:processing` to reserve (a Lua script that also writes a recovery deadline
+ *   to `<queue>:processing:deadlines`), and a deadline-gated `LREM` to acknowledge, so an in-flight
+ *   message survives a crash. A **recovery sweep** runs before every reserve and moves a reservation
+ *   whose deadline (`retryAfter`) passed back onto `<queue>`, body untouched. The pop end changed
+ *   from the tail (`BRPOPLPUSH`) to the head (`LMOVE LEFT RIGHT`) so the queue is FIFO, like the Go,
+ *   Python, Java and .NET SDKs.
+ * - **`zset`** — the Laravel-compatible layout (`queues:<q>`, `:delayed`, `:reserved`, `:notify`):
+ *   delayed publish, `retryAfter` recovery through the reserved sorted set, a Lua reserve that
+ *   increments `attempts`, and blocking pop on the `:notify` list. Opt-in via `layout: "zset"`.
  *
  * Redis lists carry **no native metadata** — the list element **is** the canonical envelope JSON,
  * byte-for-byte, with **no wrapping** (unlike `@babelqueue/bullmq`, which uses BullMQ's own job
- * layout). Routing and tracing read the body's `job` / `trace_id`. This is a Node-owned reliable
- * queue; full parity with Laravel's reserved-sorted-set reservation on a *shared* Redis queue is a
- * separate task — for a mixed PHP+Node fleet on one queue, prefer a queue this consumer owns
- * end-to-end.
+ * layout). Routing and tracing read the body's `job` / `trace_id`.
+ *
+ * `ioredis` is an optional peer — you provide the client (an `ioredis` instance satisfies the
+ * adapter structurally).
+ *
+ * **Out-of-band headers (ADR-0028) — legacy layout only.** A Redis list element *is* the canonical
+ * envelope JSON, so there is no native per-message metadata channel. To carry a
+ * {@link HeaderCarrier} (e.g. a W3C `traceparent`) the legacy layout owns a tiny JSON *frame*
+ * distinct from the wire envelope:
+ *
+ *     {"__bq_frame":1,"headers":{"traceparent":"00-…"},"body":"<raw wire envelope>"}
  *
- * This implements §1 of the broker-bindings contract. `ioredis` is an optional peer — you provide
- * the client (an `ioredis` instance satisfies the adapter structurally).
+ * Framing is **opt-in and backward compatible**: only `publish` with a non-empty `headers` carrier
+ * writes a frame; a plain publish stores the **bare** envelope byte-for-byte. The consumer detects
+ * frame-vs-bare by the reserved `__bq_frame` sentinel (a frozen envelope can never carry it).
+ *
+ * **The zset layout never writes a frame (ADR-0033 A3).** A Laravel worker on the same queue would
+ * read the frame as a job, so a header-carrying publish drops the headers and stores the bare
+ * envelope; a `traceparent` is therefore not propagated in this layout (`trace_id` stays in the
+ * envelope, GR-4). GR-1: the wire envelope is never touched.
  */
 
 /** The subset of an ioredis client this adapter calls. */
 interface RedisClient {
     /** Append a value to the tail of a list; returns the new length. */
     rpush(key: string, value: string): Promise<number>;
-    /** Atomically pop the head of `source` and push it to the tail of `destination`, blocking up
-     *  to `timeout` seconds; resolves to the value, or `null` on timeout. */
-    brpoplpush(source: string, destination: string, timeout: number): Promise<string | null>;
-    /** Remove `count` occurrences of `value` from a list; returns how many were removed. */
-    lrem(key: string, count: number, value: string): Promise<number>;
+    /** Add `member` to a sorted set with `score`. */
+    zadd(key: string, score: number | string, member: string): Promise<number | string>;
+    /** Blocking pop from the head of a list for up to `timeout` seconds (fractions need Redis 6+);
+     *  resolves to `[key, value]`, or `null` on timeout. */
+    blpop(key: string, timeout: number): Promise<[string, string] | null>;
+    /** Run a Lua script with `numKeys` keys followed by the arguments. */
+    eval(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;
+    /**
+     * The binary-safe twin of {@link RedisClient.eval} (ioredis `evalBuffer`): string replies come back as
+     * `Buffer`s and `Buffer` arguments are sent byte for byte. Optional for publishing, but required to consume
+     * ({@link RedisQueue.reserve} / {@link RedisConsumer} throw without it): the reserve scripts and the settle
+     * scripts of a body that is not valid UTF-8 use it so the exact stored bytes survive. Invalid UTF-8 is poison
+     * and a poison record never carries a U+FFFD substitution (broker-bindings.md section 1.1, ADR-0035 section 1),
+     * which a string-only `eval` cannot honour.
+     */
+    evalBuffer?(script: string, numKeys: number, ...args: Array<string | number | Buffer>): Promise<unknown>;
 }
 /** The list element for an envelope: the canonical JSON, verbatim — no wrapping (§1). */
 declare function redisValue(envelope: Envelope): string;
+/** The reserved discriminator key + current version of the transport-owned header frame. */
+declare const FRAME_KEY = "__bq_frame";
+/**
+ * The pure produce-side decision: the exact string to `RPUSH` for `body` + `headers`. With no
+ * usable headers it returns `body` verbatim (the **bare** form, so a plain publish and a
+ * header-less publish store byte-identical values); otherwise it returns the transport-owned frame
+ * JSON. Kept pure so the framing decision is unit-testable without a broker.
+ */
+declare function frameValue(body: string, headers: HeaderCarrier | null | undefined): string;
+/**
+ * Interpret a stored Redis list value: `[wire-envelope-body, headers]`. A value is a header frame
+ * iff it is a JSON object carrying the reserved `__bq_frame` sentinel (a frozen wire envelope never
+ * has it); then it yields the unframed body plus the carried headers. Any other value — a bare
+ * envelope, non-JSON, or JSON without the sentinel — is returned verbatim as the body with empty
+ * headers, so older / cross-version queue values consume exactly as before.
+ */
+declare function unframe(value: string): [string, HeaderCarrier];
+/** The out-of-band headers carried by a stored list value (empty for a bare value). */
+declare function headersOf(value: string): HeaderCarrier;
+/** The Redis layout a queue uses. `legacy` is the default `:processing` reliable queue. */
+type RedisLayout = "legacy" | "zset";
+/** The four keys of the Laravel-compatible zset layout. */
+interface ZsetKeys {
+    ready: string;
+    delayed: string;
+    reserved: string;
+    notify: string;
+}
+/** The default key prefix of the zset layout (Laravel's `queues:`). */
+declare const ZSET_KEY_PREFIX = "queues:";
+/**
+ * The zset-layout keys for `queue`: `queues:<q>`, `:delayed`, `:reserved`, `:notify`. In a Redis
+ * Cluster, hash tags (`{orders}`) are the caller's responsibility (put them in `queue`).
+ */
+declare function zsetKeys(queue: string, prefix?: string): ZsetKeys;
+/**
+ * The Lua scripts, exported so a test double can dispatch `eval` on script identity. Every script
+ * is atomic; none of them rewrites a body except the zset reserve (Laravel's `cjson` increment).
+ */
+declare const LUA: {
+    /** KEYS=[q, q:processing, q:processing:deadlines] ARGV=[deadline, token]. Returns the raw body or nil. */
+    readonly legacyReserve: "\nlocal raw = redis.call('LMOVE', KEYS[1], KEYS[2], 'LEFT', 'RIGHT')\nif not raw then return false end\nredis.call('ZADD', KEYS[3], ARGV[1], ARGV[2] .. ':' .. raw)\nreturn raw\n";
+    /** KEYS=[q, q:processing, q:processing:deadlines] ARGV=[floor(now), batch]. Returns the count moved. */
+    readonly legacySweep: "\nlocal batch = tonumber(ARGV[2])\nlocal members\nif batch > 0 then\n  members = redis.call('ZRANGEBYSCORE', KEYS[3], '-inf', ARGV[1], 'LIMIT', 0, batch)\nelse\n  members = redis.call('ZRANGEBYSCORE', KEYS[3], '-inf', ARGV[1])\nend\nlocal moved = 0\nfor _, m in ipairs(members) do\n  if #m >= 34 and string.sub(m, 33, 33) == ':' then\n    local raw = string.sub(m, 34)\n    if redis.call('LREM', KEYS[2], 1, raw) == 1 then\n      redis.call('RPUSH', KEYS[1], raw)\n      moved = moved + 1\n    end\n  end\n  redis.call('ZREM', KEYS[3], m)\nend\nreturn moved\n";
+    /** KEYS=[q:processing, q:processing:deadlines] ARGV=[token, raw]. 1 if the reservation was live. */
+    readonly legacyAck: "\nif redis.call('ZREM', KEYS[2], ARGV[1] .. ':' .. ARGV[2]) == 1 then\n  redis.call('LREM', KEYS[1], 1, ARGV[2])\n  return 1\nend\nreturn 0\n";
+    /** KEYS=[q, q:processing, q:processing:deadlines] ARGV=[token, raw, body]. */
+    readonly legacyRelease: "\nif redis.call('ZREM', KEYS[3], ARGV[1] .. ':' .. ARGV[2]) == 1 then\n  redis.call('LREM', KEYS[2], 1, ARGV[2])\n  redis.call('RPUSH', KEYS[1], ARGV[3])\n  return 1\nend\nreturn 0\n";
+    /** KEYS=[q:processing, q:processing:deadlines, dlq] ARGV=[token, raw, body]. */
+    readonly legacyDeadLetter: "\nif redis.call('ZREM', KEYS[2], ARGV[1] .. ':' .. ARGV[2]) == 1 then\n  redis.call('LREM', KEYS[1], 1, ARGV[2])\n  redis.call('RPUSH', KEYS[3], ARGV[3])\n  return 1\nend\nreturn 0\n";
+    /**
+     * KEYS=[q, q:reserved, q:notify] ARGV=[expiry]. Returns `{job, reserved, flag}` or nil; flag `'1'`
+     * is poison (`reserved == job`), `'0'` a delivered body. Nothing after the LPOP may raise, so the
+     * re-encode is guarded too: lua-cjson decodes `1e999` / `NaN` / `Infinity` but refuses to encode
+     * them, and a bare `cjson.encode` here would lose the already-popped message (broker-bindings
+     * section 1.1, ADR-0033 A1). An unencodable body takes the poison path.
+     */
+    readonly zsetReserve: "\nlocal job = redis.call('LPOP', KEYS[1])\nif not job then return false end\nlocal ok, decoded = pcall(cjson.decode, job)\nif ok and type(decoded) == 'table' and type(decoded['attempts']) == 'number' then\n  decoded['attempts'] = decoded['attempts'] + 1\n  local eok, reserved = pcall(cjson.encode, decoded)\n  if eok and type(reserved) == 'string' then\n    redis.call('ZADD', KEYS[2], ARGV[1], reserved)\n    redis.call('LPOP', KEYS[3])\n    return {job, reserved, '0'}\n  end\nend\nredis.call('ZADD', KEYS[2], ARGV[1], job)\nreturn {job, job, '1'}\n";
+    /** KEYS=[source zset, q, q:notify] ARGV=[floor(now), batch]. Returns the count moved. */
+    readonly zsetMigrate: "\nlocal batch = tonumber(ARGV[2])\nlocal val\nif batch > 0 then\n  val = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1], 'LIMIT', 0, batch)\nelse\n  val = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1])\nend\nif #val > 0 then\n  redis.call('ZREMRANGEBYRANK', KEYS[1], 0, #val - 1)\n  for i = 1, #val, 100 do\n    redis.call('RPUSH', KEYS[2], unpack(val, i, math.min(i + 99, #val)))\n  end\n  for _ = 1, #val do\n    redis.call('RPUSH', KEYS[3], '1')\n  end\nend\nreturn #val\n";
+    /** KEYS=[q, q:notify] ARGV=[body]. */
+    readonly zsetPush: "\nredis.call('RPUSH', KEYS[1], ARGV[1])\nredis.call('RPUSH', KEYS[2], '1')\nreturn 1\n";
+    /** KEYS=[q:reserved] ARGV=[member]. */
+    readonly zsetAck: "\nreturn redis.call('ZREM', KEYS[1], ARGV[1])\n";
+    /** KEYS=[q:delayed, q:reserved] ARGV=[member, score, body]. The ZADD is unconditional. */
+    readonly zsetRelease: "\nredis.call('ZREM', KEYS[2], ARGV[1])\nredis.call('ZADD', KEYS[1], ARGV[2], ARGV[3])\nreturn 1\n";
+    /**
+     * KEYS=[q:reserved, dlq] ARGV=[member, body]. Terminal-failure dead-letter, gated on the ZREM like
+     * the legacy scripts: a late dead-letter whose reservation was already recovered (back on `<q>`)
+     * writes nothing, so the body is never both ready and dead-lettered. A poison reservation uses
+     * `zsetDeadLetterPoison` instead (unconditional, as the contract requires).
+     */
+    readonly zsetDeadLetter: "\nif redis.call('ZREM', KEYS[1], ARGV[1]) == 1 then\n  redis.call('RPUSH', KEYS[2], ARGV[2])\n  return 1\nend\nreturn 0\n";
+    /**
+     * KEYS=[q:reserved, dlq] ARGV=[member, body]. The poison dead-letter (broker-bindings section 1.1):
+     * the SDK MUST write the message to the DLQ and `ZREM` it, unconditionally. Two byte-equal poison
+     * bodies reserved together share one `:reserved` member, so a `ZREM` gate would drop the second
+     * copy without ever writing it.
+     */
+    readonly zsetDeadLetterPoison: "\nredis.call('RPUSH', KEYS[2], ARGV[2])\nredis.call('ZREM', KEYS[1], ARGV[1])\nreturn 1\n";
+};
+/** Options for {@link RedisQueue} (and, through it, {@link RedisPublisher} / {@link RedisConsumer}). */
+interface RedisQueueOptions {
+    /** `"legacy"` (default, the `:processing` reliable queue) or `"zset"` (Laravel-compatible). */
+    layout?: RedisLayout;
+    /**
+     * Seconds before an unacknowledged reservation is recovered (default 90). `null` disables
+     * recovery (the legacy deadline member is written with score `+inf`; the zset `:reserved`
+     * migrate is skipped). A negative or non-finite value is a configuration error. In the zset
+     * layout a recovery counts as an attempt. The handler timeout SHOULD be shorter than this.
+     */
+    retryAfter?: number | null;
+    /** Max items one migrate/sweep moves; `-1` (default) or `0` means no limit. */
+    migrationBatchSize?: number;
+    /** Epoch-seconds clock (fractions allowed); injectable for tests. Default `Date.now() / 1000`. */
+    clock?: () => number;
+    /** Zset key prefix (default `"queues:"`). Ignored by the legacy layout. */
+    keyPrefix?: string;
+    /** Suffix for the legacy reservation list (default `":processing"`). */
+    processingSuffix?: string;
+    /** The dead-letter list (default `<queue>.dlq`); `null` drops on terminal failure. */
+    deadLetterQueue?: string | null;
+    /** Receives the "reservation expired" warning (default `console.warn`). */
+    onWarn?: (message: string) => void;
+}
+/** A legacy reservation: the raw body plus the 32-hex token of its deadline member. */
+interface LegacyReservation {
+    layout: "legacy";
+    raw: string;
+    token: string;
+    /**
+     * The exact stored bytes, set only when they are not valid UTF-8 (so `raw` carries U+FFFD substitutions).
+     * The settle scripts and the poison record use these, never the lossy `raw`.
+     */
+    rawBytes?: Buffer;
+}
+/** A zset reservation: the raw body (what the handler sees) and the exact `:reserved` member. */
+interface ZsetReservation {
+    layout: "zset";
+    raw: string;
+    reserved: string;
+    /** The exact stored bytes of the job / `:reserved` member, set only when they are not valid UTF-8. */
+    rawBytes?: Buffer;
+    reservedBytes?: Buffer;
+    /**
+     * Set when the reserve script flagged the body as poison (undecodable, or `attempts` not a
+     * number): its dead-letter is then unconditional, not gated on the `ZREM`.
+     */
+    poison?: boolean;
+}
+/** Whatever a reserve handed out; pass it back to ack / release / deadLetter. */
+type Reservation = LegacyReservation | ZsetReservation;
+/** The outcome of one non-blocking {@link RedisQueue.reserve}. */
+interface ReserveResult {
+    outcome: "delivered" | "empty" | "poison";
+    /** The raw body the handler sees (absent on `empty`). */
+    raw?: string;
+    /** The reservation handle (absent on `empty`). */
+    reservation?: Reservation;
+    /** Zset only: the delivery count the handler is told (`job.attempts + 1`); absent on poison. */
+    attempts?: number;
+}
+/** A fresh 128-bit reservation token: 32 lowercase hex characters from the OS CSPRNG. */
+declare function newReservationToken(): string;
+/**
+ * The Redis operations behind the publisher and the consumer, one set per layout. The methods are
+ * non-blocking and take their time from the injectable clock, so they can be driven step by step
+ * (the conformance suite does exactly that).
+ */
+declare class RedisQueue {
+    private readonly client;
+    readonly queue: string;
+    readonly layout: RedisLayout;
+    readonly retryAfter: number | null;
+    readonly migrationBatchSize: number;
+    readonly deadLetterKey: string | null;
+    /** The zset keys (zset layout) — also usable to inspect the legacy ready list via `ready`. */
+    readonly keys: ZsetKeys;
+    readonly processingKey: string;
+    readonly deadlinesKey: string;
+    private readonly clock;
+    private readonly warn;
+    constructor(client: RedisClient, queue: string, options?: RedisQueueOptions);
+    /**
+     * Run a script. `binary` (or any `Buffer` argument) selects the client's `evalBuffer`, when it has one,
+     * so replies and arguments are exact bytes.
+     */
+    private run;
+    private nowSeconds;
+    private deadlineScore;
+    /** Append a body to the ready list (zset: also one `:notify` token). */
+    push(body: string): Promise<void>;
+    /**
+     * Schedule a body for `delay` seconds from now: `ZADD <q>:delayed floor(now)+ceil(delay)` with
+     * the body byte-for-byte and no `:notify` token. Zset layout only.
+     */
+    pushDelayed(body: string, delay: number): Promise<void>;
+    /** Zset: move due `:delayed` items, then due `:reserved` ones (skipped if `retryAfter` is null). */
+    migrate(): Promise<number>;
+    private migrateFrom;
+    /** Legacy: move expired reservations back onto the ready list (body untouched). */
+    sweep(): Promise<number>;
+    /** Recovery and migration for the layout; runs before every reserve. */
+    maintain(): Promise<number>;
+    /** One non-blocking reserve, preceded by the layout's migrate / sweep. */
+    reserve(): Promise<ReserveResult>;
+    private reserveLegacy;
+    private reserveZset;
+    /** Acknowledge. Legacy: false (plus a warning) if the reservation had already expired. */
+    ack(reservation: Reservation): Promise<boolean>;
+    /**
+     * Give a reservation back. Legacy: the body (default: `raw`) goes to the ready list, gated on the
+     * deadline member; `delay` is ignored. Zset: one script `ZREM`s the `:reserved` member and `ZADD`s
+     * `<q>:delayed` at `floor(now)+ceil(delay)` with the body (default: `raw` re-encoded with
+     * `attempts + 1`, every other key preserved).
+     */
+    release(reservation: Reservation, delay?: number, body?: string): Promise<boolean>;
+    /** Write `body` (default: `raw`) to the dead-letter list and settle the reservation. */
+    deadLetter(reservation: Reservation, body?: string): Promise<boolean>;
+    private liveOrWarn;
+}
 /** Options for {@link RedisPublisher.publish}. */
 interface PublishOptions {
     traceId?: string;
+    /**
+     * Out-of-band transport headers to carry beside the frozen envelope (ADR-0028) — e.g. a W3C
+     * `traceparent`. Legacy layout: a non-empty carrier RPUSHes a transport-owned frame; an
+     * empty/omitted carrier stays a byte-identical bare publish. **Zset layout: dropped** (ADR-0033
+     * A3) — the bare envelope is written and the `traceparent` is not propagated.
+     */
+    headers?: HeaderCarrier;
+    /**
+     * Deliver after `delay` seconds (`ZADD <q>:delayed floor(now)+ceil(delay)`, no `:notify` token).
+     * Requires `layout: "zset"`; the legacy layout throws {@link BabelQueueError}.
+     */
+    delay?: number;
 }
-/** Sends canonical-envelope messages to one Redis list (§1 reliable-queue). */
+/** Sends canonical-envelope messages to one Redis queue. */
 declare class RedisPublisher {
-    private readonly client;
     private readonly queue;
+    private readonly transport;
     private constructor();
-    /** A publisher over `client`, producing to the list named `queue`. */
-    static create(client: RedisClient, queue: string): RedisPublisher;
-    /** Build + `RPUSH` the canonical envelope; returns the message id (`meta.id`). */
+    /** A publisher over `client`, producing to the queue named `queue`. */
+    static create(client: RedisClient, queue: string, options?: RedisQueueOptions): RedisPublisher;
+    /**
+     * Build + push the canonical envelope; returns the message id (`meta.id`). Legacy layout: a
+     * non-empty `options.headers` pushes a transport-owned frame (ADR-0028), otherwise the bare
+     * envelope byte-for-byte. Zset layout: always the bare envelope (A3); with `options.delay > 0`
+     * it goes to `<q>:delayed` instead of the ready list.
+     */
     publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
 }
-/** A URN handler. Receives the validated envelope and the raw list element. */
-type BabelHandler = (envelope: Envelope, raw: string) => unknown | Promise<unknown>;
+/**
+ * A URN handler. Receives the validated envelope, the raw stored list element, and the out-of-band
+ * {@link HeaderCarrier} carried beside it (empty for a bare value and always empty in the zset
+ * layout). Pass `headers` to `@babelqueue/core/otel`'s `wrapHandler` to link the consumer span as a
+ * child of the producer span (ADR-0028).
+ */
+type BabelHandler = (envelope: Envelope, raw: string, headers: HeaderCarrier) => unknown | Promise<unknown>;
 /** A map of URN → handler. */
 type BabelHandlers = Record<string, BabelHandler>;
 /** Options for {@link RedisConsumer}. */
-interface RedisConsumerOptions {
-    /** Suffix for the per-queue reservation list (default `":processing"`). */
-    processingSuffix?: string;
-    /** Block timeout (seconds) for a single reserve (default 5). */
+interface RedisConsumerOptions extends RedisQueueOptions {
+    /**
+     * How long one {@link RedisConsumer.poll} waits for a message, in seconds (default 5). Legacy:
+     * a sleep-poll (100 ms, doubling, capped at 1 s). Zset: `BLPOP` on `:notify` in slices of at most
+     * 1 s, migrating between slices. `0` or less means one non-blocking attempt.
+     */
     blockTimeout?: number;
     /** Attempts before terminal dead-lettering (default 3). */
     maxTries?: number;
-    /** The dead-letter list (default `<queue>.dlq`); set to `null` to drop on terminal failure. */
-    deadLetterQueue?: string | null;
     /** Strategy for a URN with no handler (default `fail`). */
     unknownUrn?: string;
     /** Called for a non-conformant message, an unmapped URN, or a throwing handler. */
     onError?: (error: unknown, envelope: IncomingEnvelope | null, raw: string) => void;
 }
 /**
- * Consumes a Redis list: reserve the head into `<queue>:processing` (`BRPOPLPUSH`), decode +
- * validate, route to the handler for its URN, then `LREM` it from the reservation list on success.
- * A throwing handler requeues the envelope with `attempts + 1` (at-least-once) up to `maxTries`,
- * then dead-letters to `<queue>.dlq`. Redis has no native delivery count, so `attempts` lives in
- * the body and the runtime owns retry.
+ * Consumes a Redis queue: reserve one message (legacy: `LMOVE` into `<queue>:processing` with a
+ * deadline; zset: the Laravel pop), decode + validate, route to the handler for its URN, then
+ * acknowledge. A throwing handler gives the message back with `attempts + 1` (at-least-once) up to
+ * `maxTries`, then dead-letters to `<queue>.dlq`. Redis has no native delivery count, so `attempts`
+ * lives in the body and the runtime owns retry.
  */
 declare class RedisConsumer {
     private readonly client;
     private readonly queue;
     private readonly handlers;
     private readonly options;
-    private readonly processing;
+    private readonly transport;
     private readonly blockTimeout;
     private readonly maxTries;
-    private readonly dlq;
     private readonly unknownUrn;
     constructor(client: RedisClient, queue: string, handlers: BabelHandlers, options?: RedisConsumerOptions);
+    /** The underlying transport (for diagnostics and tests). */
+    get redisQueue(): RedisQueue;
     /** Reserve + route + settle one message. Returns true if one was handled, false on timeout. */
     poll(): Promise<boolean>;
     /** Poll while `shouldContinue` returns true. */
     run(shouldContinue: () => boolean): Promise<void>;
-    /** Route + settle one reserved element. Exposed for testing. */
-    handle(raw: string): Promise<void>;
+    private dispatch;
+    /**
+     * Route + settle one reserved message. Exposed for testing.
+     *
+     * Legacy layout: `reservation.raw` may be a transport-owned header frame or a bare envelope; it is
+     * unframed first so the envelope is decoded from the verbatim wire body while the carried headers
+     * (e.g. a `traceparent`, ADR-0028) reach the handler. The zset layout is never framed (A3).
+     */
+    handle(reservation: Reservation): Promise<void>;
     private onUnknownUrn;
     private retryOrDeadLetter;
-    /** Republish with `attempts + 1` onto the work list (at-least-once retry). */
+    /** Give the message back with `attempts + 1` (at-least-once retry). */
     private requeue;
     private deadLetter;
-    private deadLetterRaw;
-    /** Remove the element from the reservation list (acknowledge). */
-    private settle;
+    /**
+     * The poison DLQ record of a reservation (ADR-0035, broker-bindings section 1.1): the delivered body (a legacy
+     * header frame is unwrapped first) with a `dead_letter` block of reason `poison`. A strict JSON object is
+     * spliced, anything else is wrapped as `{"raw", "dead_letter"}`.
+     *
+     * A body that is not valid UTF-8 is read as exact bytes (`evalBuffer`, see {@link RedisClient.evalBuffer}) and
+     * kept as stored (no frame is peeled off it), so it lands in the base64 wrapper, never as U+FFFD text.
+     */
+    private poisonRecord;
     private report;
 }
 
-export { type BabelHandler, type BabelHandlers, type PublishOptions, type RedisClient, RedisConsumer, type RedisConsumerOptions, RedisPublisher, redisValue };
+export { type BabelHandler, type BabelHandlers, FRAME_KEY, LUA, type LegacyReservation, type PublishOptions, type RedisClient, RedisConsumer, type RedisConsumerOptions, type RedisLayout, RedisPublisher, RedisQueue, type RedisQueueOptions, type Reservation, type ReserveResult, ZSET_KEY_PREFIX, type ZsetKeys, type ZsetReservation, frameValue, headersOf, newReservationToken, redisValue, unframe, zsetKeys };