@drarzter/kafka-client 0.7.2 → 0.7.3

package/dist/core.js

@@ -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) {
@@ -214,7 +214,7 @@ async function buildSendPayload(topicOrDesc, messages, deps, compression) {
   return { topic: topic2, messages: builtMessages, ...compression && { compression } };
 }
 
-// src/client/kafka.client/consumer-ops.ts
+// 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;
@@ -277,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));
 }
@@ -627,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;
@@ -948,7 +948,7 @@ 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;
@@ -969,7 +969,7 @@ async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
   }
 }
 
-// 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;
@@ -1223,9 +1223,7 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
   return levelGroupIds;
 }
 
-// src/client/kafka.client/index.ts
-var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = import_kafka_javascript2.KafkaJS;
-var _activeTransactionalIds = /* @__PURE__ */ new Set();
+// src/client/kafka.client/consumer/queue.ts
 var AsyncQueue = class {
   constructor(highWaterMark = Infinity, onFull = () => {
   }, onDrained = () => {
@@ -1274,6 +1272,562 @@ var AsyncQueue = class {
     return new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
   }
 };
+
+// src/client/kafka.client/infra/circuit-breaker.ts
+var CircuitBreakerManager = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  states = /* @__PURE__ */ new Map();
+  configs = /* @__PURE__ */ new Map();
+  setConfig(gid, options) {
+    this.configs.set(gid, options);
+  }
+  /**
+   * 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
+    };
+  }
+  /**
+   * 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}`
+        );
+        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;
+    }
+    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);
+      }
+    }
+  }
+  /**
+   * Remove all circuit state and config for the given group.
+   * Called when a consumer is stopped via `stopConsumer(groupId)`.
+   */
+  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;
+  }
+  /**
+   * 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 ensureConnected() {
+    if (this.isConnected) return;
+    try {
+      await this.deps.admin.connect();
+      this.isConnected = true;
+    } catch (err) {
+      this.isConnected = false;
+      throw err;
+    }
+  }
+  /** 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(
+        `resetOffsets: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before resetting offsets.`
+      );
+    }
+    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}"`
+    );
+  }
+  /**
+   * 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 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;
@@ -1282,7 +1836,6 @@ var KafkaClient = class _KafkaClient {
   /** Maps transactionalId → Producer for each active retry level consumer. */
   retryTxProducers = /* @__PURE__ */ new Map();
   consumers = /* @__PURE__ */ new Map();
-  admin;
   logger;
   autoCreateTopicsEnabled;
   strictSchemasEnabled;
@@ -1302,20 +1855,26 @@ var KafkaClient = class _KafkaClient {
   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 = [];
+  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;
@@ -1340,12 +1899,41 @@ var KafkaClient = class _KafkaClient {
         logLevel: KafkaLogLevel.ERROR
       }
     });
-    this.producer = this.kafka.producer({
-      kafkaJS: {
-        acks: -1
-      }
+    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.admin = this.kafka.admin();
+    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(
@@ -1363,7 +1951,7 @@ var KafkaClient = class _KafkaClient {
       options.compression
     );
     await this.producer.send(payload);
-    this.notifyAfterSend(payload.topic, payload.messages.length);
+    this.metrics.notifyAfterSend(payload.topic, payload.messages.length);
   }
   /**
    * Send a null-value (tombstone) message. Used with log-compacted topics to signal
@@ -1378,26 +1966,15 @@ var KafkaClient = class _KafkaClient {
    */
   async sendTombstone(topic2, key, headers) {
     const hdrs = { ...headers };
-    for (const inst of this.instrumentation) {
-      inst.beforeSend?.(topic2, hdrs);
-    }
+    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);
-    }
+    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
-    );
+    const payload = await this.preparePayload(topicOrDesc, messages, options?.compression);
     await this.producer.send(payload);
