@babelqueue/pulsar 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -20,7 +20,7 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  *     });
  *     const consumer = new PulsarConsumer(sub, {
  *       "urn:babel:orders:created": async (env) => { ... },
- *     });
+ *     }, { subscriptionType: "Shared" }); // declare it (or pass `client` together with `topic`): see PulsarConsumerOptions
  *     await consumer.run();
  *
  * This implements §5 of the broker-bindings contract: the canonical envelope is the message
@@ -28,7 +28,12 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /
  * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);
  * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is
- * redelivered (at-least-once) and `getRedeliveryCount()` is incremented. Per §5.2 / §5.7 the
+ * redelivered (at-least-once) and `getRedeliveryCount()` is incremented — up to `maxAttempts`
+ * deliveries (default 3, ADR-0036): the message that exhausts them is written to `<queue>.dlq`
+ * (when a `deadLetterProducer` is given) or acknowledged and dropped. A body that does not decode
+ * into an envelope (including an object with no valid identity) is poison: it never reaches a
+ * handler, and with dead-lettering on it is recorded in `<queue>.dlq` in the ADR-0035 shape without
+ * retry. Per §5.2 / §5.7 the
  * consumer routes on the `bq-job` property (the body's URN is used only when the property is
  * absent or blank) and takes `attempts` from the authoritative `bq-attempts` property (the
  * body's value is used only when the property is absent or not a plain ASCII-decimal integer
@@ -79,10 +84,27 @@ interface PulsarReceivedMessage {
  * satisfies it structurally; a fake satisfies it in tests.
  */
 interface PulsarConsumerClient {
+    /**
+     * The topic the subscription reads. pulsar-client's `Consumer` has **no** such method (only its `Producer`
+     * does), so with it the topic comes from the {@link PulsarConsumerOptions.topic} option; a custom
+     * subscription wrapper may provide this to make `topic` unnecessary.
+     */
+    getTopic?(): string;
     receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;
     acknowledge(message: PulsarReceivedMessage): Promise<void> | void;
     negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;
 }
+/**
+ * The subset of the Pulsar client this adapter calls to build its own retry producer. A `Client` from
+ * `pulsar-client` satisfies it structurally.
+ */
+interface PulsarClientLike {
+    createProducer(config: {
+        topic: string;
+    }): Promise<PulsarProducer>;
+}
+/** The subscription type, as pulsar-client names it (`Key_Shared` is accepted as an alias of `KeyShared`). */
+type PulsarSubscriptionType = "Exclusive" | "Shared" | "Failover" | "KeyShared" | "Key_Shared";
 /**
  * Project the envelope's contract fields onto native Pulsar message properties
  * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus
@@ -153,26 +175,118 @@ interface PulsarConsumerOptions {
      * rejects with) is swallowed — it never changes how the message is handled or acknowledged.
      */
     onRoutingMismatch?: (propertyUrn: string, bodyUrn: string, envelope: IncomingEnvelope) => unknown;
+    /**
+     * The total number of deliveries a message gets, the first included (default 3; `1` = no retry;
+     * ADR-0036 decision 1). A failing handler, an unmapped URN without {@link onUnknownUrn} and a poison
+     * body with dead-lettering off are retried (`negativeAcknowledge`) while `reconciled attempts + 1`
+     * is below it; the delivery that reaches it is dead-lettered (when {@link deadLetterProducer} is
+     * set) or acknowledged and dropped. Must be an integer of at least 1.
+     */
+    maxAttempts?: number;
+    /**
+     * A producer on the dead-letter topic (by convention `<queue>.dlq`). Dead-lettering is on exactly
+     * when it is set; the SDK does not use Pulsar's native `DeadLetterPolicy`. The original message is
+     * acknowledged only after the record was sent; a failed send leaves it negatively acknowledged so
+     * it is redelivered and the write is tried again.
+     */
+    deadLetterProducer?: PulsarProducer;
+    /**
+     * A producer on the consumer's **own** topic. A retry re-publishes the message to that topic with
+     * `bq-attempts` (and the body's `attempts`) raised to the counted value and then acknowledges the
+     * original — the Go model. The count then lives in the message itself, so the bound holds on every
+     * subscription type. Optional when {@link client} is given (the consumer builds the producer itself);
+     * a failed re-publish leaves the original negatively acknowledged (never lost).
+     *
+     * Without a producer or a client a retry is a `negativeAcknowledge`, which advances the native
+     * redelivery count only on `Shared` / `Key_Shared`: on `Exclusive` / `Failover` it stays 0 and the retry
+     * would never reach `maxAttempts`, so that combination is rejected at construction (see
+     * {@link subscriptionType}).
+     */
+    retryProducer?: PulsarProducer;
+    /**
+     * The Pulsar client the consumer builds its retry producer from, lazily on the first retry, on
+     * {@link topic}. Needs `topic` (pulsar-client's `Consumer` cannot tell its topic). Ignored when
+     * {@link retryProducer} is given.
+     */
+    client?: PulsarClientLike;
+    /**
+     * The topic the retry producer is created on — the topic the consumer reads. Required together with
+     * {@link client} (a pulsar-client `Consumer` has no `getTopic()`); a subscription wrapper that provides
+     * `getTopic()` makes it optional.
+     */
+    topic?: string;
+    /**
+     * The subscription type the consumer was created with. `Exclusive` and `Failover` cannot bound a
+     * nack-driven retry (a negative acknowledgement does not advance the redelivery count there), so with
+     * `maxAttempts > 1` they require a {@link retryProducer} or a {@link client}. **Not declaring it counts as
+     * `Exclusive`** (pulsar-client's own default, and the fail-closed choice): without a `retryProducer` or a
+     * `client` the constructor throws `BabelQueueError`. Declare `"Shared"` or `"Key_Shared"` to keep the
+     * `negativeAcknowledge` retry without a producer.
+     */
+    subscriptionType?: PulsarSubscriptionType;
+    /**
+     * The queue name written to `dead_letter.original_queue` of a poison record (a decodable envelope
+     * uses its own `meta.queue`). Defaults to the {@link deadLetterProducer} topic without its `.dlq`
+     * suffix.
+     */
+    queue?: string;
+    /** Receives the "message dropped" and "dead-letter write failed" warnings (default `console.warn`). */
+    onWarn?: (message: string) => void;
 }
+/** Default total number of deliveries (ADR-0036 decision 1). */
+declare const DEFAULT_MAX_ATTEMPTS = 3;
 /**
  * Receives from a Pulsar subscription, decodes + validates each message, routes it to the
  * handler for its URN, and acknowledges it on success. A throwing handler
  * `negativeAcknowledge`s the message — the broker redelivers it and increments
- * `getRedeliveryCount()` (at-least-once). Routing uses the `bq-job` property (body URN as the
- * fallback); `attempts` is the `bq-attempts` property (body value as the fallback) reconciled to
- * `max(.., getRedeliveryCount())` for the handler.
+ * `getRedeliveryCount()` (at-least-once; with a `retryProducer` the message is instead re-published with
+ * `bq-attempts` + 1, which also bounds `Exclusive` / `Failover` subscriptions) — until `maxAttempts` deliveries are used up; the last one is
+ * dead-lettered to `<queue>.dlq` or acknowledged and dropped (ADR-0036). Routing uses the `bq-job`
+ * property (body URN as the fallback); `attempts` is the `bq-attempts` property (body value as the
+ * fallback) reconciled to `max(.., getRedeliveryCount())` for the handler.
  */
 declare class PulsarConsumer {
     private readonly consumer;
     private readonly handlers;
     private readonly options;
+    private readonly maxAttempts;
+    private builtRetryProducer;
+    private readonly warn;
     constructor(consumer: PulsarConsumerClient, handlers: BabelHandlers, options?: PulsarConsumerOptions);
+    /**
+     * Setup check: on `Exclusive` / `Failover` (and an undeclared type) a negative acknowledgement does not advance the native
+     * redelivery count, so a retry needs a re-publish. Fail loudly here instead of looping at run time.
+     */
+    private checkRetryBound;
+    private retryTopic;
+    /** The retry producer: the one given, else one built (once) from the client; undefined when neither exists. */
+    private resolveRetryProducer;
     /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
     poll(): Promise<number>;
     /** Poll until `signal` aborts. */
     run(signal?: AbortSignal): Promise<void>;
     private handle;
+    /**
+     * The settle decision of a retryable outcome (ADR-0036 decisions 1 and 2). `counted` is the reconciled
+     * attempts plus one for this delivery. A poison body with dead-lettering on is recorded without retry;
+     * every other outcome retries (`negativeAcknowledge`: the native redelivery count advances, so the
+     * next delivery counts one more) while `counted < maxAttempts`, then dead-letters or drops.
+     */
+    private settle;
+    /**
+     * Retry one delivery. With a {@link PulsarConsumerOptions.retryProducer}: re-publish to the consumer's
+     * own topic carrying `bq-attempts = counted` (reconcile = max(bq-attempts, RedeliveryCount) on the next
+     * delivery), then acknowledge the original — only after the send succeeded. Otherwise `negativeAcknowledge`.
+     */
+    private retry;
+    private retryMessage;
+    /**
+     * Write the DLQ record, then acknowledge the original — only after the send succeeded. A failed send
+     * leaves the original negatively acknowledged, so it is redelivered and the write is tried again.
+     */
+    private deadLetter;
+    private deadLetterMessage;
     private notifyRoutingMismatch;
 }
 
-export { type BabelHandler, type BabelHandlers, type PublishOptions, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, headersOf, pulsarProperties, toPulsarMessage };
+export { type BabelHandler, type BabelHandlers, DEFAULT_MAX_ATTEMPTS, type PublishOptions, type PulsarClientLike, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, type PulsarSubscriptionType, headersOf, pulsarProperties, toPulsarMessage };

package/dist/index.d.ts

@@ -20,7 +20,7 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  *     });
  *     const consumer = new PulsarConsumer(sub, {
  *       "urn:babel:orders:created": async (env) => { ... },
- *     });
+ *     }, { subscriptionType: "Shared" }); // declare it (or pass `client` together with `topic`): see PulsarConsumerOptions
  *     await consumer.run();
  *
  * This implements §5 of the broker-bindings contract: the canonical envelope is the message
