@drarzter/kafka-client 0.7.1 → 0.7.3

package/dist/core.js

@@ -40,7 +40,7 @@ __export(core_exports, {
 module.exports = __toCommonJS(core_exports);
 
 // src/client/kafka.client/index.ts
-var import_kafka_javascript = require("@confluentinc/kafka-javascript");
+var import_kafka_javascript2 = require("@confluentinc/kafka-javascript");
 
 // src/client/message/envelope.ts
 var import_node_async_hooks = require("async_hooks");
@@ -136,7 +136,7 @@ var KafkaRetryExhaustedError = class extends KafkaProcessingError {
   }
 };
 
-// src/client/kafka.client/producer-ops.ts
+// src/client/kafka.client/producer/ops.ts
 function resolveTopicName(topicOrDescriptor) {
   if (typeof topicOrDescriptor === "string") return topicOrDescriptor;
   if (topicOrDescriptor && typeof topicOrDescriptor === "object" && "__topic" in topicOrDescriptor) {
@@ -181,7 +181,7 @@ async function validateMessage(topicOrDesc, message, deps, ctx) {
   }
   return message;
 }
-async function buildSendPayload(topicOrDesc, messages, deps) {
+async function buildSendPayload(topicOrDesc, messages, deps, compression) {
   const topic2 = resolveTopicName(topicOrDesc);
   const builtMessages = await Promise.all(
     messages.map(async (m) => {
@@ -211,11 +211,12 @@ async function buildSendPayload(topicOrDesc, messages, deps) {
       };
     })
   );
-  return { topic: topic2, messages: builtMessages };
+  return { topic: topic2, messages: builtMessages, ...compression && { compression } };
 }
 
-// src/client/kafka.client/consumer-ops.ts
-function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps) {
+// src/client/kafka.client/consumer/ops.ts
+var import_kafka_javascript = require("@confluentinc/kafka-javascript");
+function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps, partitionAssigner) {
   const { consumers, consumerCreationOptions, kafka, onRebalance, logger } = deps;
   if (consumers.has(groupId)) {
     const prev = consumerCreationOptions.get(groupId);
@@ -227,8 +228,11 @@ function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps) {
     return consumers.get(groupId);
   }
   consumerCreationOptions.set(groupId, { fromBeginning, autoCommit });
+  const assigners = [
+    partitionAssigner === "roundrobin" ? import_kafka_javascript.KafkaJS.PartitionAssigners.roundRobin : partitionAssigner === "range" ? import_kafka_javascript.KafkaJS.PartitionAssigners.range : import_kafka_javascript.KafkaJS.PartitionAssigners.cooperativeSticky
+  ];
   const config = {
-    kafkaJS: { groupId, fromBeginning, autoCommit }
+    kafkaJS: { groupId, fromBeginning, autoCommit, partitionAssigners: assigners }
   };
   if (onRebalance) {
     const cb = onRebalance;
@@ -273,7 +277,7 @@ function buildSchemaMap(topics, schemaRegistry, optionSchemas, logger) {
   return schemaMap;
 }
 
-// src/client/consumer/pipeline.ts
+// src/client/kafka.client/consumer/pipeline.ts
 function toError(error) {
   return error instanceof Error ? error : new Error(String(error));
 }
@@ -623,7 +627,7 @@ async function executeWithRetry(fn, ctx, deps) {
   }
 }
 
-// src/client/kafka.client/message-handler.ts
+// src/client/kafka.client/consumer/handler.ts
 async function applyDeduplication(envelope, raw, dedup, dlq, deps) {
   const clockRaw = envelope.headers[HEADER_LAMPORT_CLOCK];
   if (clockRaw === void 0) return false;
@@ -773,7 +777,8 @@ async function handleEachMessage(payload, opts, deps) {
         });
         deps.onDlq?.(envelope, "ttl-expired");
       } else {
-        await deps.onTtlExpired?.({
+        const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
+        await ttlHandler?.({
           topic: topic2,
           ageMs,
           messageTtlMs: opts.messageTtlMs,
@@ -900,7 +905,8 @@ async function handleEachBatch(payload, opts, deps) {
           });
           deps.onDlq?.(envelope, "ttl-expired");
         } else {
-          await deps.onTtlExpired?.({
+          const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
+          await ttlHandler?.({
             topic: batch.topic,
             ageMs,
             messageTtlMs: opts.messageTtlMs,
@@ -942,10 +948,11 @@ async function handleEachBatch(payload, opts, deps) {
   );
 }
 
-// src/client/consumer/subscribe-retry.ts
+// src/client/kafka.client/consumer/subscribe-retry.ts
 async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
   const maxAttempts = retryOpts?.retries ?? 5;
   const backoffMs = retryOpts?.backoffMs ?? 5e3;
+  const displayTopics = topics.map((t) => t instanceof RegExp ? t.toString() : t).join(", ");
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
       await consumer.subscribe({ topics });
@@ -955,14 +962,14 @@ async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
       const msg = toError(error).message;
       const delay = Math.floor(Math.random() * backoffMs);
       logger.warn(
-        `Failed to subscribe to [${topics.join(", ")}] (attempt ${attempt}/${maxAttempts}): ${msg}. Retrying in ${delay}ms...`
+        `Failed to subscribe to [${displayTopics}] (attempt ${attempt}/${maxAttempts}): ${msg}. Retrying in ${delay}ms...`
       );
       await sleep(delay);
     }
   }
 }
 
-// src/client/kafka.client/retry-topic.ts
+// src/client/kafka.client/consumer/retry-topic.ts
 async function waitForPartitionAssignment(consumer, topics, logger, timeoutMs = 1e4) {
   const topicSet = new Set(topics);
   const deadline = Date.now() + timeoutMs;
@@ -1216,9 +1223,7 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
   return levelGroupIds;
 }
 
-// src/client/kafka.client/index.ts
-var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = import_kafka_javascript.KafkaJS;
-var _activeTransactionalIds = /* @__PURE__ */ new Set();
+// src/client/kafka.client/consumer/queue.ts
 var AsyncQueue = class {
   constructor(highWaterMark = Infinity, onFull = () => {
   }, onDrained = () => {
@@ -1267,216 +1272,806 @@ var AsyncQueue = class {
     return new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
   }
 };
-var KafkaClient = class _KafkaClient {
-  kafka;
-  producer;
-  txProducer;
-  txProducerInitPromise;
-  /** Maps transactionalId → Producer for each active retry level consumer. */
-  retryTxProducers = /* @__PURE__ */ new Map();
-  consumers = /* @__PURE__ */ new Map();
-  admin;
-  logger;
-  autoCreateTopicsEnabled;
-  strictSchemasEnabled;
-  numPartitions;
-  ensuredTopics = /* @__PURE__ */ new Set();
-  /** Pending topic-creation promises keyed by topic name. Prevents duplicate createTopics calls. */
-  ensureTopicPromises = /* @__PURE__ */ new Map();
-  defaultGroupId;
-  schemaRegistry = /* @__PURE__ */ new Map();
-  runningConsumers = /* @__PURE__ */ new Map();
-  consumerCreationOptions = /* @__PURE__ */ new Map();
-  /** Maps each main consumer groupId to its companion retry level groupIds. */
-  companionGroupIds = /* @__PURE__ */ new Map();
-  instrumentation;
-  onMessageLost;
-  onTtlExpired;
-  onRebalance;
-  /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
-  txId;
-  /** Per-topic event counters, lazily created on first event. Aggregated by `getMetrics()`. */
-  _topicMetrics = /* @__PURE__ */ new Map();
-  /** Monotonically increasing Lamport clock stamped on every outgoing message. */
-  _lamportClock = 0;
-  /** Per-groupId deduplication state: `"topic:partition"` → last processed clock. */
-  dedupStates = /* @__PURE__ */ new Map();
-  /** Circuit breaker state per `"${gid}:${topic}:${partition}"` key. */
-  circuitStates = /* @__PURE__ */ new Map();
-  /** Circuit breaker config per groupId, set at startConsumer/startBatchConsumer time. */
-  circuitConfigs = /* @__PURE__ */ new Map();
-  isAdminConnected = false;
-  inFlightTotal = 0;
-  drainResolvers = [];
-  clientId;
-  constructor(clientId, groupId, brokers, options) {
-    this.clientId = clientId;
-    this.defaultGroupId = groupId;
-    this.logger = options?.logger ?? {
-      log: (msg) => console.log(`[KafkaClient:${clientId}] ${msg}`),
-      warn: (msg, ...args) => console.warn(`[KafkaClient:${clientId}] ${msg}`, ...args),
-      error: (msg, ...args) => console.error(`[KafkaClient:${clientId}] ${msg}`, ...args),
-      debug: (msg, ...args) => console.debug(`[KafkaClient:${clientId}] ${msg}`, ...args)
-    };
-    this.autoCreateTopicsEnabled = options?.autoCreateTopics ?? false;
-    this.strictSchemasEnabled = options?.strictSchemas ?? true;
-    this.numPartitions = options?.numPartitions ?? 1;
-    this.instrumentation = options?.instrumentation ?? [];
-    this.onMessageLost = options?.onMessageLost;
-    this.onTtlExpired = options?.onTtlExpired;
-    this.onRebalance = options?.onRebalance;
-    this.txId = options?.transactionalId ?? `${clientId}-tx`;
-    this.kafka = new KafkaClass({
-      kafkaJS: {
-        clientId: this.clientId,
-        brokers,
-        logLevel: KafkaLogLevel.ERROR
-      }
-    });
-    this.producer = this.kafka.producer({
-      kafkaJS: {
-        acks: -1
-      }
-    });
-    this.admin = this.kafka.admin();
+
+// src/client/kafka.client/infra/circuit-breaker.ts
+var CircuitBreakerManager = class {
+  constructor(deps) {
+    this.deps = deps;
   }
-  async sendMessage(topicOrDesc, message, options = {}) {
-    const payload = await this.preparePayload(topicOrDesc, [
-      {
-        value: message,
-        key: options.key,
-        headers: options.headers,
-        correlationId: options.correlationId,
-        schemaVersion: options.schemaVersion,
-        eventId: options.eventId
-      }
-    ]);
-    await this.producer.send(payload);
-    this.notifyAfterSend(payload.topic, payload.messages.length);
+  states = /* @__PURE__ */ new Map();
+  configs = /* @__PURE__ */ new Map();
+  setConfig(gid, options) {
+    this.configs.set(gid, options);
   }
-  async sendBatch(topicOrDesc, messages) {
-    const payload = await this.preparePayload(topicOrDesc, messages);
-    await this.producer.send(payload);
-    this.notifyAfterSend(payload.topic, payload.messages.length);
+  /**
+   * Returns a snapshot of the circuit breaker state for a given topic-partition.
+   * Returns `undefined` when no state exists for the key.
+   */
+  getState(topic2, partition, gid) {
+    const state = this.states.get(`${gid}:${topic2}:${partition}`);
+    if (!state) return void 0;
+    return {
+      status: state.status,
+      failures: state.window.filter((v) => !v).length,
+      windowSize: state.window.length
+    };
   }
-  /** Execute multiple sends atomically. Commits on success, aborts on error. */
-  async transaction(fn) {
-    if (!this.txProducerInitPromise) {
-      if (_activeTransactionalIds.has(this.txId)) {
-        this.logger.warn(
-          `transactionalId "${this.txId}" is already in use by another KafkaClient in this process. Kafka will fence one of the producers. Set a unique \`transactionalId\` (or distinct \`clientId\`) per instance.`
+  /**
+   * Record a failure for the given envelope and group.
+   * Drives the CLOSED → OPEN and HALF-OPEN → OPEN transitions.
+   */
+  onFailure(envelope, gid) {
+    const cfg = this.configs.get(gid);
+    if (!cfg) return;
+    const threshold = cfg.threshold ?? 5;
+    const recoveryMs = cfg.recoveryMs ?? 3e4;
+    const stateKey = `${gid}:${envelope.topic}:${envelope.partition}`;
+    let state = this.states.get(stateKey);
+    if (!state) {
+      state = { status: "closed", window: [], successes: 0 };
+      this.states.set(stateKey, state);
+    }
+    if (state.status === "open") return;
+    const openCircuit = () => {
+      state.status = "open";
+      state.window = [];
+      state.successes = 0;
+      clearTimeout(state.timer);
+      for (const inst of this.deps.instrumentation)
+        inst.onCircuitOpen?.(envelope.topic, envelope.partition);
+      this.deps.pauseConsumer(gid, [{ topic: envelope.topic, partitions: [envelope.partition] }]);
+      state.timer = setTimeout(() => {
+        state.status = "half-open";
+        state.successes = 0;
+        this.deps.logger.log(
+          `[CircuitBreaker] HALF-OPEN \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
         );
-      }
-      const initPromise = (async () => {
-        const p = this.kafka.producer({
-          kafkaJS: {
-            acks: -1,
-            idempotent: true,
-            transactionalId: this.txId,
-            maxInFlightRequests: 1
-          }
-        });
-        await p.connect();
-        _activeTransactionalIds.add(this.txId);
-        return p;
-      })();
-      this.txProducerInitPromise = initPromise.catch((err) => {
-        this.txProducerInitPromise = void 0;
-        throw err;
-      });
+        for (const inst of this.deps.instrumentation)
+          inst.onCircuitHalfOpen?.(envelope.topic, envelope.partition);
+        this.deps.resumeConsumer(gid, [{ topic: envelope.topic, partitions: [envelope.partition] }]);
+      }, recoveryMs);
+    };
+    if (state.status === "half-open") {
+      clearTimeout(state.timer);
+      this.deps.logger.warn(
+        `[CircuitBreaker] OPEN (half-open failure) \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
+      );
+      openCircuit();
+      return;
     }
-    this.txProducer = await this.txProducerInitPromise;
-    const tx = await this.txProducer.transaction();
-    try {
-      const ctx = {
-        send: async (topicOrDesc, message, options = {}) => {
-          const payload = await this.preparePayload(topicOrDesc, [
-            {
-              value: message,
-              key: options.key,
-              headers: options.headers,
-              correlationId: options.correlationId,
-              schemaVersion: options.schemaVersion,
-              eventId: options.eventId
-            }
-          ]);
-          await tx.send(payload);
-          this.notifyAfterSend(payload.topic, payload.messages.length);
-        },
-        sendBatch: async (topicOrDesc, messages) => {
-          const payload = await this.preparePayload(topicOrDesc, messages);
-          await tx.send(payload);
-          this.notifyAfterSend(payload.topic, payload.messages.length);
-        }
-      };
-      await fn(ctx);
-      await tx.commit();
-    } catch (error) {
-      try {
-        await tx.abort();
-      } catch (abortError) {
-        this.logger.error(
-          "Failed to abort transaction:",
-          toError(abortError).message
+    const windowSize = cfg.windowSize ?? Math.max(threshold * 2, 10);
+    state.window = [...state.window, false];
+    if (state.window.length > windowSize) {
+      state.window = state.window.slice(state.window.length - windowSize);
+    }
+    const failures = state.window.filter((v) => !v).length;
+    if (failures >= threshold) {
+      this.deps.logger.warn(
+        `[CircuitBreaker] OPEN \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition} (${failures}/${state.window.length} failures, threshold=${threshold})`
+      );
+      openCircuit();
+    }
+  }
+  /**
+   * Record a success for the given envelope and group.
+   * Drives the HALF-OPEN → CLOSED transition and updates the success window.
+   */
+  onSuccess(envelope, gid) {
+    const cfg = this.configs.get(gid);
+    if (!cfg) return;
+    const stateKey = `${gid}:${envelope.topic}:${envelope.partition}`;
+    const state = this.states.get(stateKey);
+    if (!state) return;
+    const halfOpenSuccesses = cfg.halfOpenSuccesses ?? 1;
+    if (state.status === "half-open") {
+      state.successes++;
+      if (state.successes >= halfOpenSuccesses) {
+        clearTimeout(state.timer);
+        state.timer = void 0;
+        state.status = "closed";
+        state.window = [];
+        state.successes = 0;
+        this.deps.logger.log(
+          `[CircuitBreaker] CLOSED \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
         );
+        for (const inst of this.deps.instrumentation)
+          inst.onCircuitClose?.(envelope.topic, envelope.partition);
+      }
+    } else if (state.status === "closed") {
+      const threshold = cfg.threshold ?? 5;
+      const windowSize = cfg.windowSize ?? Math.max(threshold * 2, 10);
+      state.window = [...state.window, true];
+      if (state.window.length > windowSize) {
+        state.window = state.window.slice(state.window.length - windowSize);
       }
-      throw error;
     }
   }
-  // ── Producer lifecycle ───────────────────────────────────────────
   /**
-   * Connect the idempotent producer. Called automatically by `KafkaModule.register()`.
-   * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
+   * Remove all circuit state and config for the given group.
+   * Called when a consumer is stopped via `stopConsumer(groupId)`.
    */
-  async connectProducer() {
-    await this.producer.connect();
-    this.logger.log("Producer connected");
+  removeGroup(gid) {
+    for (const key of [...this.states.keys()]) {
+      if (key.startsWith(`${gid}:`)) {
+        clearTimeout(this.states.get(key).timer);
+        this.states.delete(key);
+      }
+    }
+    this.configs.delete(gid);
+  }
+  /** Clear all circuit state and config. Called on `disconnect()`. */
+  clear() {
+    for (const state of this.states.values()) clearTimeout(state.timer);
+    this.states.clear();
+    this.configs.clear();
+  }
+};
+
+// src/client/kafka.client/admin/ops.ts
+var AdminOps = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  isConnected = false;
+  /** Underlying admin client — used by index.ts for topic validation. */
+  get admin() {
+    return this.deps.admin;
+  }
+  /** Whether the admin client is currently connected. */
+  get connected() {
+    return this.isConnected;
   }
   /**
-   * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
+   * Connect the admin client if not already connected.
+   * The flag is only set to `true` after a successful connect — if `admin.connect()`
+   * throws the flag remains `false` so the next call will retry the connection.
    */
-  async disconnectProducer() {
-    await this.producer.disconnect();
-    this.logger.log("Producer disconnected");
+  async ensureConnected() {
+    if (this.isConnected) return;
+    try {
+      await this.deps.admin.connect();
+      this.isConnected = true;
+    } catch (err) {
+      this.isConnected = false;
+      throw err;
+    }
   }
-  async startConsumer(topics, handleMessage, options = {}) {
-    if (options.retryTopics && !options.retry) {
+  /** Disconnect admin if connected. Resets the connected flag. */
+  async disconnect() {
+    if (!this.isConnected) return;
+    await this.deps.admin.disconnect();
+    this.isConnected = false;
+  }
+  async resetOffsets(groupId, topic2, position) {
+    const gid = groupId ?? this.deps.defaultGroupId;
+    if (this.deps.runningConsumers.has(gid)) {
       throw new Error(
-        "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
+        `resetOffsets: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before resetting offsets.`
       );
     }
-    const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
-    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", setupOptions);
-    if (options.circuitBreaker)
-      this.circuitConfigs.set(gid, options.circuitBreaker);
-    const deps = this.messageDepsFor(gid);
-    const timeoutMs = options.handlerTimeoutMs;
-    const deduplication = this.resolveDeduplicationContext(
-      gid,
-      options.deduplication
+    await this.ensureConnected();
+    const partitionOffsets = await this.deps.admin.fetchTopicOffsets(topic2);
+    const partitions = partitionOffsets.map(({ partition, low, high }) => ({
+      partition,
+      offset: position === "earliest" ? low : high
+    }));
+    await this.deps.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
+    this.deps.logger.log(
+      `Offsets reset to ${position} for group "${gid}" on topic "${topic2}"`
     );
-    let eosMainContext;
-    if (options.retryTopics && retry) {
-      const mainTxId = `${gid}-main-tx`;
-      const txProducer = await this.createRetryTxProducer(mainTxId);
-      eosMainContext = { txProducer, consumer };
+  }
+  /**
+   * Seek specific topic-partition pairs to explicit offsets for a stopped consumer group.
+   * Throws if the group is still running — call `stopConsumer(groupId)` first.
+   * Assignments are grouped by topic and committed via `admin.setOffsets`.
+   */
+  async seekToOffset(groupId, assignments) {
+    const gid = groupId ?? this.deps.defaultGroupId;
+    if (this.deps.runningConsumers.has(gid)) {
+      throw new Error(
+        `seekToOffset: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before seeking offsets.`
+      );
     }
-    await consumer.run({
-      eachMessage: (payload) => this.trackInFlight(
-        () => handleEachMessage(
-          payload,
-          {
-            schemaMap,
-            handleMessage,
-            interceptors,
-            dlq,
-            retry,
-            retryTopics: options.retryTopics,
-            timeoutMs,
-            wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
-            deduplication,
-            messageTtlMs: options.messageTtlMs,
-            eosMainContext
+    await this.ensureConnected();
+    const byTopic = /* @__PURE__ */ new Map();
+    for (const { topic: topic2, partition, offset } of assignments) {
+      const list = byTopic.get(topic2) ?? [];
+      list.push({ partition, offset });
+      byTopic.set(topic2, list);
+    }
+    for (const [topic2, partitions] of byTopic) {
+      await this.deps.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
+      this.deps.logger.log(
+        `Offsets set for group "${gid}" on "${topic2}": ${JSON.stringify(partitions)}`
+      );
+    }
+  }
+  /**
+   * Seek specific topic-partition pairs to the offset nearest to a given timestamp
+   * (in milliseconds) for a stopped consumer group.
+   * Throws if the group is still running — call `stopConsumer(groupId)` first.
+   * Assignments are grouped by topic and committed via `admin.setOffsets`.
+   * If no offset exists at the requested timestamp (e.g. empty partition or
+   * future timestamp), the partition falls back to `-1` (end of topic — new messages only).
+   */
+  async seekToTimestamp(groupId, assignments) {
+    const gid = groupId ?? this.deps.defaultGroupId;
+    if (this.deps.runningConsumers.has(gid)) {
+      throw new Error(
+        `seekToTimestamp: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before seeking offsets.`
+      );
+    }
+    await this.ensureConnected();
+    const byTopic = /* @__PURE__ */ new Map();
+    for (const { topic: topic2, partition, timestamp } of assignments) {
+      const list = byTopic.get(topic2) ?? [];
+      list.push({ partition, timestamp });
+      byTopic.set(topic2, list);
+    }
+    for (const [topic2, parts] of byTopic) {
+      const offsets = await Promise.all(
+        parts.map(async ({ partition, timestamp }) => {
+          const results = await this.deps.admin.fetchTopicOffsetsByTime(
+            topic2,
+            timestamp
+          );
+          const found = results.find(
+            (r) => r.partition === partition
+          );
+          return { partition, offset: found?.offset ?? "-1" };
+        })
+      );
+      await this.deps.admin.setOffsets({ groupId: gid, topic: topic2, partitions: offsets });
+      this.deps.logger.log(
+        `Offsets set by timestamp for group "${gid}" on "${topic2}": ${JSON.stringify(offsets)}`
+      );
+    }
+  }
+  /**
+   * Query consumer group lag per partition.
+   * Lag = broker high-watermark − last committed offset.
+   * A committed offset of -1 (nothing committed yet) counts as full lag.
+   *
+   * Returns an empty array when the consumer group has never committed any
+   * offsets (freshly created group, `autoCommit: false` with no manual commits,
+   * or group not yet assigned). This is a Kafka protocol limitation:
+   * `fetchOffsets` only returns data for topic-partitions that have at least one
+   * committed offset. Use `checkStatus()` to verify broker connectivity in that case.
+   */
+  async getConsumerLag(groupId) {
+    const gid = groupId ?? this.deps.defaultGroupId;
+    await this.ensureConnected();
+    const committedByTopic = await this.deps.admin.fetchOffsets({ groupId: gid });
+    const brokerOffsetsAll = await Promise.all(
+      committedByTopic.map(({ topic: topic2 }) => this.deps.admin.fetchTopicOffsets(topic2))
+    );
+    const result = [];
+    for (let i = 0; i < committedByTopic.length; i++) {
+      const { topic: topic2, partitions } = committedByTopic[i];
+      const brokerOffsets = brokerOffsetsAll[i];
+      for (const { partition, offset } of partitions) {
+        const broker = brokerOffsets.find((o) => o.partition === partition);
+        if (!broker) continue;
+        const committed = parseInt(offset, 10);
+        const high = parseInt(broker.high, 10);
+        const lag = committed === -1 ? high : Math.max(0, high - committed);
+        result.push({ topic: topic2, partition, lag });
+      }
+    }
+    return result;
+  }
+  /** Check broker connectivity. Never throws — returns a discriminated union. */
+  async checkStatus() {
+    try {
+      await this.ensureConnected();
+      const topics = await this.deps.admin.listTopics();
+      return { status: "up", clientId: this.deps.clientId, topics };
+    } catch (error) {
+      return {
+        status: "down",
+        clientId: this.deps.clientId,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  /**
+   * List all consumer groups known to the broker.
+   * Useful for monitoring which groups are active and their current state.
+   */
+  async listConsumerGroups() {
+    await this.ensureConnected();
+    const result = await this.deps.admin.listGroups();
+    return result.groups.map((g) => ({
+      groupId: g.groupId,
+      state: g.state ?? "Unknown"
+    }));
+  }
+  /**
+   * Describe topics — returns partition layout, leader, replicas, and ISR.
+   * @param topics Topic names to describe. Omit to describe all topics.
+   */
+  async describeTopics(topics) {
+    await this.ensureConnected();
+    const result = await this.deps.admin.fetchTopicMetadata(
+      topics ? { topics } : void 0
+    );
+    return result.topics.map((t) => ({
+      name: t.name,
+      partitions: t.partitions.map((p) => ({
+        partition: p.partitionId ?? p.partition,
+        leader: p.leader,
+        replicas: p.replicas.map(
+          (r) => typeof r === "number" ? r : r.nodeId
+        ),
+        isr: p.isr.map(
+          (r) => typeof r === "number" ? r : r.nodeId
+        )
+      }))
+    }));
+  }
+  /**
+   * Delete records from a topic up to (but not including) the given offsets.
+   * All messages with offsets **before** the given offset are deleted.
+   */
+  async deleteRecords(topic2, partitions) {
+    await this.ensureConnected();
+    await this.deps.admin.deleteTopicRecords({ topic: topic2, partitions });
+  }
+  /**
+   * When `retryTopics: true` and `autoCreateTopics: false`, verify that every
+   * `<topic>.retry.<level>` topic already exists. Throws a clear error at startup
+   * rather than silently discovering missing topics on the first handler failure.
+   */
+  async validateRetryTopicsExist(topicNames, maxRetries) {
+    await this.ensureConnected();
+    const existing = new Set(await this.deps.admin.listTopics());
+    const missing = [];
+    for (const t of topicNames) {
+      for (let level = 1; level <= maxRetries; level++) {
+        const retryTopic = `${t}.retry.${level}`;
+        if (!existing.has(retryTopic)) missing.push(retryTopic);
+      }
+    }
+    if (missing.length > 0) {
+      throw new Error(
+        `retryTopics: true but the following retry topics do not exist: ${missing.join(", ")}. Create them manually or set autoCreateTopics: true.`
+      );
+    }
+  }
+  /**
+   * When `autoCreateTopics` is disabled, verify that `<topic>.dlq` exists for every
+   * consumed topic. Throws a clear error at startup rather than silently discovering
+   * missing DLQ topics on the first handler failure.
+   */
+  async validateDlqTopicsExist(topicNames) {
+    await this.ensureConnected();
+    const existing = new Set(await this.deps.admin.listTopics());
+    const missing = topicNames.filter((t) => !existing.has(`${t}.dlq`)).map((t) => `${t}.dlq`);
+    if (missing.length > 0) {
+      throw new Error(
+        `dlq: true but the following DLQ topics do not exist: ${missing.join(", ")}. Create them manually or set autoCreateTopics: true.`
+      );
+    }
+  }
+  /**
+   * When `deduplication.strategy: 'topic'` and `autoCreateTopics: false`, verify
+   * that every `<topic>.duplicates` destination topic already exists. Throws a
+   * clear error at startup rather than silently dropping duplicates on first hit.
+   */
+  async validateDuplicatesTopicsExist(topicNames, customDestination) {
+    await this.ensureConnected();
+    const existing = new Set(await this.deps.admin.listTopics());
+    const toCheck = customDestination ? [customDestination] : topicNames.map((t) => `${t}.duplicates`);
+    const missing = toCheck.filter((t) => !existing.has(t));
+    if (missing.length > 0) {
+      throw new Error(
+        `deduplication.strategy: 'topic' but the following duplicate-routing topics do not exist: ${missing.join(", ")}. Create them manually or set autoCreateTopics: true.`
+      );
+    }
+  }
+};
+
+// src/client/kafka.client/consumer/dlq-replay.ts
+async function replayDlqTopic(topic2, options = {}, deps) {
+  const dlqTopic = `${topic2}.dlq`;
+  const partitionOffsets = await deps.fetchTopicOffsets(dlqTopic);
+  const activePartitions = partitionOffsets.filter((p) => parseInt(p.high, 10) > 0);
+  if (activePartitions.length === 0) {
+    deps.logger.log(`replayDlq: "${dlqTopic}" is empty \u2014 nothing to replay`);
+    return { replayed: 0, skipped: 0 };
+  }
+  const highWatermarks = new Map(
+    activePartitions.map(({ partition, high }) => [partition, parseInt(high, 10)])
+  );
+  const processedOffsets = /* @__PURE__ */ new Map();
+  let replayed = 0;
+  let skipped = 0;
+  const tempGroupId = `${dlqTopic}-replay-${Date.now()}`;
+  await new Promise((resolve, reject) => {
+    const consumer = deps.createConsumer(tempGroupId);
+    const cleanup = () => deps.cleanupConsumer(consumer, tempGroupId);
+    consumer.connect().then(() => subscribeWithRetry(consumer, [dlqTopic], deps.logger)).then(
+      () => consumer.run({
+        eachMessage: async ({ partition, message }) => {
+          if (!message.value) return;
+          const offset = parseInt(message.offset, 10);
+          processedOffsets.set(partition, offset);
+          const headers = decodeHeaders(message.headers);
+          const targetTopic = options.targetTopic ?? headers["x-dlq-original-topic"];
+          const originalHeaders = Object.fromEntries(
+            Object.entries(headers).filter(([k]) => !deps.dlqHeaderKeys.has(k))
+          );
+          const value = message.value.toString();
+          const shouldProcess = !options.filter || options.filter(headers, value);
+          if (!targetTopic || !shouldProcess) {
+            skipped++;
+          } else if (options.dryRun) {
+            deps.logger.log(`[DLQ replay dry-run] Would replay to "${targetTopic}"`);
+            replayed++;
+          } else {
+            await deps.send(targetTopic, [{ value, headers: originalHeaders }]);
+            replayed++;
+          }
+          const allDone = Array.from(highWatermarks.entries()).every(
+            ([p, hwm]) => (processedOffsets.get(p) ?? -1) >= hwm - 1
+          );
+          if (allDone) {
+            cleanup();
+            resolve();
+          }
+        }
+      })
+    ).catch((err) => {
+      cleanup();
+      reject(err);
+    });
+  });
+  deps.logger.log(`replayDlq: replayed ${replayed}, skipped ${skipped} from "${dlqTopic}"`);
+  return { replayed, skipped };
+}
+
+// src/client/kafka.client/infra/metrics-manager.ts
+var MetricsManager = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  topicMetrics = /* @__PURE__ */ new Map();
+  metricsFor(topic2) {
+    let m = this.topicMetrics.get(topic2);
+    if (!m) {
+      m = { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
+      this.topicMetrics.set(topic2, m);
+    }
+    return m;
+  }
+  /** Fire `afterSend` instrumentation hooks for each message in a batch. */
+  notifyAfterSend(topic2, count) {
+    for (let i = 0; i < count; i++)
+      for (const inst of this.deps.instrumentation) inst.afterSend?.(topic2);
+  }
+  notifyRetry(envelope, attempt, maxRetries) {
+    this.metricsFor(envelope.topic).retryCount++;
+    for (const inst of this.deps.instrumentation) inst.onRetry?.(envelope, attempt, maxRetries);
+  }
+  notifyDlq(envelope, reason, gid) {
+    this.metricsFor(envelope.topic).dlqCount++;
+    for (const inst of this.deps.instrumentation) inst.onDlq?.(envelope, reason);
+    if (gid) this.deps.onCircuitFailure(envelope, gid);
+  }
+  notifyDuplicate(envelope, strategy) {
+    this.metricsFor(envelope.topic).dedupCount++;
+    for (const inst of this.deps.instrumentation) inst.onDuplicate?.(envelope, strategy);
+  }
+  notifyMessage(envelope, gid) {
+    this.metricsFor(envelope.topic).processedCount++;
+    for (const inst of this.deps.instrumentation) inst.onMessage?.(envelope);
+    if (gid) this.deps.onCircuitSuccess(envelope, gid);
+  }
+  getMetrics(topic2) {
+    if (topic2 !== void 0) {
+      const m = this.topicMetrics.get(topic2);
+      return m ? { ...m } : { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
+    }
+    const agg = { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
+    for (const m of this.topicMetrics.values()) {
+      agg.processedCount += m.processedCount;
+      agg.retryCount += m.retryCount;
+      agg.dlqCount += m.dlqCount;
+      agg.dedupCount += m.dedupCount;
+    }
+    return agg;
+  }
+  resetMetrics(topic2) {
+    if (topic2 !== void 0) {
+      this.topicMetrics.delete(topic2);
+      return;
+    }
+    this.topicMetrics.clear();
+  }
+};
+
+// src/client/kafka.client/infra/inflight-tracker.ts
+var InFlightTracker = class {
+  constructor(warn) {
+    this.warn = warn;
+  }
+  inFlightTotal = 0;
+  drainResolvers = [];
+  track(fn) {
+    this.inFlightTotal++;
+    return fn().finally(() => {
+      this.inFlightTotal--;
+      if (this.inFlightTotal === 0) this.drainResolvers.splice(0).forEach((r) => r());
+    });
+  }
+  waitForDrain(timeoutMs) {
+    if (this.inFlightTotal === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      let handle;
+      const onDrain = () => {
+        clearTimeout(handle);
+        resolve();
+      };
+      this.drainResolvers.push(onDrain);
+      handle = setTimeout(() => {
+        const idx = this.drainResolvers.indexOf(onDrain);
+        if (idx !== -1) this.drainResolvers.splice(idx, 1);
+        this.warn(
+          `Drain timed out after ${timeoutMs}ms \u2014 ${this.inFlightTotal} handler(s) still in flight`
+        );
+        resolve();
+      }, timeoutMs);
+    });
+  }
+};
+
+// src/client/kafka.client/index.ts
+var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = import_kafka_javascript2.KafkaJS;
+var _activeTransactionalIds = /* @__PURE__ */ new Set();
+var KafkaClient = class _KafkaClient {
+  kafka;
+  producer;
+  txProducer;
+  txProducerInitPromise;
+  /** Maps transactionalId → Producer for each active retry level consumer. */
+  retryTxProducers = /* @__PURE__ */ new Map();
+  consumers = /* @__PURE__ */ new Map();
+  logger;
+  autoCreateTopicsEnabled;
+  strictSchemasEnabled;
+  numPartitions;
+  ensuredTopics = /* @__PURE__ */ new Set();
+  /** Pending topic-creation promises keyed by topic name. Prevents duplicate createTopics calls. */
+  ensureTopicPromises = /* @__PURE__ */ new Map();
+  defaultGroupId;
+  schemaRegistry = /* @__PURE__ */ new Map();
+  runningConsumers = /* @__PURE__ */ new Map();
+  consumerCreationOptions = /* @__PURE__ */ new Map();
+  /** Maps each main consumer groupId to its companion retry level groupIds. */
+  companionGroupIds = /* @__PURE__ */ new Map();
+  instrumentation;
+  onMessageLost;
+  onTtlExpired;
+  onRebalance;
+  /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
+  txId;
+  /** Monotonically increasing Lamport clock stamped on every outgoing message. */
+  _lamportClock = 0;
+  /** Per-groupId deduplication state: `"topic:partition"` → last processed clock. */
+  dedupStates = /* @__PURE__ */ new Map();
+  circuitBreaker;
+  adminOps;
+  metrics;
+  inFlight;
+  clientId;
+  _producerOpsDeps;
+  _consumerOpsDeps;
+  _retryTopicDeps;
+  /** DLQ header keys added by the pipeline — stripped before re-publishing. */
+  static DLQ_HEADER_KEYS = /* @__PURE__ */ new Set([
+    "x-dlq-original-topic",
+    "x-dlq-failed-at",
+    "x-dlq-error-message",
+    "x-dlq-error-stack",
+    "x-dlq-attempt-count"
+  ]);
+  constructor(clientId, groupId, brokers, options) {
+    this.clientId = clientId;
+    this.defaultGroupId = groupId;
+    this.logger = options?.logger ?? {
+      log: (msg) => console.log(`[KafkaClient:${clientId}] ${msg}`),
+      warn: (msg, ...args) => console.warn(`[KafkaClient:${clientId}] ${msg}`, ...args),
+      error: (msg, ...args) => console.error(`[KafkaClient:${clientId}] ${msg}`, ...args),
+      debug: (msg, ...args) => console.debug(`[KafkaClient:${clientId}] ${msg}`, ...args)
+    };
+    this.autoCreateTopicsEnabled = options?.autoCreateTopics ?? false;
+    this.strictSchemasEnabled = options?.strictSchemas ?? true;
+    this.numPartitions = options?.numPartitions ?? 1;
+    this.instrumentation = options?.instrumentation ?? [];
+    this.onMessageLost = options?.onMessageLost;
+    this.onTtlExpired = options?.onTtlExpired;
+    this.onRebalance = options?.onRebalance;
+    this.txId = options?.transactionalId ?? `${clientId}-tx`;
+    this.kafka = new KafkaClass({
+      kafkaJS: {
+        clientId: this.clientId,
+        brokers,
+        logLevel: KafkaLogLevel.ERROR
+      }
+    });
+    this.producer = this.kafka.producer({ kafkaJS: { acks: -1 } });
+    this.adminOps = new AdminOps({
+      admin: this.kafka.admin(),
+      logger: this.logger,
+      runningConsumers: this.runningConsumers,
+      defaultGroupId: this.defaultGroupId,
+      clientId: this.clientId
+    });
+    this.circuitBreaker = new CircuitBreakerManager({
+      pauseConsumer: (gid, assignments) => this.pauseConsumer(gid, assignments),
+      resumeConsumer: (gid, assignments) => this.resumeConsumer(gid, assignments),
+      logger: this.logger,
+      instrumentation: this.instrumentation
+    });
+    this.metrics = new MetricsManager({
+      instrumentation: this.instrumentation,
+      onCircuitFailure: (envelope, gid) => this.circuitBreaker.onFailure(envelope, gid),
+      onCircuitSuccess: (envelope, gid) => this.circuitBreaker.onSuccess(envelope, gid)
+    });
+    this.inFlight = new InFlightTracker((msg) => this.logger.warn(msg));
+    this._producerOpsDeps = {
+      schemaRegistry: this.schemaRegistry,
+      strictSchemasEnabled: this.strictSchemasEnabled,
+      instrumentation: this.instrumentation,
+      logger: this.logger,
+      nextLamportClock: () => ++this._lamportClock
+    };
+    this._consumerOpsDeps = {
+      consumers: this.consumers,
+      consumerCreationOptions: this.consumerCreationOptions,
+      kafka: this.kafka,
+      onRebalance: this.onRebalance,
+      logger: this.logger
+    };
+    this._retryTopicDeps = this.buildRetryTopicDeps();
+  }
+  async sendMessage(topicOrDesc, message, options = {}) {
+    const payload = await this.preparePayload(
+      topicOrDesc,
+      [
+        {
+          value: message,
+          key: options.key,
+          headers: options.headers,
+          correlationId: options.correlationId,
+          schemaVersion: options.schemaVersion,
+          eventId: options.eventId
+        }
+      ],
+      options.compression
+    );
+    await this.producer.send(payload);
+    this.metrics.notifyAfterSend(payload.topic, payload.messages.length);
+  }
+  /**
+   * Send a null-value (tombstone) message. Used with log-compacted topics to signal
+   * that a key's record should be removed during the next compaction cycle.
+   *
+   * Tombstones skip envelope headers, schema validation, and Lamport clock stamping.
+   * Both `beforeSend` and `afterSend` instrumentation hooks are still called so tracing works correctly.
+   *
+   * @param topic Topic name.
+   * @param key Partition key identifying the record to tombstone.
+   * @param headers Optional custom Kafka headers.
+   */
+  async sendTombstone(topic2, key, headers) {
+    const hdrs = { ...headers };
+    for (const inst of this.instrumentation) inst.beforeSend?.(topic2, hdrs);
+    await this.ensureTopic(topic2);
+    await this.producer.send({ topic: topic2, messages: [{ value: null, key, headers: hdrs }] });
+    for (const inst of this.instrumentation) inst.afterSend?.(topic2);
+  }
+  async sendBatch(topicOrDesc, messages, options) {
+    const payload = await this.preparePayload(topicOrDesc, messages, options?.compression);
+    await this.producer.send(payload);
+    this.metrics.notifyAfterSend(payload.topic, payload.messages.length);
+  }
+  /** Execute multiple sends atomically. Commits on success, aborts on error. */
+  async transaction(fn) {
+    if (!this.txProducerInitPromise) {
+      if (_activeTransactionalIds.has(this.txId)) {
+        this.logger.warn(
+          `transactionalId "${this.txId}" is already in use by another KafkaClient in this process. Kafka will fence one of the producers. Set a unique \`transactionalId\` (or distinct \`clientId\`) per instance.`
+        );
+      }
+      const initPromise = (async () => {
+        const p = this.kafka.producer({
+          kafkaJS: { acks: -1, idempotent: true, transactionalId: this.txId, maxInFlightRequests: 1 }
+        });
+        await p.connect();
+        _activeTransactionalIds.add(this.txId);
+        return p;
+      })();
+      this.txProducerInitPromise = initPromise.catch((err) => {
+        this.txProducerInitPromise = void 0;
+        throw err;
+      });
+    }
+    this.txProducer = await this.txProducerInitPromise;
+    const tx = await this.txProducer.transaction();
+    try {
+      const ctx = {
+        send: async (topicOrDesc, message, options = {}) => {
+          const payload = await this.preparePayload(topicOrDesc, [
+            {
+              value: message,
+              key: options.key,
+              headers: options.headers,
+              correlationId: options.correlationId,
+              schemaVersion: options.schemaVersion,
+              eventId: options.eventId
+            }
+          ]);
+          await tx.send(payload);
+          this.metrics.notifyAfterSend(payload.topic, payload.messages.length);
+        },
+        sendBatch: async (topicOrDesc, messages) => {
+          const payload = await this.preparePayload(topicOrDesc, messages);
+          await tx.send(payload);
+          this.metrics.notifyAfterSend(payload.topic, payload.messages.length);
+        }
+      };
+      await fn(ctx);
+      await tx.commit();
+    } catch (error) {
+      try {
+        await tx.abort();
+      } catch (abortError) {
+        this.logger.error("Failed to abort transaction:", toError(abortError).message);
+      }
+      throw error;
+    }
+  }
+  // ── Producer lifecycle ───────────────────────────────────────────
+  /**
+   * Connect the idempotent producer. Called automatically by `KafkaModule.register()`.
+   * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
+   */
+  async connectProducer() {
+    await this.producer.connect();
+    this.logger.log("Producer connected");
+  }
+  /**
+   * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
+   */
+  async disconnectProducer() {
+    await this.producer.disconnect();
+    this.logger.log("Producer disconnected");
+  }
+  async startConsumer(topics, handleMessage, options = {}) {
+    this.validateTopicConsumerOpts(topics, options);
+    const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
+    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", setupOptions);
+    if (options.circuitBreaker) this.circuitBreaker.setConfig(gid, options.circuitBreaker);
+    const deps = this.messageDepsFor(gid);
+    const eosMainContext = await this.makeEosMainContext(gid, consumer, options);
+    await consumer.run({
+      eachMessage: (payload) => this.inFlight.track(
+        () => handleEachMessage(
+          payload,
+          {
+            schemaMap,
+            handleMessage,
+            interceptors,
+            dlq,
+            retry,
+            retryTopics: options.retryTopics,
+            timeoutMs: options.handlerTimeoutMs,
+            wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
+            deduplication: this.resolveDeduplicationContext(gid, options.deduplication),
+            messageTtlMs: options.messageTtlMs,
+            onTtlExpired: options.onTtlExpired,
+            eosMainContext
           },
           deps
         )
@@ -1484,54 +2079,24 @@ var KafkaClient = class _KafkaClient {
     });
     this.runningConsumers.set(gid, "eachMessage");
     if (options.retryTopics && retry) {
-      if (!this.autoCreateTopicsEnabled) {
-        await this.validateRetryTopicsExist(topicNames, retry.maxRetries);
-      }
-      const companions = await startRetryTopicConsumers(
-        topicNames,
-        gid,
-        handleMessage,
-        retry,
-        dlq,
-        interceptors,
-        schemaMap,
-        this.retryTopicDeps,
-        options.retryTopicAssignmentTimeoutMs
-      );
-      this.companionGroupIds.set(gid, companions);
+      await this.launchRetryChain(gid, topicNames, handleMessage, retry, dlq, interceptors, schemaMap, options.retryTopicAssignmentTimeoutMs);
     }
     return { groupId: gid, stop: () => this.stopConsumer(gid) };
   }
   async startBatchConsumer(topics, handleBatch, options = {}) {
-    if (options.retryTopics && !options.retry) {
-      throw new Error(
-        "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
-      );
-    }
-    if (options.retryTopics) {
-    } else if (options.autoCommit !== false) {
+    this.validateTopicConsumerOpts(topics, options);
+    if (!options.retryTopics && options.autoCommit !== false) {
       this.logger.debug?.(
         `startBatchConsumer: autoCommit is enabled (default true). If your handler calls resolveOffset() or commitOffsetsIfNecessary(), set autoCommit: false to avoid offset conflicts.`
       );
     }
     const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
     const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachBatch", setupOptions);
-    if (options.circuitBreaker)
-      this.circuitConfigs.set(gid, options.circuitBreaker);
+    if (options.circuitBreaker) this.circuitBreaker.setConfig(gid, options.circuitBreaker);
     const deps = this.messageDepsFor(gid);
-    const timeoutMs = options.handlerTimeoutMs;
-    const deduplication = this.resolveDeduplicationContext(
-      gid,
-      options.deduplication
-    );
-    let eosMainContext;
-    if (options.retryTopics && retry) {
-      const mainTxId = `${gid}-main-tx`;
-      const txProducer = await this.createRetryTxProducer(mainTxId);
-      eosMainContext = { txProducer, consumer };
-    }
+    const eosMainContext = await this.makeEosMainContext(gid, consumer, options);
     await consumer.run({
-      eachBatch: (payload) => this.trackInFlight(
+      eachBatch: (payload) => this.inFlight.track(
         () => handleEachBatch(
           payload,
           {
@@ -1541,10 +2106,11 @@ var KafkaClient = class _KafkaClient {
             dlq,
             retry,
             retryTopics: options.retryTopics,
-            timeoutMs,
+            timeoutMs: options.handlerTimeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
-            deduplication,
+            deduplication: this.resolveDeduplicationContext(gid, options.deduplication),
             messageTtlMs: options.messageTtlMs,
+            onTtlExpired: options.onTtlExpired,
             eosMainContext
           },
           deps
@@ -1553,9 +2119,6 @@ var KafkaClient = class _KafkaClient {
     });
     this.runningConsumers.set(gid, "eachBatch");
     if (options.retryTopics && retry) {
-      if (!this.autoCreateTopicsEnabled) {
-        await this.validateRetryTopicsExist(topicNames, retry.maxRetries);
-      }
       const handleMessageForRetry = (env) => handleBatch([env], {
         partition: env.partition,
         highWatermark: null,
@@ -1566,18 +2129,7 @@ var KafkaClient = class _KafkaClient {
         commitOffsetsIfNecessary: async () => {
         }
       });
-      const companions = await startRetryTopicConsumers(
-        topicNames,
-        gid,
-        handleMessageForRetry,
-        retry,
-        dlq,
-        interceptors,
-        schemaMap,
-        this.retryTopicDeps,
-        options.retryTopicAssignmentTimeoutMs
-      );
-      this.companionGroupIds.set(gid, companions);
+      await this.launchRetryChain(gid, topicNames, handleMessageForRetry, retry, dlq, interceptors, schemaMap, options.retryTopicAssignmentTimeoutMs);
     }
     return { groupId: gid, stop: () => this.stopConsumer(gid) };
   }
@@ -1591,6 +2143,11 @@ var KafkaClient = class _KafkaClient {
    * }
    */
   consume(topic2, options) {
+    if (options?.retryTopics) {
+      throw new Error(
+        "consume() does not support retryTopics (EOS retry chains). Use startConsumer() with retryTopics: true for guaranteed retry delivery."
+      );
+    }
     const gid = options?.groupId ?? this.defaultGroupId;
     const queue = new AsyncQueue(
       options?.queueHighWaterMark,
@@ -1619,42 +2176,32 @@ var KafkaClient = class _KafkaClient {
     };
   }
   // ── Consumer lifecycle ───────────────────────────────────────────
+  /**
+   * Stop all consumers or a specific group.
+   *
+   * If `groupId` is unspecified, all active consumers are stopped.
+   * If `groupId` is specified, only the consumer with that group ID is stopped.
+   *
+   * @throws {Error} if the consumer fails to disconnect.
+   */
   async stopConsumer(groupId) {
     if (groupId !== void 0) {
       const consumer = this.consumers.get(groupId);
       if (!consumer) {
-        this.logger.warn(
-          `stopConsumer: no active consumer for group "${groupId}"`
-        );
+        this.logger.warn(`stopConsumer: no active consumer for group "${groupId}"`);
         return;
       }
-      await consumer.disconnect().catch(
-        (e) => this.logger.warn(
-          `Error disconnecting consumer "${groupId}":`,
-          toError(e).message
-        )
-      );
+      await consumer.disconnect().catch((e) => this.logger.warn(`Error disconnecting consumer "${groupId}":`, toError(e).message));
       this.consumers.delete(groupId);
       this.runningConsumers.delete(groupId);
       this.consumerCreationOptions.delete(groupId);
       this.dedupStates.delete(groupId);
-      for (const key of [...this.circuitStates.keys()]) {
-        if (key.startsWith(`${groupId}:`)) {
-          clearTimeout(this.circuitStates.get(key).timer);
-          this.circuitStates.delete(key);
-        }
-      }
-      this.circuitConfigs.delete(groupId);
+      this.circuitBreaker.removeGroup(groupId);
       this.logger.log(`Consumer disconnected: group "${groupId}"`);
       const mainTxId = `${groupId}-main-tx`;
       const mainTxProducer = this.retryTxProducers.get(mainTxId);
       if (mainTxProducer) {
-        await mainTxProducer.disconnect().catch(
-          (e) => this.logger.warn(
-            `Error disconnecting main tx producer "${mainTxId}":`,
-            toError(e).message
-          )
-        );
+        await mainTxProducer.disconnect().catch((e) => this.logger.warn(`Error disconnecting main tx producer "${mainTxId}":`, toError(e).message));
         _activeTransactionalIds.delete(mainTxId);
         this.retryTxProducers.delete(mainTxId);
       }
@@ -1662,12 +2209,7 @@ var KafkaClient = class _KafkaClient {
       for (const cGroupId of companions) {
         const cConsumer = this.consumers.get(cGroupId);
         if (cConsumer) {
-          await cConsumer.disconnect().catch(
-            (e) => this.logger.warn(
-              `Error disconnecting retry consumer "${cGroupId}":`,
-              toError(e).message
-            )
-          );
+          await cConsumer.disconnect().catch((e) => this.logger.warn(`Error disconnecting retry consumer "${cGroupId}":`, toError(e).message));
           this.consumers.delete(cGroupId);
           this.runningConsumers.delete(cGroupId);
           this.consumerCreationOptions.delete(cGroupId);
@@ -1676,12 +2218,7 @@ var KafkaClient = class _KafkaClient {
         const txId = `${cGroupId}-tx`;
         const txProducer = this.retryTxProducers.get(txId);
         if (txProducer) {
-          await txProducer.disconnect().catch(
-            (e) => this.logger.warn(
-              `Error disconnecting retry tx producer "${txId}":`,
-              toError(e).message
-            )
-          );
+          await txProducer.disconnect().catch((e) => this.logger.warn(`Error disconnecting retry tx producer "${txId}":`, toError(e).message));
           _activeTransactionalIds.delete(txId);
           this.retryTxProducers.delete(txId);
         }
@@ -1689,14 +2226,10 @@ var KafkaClient = class _KafkaClient {
       this.companionGroupIds.delete(groupId);
     } else {
       const tasks = [
-        ...Array.from(this.consumers.values()).map(
-          (c) => c.disconnect().catch(() => {
-          })
-        ),
-        ...Array.from(this.retryTxProducers.values()).map(
-          (p) => p.disconnect().catch(() => {
-          })
-        )
+        ...Array.from(this.consumers.values()).map((c) => c.disconnect().catch(() => {
+        })),
+        ...Array.from(this.retryTxProducers.values()).map((p) => p.disconnect().catch(() => {
+        }))
       ];
       await Promise.allSettled(tasks);
       this.consumers.clear();
@@ -1705,13 +2238,16 @@ var KafkaClient = class _KafkaClient {
       this.companionGroupIds.clear();
       this.retryTxProducers.clear();
       this.dedupStates.clear();
-      for (const state of this.circuitStates.values())
-        clearTimeout(state.timer);
-      this.circuitStates.clear();
-      this.circuitConfigs.clear();
+      this.circuitBreaker.clear();
       this.logger.log("All consumers disconnected");
     }
   }
+  /**
+   * Temporarily stop delivering messages from specific partitions without disconnecting the consumer.
+   *
+   * @param groupId Consumer group to pause. Defaults to the client's default groupId.
+   * @param assignments Topic-partition pairs to pause.
+   */
   pauseConsumer(groupId, assignments) {
     const gid = groupId ?? this.defaultGroupId;
     const consumer = this.consumers.get(gid);
@@ -1720,11 +2256,15 @@ var KafkaClient = class _KafkaClient {
       return;
     }
     consumer.pause(
-      assignments.flatMap(
-        ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
-      )
+      assignments.flatMap(({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] })))
     );
   }
+  /**
+   * Resume message delivery for previously paused topic-partitions.
+   *
+   * @param {string|undefined} groupId Consumer group to resume. Defaults to the client's default groupId.
+   * @param {Array<{ topic: string; partitions: number[] }>} assignments Topic-partition pairs to resume.
+   */
   resumeConsumer(groupId, assignments) {
     const gid = groupId ?? this.defaultGroupId;
     const consumer = this.consumers.get(gid);
@@ -1733,9 +2273,7 @@ var KafkaClient = class _KafkaClient {
       return;
     }
     consumer.resume(
-      assignments.flatMap(
-        ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
-      )
+      assignments.flatMap(({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] })))
     );
   }
   /** Pause all assigned partitions of a topic for a consumer group (used for queue backpressure). */
@@ -1756,115 +2294,39 @@ var KafkaClient = class _KafkaClient {
     if (partitions.length > 0)
       consumer.resume(partitions.map((p) => ({ topic: topic2, partitions: [p] })));
   }
-  /** DLQ header keys added by `sendToDlq` — stripped before re-publishing. */
-  static DLQ_HEADER_KEYS = /* @__PURE__ */ new Set([
-    "x-dlq-original-topic",
-    "x-dlq-failed-at",
-    "x-dlq-error-message",
-    "x-dlq-error-stack",
-    "x-dlq-attempt-count"
-  ]);
+  /**
+   * Re-publish messages from a dead letter queue back to the original topic.
+   *
+   * Messages are consumed from `<topic>.dlq` and re-published to `<topic>`.
+   * The original topic is determined by the `x-dlq-original-topic` header.
+   * The `x-dlq-*` headers are stripped before re-publishing.
+   *
+   * @param topic - The topic to replay from `<topic>.dlq`
+   * @param options - Options for replay
+   * @returns { replayed: number; skipped: number } - counts of re-published vs skipped messages
+   */
   async replayDlq(topic2, options = {}) {
-    const dlqTopic = `${topic2}.dlq`;
-    await this.ensureAdminConnected();
-    const partitionOffsets = await this.admin.fetchTopicOffsets(dlqTopic);
-    const activePartitions = partitionOffsets.filter(
-      (p) => parseInt(p.high, 10) > 0
-    );
-    if (activePartitions.length === 0) {
-      this.logger.log(`replayDlq: "${dlqTopic}" is empty \u2014 nothing to replay`);
-      return { replayed: 0, skipped: 0 };
-    }
-    const highWatermarks = new Map(
-      activePartitions.map(({ partition, high }) => [
-        partition,
-        parseInt(high, 10)
-      ])
-    );
-    const processedOffsets = /* @__PURE__ */ new Map();
-    let replayed = 0;
-    let skipped = 0;
-    const tempGroupId = `${dlqTopic}-replay-${Date.now()}`;
-    await new Promise((resolve, reject) => {
-      const consumer = getOrCreateConsumer(
-        tempGroupId,
-        true,
-        true,
-        this.consumerOpsDeps
-      );
-      const cleanup = () => {
+    await this.adminOps.ensureConnected();
+    return replayDlqTopic(topic2, options, {
+      logger: this.logger,
+      fetchTopicOffsets: (t) => this.adminOps.admin.fetchTopicOffsets(t),
+      send: async (t, messages) => {
+        await this.producer.send({ topic: t, messages });
+      },
+      createConsumer: (gid) => getOrCreateConsumer(gid, true, true, this._consumerOpsDeps),
+      cleanupConsumer: (consumer, gid) => {
         consumer.disconnect().catch(() => {
         }).finally(() => {
-          this.consumers.delete(tempGroupId);
-          this.runningConsumers.delete(tempGroupId);
-          this.consumerCreationOptions.delete(tempGroupId);
+          this.consumers.delete(gid);
+          this.runningConsumers.delete(gid);
+          this.consumerCreationOptions.delete(gid);
         });
-      };
-      consumer.connect().then(() => subscribeWithRetry(consumer, [dlqTopic], this.logger)).then(
-        () => consumer.run({
-          eachMessage: async ({ partition, message }) => {
-            if (!message.value) return;
-            const offset = parseInt(message.offset, 10);
-            processedOffsets.set(partition, offset);
-            const headers = decodeHeaders(message.headers);
-            const targetTopic = options.targetTopic ?? headers["x-dlq-original-topic"];
-            const originalHeaders = Object.fromEntries(
-              Object.entries(headers).filter(
-                ([k]) => !_KafkaClient.DLQ_HEADER_KEYS.has(k)
-              )
-            );
-            const value = message.value.toString();
-            const shouldProcess = !options.filter || options.filter(headers, value);
-            if (!targetTopic || !shouldProcess) {
-              skipped++;
-            } else if (options.dryRun) {
-              this.logger.log(
-                `[DLQ replay dry-run] Would replay to "${targetTopic}"`
-              );
-              replayed++;
-            } else {
-              await this.producer.send({
-                topic: targetTopic,
-                messages: [{ value, headers: originalHeaders }]
-              });
-              replayed++;
-            }
-            const allDone = Array.from(highWatermarks.entries()).every(
-              ([p, hwm]) => (processedOffsets.get(p) ?? -1) >= hwm - 1
-            );
-            if (allDone) {
-              cleanup();
-              resolve();
-            }
-          }
-        })
-      ).catch((err) => {
-        cleanup();
-        reject(err);
-      });
+      },
+      dlqHeaderKeys: _KafkaClient.DLQ_HEADER_KEYS
     });
-    this.logger.log(
-      `replayDlq: replayed ${replayed}, skipped ${skipped} from "${dlqTopic}"`
-    );
-    return { replayed, skipped };
   }
   async resetOffsets(groupId, topic2, position) {
-    const gid = groupId ?? this.defaultGroupId;
-    if (this.runningConsumers.has(gid)) {
-      throw new Error(
-        `resetOffsets: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before resetting offsets.`
-      );
-    }
-    await this.ensureAdminConnected();
-    const partitionOffsets = await this.admin.fetchTopicOffsets(topic2);
-    const partitions = partitionOffsets.map(({ partition, low, high }) => ({
-      partition,
-      offset: position === "earliest" ? low : high
-    }));
-    await this.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
-    this.logger.log(
-      `Offsets reset to ${position} for group "${gid}" on topic "${topic2}"`
-    );
+    return this.adminOps.resetOffsets(groupId, topic2, position);
   }
   /**
    * Seek specific topic-partition pairs to explicit offsets for a stopped consumer group.
@@ -1872,68 +2334,32 @@ var KafkaClient = class _KafkaClient {
    * Assignments are grouped by topic and committed via `admin.setOffsets`.
    */
   async seekToOffset(groupId, assignments) {
-    const gid = groupId ?? this.defaultGroupId;
-    if (this.runningConsumers.has(gid)) {
-      throw new Error(
-        `seekToOffset: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before seeking offsets.`
-      );
-    }
-    await this.ensureAdminConnected();
-    const byTopic = /* @__PURE__ */ new Map();
-    for (const { topic: topic2, partition, offset } of assignments) {
-      const list = byTopic.get(topic2) ?? [];
-      list.push({ partition, offset });
-      byTopic.set(topic2, list);
-    }
-    for (const [topic2, partitions] of byTopic) {
-      await this.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
-      this.logger.log(
-        `Offsets set for group "${gid}" on "${topic2}": ${JSON.stringify(partitions)}`
-      );
-    }
+    return this.adminOps.seekToOffset(groupId, assignments);
   }
+  /**
+   * Seek specific topic-partition pairs to the offset nearest to a given timestamp
+   * (in milliseconds) for a stopped consumer group.
+   * Throws if the group is still running — call `stopConsumer(groupId)` first.
+   * Assignments are grouped by topic and committed via `admin.setOffsets`.
+   * If no offset exists at the requested timestamp (e.g. empty partition or
+   * future timestamp), the partition falls back to `-1` (end of topic — new messages only).
+   */
   async seekToTimestamp(groupId, assignments) {
-    const gid = groupId ?? this.defaultGroupId;
-    if (this.runningConsumers.has(gid)) {
-      throw new Error(
-        `seekToTimestamp: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before seeking offsets.`
-      );
-    }
-    await this.ensureAdminConnected();
-    const byTopic = /* @__PURE__ */ new Map();
-    for (const { topic: topic2, partition, timestamp } of assignments) {
-      const list = byTopic.get(topic2) ?? [];
-      list.push({ partition, timestamp });
-      byTopic.set(topic2, list);
-    }
-    for (const [topic2, parts] of byTopic) {
-      const offsets = await Promise.all(
-        parts.map(async ({ partition, timestamp }) => {
-          const results = await this.admin.fetchTopicOffsetsByTime(
-            topic2,
-            timestamp
-          );
-          const found = results.find(
-            (r) => r.partition === partition
-          );
-          return { partition, offset: found?.offset ?? "-1" };
-        })
-      );
-      await this.admin.setOffsets({ groupId: gid, topic: topic2, partitions: offsets });
-      this.logger.log(
-        `Offsets set by timestamp for group "${gid}" on "${topic2}": ${JSON.stringify(offsets)}`
-      );
-    }
+    return this.adminOps.seekToTimestamp(groupId, assignments);
   }
+  /**
+   * Returns the current circuit breaker state for a specific topic partition.
+   * Returns `undefined` when no circuit state exists — either `circuitBreaker` is not
+   * configured for the group, or the circuit has never been tripped.
+   *
+   * @param topic Topic name.
+   * @param partition Partition index.
+   * @param groupId Consumer group. Defaults to the client's default groupId.
+   *
+   * @returns `{ status, failures, windowSize }` snapshot for a given partition or `undefined` if no state exists.
+   */
   getCircuitState(topic2, partition, groupId) {
-    const gid = groupId ?? this.defaultGroupId;
-    const state = this.circuitStates.get(`${gid}:${topic2}:${partition}`);
-    if (!state) return void 0;
-    return {
-      status: state.status,
-      failures: state.window.filter((v) => !v).length,
-      windowSize: state.window.length
-    };
+    return this.circuitBreaker.getState(topic2, partition, groupId ?? this.defaultGroupId);
   }
   /**
    * Query consumer group lag per partition.
@@ -1947,73 +2373,60 @@ var KafkaClient = class _KafkaClient {
    * committed offset. Use `checkStatus()` to verify broker connectivity in that case.
    */
   async getConsumerLag(groupId) {
-    const gid = groupId ?? this.defaultGroupId;
-    await this.ensureAdminConnected();
-    const committedByTopic = await this.admin.fetchOffsets({ groupId: gid });
-    const brokerOffsetsAll = await Promise.all(
-      committedByTopic.map(({ topic: topic2 }) => this.admin.fetchTopicOffsets(topic2))
-    );
-    const result = [];
-    for (let i = 0; i < committedByTopic.length; i++) {
-      const { topic: topic2, partitions } = committedByTopic[i];
-      const brokerOffsets = brokerOffsetsAll[i];
-      for (const { partition, offset } of partitions) {
-        const broker = brokerOffsets.find((o) => o.partition === partition);
-        if (!broker) continue;
-        const committed = parseInt(offset, 10);
-        const high = parseInt(broker.high, 10);
-        const lag = committed === -1 ? high : Math.max(0, high - committed);
-        result.push({ topic: topic2, partition, lag });
-      }
-    }
-    return result;
+    return this.adminOps.getConsumerLag(groupId);
   }
   /** Check broker connectivity. Never throws — returns a discriminated union. */
   async checkStatus() {
-    try {
-      await this.ensureAdminConnected();
-      const topics = await this.admin.listTopics();
-      return { status: "up", clientId: this.clientId, topics };
-    } catch (error) {
-      return {
-        status: "down",
-        clientId: this.clientId,
-        error: error instanceof Error ? error.message : String(error)
-      };
-    }
+    return this.adminOps.checkStatus();
+  }
+  /**
+   * List all consumer groups known to the broker.
+   * Useful for monitoring which groups are active and their current state.
+   */
+  async listConsumerGroups() {
+    return this.adminOps.listConsumerGroups();
   }
+  /**
+   * Describe topics — returns partition layout, leader, replicas, and ISR.
+   * @param topics Topic names to describe. Omit to describe all topics.
+   */
+  async describeTopics(topics) {
+    return this.adminOps.describeTopics(topics);
+  }
+  /**
+   * Delete records from a topic up to (but not including) the given offsets.
+   * All messages with offsets **before** the given offset are deleted.
+   */
+  async deleteRecords(topic2, partitions) {
+    return this.adminOps.deleteRecords(topic2, partitions);
+  }
+  /** Return the client ID provided during `KafkaClient` construction. */
   getClientId() {
     return this.clientId;
   }
+  /**
+   * Return a snapshot of internal event counters accumulated since client creation
+   * (or since the last `resetMetrics()` call).
+   *
+   * @param topic Topic name to scope the snapshot to. When omitted, counters are
+   *   aggregated across all topics. If the topic has no recorded events yet, returns
+   *   a zero-valued snapshot.
+   * @returns Read-only `KafkaMetrics` snapshot: `processedCount`, `retryCount`, `dlqCount`, `dedupCount`.
+   */
   getMetrics(topic2) {
-    if (topic2 !== void 0) {
-      const m = this._topicMetrics.get(topic2);
-      return m ? { ...m } : { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
-    }
-    const agg = {
-      processedCount: 0,
-      retryCount: 0,
-      dlqCount: 0,
-      dedupCount: 0
-    };
-    for (const m of this._topicMetrics.values()) {
-      agg.processedCount += m.processedCount;
-      agg.retryCount += m.retryCount;
-      agg.dlqCount += m.dlqCount;
-      agg.dedupCount += m.dedupCount;
-    }
-    return agg;
+    return this.metrics.getMetrics(topic2);
   }
+  /**
+   * Reset internal event counters to zero.
+   *
+   * @param topic Topic name to reset. When omitted, all topics are reset.
+   */
   resetMetrics(topic2) {
-    if (topic2 !== void 0) {
-      this._topicMetrics.delete(topic2);
-      return;
-    }
-    this._topicMetrics.clear();
+    this.metrics.resetMetrics(topic2);
   }
   /** Gracefully disconnect producer, all consumers, and admin. */
   async disconnect(drainTimeoutMs = 3e4) {
-    await this.waitForDrain(drainTimeoutMs);
+    await this.inFlight.waitForDrain(drainTimeoutMs);
     const tasks = [this.producer.disconnect()];
     if (this.txProducer) {
       tasks.push(this.txProducer.disconnect());
@@ -2021,28 +2434,17 @@ var KafkaClient = class _KafkaClient {
       this.txProducer = void 0;
       this.txProducerInitPromise = void 0;
     }
-    for (const txId of this.retryTxProducers.keys()) {
-      _activeTransactionalIds.delete(txId);
-    }
-    for (const p of this.retryTxProducers.values()) {
-      tasks.push(p.disconnect());
-    }
+    for (const txId of this.retryTxProducers.keys()) _activeTransactionalIds.delete(txId);
+    for (const p of this.retryTxProducers.values()) tasks.push(p.disconnect());
     this.retryTxProducers.clear();
-    for (const consumer of this.consumers.values()) {
-      tasks.push(consumer.disconnect());
-    }
-    if (this.isAdminConnected) {
-      tasks.push(this.admin.disconnect());
-      this.isAdminConnected = false;
-    }
+    for (const consumer of this.consumers.values()) tasks.push(consumer.disconnect());
+    tasks.push(this.adminOps.disconnect());
     await Promise.allSettled(tasks);
     this.consumers.clear();
     this.runningConsumers.clear();
     this.consumerCreationOptions.clear();
     this.companionGroupIds.clear();
-    for (const state of this.circuitStates.values()) clearTimeout(state.timer);
-    this.circuitStates.clear();
-    this.circuitConfigs.clear();
+    this.circuitBreaker.clear();
     this.logger.log("All connections closed");
   }
   // ── Graceful shutdown ────────────────────────────────────────────
@@ -2061,183 +2463,20 @@ var KafkaClient = class _KafkaClient {
    */
   enableGracefulShutdown(signals = ["SIGTERM", "SIGINT"], drainTimeoutMs = 3e4) {
     const handler = () => {
-      this.logger.log(
-        "Shutdown signal received \u2014 draining in-flight handlers..."
-      );
+      this.logger.log("Shutdown signal received \u2014 draining in-flight handlers...");
       this.disconnect(drainTimeoutMs).catch(
-        (err) => this.logger.error(
-          "Error during graceful shutdown:",
-          toError(err).message
-        )
+        (err) => this.logger.error("Error during graceful shutdown:", toError(err).message)
       );
     };
-    for (const signal of signals) {
-      process.once(signal, handler);
-    }
-  }
-  trackInFlight(fn) {
-    this.inFlightTotal++;
-    return fn().finally(() => {
-      this.inFlightTotal--;
-      if (this.inFlightTotal === 0) {
-        this.drainResolvers.splice(0).forEach((r) => r());
-      }
-    });
-  }
-  waitForDrain(timeoutMs) {
-    if (this.inFlightTotal === 0) return Promise.resolve();
-    return new Promise((resolve) => {
-      let handle;
-      const onDrain = () => {
-        clearTimeout(handle);
-        resolve();
-      };
-      this.drainResolvers.push(onDrain);
-      handle = setTimeout(() => {
-        const idx = this.drainResolvers.indexOf(onDrain);
-        if (idx !== -1) this.drainResolvers.splice(idx, 1);
-        this.logger.warn(
-          `Drain timed out after ${timeoutMs}ms \u2014 ${this.inFlightTotal} handler(s) still in flight`
-        );
-        resolve();
-      }, timeoutMs);
-    });
+    for (const signal of signals) process.once(signal, handler);
   }
   // ── Private helpers ──────────────────────────────────────────────
-  async preparePayload(topicOrDesc, messages) {
+  async preparePayload(topicOrDesc, messages, compression) {
     registerSchema(topicOrDesc, this.schemaRegistry, this.logger);
-    const payload = await buildSendPayload(
-      topicOrDesc,
-      messages,
-      this.producerOpsDeps
-    );
+    const payload = await buildSendPayload(topicOrDesc, messages, this._producerOpsDeps, compression);
     await this.ensureTopic(payload.topic);
     return payload;
   }
-  // afterSend is called once per message — symmetric with beforeSend in buildSendPayload.
-  notifyAfterSend(topic2, count) {
-    for (let i = 0; i < count; i++) {
-      for (const inst of this.instrumentation) {
-        inst.afterSend?.(topic2);
-      }
-    }
-  }
-  metricsFor(topic2) {
-    let m = this._topicMetrics.get(topic2);
-    if (!m) {
-      m = { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
-      this._topicMetrics.set(topic2, m);
-    }
-    return m;
-  }
-  notifyRetry(envelope, attempt, maxRetries) {
-    this.metricsFor(envelope.topic).retryCount++;
-    for (const inst of this.instrumentation) {
-      inst.onRetry?.(envelope, attempt, maxRetries);
-    }
-  }
-  notifyDlq(envelope, reason, gid) {
-    this.metricsFor(envelope.topic).dlqCount++;
-    for (const inst of this.instrumentation) {
-      inst.onDlq?.(envelope, reason);
-    }
-    if (!gid) return;
-    const cfg = this.circuitConfigs.get(gid);
-    if (!cfg) return;
-    const threshold = cfg.threshold ?? 5;
-    const recoveryMs = cfg.recoveryMs ?? 3e4;
-    const stateKey = `${gid}:${envelope.topic}:${envelope.partition}`;
-    let state = this.circuitStates.get(stateKey);
-    if (!state) {
-      state = { status: "closed", window: [], successes: 0 };
-      this.circuitStates.set(stateKey, state);
-    }
-    if (state.status === "open") return;
-    const openCircuit = () => {
-      state.status = "open";
-      state.window = [];
-      state.successes = 0;
-      clearTimeout(state.timer);
-      for (const inst of this.instrumentation)
-        inst.onCircuitOpen?.(envelope.topic, envelope.partition);
-      this.pauseConsumer(gid, [
-        { topic: envelope.topic, partitions: [envelope.partition] }
-      ]);
-      state.timer = setTimeout(() => {
-        state.status = "half-open";
-        state.successes = 0;
-        this.logger.log(
-          `[CircuitBreaker] HALF-OPEN \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
-        );
-        for (const inst of this.instrumentation)
-          inst.onCircuitHalfOpen?.(envelope.topic, envelope.partition);
-        this.resumeConsumer(gid, [
-          { topic: envelope.topic, partitions: [envelope.partition] }
-        ]);
-      }, recoveryMs);
-    };
-    if (state.status === "half-open") {
-      clearTimeout(state.timer);
-      this.logger.warn(
-        `[CircuitBreaker] OPEN (half-open failure) \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
-      );
-      openCircuit();
-      return;
-    }
-    const windowSize = cfg.windowSize ?? Math.max(threshold * 2, 10);
-    state.window = [...state.window, false];
-    if (state.window.length > windowSize) {
-      state.window = state.window.slice(state.window.length - windowSize);
-    }
-    const failures = state.window.filter((v) => !v).length;
-    if (failures >= threshold) {
-      this.logger.warn(
-        `[CircuitBreaker] OPEN \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition} (${failures}/${state.window.length} failures, threshold=${threshold})`
-      );
-      openCircuit();
-    }
-  }
-  notifyDuplicate(envelope, strategy) {
-    this.metricsFor(envelope.topic).dedupCount++;
-    for (const inst of this.instrumentation) {
-      inst.onDuplicate?.(envelope, strategy);
-    }
-  }
-  notifyMessage(envelope, gid) {
-    this.metricsFor(envelope.topic).processedCount++;
-    for (const inst of this.instrumentation) {
-      inst.onMessage?.(envelope);
-    }
-    if (!gid) return;
-    const cfg = this.circuitConfigs.get(gid);
-    if (!cfg) return;
-    const stateKey = `${gid}:${envelope.topic}:${envelope.partition}`;
-    const state = this.circuitStates.get(stateKey);
-    if (!state) return;
-    const halfOpenSuccesses = cfg.halfOpenSuccesses ?? 1;
-    if (state.status === "half-open") {
-      state.successes++;
-      if (state.successes >= halfOpenSuccesses) {
-        clearTimeout(state.timer);
-        state.timer = void 0;
-        state.status = "closed";
-        state.window = [];
-        state.successes = 0;
-        this.logger.log(
-          `[CircuitBreaker] CLOSED \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
-        );
-        for (const inst of this.instrumentation)
-          inst.onCircuitClose?.(envelope.topic, envelope.partition);
-      }
-    } else if (state.status === "closed") {
-      const threshold = cfg.threshold ?? 5;
-      const windowSize = cfg.windowSize ?? Math.max(threshold * 2, 10);
-      state.window = [...state.window, true];
-      if (state.window.length > windowSize) {
-        state.window = state.window.slice(state.window.length - windowSize);
-      }
-    }
-  }
   /**
    * Start a timer that logs a warning if `fn` hasn't resolved within `timeoutMs`.
    * The handler itself is not cancelled — the warning is diagnostic only.
@@ -2248,79 +2487,10 @@ var KafkaClient = class _KafkaClient {
       if (timer !== void 0) clearTimeout(timer);
     });
     timer = setTimeout(() => {
-      this.logger.warn(
-        `Handler for topic "${topic2}" has not resolved after ${timeoutMs}ms \u2014 possible stuck handler`
-      );
+      this.logger.warn(`Handler for topic "${topic2}" has not resolved after ${timeoutMs}ms \u2014 possible stuck handler`);
     }, timeoutMs);
     return promise;
   }
-  /**
-   * When `retryTopics: true` and `autoCreateTopics: false`, verify that every
-   * `<topic>.retry.<level>` topic already exists. Throws a clear error at startup
-   * rather than silently discovering missing topics on the first handler failure.
-   */
-  async validateRetryTopicsExist(topicNames, maxRetries) {
-    await this.ensureAdminConnected();
-    const existing = new Set(await this.admin.listTopics());
-    const missing = [];
-    for (const t of topicNames) {
-      for (let level = 1; level <= maxRetries; level++) {
-        const retryTopic = `${t}.retry.${level}`;
-        if (!existing.has(retryTopic)) missing.push(retryTopic);
-      }
-    }
-    if (missing.length > 0) {
-      throw new Error(
-        `retryTopics: true but the following retry topics do not exist: ${missing.join(", ")}. Create them manually or set autoCreateTopics: true.`
-      );
-    }
-  }
-  /**
-   * When `autoCreateTopics` is disabled, verify that `<topic>.dlq` exists for every
-   * consumed topic. Throws a clear error at startup rather than silently discovering
-   * missing DLQ topics on the first handler failure.
-   */
-  async validateDlqTopicsExist(topicNames) {
-    await this.ensureAdminConnected();
-    const existing = new Set(await this.admin.listTopics());
-    const missing = topicNames.filter((t) => !existing.has(`${t}.dlq`)).map((t) => `${t}.dlq`);
-    if (missing.length > 0) {
-      throw new Error(
-        `dlq: true but the following DLQ topics do not exist: ${missing.join(", ")}. Create them manually or set autoCreateTopics: true.`
-      );
-    }
-  }
-  /**
-   * When `deduplication.strategy: 'topic'` and `autoCreateTopics: false`, verify
-   * that every `<topic>.duplicates` destination topic already exists. Throws a
-   * clear error at startup rather than silently dropping duplicates on first hit.
-   */
-  async validateDuplicatesTopicsExist(topicNames, customDestination) {
-    await this.ensureAdminConnected();
-    const existing = new Set(await this.admin.listTopics());
-    const toCheck = customDestination ? [customDestination] : topicNames.map((t) => `${t}.duplicates`);
-    const missing = toCheck.filter((t) => !existing.has(t));
-    if (missing.length > 0) {
-      throw new Error(
-        `deduplication.strategy: 'topic' but the following duplicate-routing topics do not exist: ${missing.join(", ")}. Create them manually or set autoCreateTopics: true.`
-      );
-    }
-  }
-  /**
-   * Connect the admin client if not already connected.
-   * The flag is only set to `true` after a successful connect — if `admin.connect()`
-   * throws the flag remains `false` so the next call will retry the connection.
-   */
-  async ensureAdminConnected() {
-    if (this.isAdminConnected) return;
-    try {
-      await this.admin.connect();
-      this.isAdminConnected = true;
-    } catch (err) {
-      this.isAdminConnected = false;
-      throw err;
-    }
-  }
   /**
    * Create and connect a transactional producer for EOS retry routing.
    * Each retry level consumer gets its own producer with a unique `transactionalId`
@@ -2333,25 +2503,25 @@ var KafkaClient = class _KafkaClient {
       );
     }
     const p = this.kafka.producer({
-      kafkaJS: {
-        acks: -1,
-        idempotent: true,
-        transactionalId,
-        maxInFlightRequests: 1
-      }
+      kafkaJS: { acks: -1, idempotent: true, transactionalId, maxInFlightRequests: 1 }
     });
     await p.connect();
     _activeTransactionalIds.add(transactionalId);
     this.retryTxProducers.set(transactionalId, p);
     return p;
   }
+  /**
+   * Ensure that a topic exists by creating it if it doesn't already exist.
+   * If `autoCreateTopics` is disabled, returns immediately.
+   * Concurrent calls for the same topic are deduplicated.
+   */
   async ensureTopic(topic2) {
     if (!this.autoCreateTopicsEnabled || this.ensuredTopics.has(topic2)) return;
     let p = this.ensureTopicPromises.get(topic2);
     if (!p) {
       p = (async () => {
-        await this.ensureAdminConnected();
-        await this.admin.createTopics({
+        await this.adminOps.ensureConnected();
+        await this.adminOps.admin.createTopics({
           topics: [{ topic: topic2, numPartitions: this.numPartitions }]
         });
         this.ensuredTopics.add(topic2);
@@ -2370,6 +2540,9 @@ var KafkaClient = class _KafkaClient {
       interceptors = [],
       schemas: optionSchemas
     } = options;
+    const stringTopics = topics.filter((t) => !(t instanceof RegExp));
+    const regexTopics = topics.filter((t) => t instanceof RegExp);
+    const hasRegex = regexTopics.length > 0;
     const gid = optGroupId || this.defaultGroupId;
     const existingMode = this.runningConsumers.get(gid);
     const oppositeMode = mode === "eachMessage" ? "eachBatch" : "eachMessage";
@@ -2388,75 +2561,78 @@ var KafkaClient = class _KafkaClient {
       gid,
       fromBeginning,
       options.autoCommit ?? true,
-      this.consumerOpsDeps
-    );
-    const schemaMap = buildSchemaMap(
-      topics,
-      this.schemaRegistry,
-      optionSchemas,
-      this.logger
+      this._consumerOpsDeps,
+      options.partitionAssigner
     );
-    const topicNames = topics.map((t) => resolveTopicName(t));
-    for (const t of topicNames) {
-      await this.ensureTopic(t);
-    }
+    const schemaMap = buildSchemaMap(stringTopics, this.schemaRegistry, optionSchemas, this.logger);
+    const topicNames = stringTopics.map((t) => resolveTopicName(t));
+    const subscribeTopics = [...topicNames, ...regexTopics];
+    for (const t of topicNames) await this.ensureTopic(t);
     if (dlq) {
-      for (const t of topicNames) {
-        await this.ensureTopic(`${t}.dlq`);
-      }
-      if (!this.autoCreateTopicsEnabled) {
-        await this.validateDlqTopicsExist(topicNames);
+      for (const t of topicNames) await this.ensureTopic(`${t}.dlq`);
+      if (!this.autoCreateTopicsEnabled && topicNames.length > 0) {
+        await this.adminOps.validateDlqTopicsExist(topicNames);
       }
     }
     if (options.deduplication?.strategy === "topic") {
       const dest = options.deduplication.duplicatesTopic;
       if (this.autoCreateTopicsEnabled) {
-        for (const t of topicNames) {
-          await this.ensureTopic(dest ?? `${t}.duplicates`);
-        }
-      } else {
-        await this.validateDuplicatesTopicsExist(topicNames, dest);
+        for (const t of topicNames) await this.ensureTopic(dest ?? `${t}.duplicates`);
+      } else if (topicNames.length > 0) {
+        await this.adminOps.validateDuplicatesTopicsExist(topicNames, dest);
       }
     }
     await consumer.connect();
-    await subscribeWithRetry(
-      consumer,
-      topicNames,
-      this.logger,
-      options.subscribeRetry
-    );
-    this.logger.log(
-      `${mode === "eachBatch" ? "Batch consumer" : "Consumer"} subscribed to topics: ${topicNames.join(", ")}`
-    );
-    return { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry };
+    await subscribeWithRetry(consumer, subscribeTopics, this.logger, options.subscribeRetry);
+    const displayTopics = subscribeTopics.map((t) => t instanceof RegExp ? t.toString() : t).join(", ");
+    this.logger.log(`${mode === "eachBatch" ? "Batch consumer" : "Consumer"} subscribed to topics: ${displayTopics}`);
+    return { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry, hasRegex };
   }
   /** Create or retrieve the deduplication context for a consumer group. */
   resolveDeduplicationContext(groupId, options) {
     if (!options) return void 0;
-    if (!this.dedupStates.has(groupId)) {
-      this.dedupStates.set(groupId, /* @__PURE__ */ new Map());
-    }
+    if (!this.dedupStates.has(groupId)) this.dedupStates.set(groupId, /* @__PURE__ */ new Map());
     return { options, state: this.dedupStates.get(groupId) };
   }
-  // ── Deps object getters ──────────────────────────────────────────
-  get producerOpsDeps() {
-    return {
-      schemaRegistry: this.schemaRegistry,
-      strictSchemasEnabled: this.strictSchemasEnabled,
-      instrumentation: this.instrumentation,
-      logger: this.logger,
-      nextLamportClock: () => ++this._lamportClock
-    };
+  // ── Shared consumer setup helpers ────────────────────────────────
+  /** Guard checks shared by startConsumer and startBatchConsumer. */
+  validateTopicConsumerOpts(topics, options) {
+    if (options.retryTopics && !options.retry) {
+      throw new Error(
+        "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
+      );
+    }
+    if (options.retryTopics && topics.some((t) => t instanceof RegExp)) {
+      throw new Error(
+        "retryTopics is incompatible with regex topic patterns \u2014 retry topics require a fixed topic name to build the retry chain."
+      );
+    }
   }
-  get consumerOpsDeps() {
-    return {
-      consumers: this.consumers,
-      consumerCreationOptions: this.consumerCreationOptions,
-      kafka: this.kafka,
-      onRebalance: this.onRebalance,
-      logger: this.logger
-    };
+  /** Create EOS transactional producer context for atomic main → retry.1 routing. */
+  async makeEosMainContext(gid, consumer, options) {
+    if (!options.retryTopics || !options.retry) return void 0;
+    const txProducer = await this.createRetryTxProducer(`${gid}-main-tx`);
+    return { txProducer, consumer };
+  }
+  /** Start companion retry-level consumers and register them under the main groupId. */
+  async launchRetryChain(gid, topicNames, handleMessage, retry, dlq, interceptors, schemaMap, assignmentTimeoutMs) {
+    if (!this.autoCreateTopicsEnabled) {
+      await this.adminOps.validateRetryTopicsExist(topicNames, retry.maxRetries);
+    }
+    const companions = await startRetryTopicConsumers(
+      topicNames,
+      gid,
+      handleMessage,
+      retry,
+      dlq,
+      interceptors,
+      schemaMap,
+      this._retryTopicDeps,
+      assignmentTimeoutMs
+    );
+    this.companionGroupIds.set(gid, companions);
   }
+  // ── Deps object builders ─────────────────────────────────────────
   /** Build MessageHandlerDeps with circuit breaker callbacks bound to the given groupId. */
   messageDepsFor(gid) {
     return {
@@ -2465,23 +2641,24 @@ var KafkaClient = class _KafkaClient {
       instrumentation: this.instrumentation,
       onMessageLost: this.onMessageLost,
       onTtlExpired: this.onTtlExpired,
-      onRetry: this.notifyRetry.bind(this),
-      onDlq: (envelope, reason) => this.notifyDlq(envelope, reason, gid),
-      onDuplicate: this.notifyDuplicate.bind(this),
-      onMessage: (envelope) => this.notifyMessage(envelope, gid)
+      onRetry: this.metrics.notifyRetry.bind(this.metrics),
+      onDlq: (envelope, reason) => this.metrics.notifyDlq(envelope, reason, gid),
+      onDuplicate: this.metrics.notifyDuplicate.bind(this.metrics),
+      onMessage: (envelope) => this.metrics.notifyMessage(envelope, gid)
     };
   }
-  get retryTopicDeps() {
+  /** Build the deps object passed to retry topic consumers. */
+  buildRetryTopicDeps() {
     return {
       logger: this.logger,
       producer: this.producer,
       instrumentation: this.instrumentation,
       onMessageLost: this.onMessageLost,
-      onRetry: this.notifyRetry.bind(this),
-      onDlq: this.notifyDlq.bind(this),
-      onMessage: this.notifyMessage.bind(this),
+      onRetry: this.metrics.notifyRetry.bind(this.metrics),
+      onDlq: this.metrics.notifyDlq.bind(this.metrics),
+      onMessage: this.metrics.notifyMessage.bind(this.metrics),
       ensureTopic: (t) => this.ensureTopic(t),
-      getOrCreateConsumer: (gid, fb, ac) => getOrCreateConsumer(gid, fb, ac, this.consumerOpsDeps),
+      getOrCreateConsumer: (gid, fb, ac) => getOrCreateConsumer(gid, fb, ac, this._consumerOpsDeps),
       runningConsumers: this.runningConsumers,
       createRetryTxProducer: (txId) => this.createRetryTxProducer(txId)
     };