-    this.notifyAfterSend(payload.topic, payload.messages.length);
+    this.metrics.notifyAfterSend(payload.topic, payload.messages.length);
   }
   /** Execute multiple sends atomically. Commits on success, aborts on error. */
   async transaction(fn) {
@@ -1409,12 +1986,7 @@ var KafkaClient = class _KafkaClient {
       }
       const initPromise = (async () => {
         const p = this.kafka.producer({
-          kafkaJS: {
-            acks: -1,
-            idempotent: true,
-            transactionalId: this.txId,
-            maxInFlightRequests: 1
-          }
+          kafkaJS: { acks: -1, idempotent: true, transactionalId: this.txId, maxInFlightRequests: 1 }
         });
         await p.connect();
         _activeTransactionalIds.add(this.txId);
@@ -1441,19 +2013,12 @@ var KafkaClient = class _KafkaClient {
             }
           ]);
           await tx.send(payload);
-          this.notifyAfterSend(payload.topic, payload.messages.length);
+          this.metrics.notifyAfterSend(payload.topic, payload.messages.length);
         },
-        /**
-         * Send multiple messages in a single call to the topic.
-         * All messages in the batch will be sent atomically.
-         * If any message fails to send, the entire batch will be aborted.
-         * @param topicOrDesc - topic name or TopicDescriptor
-         * @param messages - array of messages to send with optional key, headers, correlationId, schemaVersion, and eventId
-         */
         sendBatch: async (topicOrDesc, messages) => {
           const payload = await this.preparePayload(topicOrDesc, messages);
           await tx.send(payload);
-          this.notifyAfterSend(payload.topic, payload.messages.length);
+          this.metrics.notifyAfterSend(payload.topic, payload.messages.length);
         }
       };
       await fn(ctx);
@@ -1462,10 +2027,7 @@ var KafkaClient = class _KafkaClient {
       try {
         await tx.abort();
       } catch (abortError) {
-        this.logger.error(
-          "Failed to abort transaction:",
-          toError(abortError).message
-        );
+        this.logger.error("Failed to abort transaction:", toError(abortError).message);
       }
       throw error;
     }
@@ -1487,35 +2049,14 @@ var KafkaClient = class _KafkaClient {
     this.logger.log("Producer disconnected");
   }
   async startConsumer(topics, handleMessage, 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"
-      );
-    }
-    const hasRegexTopics = topics.some((t) => t instanceof RegExp);
-    if (options.retryTopics && hasRegexTopics) {
-      throw new Error(
-        "retryTopics is incompatible with regex topic patterns \u2014 retry topics require a fixed topic name to build the retry chain."
-      );
-    }
+    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.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({
-      eachMessage: (payload) => this.trackInFlight(
+      eachMessage: (payload) => this.inFlight.track(
         () => handleEachMessage(
           payload,
           {
@@ -1525,9 +2066,9 @@ 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
@@ -1538,70 +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"
-      );
-    }
-    const hasRegexTopics = topics.some((t) => t instanceof RegExp);
-    if (options.retryTopics && hasRegexTopics) {
-      throw new Error(
-        "retryTopics is incompatible with regex topic patterns \u2014 retry topics require a fixed topic name to build the retry 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: called by the consumer for each batch of messages.
-       * Called with the `payload` argument, which is an object containing the
-       * batch of messages and a `BatchMeta` object with offset management controls.
-       *
-       * The function is wrapped with `trackInFlight` and `handleEachBatch` to provide
-       * error handling and offset management.
-       *
-       * @param payload - an object containing the batch of messages and a `BatchMeta` object.
-       */
-      eachBatch: (payload) => this.trackInFlight(
+      eachBatch: (payload) => this.inFlight.track(
         () => handleEachBatch(
           payload,
           {
@@ -1611,9 +2106,9 @@ 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
@@ -1624,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,
@@ -1637,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) };
   }
@@ -1707,38 +2188,20 @@ var KafkaClient = class _KafkaClient {
     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);
       }
@@ -1746,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);
@@ -1760,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);
         }
@@ -1773,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();
@@ -1789,10 +2238,7 @@ 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");
     }
   }
@@ -1810,9 +2256,7 @@ 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] })))
     );
   }
   /**
@@ -1829,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). */
@@ -1852,14 +2294,6 @@ 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.
    *