@@ -28,7 +28,12 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /
  * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);
  * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is
- * redelivered (at-least-once) and `getRedeliveryCount()` is incremented. Per §5.2 / §5.7 the
+ * redelivered (at-least-once) and `getRedeliveryCount()` is incremented — up to `maxAttempts`
+ * deliveries (default 3, ADR-0036): the message that exhausts them is written to `<queue>.dlq`
+ * (when a `deadLetterProducer` is given) or acknowledged and dropped. A body that does not decode
+ * into an envelope (including an object with no valid identity) is poison: it never reaches a
+ * handler, and with dead-lettering on it is recorded in `<queue>.dlq` in the ADR-0035 shape without
+ * retry. Per §5.2 / §5.7 the
  * consumer routes on the `bq-job` property (the body's URN is used only when the property is
  * absent or blank) and takes `attempts` from the authoritative `bq-attempts` property (the
  * body's value is used only when the property is absent or not a plain ASCII-decimal integer
@@ -79,10 +84,27 @@ interface PulsarReceivedMessage {
  * satisfies it structurally; a fake satisfies it in tests.
  */
 interface PulsarConsumerClient {
+    /**
+     * The topic the subscription reads. pulsar-client's `Consumer` has **no** such method (only its `Producer`
+     * does), so with it the topic comes from the {@link PulsarConsumerOptions.topic} option; a custom
+     * subscription wrapper may provide this to make `topic` unnecessary.
+     */
+    getTopic?(): string;
     receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;
     acknowledge(message: PulsarReceivedMessage): Promise<void> | void;
     negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;
 }
+/**
+ * The subset of the Pulsar client this adapter calls to build its own retry producer. A `Client` from
+ * `pulsar-client` satisfies it structurally.
+ */
+interface PulsarClientLike {
+    createProducer(config: {
+        topic: string;
+    }): Promise<PulsarProducer>;
+}
+/** The subscription type, as pulsar-client names it (`Key_Shared` is accepted as an alias of `KeyShared`). */
+type PulsarSubscriptionType = "Exclusive" | "Shared" | "Failover" | "KeyShared" | "Key_Shared";
 /**
  * Project the envelope's contract fields onto native Pulsar message properties
  * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus
@@ -153,26 +175,118 @@ interface PulsarConsumerOptions {
      * rejects with) is swallowed — it never changes how the message is handled or acknowledged.
      */
     onRoutingMismatch?: (propertyUrn: string, bodyUrn: string, envelope: IncomingEnvelope) => unknown;
+    /**
+     * The total number of deliveries a message gets, the first included (default 3; `1` = no retry;
+     * ADR-0036 decision 1). A failing handler, an unmapped URN without {@link onUnknownUrn} and a poison
+     * body with dead-lettering off are retried (`negativeAcknowledge`) while `reconciled attempts + 1`
+     * is below it; the delivery that reaches it is dead-lettered (when {@link deadLetterProducer} is
+     * set) or acknowledged and dropped. Must be an integer of at least 1.
+     */
+    maxAttempts?: number;
+    /**
+     * A producer on the dead-letter topic (by convention `<queue>.dlq`). Dead-lettering is on exactly
+     * when it is set; the SDK does not use Pulsar's native `DeadLetterPolicy`. The original message is
+     * acknowledged only after the record was sent; a failed send leaves it negatively acknowledged so
+     * it is redelivered and the write is tried again.
+     */
+    deadLetterProducer?: PulsarProducer;
+    /**
+     * A producer on the consumer's **own** topic. A retry re-publishes the message to that topic with
+     * `bq-attempts` (and the body's `attempts`) raised to the counted value and then acknowledges the
+     * original — the Go model. The count then lives in the message itself, so the bound holds on every
+     * subscription type. Optional when {@link client} is given (the consumer builds the producer itself);
+     * a failed re-publish leaves the original negatively acknowledged (never lost).
+     *
+     * Without a producer or a client a retry is a `negativeAcknowledge`, which advances the native
+     * redelivery count only on `Shared` / `Key_Shared`: on `Exclusive` / `Failover` it stays 0 and the retry
+     * would never reach `maxAttempts`, so that combination is rejected at construction (see
+     * {@link subscriptionType}).
+     */
+    retryProducer?: PulsarProducer;
+    /**
+     * The Pulsar client the consumer builds its retry producer from, lazily on the first retry, on
+     * {@link topic}. Needs `topic` (pulsar-client's `Consumer` cannot tell its topic). Ignored when
+     * {@link retryProducer} is given.
+     */
+    client?: PulsarClientLike;
+    /**
+     * The topic the retry producer is created on — the topic the consumer reads. Required together with
+     * {@link client} (a pulsar-client `Consumer` has no `getTopic()`); a subscription wrapper that provides
+     * `getTopic()` makes it optional.
+     */
+    topic?: string;
+    /**
+     * The subscription type the consumer was created with. `Exclusive` and `Failover` cannot bound a
+     * nack-driven retry (a negative acknowledgement does not advance the redelivery count there), so with
+     * `maxAttempts > 1` they require a {@link retryProducer} or a {@link client}. **Not declaring it counts as
+     * `Exclusive`** (pulsar-client's own default, and the fail-closed choice): without a `retryProducer` or a
+     * `client` the constructor throws `BabelQueueError`. Declare `"Shared"` or `"Key_Shared"` to keep the
+     * `negativeAcknowledge` retry without a producer.
+     */
+    subscriptionType?: PulsarSubscriptionType;
+    /**
+     * The queue name written to `dead_letter.original_queue` of a poison record (a decodable envelope
+     * uses its own `meta.queue`). Defaults to the {@link deadLetterProducer} topic without its `.dlq`
+     * suffix.
+     */
+    queue?: string;
+    /** Receives the "message dropped" and "dead-letter write failed" warnings (default `console.warn`). */
+    onWarn?: (message: string) => void;
 }
+/** Default total number of deliveries (ADR-0036 decision 1). */
+declare const DEFAULT_MAX_ATTEMPTS = 3;
 /**
  * Receives from a Pulsar subscription, decodes + validates each message, routes it to the
  * handler for its URN, and acknowledges it on success. A throwing handler
  * `negativeAcknowledge`s the message — the broker redelivers it and increments
- * `getRedeliveryCount()` (at-least-once). Routing uses the `bq-job` property (body URN as the
- * fallback); `attempts` is the `bq-attempts` property (body value as the fallback) reconciled to
- * `max(.., getRedeliveryCount())` for the handler.
+ * `getRedeliveryCount()` (at-least-once; with a `retryProducer` the message is instead re-published with
+ * `bq-attempts` + 1, which also bounds `Exclusive` / `Failover` subscriptions) — until `maxAttempts` deliveries are used up; the last one is
+ * dead-lettered to `<queue>.dlq` or acknowledged and dropped (ADR-0036). Routing uses the `bq-job`
+ * property (body URN as the fallback); `attempts` is the `bq-attempts` property (body value as the
+ * fallback) reconciled to `max(.., getRedeliveryCount())` for the handler.
  */
 declare class PulsarConsumer {
     private readonly consumer;
     private readonly handlers;
     private readonly options;
+    private readonly maxAttempts;
+    private builtRetryProducer;
+    private readonly warn;
     constructor(consumer: PulsarConsumerClient, handlers: BabelHandlers, options?: PulsarConsumerOptions);
+    /**
+     * Setup check: on `Exclusive` / `Failover` (and an undeclared type) a negative acknowledgement does not advance the native
+     * redelivery count, so a retry needs a re-publish. Fail loudly here instead of looping at run time.
+     */
+    private checkRetryBound;
+    private retryTopic;
+    /** The retry producer: the one given, else one built (once) from the client; undefined when neither exists. */
+    private resolveRetryProducer;
     /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
     poll(): Promise<number>;
     /** Poll until `signal` aborts. */
     run(signal?: AbortSignal): Promise<void>;
     private handle;
+    /**
+     * The settle decision of a retryable outcome (ADR-0036 decisions 1 and 2). `counted` is the reconciled
+     * attempts plus one for this delivery. A poison body with dead-lettering on is recorded without retry;
+     * every other outcome retries (`negativeAcknowledge`: the native redelivery count advances, so the
+     * next delivery counts one more) while `counted < maxAttempts`, then dead-letters or drops.
+     */
+    private settle;
+    /**
+     * Retry one delivery. With a {@link PulsarConsumerOptions.retryProducer}: re-publish to the consumer's
+     * own topic carrying `bq-attempts = counted` (reconcile = max(bq-attempts, RedeliveryCount) on the next
+     * delivery), then acknowledge the original — only after the send succeeded. Otherwise `negativeAcknowledge`.
+     */
+    private retry;
+    private retryMessage;
+    /**
+     * Write the DLQ record, then acknowledge the original — only after the send succeeded. A failed send
+     * leaves the original negatively acknowledged, so it is redelivered and the write is tried again.
+     */
+    private deadLetter;
+    private deadLetterMessage;
     private notifyRoutingMismatch;
 }
 
-export { type BabelHandler, type BabelHandlers, type PublishOptions, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, headersOf, pulsarProperties, toPulsarMessage };
+export { type BabelHandler, type BabelHandlers, DEFAULT_MAX_ATTEMPTS, type PublishOptions, type PulsarClientLike, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, type PulsarSubscriptionType, headersOf, pulsarProperties, toPulsarMessage };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { BabelQueueError, EnvelopeCodec, SCHEMA_VERSION, UnknownUrnError } from "@babelqueue/core";
+import { BabelQueueError, EnvelopeCodec, SCHEMA_VERSION, UnknownUrnError, annotate, buildPoisonRecord } from "@babelqueue/core";
 
 // src/headers.ts
 function sanitizeHeaders(headers) {
@@ -77,12 +77,19 @@ var PulsarPublisher = class {
     return envelope.meta.id;
   }
 };
+var DEFAULT_MAX_ATTEMPTS = 3;
 var MAX_ATTEMPTS = 2 ** 31 - 1;
 function parseAttempts(raw) {
   if (typeof raw !== "string" || !/^[0-9]+$/.test(raw)) return void 0;
   const value = Number(raw);
   return value <= MAX_ATTEMPTS ? value : void 0;
 }
+function reconcileAttempts(properties, bodyAttempts, redeliveryCount) {
+  let attempts = bodyAttempts;
+  const fromProperty = parseAttempts(properties["bq-attempts"]);
+  if (fromProperty !== void 0) attempts = fromProperty;
+  return redeliveryCount > attempts ? redeliveryCount : attempts;
+}
 var BLANK_ASCII = /^[ \t\n\v\f\r]*$/;
 function unsupportedSchemaVersion(properties) {
   const raw = properties["bq-schema-version"];
@@ -101,10 +108,62 @@ var PulsarConsumer = class {
     this.consumer = consumer;
     this.handlers = handlers;
     this.options = options;
+    const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+      throw new BabelQueueError(`maxAttempts must be an integer of at least 1, got ${String(maxAttempts)}.`);
+    }
+    this.maxAttempts = maxAttempts;
+    this.checkRetryBound(maxAttempts);
+    this.warn = options.onWarn ?? ((message) => console.warn(message));
   }
   consumer;
   handlers;
   options;
+  maxAttempts;
+  builtRetryProducer;
+  warn;
+  /**
+   * Setup check: on `Exclusive` / `Failover` (and an undeclared type) a negative acknowledgement does not advance the native
+   * redelivery count, so a retry needs a re-publish. Fail loudly here instead of looping at run time.
+   */
+  checkRetryBound(maxAttempts) {
+    const declared = this.options.subscriptionType;
+    if (declared !== void 0 && !["Exclusive", "Shared", "Failover", "KeyShared"].includes(declared.replace("_", ""))) {
+      throw new BabelQueueError(`Unknown subscriptionType "${String(declared)}".`);
+    }
+    const type = declared === void 0 ? "Exclusive" : declared.replace("_", "");
+    if (type !== "Exclusive" && type !== "Failover") return;
+    if (maxAttempts === 1 || this.options.retryProducer !== void 0) return;
+    if (this.options.client !== void 0 && this.retryTopic() !== void 0) return;
+    const shown = declared === void 0 ? "An undeclared subscriptionType (treated as Exclusive)" : `A ${type} subscription`;
+    if (this.options.client !== void 0) {
+      throw new BabelQueueError(
+        `${shown} with a client needs the \`topic\` option (the topic this consumer reads) to build the retry producer: pulsar-client's Consumer cannot report its own topic.`
+      );
+    }
+    throw new BabelQueueError(
+      `${shown} needs a retryProducer (or a client plus a topic) to bound retries: a negative acknowledgement does not advance the redelivery count there, so a retry would never reach maxAttempts. Pass a client plus topic (the topic you subscribed to), or a retryProducer, or declare subscriptionType: "Shared" / "Key_Shared".`
+    );
+  }
+  retryTopic() {
+    const configured = this.options.topic;
+    if (configured !== void 0 && configured !== "") return configured;
+    const own = typeof this.consumer.getTopic === "function" ? this.consumer.getTopic() : void 0;
+    return own !== void 0 && own !== "" ? own : void 0;
+  }
+  /** The retry producer: the one given, else one built (once) from the client; undefined when neither exists. */
+  async resolveRetryProducer() {
+    if (this.options.retryProducer !== void 0) return this.options.retryProducer;
+    const client = this.options.client;
+    const topic = this.retryTopic();
+    if (client === void 0 || topic === void 0) return void 0;
+    this.builtRetryProducer ??= client.createProducer({ topic }).catch((error) => {
+      this.builtRetryProducer = void 0;
+      this.warn(`babelqueue: creating the retry producer on ${topic} failed (${errorText(error)}).`);
+      return void 0;
+    });
+    return this.builtRetryProducer;
+  }
   /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
   async poll() {
     let message;
@@ -137,29 +196,23 @@ var PulsarConsumer = class {
       await this.consumer.negativeAcknowledge(message);
       return;
     }
-    const envelope = EnvelopeCodec.decode(decodePayload(message.getData()));
     const redeliveryCount = typeof message.getRedeliveryCount === "function" ? message.getRedeliveryCount() : 0;
-    const bodyAttempts = envelope.attempts;
-    let attempts = typeof bodyAttempts === "number" && Number.isInteger(bodyAttempts) ? bodyAttempts : 0;
-    const fromProperty = parseAttempts(properties["bq-attempts"]);
-    if (fromProperty !== void 0) attempts = fromProperty;
-    if (redeliveryCount > attempts) attempts = redeliveryCount;
-    if (typeof bodyAttempts === "number" && Number.isInteger(bodyAttempts) && bodyAttempts !== attempts) {
-      envelope.attempts = attempts;
-    }
+    const envelope = EnvelopeCodec.decode(decodePayload(message.getData()));
     const bodyUrn = EnvelopeCodec.urn(envelope);
     const rawJob = properties["bq-job"];
     const propertyUrn = typeof rawJob === "string" ? rawJob.trim() : "";
     const urn = propertyUrn !== "" ? propertyUrn : bodyUrn;
     if (!EnvelopeCodec.accepts(envelope)) {
-      this.options.onError?.(
-        new BabelQueueError("Rejected a non-conformant BabelQueue envelope from Apache Pulsar."),
-        envelope,
-        message
-      );
-      await this.consumer.negativeAcknowledge(message);
+      const error = new BabelQueueError("Rejected a non-conformant BabelQueue envelope from Apache Pulsar.");
+      this.options.onError?.(error, envelope, message);
+      await this.settle("poison", reconcileAttempts(properties, 0, redeliveryCount) + 1, null, message, error);
       return;
     }
+    const bodyAttempts = envelope.attempts;
+    const attempts = reconcileAttempts(properties, bodyAttempts, redeliveryCount);
+    if (bodyAttempts !== attempts) {
+      envelope.attempts = attempts;
+    }
     if (propertyUrn !== "" && bodyUrn !== "" && propertyUrn !== bodyUrn) {
       this.notifyRoutingMismatch(propertyUrn, bodyUrn, envelope);
     }
@@ -169,8 +222,9 @@ var PulsarConsumer = class {
         await this.options.onUnknownUrn(envelope, message);
         await this.consumer.acknowledge(message);
       } else {
-        this.options.onError?.(new UnknownUrnError(urn), envelope, message);
-        await this.consumer.negativeAcknowledge(message);
+        const error = new UnknownUrnError(urn);
+        this.options.onError?.(error, envelope, message);
+        await this.settle("unknown_urn", attempts + 1, envelope, message, error);
       }
       return;
     }
@@ -179,8 +233,108 @@ var PulsarConsumer = class {
       await this.consumer.acknowledge(message);
     } catch (error) {
       this.options.onError?.(error, envelope, message);
+      await this.settle("failed", attempts + 1, envelope, message, error);
+    }
+  }
+  /**
+   * The settle decision of a retryable outcome (ADR-0036 decisions 1 and 2). `counted` is the reconciled
+   * attempts plus one for this delivery. A poison body with dead-lettering on is recorded without retry;
+   * every other outcome retries (`negativeAcknowledge`: the native redelivery count advances, so the
+   * next delivery counts one more) while `counted < maxAttempts`, then dead-letters or drops.
+   */
+  async settle(kind, counted, envelope, message, error) {
+    const producer = this.options.deadLetterProducer;
+    if (kind === "poison" && producer !== void 0) {
+      await this.deadLetter(producer, kind, counted, null, message, error);
+      return;
+    }
+    if (counted < this.maxAttempts) {
+      await this.retry(counted, envelope, message);
+      return;
+    }
+    if (producer !== void 0) {
+      await this.deadLetter(producer, kind, counted, envelope, message, error);
+      return;
+    }
+    this.warn(
+      `babelqueue: dropped a ${kind} Apache Pulsar message after ${counted} of ${this.maxAttempts} deliveries (dead-lettering is off).`
+    );
+    await this.consumer.acknowledge(message);
+  }
+  /**
+   * Retry one delivery. With a {@link PulsarConsumerOptions.retryProducer}: re-publish to the consumer's
+   * own topic carrying `bq-attempts = counted` (reconcile = max(bq-attempts, RedeliveryCount) on the next
+   * delivery), then acknowledge the original — only after the send succeeded. Otherwise `negativeAcknowledge`.
+   */
+  async retry(counted, envelope, message) {
+    const producer = await this.resolveRetryProducer();
+    if (producer === void 0) {
+      await this.consumer.negativeAcknowledge(message);
+      return;
+    }
+    try {
+      await producer.send(this.retryMessage(counted, envelope, message));
+    } catch (writeError) {
+      this.warn(
+        `babelqueue: retry re-publish to ${producer.getTopic()} failed (${errorText(writeError)}); the message is left for redelivery.`
+      );
+      await this.consumer.negativeAcknowledge(message);
+      return;
+    }
+    await this.consumer.acknowledge(message);
+  }
+  retryMessage(counted, envelope, message) {
+    const carried = headersOf(message);
+    delete carried["bq-delay"];
+    if (envelope !== null) {
+      return keepRoute(toPulsarMessage({ ...envelope, attempts: counted }, carried), message);
+    }
+    const data = message.getData();
+    return keepRoute(
+      {
+        data: typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data),
+        properties: { ...carried, "bq-attempts": String(counted) }
+      },
+      message
+    );
+  }
+  /**
+   * Write the DLQ record, then acknowledge the original — only after the send succeeded. A failed send
+   * leaves the original negatively acknowledged, so it is redelivered and the write is tried again.
+   */
+  async deadLetter(producer, kind, counted, envelope, message, error) {
+    try {
+      await producer.send(this.deadLetterMessage(producer, kind, counted, envelope, message, error));
+    } catch (writeError) {
+      this.warn(
+        `babelqueue: dead-letter write to ${producer.getTopic()} failed (${errorText(writeError)}); the message is left for redelivery.`
+      );
       await this.consumer.negativeAcknowledge(message);
+      return;
     }
+    await this.consumer.acknowledge(message);
+  }
+  deadLetterMessage(producer, kind, counted, envelope, message, error) {
+    const details = {
+      attempts: counted,
+      error: error instanceof Error ? error.message : null,
+      exception: error instanceof Error ? error.name : null
+    };
+    if (envelope === null) {
+      const original2 = this.options.queue ?? stripDlqSuffix(topicName(producer.getTopic()));
+      const delivered = counted - 1;
+      const deadLetter = annotate({ attempts: delivered }, kind, original2, {
+        ...details,
+        attempts: delivered
+      }).dead_letter;
+      const data = message.getData();
+      const body = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+      const record = buildPoisonRecord(body, JSON.stringify(deadLetter));
+      return keepRoute({ data: Buffer.from(record, "utf8"), properties: poisonProperties(record) }, message);
+    }
+    const original = envelope.meta?.queue || this.options.queue || stripDlqSuffix(topicName(producer.getTopic()));
+    const annotated = annotate({ ...envelope, attempts: counted }, kind, original, details);
+    return keepRoute(toPulsarMessage(annotated), message);
   }
   notifyRoutingMismatch(propertyUrn, bodyUrn, envelope) {
     const hook = this.options.onRoutingMismatch;
@@ -200,7 +354,41 @@ function safeProperties(message) {
     return {};
   }
 }