@@ -1872,106 +2306,27 @@ var KafkaClient = class _KafkaClient {
    * @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.
@@ -1979,25 +2334,7 @@ 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
@@ -2008,37 +2345,7 @@ var KafkaClient = class _KafkaClient {
    * 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.
@@ -2052,14 +2359,7 @@ var KafkaClient = class _KafkaClient {
    * @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.
@@ -2073,83 +2373,32 @@ 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() {
-    await this.ensureAdminConnected();
-    const result = await this.admin.listGroups();
-    return result.groups.map((g) => ({
-      groupId: g.groupId,
-      state: g.state ?? "Unknown"
-    }));
+    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) {
-    await this.ensureAdminConnected();
-    const result = await this.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
-        )
-      }))
-    }));
+    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) {
-    await this.ensureAdminConnected();
-    await this.admin.deleteTopicRecords({ topic: topic2, partitions });
+    return this.adminOps.deleteRecords(topic2, partitions);
   }
   /** Return the client ID provided during `KafkaClient` construction. */
   getClientId() {
@@ -2164,24 +2413,8 @@ var KafkaClient = class _KafkaClient {
    *   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;
+  getMetrics(topic2) {
+    return this.metrics.getMetrics(topic2);
   }
   /**
    * Reset internal event counters to zero.
@@ -2189,15 +2422,11 @@ var KafkaClient = class _KafkaClient {
    * @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());
@@ -2205,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 ────────────────────────────────────────────
@@ -2245,235 +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);
-    }
-  }
-  /**
-   * Increment the in-flight handler count and return a promise that calls the given handler.
-   * When the promise resolves or rejects, decrement the in flight handler count.
-   * If the in flight handler count reaches 0, call all previously registered drain resolvers.
-   * @param fn The handler to call when the promise is resolved or rejected.
-   * @returns A promise that resolves or rejects with the result of calling the handler.
-   */
-  trackInFlight(fn) {
-    this.inFlightTotal++;
-    return fn().finally(() => {
-      this.inFlightTotal--;
-      if (this.inFlightTotal === 0) {
-        this.drainResolvers.splice(0).forEach((r) => r());
-      }
-    });
-  }
-  /**
-   * Waits for all in-flight handlers to complete or for a given timeout, whichever comes first.
-   * @param timeoutMs Maximum time to wait in milliseconds.
-   * @returns A promise that resolves when all handlers have completed or the timeout is reached.
-   * @private
-   */
-  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 ──────────────────────────────────────────────
-  /**
-   * Prepare a send payload by registering the topic's schema and then building the payload.
-   * @param topicOrDesc - topic name or topic descriptor
-   * @param messages - batch of messages to send
-   * @returns - prepared payload
-   */
   async preparePayload(topicOrDesc, messages, compression) {
     registerSchema(topicOrDesc, this.schemaRegistry, this.logger);
-    const payload = await buildSendPayload(
-      topicOrDesc,
-      messages,
-      this.producerOpsDeps,
-      compression
-    );
+    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);
-      }
-    }
-  }
-  /**
-   * Returns the KafkaMetrics for a given topic.
-   * If the topic hasn't seen any events, initializes a zero-valued snapshot.
-   * @param topic - name of the topic to get the metrics for
-   * @returns - KafkaMetrics for the given topic
-   */
-  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;
-  }
-  /**
-   * Notifies instrumentation hooks of a retry event.
-   * @param envelope The original message envelope that triggered the retry.
-   * @param attempt The current retry attempt (1-indexed).
-   * @param maxRetries The maximum number of retries configured for this topic.
-   */
-  notifyRetry(envelope, attempt, maxRetries) {
-    this.metricsFor(envelope.topic).retryCount++;
-    for (const inst of this.instrumentation) {
-      inst.onRetry?.(envelope, attempt, maxRetries);
-    }
-  }
-  /**
-   * Called whenever a message is routed to the dead letter queue.
-   * @param envelope The original message envelope.
-   * @param reason The reason for routing to the dead letter queue.
-   * @param gid The group ID of the consumer that triggered the circuit breaker, if any.
-   */
-  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();
-    }
-  }
-  /**
-   * Notify all instrumentation hooks about a duplicate message detection.
-   * Invoked by the consumer after a message has been successfully processed
-   * and the Lamport clock detected a duplicate.
-   * @param envelope The processed message envelope.
-   * @param strategy The duplicate detection strategy used.
-   */
-  notifyDuplicate(envelope, strategy) {
-    this.metricsFor(envelope.topic).dedupCount++;
-    for (const inst of this.instrumentation) {
-      inst.onDuplicate?.(envelope, strategy);
-    }
-  }
-  /**
-   * Notify all instrumentation hooks about a successfully processed message.
-   * Invoked by the consumer after a message has been successfully processed
-   * by the handler.
-   * @param envelope The processed message envelope.
-   * @param gid The optional consumer group ID.
-   */
-  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.
@@ -2484,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`
@@ -2569,12 +2503,7 @@ 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);
@@ -2583,20 +2512,16 @@ var KafkaClient = class _KafkaClient {
   }
   /**
    * Ensure that a topic exists by creating it if it doesn't already exist.
-   * If `autoCreateTopics` is disabled, this method will not create the topic and
-   * will return immediately.
-   * If multiple concurrent calls are made to `ensureTopic` for the same topic,
-   * they are deduplicated to prevent multiple calls to `admin.createTopics()`.
-   * @param topic - The topic to ensure exists.
-   * @returns A promise that resolves when the topic has been created or already exists.
+   * 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);
@@ -2636,99 +2561,78 @@ var KafkaClient = class _KafkaClient {
       gid,
       fromBeginning,
       options.autoCommit ?? true,
-      this.consumerOpsDeps,
+      this._consumerOpsDeps,
       options.partitionAssigner
     );
-    const schemaMap = buildSchemaMap(
-      stringTopics,
-      this.schemaRegistry,
-      optionSchemas,
-      this.logger
-    );
+    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);
-    }
+    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`);
-      }
+      for (const t of topicNames) await this.ensureTopic(`${t}.dlq`);
       if (!this.autoCreateTopicsEnabled && topicNames.length > 0) {
-        await this.validateDlqTopicsExist(topicNames);
+        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`);
-        }
+        for (const t of topicNames) await this.ensureTopic(dest ?? `${t}.duplicates`);
       } else if (topicNames.length > 0) {
-        await this.validateDuplicatesTopicsExist(topicNames, dest);
+        await this.adminOps.validateDuplicatesTopicsExist(topicNames, dest);
       }
     }
     await consumer.connect();
-    await subscribeWithRetry(
-      consumer,
-      subscribeTopics,
-      this.logger,
-      options.subscribeRetry
-    );
+    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}`
-    );
+    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 ──────────────────────────────────────────
-  /**
-   * An object containing the necessary dependencies for building a send payload.
-   *
-   * @property {Map<string, SchemaLike>} schemaRegistry - A map of topic names to their schemas.
-   * @property {boolean} strictSchemasEnabled - Whether strict schema validation is enabled.
-   * @property {KafkaInstrumentation} instrumentation - An object for creating a span for instrumentation.
-   * @property {KafkaLogger} logger - A logger for logging messages.
-   * @property {() => number} nextLamportClock - A function that returns the next value of the logical clock.
-   */
-  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."
+      );
+    }
   }