+function keepRoute(outgoing, incoming) {
+  const route = safeProperties(incoming)["bq-job"];
+  if (typeof route === "string" && route.trim() !== "") {
+    outgoing.properties = { ...outgoing.properties, "bq-job": route };
+  }
+  return outgoing;
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function stripDlqSuffix(topic) {
+  return topic.endsWith(".dlq") && topic.length > 4 ? topic.slice(0, -4) : topic;
+}
+function poisonProperties(recordJson) {
+  const properties = {};
+  let record;
+  try {
+    record = JSON.parse(recordJson);
+  } catch {
+    return properties;
+  }
+  if (record === null || typeof record !== "object") return properties;
+  const top = record;
+  const str = (value) => typeof value === "string" && value !== "" ? value : void 0;
+  const job = str(top["job"]) ?? str(top["urn"]);
+  if (job) properties["bq-job"] = job;
+  const trace = str(top["trace_id"]);
+  if (trace) properties["bq-trace-id"] = trace;
+  const meta = top["meta"] !== null && typeof top["meta"] === "object" ? top["meta"] : {};
+  const id = str(meta["id"]);
+  if (id) properties["bq-message-id"] = id;
+  return properties;
+}
 export {
+  DEFAULT_MAX_ATTEMPTS,
   PulsarConsumer,
   PulsarPublisher,
   headersOf,