-  /**
-   * ConsumerOpsDeps object properties:
-   *
-   * @property {Map<string, Consumer>} consumers - A map of consumer group IDs to their corresponding consumer instances.
-   * @property {Map<string, { fromBeginning: boolean; autoCommit: boolean }>} consumerCreationOptions - A map of consumer group IDs to their creation options.
-   * @property {Kafka} kafka - The Kafka client instance.
-   * @property {function(string, Partition[]): void} onRebalance - An optional callback function called when a consumer group is rebalanced.
-   * @property {KafkaLogger} logger - The logger instance used for logging consumer operations.
-   */
-  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 {
@@ -2737,38 +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)
     };
   }
-  /**
-   * The dependencies object passed to the retry topic consumers.
-   *
-   * `logger`: The logger instance passed to the retry topic consumers.
-   * `producer`: The producer instance passed to the retry topic consumers.
-   * `instrumentation`: The instrumentation instance passed to the retry topic consumers.
-   * `onMessageLost`: The callback function passed to the retry topic consumers for tracking lost messages.
-   * `onRetry`: The callback function passed to the retry topic consumers for tracking retry attempts.
-   * `onDlq`: The callback function passed to the retry topic consumers for tracking dead-letter queue routing.
-   * `onMessage`: The callback function passed to the retry topic consumers for tracking message delivery.
-   * `ensureTopic`: A function that ensures a topic exists before subscribing to it.
-   * `getOrCreateConsumer`: A function that creates or retrieves a consumer instance.
-   * `runningConsumers`: A map of consumer group IDs to their corresponding consumer instances.
-   * `createRetryTxProducer`: A function that creates a retry transactional producer instance.
-   */
-  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)
     };