@drarzter/kafka-client 0.9.4 → 0.11.0

package/dist/chunk-OR7TPAAE.mjs

@@ -0,0 +1,4760 @@
+import {
+  JsonSerde
+} from "./chunk-PQVBRDNV.mjs";
+
+// src/client/transport/confluent.transport.ts
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+var { Kafka: KafkaClass, logLevel: KafkaLogLevel, PartitionAssigners } = KafkaJS;
+var ConfluentTransaction = class {
+  constructor(tx) {
+    this.tx = tx;
+  }
+  tx;
+  async send(record) {
+    await this.tx.send(record);
+  }
+  async sendOffsets(options) {
+    const nativeConsumer = options.consumer.getNative();
+    await this.tx.sendOffsets({
+      consumer: nativeConsumer,
+      topics: options.topics
+    });
+  }
+  async commit() {
+    await this.tx.commit();
+  }
+  async abort() {
+    await this.tx.abort();
+  }
+};
+var ConfluentProducer = class {
+  constructor(producer) {
+    this.producer = producer;
+  }
+  producer;
+  connectPromise;
+  async connect() {
+    this.connectPromise ??= this.producer.connect().catch((err) => {
+      this.connectPromise = void 0;
+      throw err;
+    });
+    return this.connectPromise;
+  }
+  async disconnect() {
+    this.connectPromise = void 0;
+    await this.producer.disconnect();
+  }
+  async send(record) {
+    await this.producer.send(record);
+  }
+  async transaction() {
+    const tx = await this.producer.transaction();
+    return new ConfluentTransaction(tx);
+  }
+};
+var ConfluentConsumer = class {
+  constructor(consumer) {
+    this.consumer = consumer;
+  }
+  consumer;
+  /** Returns the underlying KafkaJS.Consumer — used by ConfluentTransaction.sendOffsets. */
+  getNative() {
+    return this.consumer;
+  }
+  async connect() {
+    await this.consumer.connect();
+  }
+  async disconnect() {
+    await this.consumer.disconnect();
+  }
+  async subscribe(options) {
+    await this.consumer.subscribe(options);
+  }
+  async run(config) {
+    await this.consumer.run(config);
+  }
+  pause(assignments) {
+    this.consumer.pause(assignments);
+  }
+  resume(assignments) {
+    this.consumer.resume(assignments);
+  }
+  seek(options) {
+    this.consumer.seek(options);
+  }
+  assignment() {
+    return this.consumer.assignment();
+  }
+  async commitOffsets(offsets) {
+    await this.consumer.commitOffsets(offsets);
+  }
+  async stop() {
+    await this.consumer.stop?.();
+  }
+};
+var ConfluentAdmin = class {
+  constructor(admin) {
+    this.admin = admin;
+  }
+  admin;
+  async connect() {
+    await this.admin.connect();
+  }
+  async disconnect() {
+    await this.admin.disconnect();
+  }
+  async createTopics(options) {
+    await this.admin.createTopics(options);
+  }
+  async fetchTopicOffsets(topic2) {
+    return this.admin.fetchTopicOffsets(topic2);
+  }
+  async fetchTopicOffsetsByTimestamp(topic2, timestamp) {
+    return this.admin.fetchTopicOffsetsByTimestamp(topic2, timestamp);
+  }
+  async fetchOffsets(options) {
+    return this.admin.fetchOffsets(options);
+  }
+  async setOffsets(options) {
+    await this.admin.setOffsets(options);
+  }
+  async listTopics() {
+    return this.admin.listTopics();
+  }
+  async listGroups() {
+    return this.admin.listGroups();
+  }
+  async fetchTopicMetadata(options) {
+    return this.admin.fetchTopicMetadata(options);
+  }
+  async deleteGroups(groupIds) {
+    await this.admin.deleteGroups(groupIds);
+  }
+  async deleteTopicRecords(options) {
+    await this.admin.deleteTopicRecords(options);
+  }
+};
+var ConfluentTransport = class {
+  kafka;
+  constructor(clientId, brokers, security) {
+    const kafkaJS = { clientId, brokers, logLevel: KafkaLogLevel.ERROR };
+    if (security?.ssl !== void 0) kafkaJS.ssl = security.ssl;
+    if (security?.sasl) {
+      if (security.sasl.mechanism === "oauthbearer") {
+        const provider = security.sasl.oauthBearerProvider;
+        kafkaJS.sasl = {
+          mechanism: "oauthbearer",
+          oauthBearerProvider: async () => {
+            const token = await provider();
+            return {
+              value: token.value,
+              principal: token.principal ?? "kafka-client",
+              lifetime: token.lifetimeMs ?? Date.now() + 15 * 6e4,
+              ...token.extensions && { extensions: token.extensions }
+            };
+          }
+        };
+      } else {
+        kafkaJS.sasl = security.sasl;
+      }
+    }
+    this.kafka = new KafkaClass({ kafkaJS });
+  }
+  producer(options) {
+    const native = this.kafka.producer({
+      kafkaJS: {
+        acks: -1,
+        ...options?.idempotent !== void 0 && {
+          idempotent: options.idempotent
+        },
+        ...options?.transactionalId !== void 0 && {
+          transactionalId: options.transactionalId,
+          maxInFlightRequests: 1
+        }
+      }
+    });
+    return new ConfluentProducer(native);
+  }
+  consumer(options) {
+    const assigner = options.partitionAssigner === "roundrobin" ? PartitionAssigners.roundRobin : options.partitionAssigner === "range" ? PartitionAssigners.range : PartitionAssigners.cooperativeSticky;
+    const config = {
+      kafkaJS: {
+        groupId: options.groupId,
+        fromBeginning: options.fromBeginning,
+        autoCommit: options.autoCommit,
+        partitionAssigners: [assigner]
+      }
+    };
+    if (options.groupInstanceId) {
+      config["group.instance.id"] = options.groupInstanceId;
+    }
+    if (options.onRebalance) {
+      const cb = options.onRebalance;
+      config.rebalance_cb = (err, assignment) => {
+        const type = err.code === -175 ? "assign" : "revoke";
+        cb(
+          type,
+          assignment.map((p) => ({ topic: p.topic, partition: p.partition }))
+        );
+      };
+    }
+    return new ConfluentConsumer(this.kafka.consumer(config));
+  }
+  admin() {
+    return new ConfluentAdmin(this.kafka.admin());
+  }
+};
+
+// src/client/kafka.client/infra/dedup.store.ts
+var InMemoryDedupStore = class {
+  constructor(states) {
+    this.states = states;
+  }
+  states;
+  getLastClock(groupId, topicPartition) {
+    return this.states.get(groupId)?.get(topicPartition);
+  }
+  setLastClock(groupId, topicPartition, clock) {
+    let group = this.states.get(groupId);
+    if (!group) {
+      group = /* @__PURE__ */ new Map();
+      this.states.set(groupId, group);
+    }
+    group.set(topicPartition, clock);
+  }
+};
+
+// src/client/message/envelope.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { randomUUID } from "crypto";
+var HEADER_EVENT_ID = "x-event-id";
+var HEADER_CORRELATION_ID = "x-correlation-id";
+var HEADER_TIMESTAMP = "x-timestamp";
+var HEADER_SCHEMA_VERSION = "x-schema-version";
+var HEADER_TRACEPARENT = "traceparent";
+var HEADER_LAMPORT_CLOCK = "x-lamport-clock";
+var HEADER_DELAYED_UNTIL = "x-delayed-until";
+var HEADER_DELAYED_TARGET = "x-delayed-target";
+var envelopeStorage = new AsyncLocalStorage();
+function getEnvelopeContext() {
+  return envelopeStorage.getStore();
+}
+function runWithEnvelopeContext(ctx, fn) {
+  return envelopeStorage.run(ctx, fn);
+}
+function buildEnvelopeHeaders(options = {}) {
+  const ctx = getEnvelopeContext();
+  const correlationId = options.correlationId ?? ctx?.correlationId ?? randomUUID();
+  const eventId = options.eventId ?? randomUUID();
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const schemaVersion = String(options.schemaVersion ?? 1);
+  const envelope = {
+    [HEADER_EVENT_ID]: eventId,
+    [HEADER_CORRELATION_ID]: correlationId,
+    [HEADER_TIMESTAMP]: timestamp,
+    [HEADER_SCHEMA_VERSION]: schemaVersion
+  };
+  if (ctx?.traceparent) {
+    envelope[HEADER_TRACEPARENT] = ctx.traceparent;
+  }
+  return { ...envelope, ...options.headers };
+}
+function decodeHeaders(raw) {
+  if (!raw) return {};
+  const result = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      const items = value.map((v) => Buffer.isBuffer(v) ? v.toString() : v);
+      result[key] = items[items.length - 1] ?? "";
+    } else {
+      result[key] = Buffer.isBuffer(value) ? value.toString() : value;
+    }
+  }
+  return result;
+}
+function extractEnvelope(payload, headers, topic2, partition, offset) {
+  return {
+    payload,
+    topic: topic2,
+    partition,
+    offset,
+    eventId: headers[HEADER_EVENT_ID] ?? randomUUID(),
+    correlationId: headers[HEADER_CORRELATION_ID] ?? randomUUID(),
+    timestamp: headers[HEADER_TIMESTAMP] ?? (/* @__PURE__ */ new Date()).toISOString(),
+    schemaVersion: Number(headers[HEADER_SCHEMA_VERSION] ?? 1),
+    traceparent: headers[HEADER_TRACEPARENT],
+    headers
+  };
+}
+
+// src/client/errors.ts
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+var KafkaProcessingError = class extends Error {
+  constructor(message, topic2, originalMessage, options) {
+    super(message, options);
+    this.topic = topic2;
+    this.originalMessage = originalMessage;
+    this.name = "KafkaProcessingError";
+    if (options?.cause) this.cause = options.cause;
+  }
+  topic;
+  originalMessage;
+};
+var KafkaValidationError = class extends Error {
+  constructor(topic2, originalMessage, options) {
+    super(`Schema validation failed for topic "${topic2}"`, options);
+    this.topic = topic2;
+    this.originalMessage = originalMessage;
+    this.name = "KafkaValidationError";
+    if (options?.cause) this.cause = options.cause;
+  }
+  topic;
+  originalMessage;
+};
+var KafkaRetryExhaustedError = class extends KafkaProcessingError {
+  constructor(topic2, originalMessage, attempts, options) {
+    super(
+      `Message processing failed after ${attempts} attempts on topic "${topic2}"`,
+      topic2,
+      originalMessage,
+      options
+    );
+    this.attempts = attempts;
+    this.name = "KafkaRetryExhaustedError";
+  }
+  attempts;
+};
+
+// src/client/kafka.client/producer/ops.ts
+function resolveSerde(topicOrDesc, clientSerde) {
+  return topicOrDesc?.__serde ?? clientSerde;
+}
+function resolveTopicName(topicOrDescriptor) {
+  if (typeof topicOrDescriptor === "string") return topicOrDescriptor;
+  if (topicOrDescriptor && typeof topicOrDescriptor === "object" && "__topic" in topicOrDescriptor) {
+    return topicOrDescriptor.__topic;
+  }
+  return String(topicOrDescriptor);
+}
+function registerSchema(topicOrDesc, schemaRegistry, logger) {
+  if (topicOrDesc?.__schema) {
+    const topic2 = resolveTopicName(topicOrDesc);
+    const existing = schemaRegistry.get(topic2);
+    if (existing && existing !== topicOrDesc.__schema) {
+      logger?.warn(
+        `Schema conflict for topic "${topic2}": a different schema is already registered. Using the new schema \u2014 ensure consistent schemas to avoid silent validation mismatches.`
+      );
+    }
+    schemaRegistry.set(topic2, topicOrDesc.__schema);
+  }
+}
+async function validateMessage(topicOrDesc, message, deps, ctx) {
+  const topicName = resolveTopicName(topicOrDesc);
+  if (topicOrDesc?.__schema) {
+    try {
+      return await topicOrDesc.__schema.parse(message, ctx);
+    } catch (error) {
+      throw new KafkaValidationError(topicName, message, {
+        cause: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  if (deps.strictSchemasEnabled && typeof topicOrDesc === "string") {
+    const schema = deps.schemaRegistry.get(topicOrDesc);
+    if (schema) {
+      try {
+        return await schema.parse(message, ctx);
+      } catch (error) {
+        throw new KafkaValidationError(topicName, message, {
+          cause: error instanceof Error ? error : new Error(String(error))
+        });
+      }
+    }
+  }
+  return message;
+}
+async function buildSendPayload(topicOrDesc, messages, deps, compression) {
+  const topic2 = resolveTopicName(topicOrDesc);
+  const serde = resolveSerde(topicOrDesc, deps.serde);
+  const builtMessages = await Promise.all(
+    messages.map(async (m) => {
+      const envelopeHeaders = buildEnvelopeHeaders({
+        correlationId: m.correlationId,
+        schemaVersion: m.schemaVersion,
+        eventId: m.eventId,
+        headers: m.headers
+      });
+      if (deps.nextLamportClock) {
+        envelopeHeaders[HEADER_LAMPORT_CLOCK] = String(deps.nextLamportClock());
+      }
+      for (const inst of deps.instrumentation) {
+        inst.beforeSend?.(topic2, envelopeHeaders);
+      }
+      const sendCtx = {
+        topic: topic2,
+        headers: envelopeHeaders,
+        version: m.schemaVersion ?? 1
+      };
+      const validated = await validateMessage(topicOrDesc, m.value, deps, sendCtx);
+      return {
+        value: await serde.serialize(validated, {
+          topic: topic2,
+          headers: envelopeHeaders,
+          isKey: false
+        }),
+        // Explicit key wins; otherwise fall back to the descriptor's .key()
+        // extractor (runs on the original, pre-validation payload).
+        key: m.key ?? topicOrDesc?.__key?.(m.value) ?? null,
+        headers: envelopeHeaders
+      };
+    })
+  );
+  return { topic: topic2, messages: builtMessages, ...compression && { compression } };
+}
+
+// src/client/kafka.client/consumer/ops.ts
+function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps, partitionAssigner, onFirstAssignment, groupInstanceId) {
+  const { consumers, consumerCreationOptions, transport, onRebalance, logger } = deps;
+  if (consumers.has(groupId)) {
+    const prev = consumerCreationOptions.get(groupId);
+    if (prev.fromBeginning !== fromBeginning || prev.autoCommit !== autoCommit) {
+      logger.warn(
+        `Consumer group "${groupId}" already exists with options (fromBeginning: ${prev.fromBeginning}, autoCommit: ${prev.autoCommit}) \u2014 new options (fromBeginning: ${fromBeginning}, autoCommit: ${autoCommit}) ignored. Use a different groupId to apply different options.`
+      );
+    }
+    onFirstAssignment?.();
+    return consumers.get(groupId);
+  }
+  consumerCreationOptions.set(groupId, { fromBeginning, autoCommit });
+  const SETTLE_MS = fromBeginning ? 0 : 500;
+  let hasAssignment = false;
+  let settleTimer;
+  const scheduleSettle = () => {
+    if (!hasAssignment) return;
+    if (settleTimer) clearTimeout(settleTimer);
+    settleTimer = setTimeout(() => {
+      settleTimer = void 0;
+      onFirstAssignment?.();
+    }, SETTLE_MS);
+  };
+  const fireOnAssignment = () => {
+    hasAssignment = true;
+    scheduleSettle();
+  };
+  const consumer = transport.consumer({
+    groupId,
+    fromBeginning,
+    autoCommit,
+    partitionAssigner: partitionAssigner ?? "cooperative-sticky",
+    groupInstanceId,
+    onRebalance: (type, assignments) => {
+      if (type === "assign") fireOnAssignment();
+      else if (type === "revoke") scheduleSettle();
+      if (onRebalance) {
+        try {
+          onRebalance(type, assignments);
+        } catch (e) {
+          logger.warn(`onRebalance callback threw: ${e.message}`);
+        }
+      }
+    }
+  });
+  consumers.set(groupId, consumer);
+  return consumer;
+}
+function buildSchemaMap(topics, schemaRegistry, optionSchemas, logger) {
+  const schemaMap = /* @__PURE__ */ new Map();
+  const registerChecked = (name, schema) => {
+    const existing = schemaRegistry.get(name);
+    if (existing && existing !== schema) {
+      logger?.warn(
+        `Schema conflict for topic "${name}": a different schema is already registered. Using the new schema \u2014 ensure consistent schemas to avoid silent validation mismatches.`
+      );
+    }
+    schemaMap.set(name, schema);
+    schemaRegistry.set(name, schema);
+  };
+  for (const t of topics) {
+    if (t?.__schema) {
+      registerChecked(resolveTopicName(t), t.__schema);
+    }
+  }
+  if (optionSchemas) {
+    for (const [k, v] of optionSchemas) {
+      registerChecked(k, v);
+    }
+  }
+  return schemaMap;
+}
+function buildSerdeMap(topics) {
+  let serdeMap;
+  for (const t of topics) {
+    if (t?.__serde) {
+      (serdeMap ??= /* @__PURE__ */ new Map()).set(resolveTopicName(t), t.__serde);
+    }
+  }
+  return serdeMap;
+}
+
+// src/client/kafka.client/admin/ops.ts
+var AdminOps = class {
+  constructor(deps) {
+    this.deps = 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.fetchTopicOffsetsByTimestamp(
+            topic2,
+            timestamp
+          );
+          const found = results.find(
+            (r) => r.partition === partition
+          );
+          if (found) return { partition, offset: found.offset };
+          const topicOffsets = await this.deps.admin.fetchTopicOffsets(topic2);
+          const po = topicOffsets.find((o) => o.partition === partition);
+          return { partition, offset: po?.high ?? "0" };
+        })
+      );
+      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 ?? 0,
+        // -1 is Kafka's own "no leader" sentinel; 0 is a valid broker id
+        leader: p.leader ?? -1,
+        replicas: (p.replicas ?? []).map(
+          (r) => typeof r === "number" ? r : r.nodeId
+        ),
+        isr: (p.isr ?? []).map(
+          (r) => typeof r === "number" ? r : r.nodeId
+        )
+      }))
+    }));
+  }
+  /**
+   * Delete consumer groups from the broker.
+   * Groups must be empty (no active members) before deletion.
+   * Silently skips unknown group IDs.
+   * @param groupIds Consumer group IDs to delete.
+   */
+  async deleteGroups(groupIds) {
+    if (groupIds.length === 0) return;
+    await this.ensureConnected();
+    await this.deps.admin.deleteGroups(groupIds);
+  }
+  /**
+   * 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/pipeline.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function validateWithSchema(message, raw, topic2, schemaMap, interceptors, dlq, deps) {
+  const schema = schemaMap.get(topic2);
+  if (!schema) return message;
+  const ctx = {
+    topic: topic2,
+    headers: deps.originalHeaders ?? {},
+    version: Number(deps.originalHeaders?.["x-schema-version"] ?? 1)
+  };
+  try {
+    return await schema.parse(message, ctx);
+  } catch (error) {
+    const err = toError(error);
+    const validationError = new KafkaValidationError(topic2, message, {
+      cause: err
+    });
+    deps.logger.error(
+      `Schema validation failed for topic ${topic2}:`,
+      err.message
+    );
+    if (dlq) {
+      await sendToDlq(topic2, raw, deps, {
+        error: validationError,
+        attempt: 0,
+        originalHeaders: deps.originalHeaders
+      });
+    } else {
+      await deps.onMessageLost?.({
+        topic: topic2,
+        error: validationError,
+        attempt: 0,
+        headers: deps.originalHeaders ?? {}
+      });
+    }
+    const errorEnvelope = extractEnvelope(
+      message,
+      deps.originalHeaders ?? {},
+      topic2,
+      -1,
+      ""
+    );
+    for (const inst of deps.instrumentation ?? []) {
+      inst.onConsumeError?.(errorEnvelope, validationError);
+    }
+    for (const interceptor of interceptors) {
+      await interceptor.onError?.(errorEnvelope, validationError);
+    }
+    return null;
+  }
+}
+function buildDlqPayload(topic2, rawMessage, meta) {
+  const dlqTopic = `${topic2}.dlq`;
+  const headers = {
+    ...meta?.originalHeaders ?? {},
+    "x-dlq-original-topic": topic2,
+    "x-dlq-failed-at": (/* @__PURE__ */ new Date()).toISOString(),
+    "x-dlq-error-message": meta?.error.message ?? "unknown",
+    "x-dlq-error-stack": meta?.error.stack?.slice(0, 2e3) ?? "",
+    "x-dlq-attempt-count": String(meta?.attempt ?? 0)
+  };
+  return { topic: dlqTopic, messages: [{ value: rawMessage, headers }] };
+}
+async function sendToDlq(topic2, rawMessage, deps, meta) {
+  const payload = buildDlqPayload(topic2, rawMessage, meta);
+  try {
+    await deps.producer.send(payload);
+    deps.logger.warn(`Message sent to DLQ: ${payload.topic}`);
+  } catch (error) {
+    const err = toError(error);
+    deps.logger.error(
+      `Failed to send message to DLQ ${payload.topic}:`,
+      err.stack
+    );
+    await deps.onMessageLost?.({
+      topic: topic2,
+      error: err,
+      attempt: meta?.attempt ?? 0,
+      headers: meta?.originalHeaders ?? {}
+    });
+  }
+}
+var RETRY_HEADER_ATTEMPT = "x-retry-attempt";
+var RETRY_HEADER_AFTER = "x-retry-after";
+var RETRY_HEADER_MAX_RETRIES = "x-retry-max-retries";
+var RETRY_HEADER_ORIGINAL_TOPIC = "x-retry-original-topic";
+function buildRetryTopicPayload(originalTopic, rawMessages, attempt, maxRetries, delayMs, originalHeaders) {
+  const retryTopic = `${originalTopic}.retry.${attempt}`;
+  const STRIP = /* @__PURE__ */ new Set([
+    RETRY_HEADER_ATTEMPT,
+    RETRY_HEADER_AFTER,
+    RETRY_HEADER_MAX_RETRIES,
+    RETRY_HEADER_ORIGINAL_TOPIC
+  ]);
+  function buildHeaders(hdr) {
+    const userHeaders = Object.fromEntries(
+      Object.entries(hdr).filter(([k]) => !STRIP.has(k))
+    );
+    return {
+      ...userHeaders,
+      [RETRY_HEADER_ATTEMPT]: String(attempt),
+      [RETRY_HEADER_AFTER]: String(Date.now() + delayMs),
+      [RETRY_HEADER_MAX_RETRIES]: String(maxRetries),
+      [RETRY_HEADER_ORIGINAL_TOPIC]: originalTopic
+    };
+  }
+  return {
+    topic: retryTopic,
+    messages: rawMessages.map((value, i) => ({
+      value,
+      headers: buildHeaders(
+        Array.isArray(originalHeaders) ? originalHeaders[i] ?? {} : originalHeaders
+      )
+    }))
+  };
+}
+async function sendToRetryTopic(originalTopic, rawMessages, attempt, maxRetries, delayMs, originalHeaders, deps) {
+  const payload = buildRetryTopicPayload(
+    originalTopic,
+    rawMessages,
+    attempt,
+    maxRetries,
+    delayMs,
+    originalHeaders
+  );
+  try {
+    await deps.producer.send(payload);
+    deps.logger.warn(
+      `Message queued in retry topic ${payload.topic} (attempt ${attempt}/${maxRetries})`
+    );
+  } catch (error) {
+    const err = toError(error);
+    deps.logger.error(
+      `Failed to send message to retry topic ${payload.topic}:`,
+      err.stack
+    );
+    await deps.onMessageLost?.({
+      topic: originalTopic,
+      error: err,
+      attempt,
+      headers: Array.isArray(originalHeaders) ? originalHeaders[0] ?? {} : originalHeaders
+    });
+  }
+}
+function buildDuplicateTopicPayload(sourceTopic, rawMessage, destinationTopic, meta) {
+  const headers = {
+    ...meta?.originalHeaders ?? {},
+    "x-duplicate-original-topic": sourceTopic,
+    "x-duplicate-detected-at": (/* @__PURE__ */ new Date()).toISOString(),
+    "x-duplicate-reason": "lamport-clock-duplicate",
+    "x-duplicate-incoming-clock": String(meta?.incomingClock ?? 0),
+    "x-duplicate-last-processed-clock": String(meta?.lastProcessedClock ?? 0)
+  };
+  return {
+    topic: destinationTopic,
+    messages: [{ value: rawMessage, headers }]
+  };
+}
+async function sendToDuplicatesTopic(sourceTopic, rawMessage, destinationTopic, deps, meta) {
+  const payload = buildDuplicateTopicPayload(
+    sourceTopic,
+    rawMessage,
+    destinationTopic,
+    meta
+  );
+  try {
+    await deps.producer.send(payload);
+    deps.logger.warn(`Duplicate message forwarded to ${destinationTopic}`);
+  } catch (error) {
+    deps.logger.error(
+      `Failed to forward duplicate to ${destinationTopic}:`,
+      toError(error).stack
+    );
+  }
+}
+async function broadcastToInterceptors(envelopes, interceptors, cb) {
+  for (const env of envelopes) {
+    for (const interceptor of interceptors) {
+      await cb(interceptor, env);
+    }
+  }
+}
+async function runHandlerWithPipeline(fn, envelopes, interceptors, instrumentation) {
+  const cleanups = [];
+  const wraps = [];
+  try {
+    for (const env of envelopes) {
+      for (const inst of instrumentation) {
+        const result = inst.beforeConsume?.(env);
+        if (typeof result === "function") {
+          cleanups.push(result);
+        } else if (result) {
+          if (result.cleanup) cleanups.push(result.cleanup);
+          if (result.wrap) wraps.push(result.wrap);
+        }
+      }
+    }
+    for (const env of envelopes) {
+      for (const interceptor of interceptors) {
+        await interceptor.before?.(env);
+      }
+    }
+    let runFn = fn;
+    for (let i = wraps.length - 1; i >= 0; i--) {
+      const wrap = wraps[i];
+      const inner = runFn;
+      runFn = () => wrap(inner);
+    }
+    await runFn();
+    for (const env of envelopes) {
+      for (const interceptor of interceptors) {
+        await interceptor.after?.(env);
+      }
+    }
+    for (const cleanup of cleanups) cleanup();
+    return null;
+  } catch (error) {
+    const err = toError(error);
+    for (const env of envelopes) {
+      for (const inst of instrumentation) {
+        inst.onConsumeError?.(env, err);
+      }
+    }
+    for (const cleanup of cleanups) cleanup();
+    return err;
+  }
+}
+async function notifyInterceptorsOnError(envelopes, interceptors, error) {
+  await broadcastToInterceptors(
+    envelopes,
+    interceptors,
+    (i, env) => i.onError?.(env, error)
+  );
+}
+async function executeWithRetry(fn, ctx, deps) {
+  const {
+    envelope,
+    rawMessages,
+    interceptors,
+    dlq,
+    retry,
+    isBatch,
+    retryTopics
+  } = ctx;
+  const maxAttempts = retryTopics ? 1 : retry ? retry.maxRetries + 1 : 1;
+  const backoffMs = retry?.backoffMs ?? 1e3;
+  const maxBackoffMs = retry?.maxBackoffMs ?? 3e4;
+  const envelopes = Array.isArray(envelope) ? envelope : [envelope];
+  const topic2 = envelopes[0]?.topic ?? "unknown";
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const error = await runHandlerWithPipeline(
+      fn,
+      envelopes,
+      interceptors,
+      deps.instrumentation
+    );
+    if (!error) {
+      if (deps.eosCommitOnSuccess) {
+        try {
+          await deps.eosCommitOnSuccess();
+        } catch (commitErr) {
+          deps.logger.error(
+            `EOS offset commit failed after successful handler \u2014 message will be redelivered:`,
+            toError(commitErr).stack
+          );
+          return;
+        }
+      }
+      for (const env of envelopes) deps.onMessage?.(env);
+      return;
+    }
+    deps.onFailure?.(envelopes[0]);
+    const isLastAttempt = attempt === maxAttempts;
+    const reportedError = isLastAttempt && maxAttempts > 1 ? new KafkaRetryExhaustedError(
+      topic2,
+      envelopes.map((e) => e.payload),
+      maxAttempts,
+      { cause: error }
+    ) : error;
+    await notifyInterceptorsOnError(envelopes, interceptors, reportedError);
+    deps.logger.error(
+      `Error processing ${isBatch ? "batch" : "message"} from topic ${topic2} (attempt ${attempt}/${maxAttempts}):`,
+      error.stack
+    );
+    if (retryTopics && retry) {
+      const cap = Math.min(backoffMs, maxBackoffMs);
+      const delay = Math.floor(Math.random() * cap);
+      if (deps.eosRouteToRetry) {
+        try {
+          await deps.eosRouteToRetry(rawMessages, envelopes, delay);
+          deps.onRetry?.(envelopes[0], 1, retry.maxRetries);
+        } catch (txErr) {
+          deps.logger.error(
+            `EOS routing to retry topic failed \u2014 message will be redelivered:`,
+            toError(txErr).stack
+          );
+        }
+      } else {
+        await sendToRetryTopic(
+          topic2,
+          rawMessages,
+          1,
+          retry.maxRetries,
+          delay,
+          isBatch ? envelopes.map((e) => e.headers) : envelopes[0]?.headers ?? {},
+          deps
+        );
+        deps.onRetry?.(envelopes[0], 1, retry.maxRetries);
+      }
+    } else if (isLastAttempt) {
+      if (dlq) {
+        for (let i = 0; i < rawMessages.length; i++) {
+          await sendToDlq(topic2, rawMessages[i], deps, {
+            error,
+            attempt,
+            originalHeaders: envelopes[i]?.headers
+          });
+          deps.onDlq?.(envelopes[i] ?? envelopes[0], "handler-error");
+        }
+      } else {
+        await deps.onMessageLost?.({
+          topic: topic2,
+          error,
+          attempt,
+          headers: envelopes[0]?.headers ?? {}
+        });
+      }
+    } else {
+      const cap = Math.min(backoffMs * 2 ** (attempt - 1), maxBackoffMs);
+      deps.onRetry?.(envelopes[0], attempt, maxAttempts - 1);
+      await sleep(Math.floor(Math.random() * cap));
+    }
+  }
+}
+
+// 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 });
+      return;
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+      const msg = toError(error).message;
+      const delay = Math.floor(Math.random() * backoffMs);
+      logger.warn(
+        `Failed to subscribe to [${displayTopics}] (attempt ${attempt}/${maxAttempts}): ${msg}. Retrying in ${delay}ms...`
+      );
+      await sleep(delay);
+    }
+  }
+}
+
+// src/client/kafka.client/consumer/features/dlq-replay.ts
+async function replayDlqTopic(topic2, deps, options = {}) {
+  if (topic2.endsWith(".dlq")) {
+    throw new Error(
+      `replayDlq: pass the ORIGINAL topic name \u2014 "${topic2}" already ends in ".dlq" (the ".dlq" suffix is appended internally, so this would read "${topic2}.dlq")`
+    );
+  }
+  const dlqTopic = `${topic2}.dlq`;
+  const partitionOffsets = await deps.fetchTopicOffsets(dlqTopic);
+  const activePartitions = partitionOffsets.filter(
+    (p) => Number.parseInt(p.high, 10) > Number.parseInt(p.low, 10)
+  );
+  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, Number.parseInt(high, 10)])
+  );
+  const processedOffsets = /* @__PURE__ */ new Map();
+  let replayed = 0;
+  let skipped = 0;
+  const fromBeginning = options.fromBeginning ?? true;
+  const groupId = fromBeginning ? `${dlqTopic}-replay-${Date.now()}` : `${dlqTopic}-replay`;
+  await new Promise((resolve, reject) => {
+    const consumer = deps.createConsumer(groupId, fromBeginning);
+    const cleanup = () => deps.cleanupConsumer(consumer, groupId, fromBeginning);
+    consumer.connect().then(() => subscribeWithRetry(consumer, [dlqTopic], deps.logger)).then(
+      () => consumer.run({
+        eachMessage: async ({ partition, message }) => {
+          if (!message.value) return;
+          const offset = Number.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 bytes = message.value;
+          const shouldProcess = !options.filter || options.filter(headers, bytes.toString("utf8"));
+          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: bytes, 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;
+  }
+  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);
+  }
+  /**
+   * Increment the retry counter for the envelope's topic and fire all `onRetry` instrumentation hooks.
+   * @param envelope The message envelope being retried.
+   * @param attempt Current retry attempt number (1-based).
+   * @param maxRetries Maximum number of retries configured for this consumer.
+   */
+  notifyRetry(envelope, attempt, maxRetries) {
+    this.metricsFor(envelope.topic).retryCount++;
+    for (const inst of this.deps.instrumentation) inst.onRetry?.(envelope, attempt, maxRetries);
+  }
+  /**
+   * Increment the DLQ counter for the envelope's topic and fire all `onDlq` instrumentation hooks.
+   * Circuit breaker failures are recorded separately via `notifyFailure` at the
+   * handler-error boundary — dead-lettering itself is not a circuit event.
+   * @param envelope The message envelope being sent to the DLQ.
+   * @param reason The reason the message is being dead-lettered.
+   */
+  notifyDlq(envelope, reason) {
+    this.metricsFor(envelope.topic).dlqCount++;
+    for (const inst of this.deps.instrumentation) inst.onDlq?.(envelope, reason);
+  }
+  /**
+   * Notify the circuit breaker of a handler failure. Fired on every failed
+   * handler attempt (in-process retries and retry-topic levels included),
+   * independent of whether the message is ultimately dead-lettered.
+   * @param envelope The message envelope whose handler failed.
+   * @param gid Consumer group ID — used to drive circuit breaker state.
+   */
+  notifyFailure(envelope, gid) {
+    this.deps.onCircuitFailure(envelope, gid);
+  }
+  /**
+   * Increment the deduplication counter for the envelope's topic and fire all `onDuplicate` hooks.
+   * @param envelope The duplicate message envelope.
+   * @param strategy The deduplication strategy applied (`"drop"`, `"dlq"`, or `"topic"`).
+   */
+  notifyDuplicate(envelope, strategy) {
+    this.metricsFor(envelope.topic).dedupCount++;
+    for (const inst of this.deps.instrumentation) inst.onDuplicate?.(envelope, strategy);
+  }
+  /**
+   * Increment the processed counter for the envelope's topic, fire all `onMessage` hooks,
+   * and notify the circuit breaker of a success (when `gid` is provided).
+   * @param envelope The successfully processed message envelope.
+   * @param gid Consumer group ID — used to drive circuit breaker state.
+   */
+  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);
+  }
+  /**
+   * Return a snapshot of event counters.
+   * @param topic When provided, returns counters for that topic only; otherwise aggregates all topics.
+   * @returns Read-only `KafkaMetrics` snapshot. Returns zero-valued counters if the topic has no events.
+   */
+  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;
+  }
+  /**
+   * Reset event counters to zero.
+   * @param topic When provided, clears counters for that topic only; otherwise clears all topics.
+   */
+  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;
+  }
+  warn;
+  inFlightTotal = 0;
+  drainResolvers = [];
+  /**
+   * Wrap an async handler so its lifetime is counted against the in-flight total.
+   * Resolvers registered with `waitForDrain` are notified when the count reaches zero.
+   * @param fn The async function to track.
+   * @returns The same promise returned by `fn`.
+   */
+  track(fn) {
+    this.inFlightTotal++;
+    const done = () => {
+      this.inFlightTotal--;
+      if (this.inFlightTotal === 0) this.drainResolvers.splice(0).forEach((r) => r());
+    };
+    try {
+      return fn().finally(done);
+    } catch (err) {
+      done();
+      throw err;
+    }
+  }
+  /**
+   * Resolve when all tracked handlers have completed, or after `timeoutMs` elapses.
+   * Logs a warning (via the injected `warn` callback) if the timeout is hit before draining.
+   * Returns immediately if there are no in-flight handlers.
+   * @param timeoutMs Maximum time to wait in milliseconds before resolving anyway.
+   */
+  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/infra/circuit-breaker.manager.ts
+var CircuitBreakerManager = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  states = /* @__PURE__ */ new Map();
+  configs = /* @__PURE__ */ new Map();
+  /**
+   * Register or update circuit breaker configuration for a consumer group.
+   * Must be called before the group starts consuming for the config to take effect.
+   * @param gid Consumer group ID.
+   * @param options Circuit breaker thresholds and timing configuration.
+   */
+  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/consumer/queue.ts
+var AsyncQueue = class {
+  constructor(highWaterMark = Infinity, onFull = () => {
+  }, onDrained = () => {
+  }) {
+    this.highWaterMark = highWaterMark;
+    this.onFull = onFull;
+    this.onDrained = onDrained;
+  }
+  highWaterMark;
+  onFull;
+  onDrained;
+  items = [];
+  waiting = [];
+  closed = false;
+  error;
+  paused = false;
+  /**
+   * Enqueue an item. If a consumer is already awaiting the next item, delivers it immediately.
+   * When the internal buffer reaches `highWaterMark`, calls `onFull` to signal backpressure.
+   * @param item The value to enqueue.
+   */
+  push(item) {
+    if (this.closed) return;
+    if (this.waiting.length > 0) {
+      this.waiting.shift().resolve({ value: item, done: false });
+    } else {
+      this.items.push(item);
+      if (!this.paused && this.items.length >= this.highWaterMark) {
+        this.paused = true;
+        this.onFull();
+      }
+    }
+  }
+  /**
+   * Terminate the queue with an error. All pending and future `next()` calls will reject.
+   * @param err The error to propagate to all waiting consumers.
+   */
+  fail(err) {
+    this.closed = true;
+    this.error = err;
+    for (const { reject } of this.waiting.splice(0)) reject(err);
+  }
+  /**
+   * Signal end-of-stream. All pending `next()` calls resolve with `{ done: true }`,
+   * and future `next()` calls resolve immediately with `{ done: true }`.
+   */
+  close() {
+    this.closed = true;
+    for (const { resolve } of this.waiting.splice(0))
+      resolve({ value: void 0, done: true });
+  }
+  /**
+   * Pull the next item from the queue, conforming to the `AsyncIterator` protocol.
+   * Rejects if the queue has been failed. Resolves with `{ done: true }` if it has been closed.
+   * Suspends (returns a pending Promise) when the queue is empty and not yet closed.
+   * When items drain below `highWaterMark / 2`, calls `onDrained` to resume backpressure.
+   * @returns A Promise resolving to an `IteratorResult<V>`.
+   */
+  next() {
+    if (this.error) return Promise.reject(this.error);
+    if (this.items.length > 0) {
+      const value = this.items.shift();
+      if (this.paused && this.items.length <= Math.floor(this.highWaterMark / 2)) {
+        this.paused = false;
+        this.onDrained();
+      }
+      return Promise.resolve({ value, done: false });
+    }
+    if (this.closed) return Promise.resolve({ value: void 0, done: true });
+    return new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
+  }
+};
+
+// src/client/kafka.client/validate-options.ts
+function validateClientOptions(clientId, groupId, brokers, options) {
+  const problems = [];
+  if (typeof clientId !== "string" || clientId.trim() === "") {
+    problems.push("clientId must be a non-empty string");
+  }
+  if (typeof groupId !== "string" || groupId.trim() === "") {
+    problems.push("groupId must be a non-empty string");
+  }
+  if (!Array.isArray(brokers) || brokers.length === 0 && !options?.transport) {
+    problems.push("brokers must be a non-empty array of broker addresses");
+  } else if (brokers.some((b) => typeof b !== "string" || b.trim() === "")) {
+    problems.push("brokers must not contain empty entries");
+  }
+  if (options) {
+    const {
+      numPartitions,
+      transactionalId,
+      clockRecovery,
+      lagThrottle
+    } = options;
+    if (numPartitions !== void 0 && (!Number.isInteger(numPartitions) || numPartitions < 1)) {
+      problems.push(
+        `numPartitions must be a positive integer (got ${numPartitions})`
+      );
+    }
+    if (transactionalId !== void 0 && transactionalId.trim() === "") {
+      problems.push("transactionalId must be a non-empty string when set");
+    }
+    if (clockRecovery) {
+      if (!Array.isArray(clockRecovery.topics)) {
+        problems.push("clockRecovery.topics must be an array of topic names");
+      }
+      if (clockRecovery.timeoutMs !== void 0 && !(clockRecovery.timeoutMs > 0)) {
+        problems.push(
+          `clockRecovery.timeoutMs must be > 0 (got ${clockRecovery.timeoutMs})`
+        );
+      }
+    }
+    if (lagThrottle) {
+      if (!(lagThrottle.maxLag >= 0)) {
+        problems.push(`lagThrottle.maxLag must be >= 0 (got ${lagThrottle.maxLag})`);
+      }
+      if (lagThrottle.pollIntervalMs !== void 0 && !(lagThrottle.pollIntervalMs > 0)) {
+        problems.push(
+          `lagThrottle.pollIntervalMs must be > 0 (got ${lagThrottle.pollIntervalMs})`
+        );
+      }
+      if (lagThrottle.maxWaitMs !== void 0 && !(lagThrottle.maxWaitMs >= 0)) {
+        problems.push(
+          `lagThrottle.maxWaitMs must be >= 0 (got ${lagThrottle.maxWaitMs})`
+        );
+      }
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      `KafkaClient: invalid configuration:
+- ${problems.join("\n- ")}`
+    );
+  }
+}
+
+// src/client/security/resolve-security.ts
+var LOCAL_HOST_PATTERNS = [
+  /^localhost(:\d+)?$/i,
+  /^127\.\d+\.\d+\.\d+(:\d+)?$/,
+  /^\[?::1\]?(:\d+)?$/,
+  /^0\.0\.0\.0(:\d+)?$/,
+  /^host\.docker\.internal(:\d+)?$/i
+];
+function isLocalBroker(broker) {
+  return LOCAL_HOST_PATTERNS.some((re) => re.test(broker.trim()));
+}
+function resolveSecurityOptions(security, brokers, logger) {
+  const hasRemoteBroker = brokers.some((b) => !isLocalBroker(b));
+  if (!security?.sasl && security?.ssl !== true) {
+    if (hasRemoteBroker && !security?.allowInsecure) {
+      logger.warn(
+        "Connecting to non-local brokers without TLS or SASL \u2014 traffic and payloads travel in plaintext. Configure `security: { ssl, sasl }` for production clusters, or set `security: { allowInsecure: true }` to acknowledge an intentionally insecure setup."
+      );
+    }
+    return security;
+  }
+  if (security.sasl && security.ssl === void 0) {
+    return { ...security, ssl: true };
+  }
+  if (security.sasl && security.ssl === false) {
+    logger.warn(
+      "SASL credentials are configured with `ssl: false` \u2014 credentials will be sent over plaintext. This is only safe on fully trusted networks."
+    );
+  }
+  return security;
+}
+
+// src/client/kafka.client/producer/lifecycle.ts
+var _activeTransactionalIds = /* @__PURE__ */ new Set();
+async function ensureTopic(ctx, topic2) {
+  if (!ctx.autoCreateTopicsEnabled || ctx.ensuredTopics.has(topic2)) return;
+  let p = ctx.ensureTopicPromises.get(topic2);
+  if (!p) {
+    p = (async () => {
+      await ctx.adminOps.ensureConnected();
+      await ctx.adminOps.admin.createTopics({
+        topics: [{ topic: topic2, numPartitions: ctx.numPartitions }]
+      });
+      ctx.ensuredTopics.add(topic2);
+    })().finally(() => ctx.ensureTopicPromises.delete(topic2));
+    ctx.ensureTopicPromises.set(topic2, p);
+  }
+  await p;
+}
+async function createRetryTxProducer(ctx, transactionalId) {
+  if (_activeTransactionalIds.has(transactionalId)) {
+    ctx.logger.warn(
+      `transactionalId "${transactionalId}" 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 p = ctx.transport.producer({
+    idempotent: true,
+    transactionalId
+  });
+  await p.connect();
+  _activeTransactionalIds.add(transactionalId);
+  ctx.retryTxProducers.set(transactionalId, p);
+  return p;
+}
+async function connectProducerImpl(ctx) {
+  await ctx.producer.connect();
+  await recoverLamportClockImpl(ctx, ctx.clockRecoveryTopics);
+  if (ctx.lagThrottleOpts) startLagThrottlePoller(ctx);
+  ctx.logger.log("Producer connected");
+}
+async function disconnectImpl(ctx, drainTimeoutMs = 3e4) {
+  if (ctx._lagThrottleTimer) {
+    clearInterval(ctx._lagThrottleTimer);
+    ctx._lagThrottleTimer = void 0;
+  }
+  await ctx.inFlight.waitForDrain(drainTimeoutMs);
+  const tasks = [ctx.producer.disconnect()];
+  if (ctx.txProducer) {
+    tasks.push(ctx.txProducer.disconnect());
+    _activeTransactionalIds.delete(ctx.txId);
+    ctx.txProducer = void 0;
+    ctx.txProducerInitPromise = void 0;
+  }
+  for (const txId of ctx.retryTxProducers.keys())
+    _activeTransactionalIds.delete(txId);
+  for (const p of ctx.retryTxProducers.values()) tasks.push(p.disconnect());
+  ctx.retryTxProducers.clear();
+  for (const consumer of ctx.consumers.values())
+    tasks.push(consumer.disconnect());
+  tasks.push(ctx.adminOps.disconnect());
+  await Promise.allSettled(tasks);
+  ctx.consumers.clear();
+  ctx.runningConsumers.clear();
+  ctx.consumerCreationOptions.clear();
+  ctx.companionGroupIds.clear();
+  ctx.circuitBreaker.clear();
+  ctx.logger.log("All connections closed");
+}
+function startLagThrottlePoller(ctx) {
+  const opts = ctx.lagThrottleOpts;
+  const { maxLag, pollIntervalMs = 5e3 } = opts;
+  const groupId = opts.groupId;
+  const poll = async () => {
+    try {
+      const lags = await ctx.adminOps.getConsumerLag(groupId);
+      const total = lags.reduce((sum, e) => sum + e.lag, 0);
+      if (total > maxLag && !ctx._lagThrottled) {
+        ctx._lagThrottled = true;
+        ctx.logger.warn(
+          `lagThrottle: lag ${total} > ${maxLag} \u2014 producer sends will be delayed`
+        );
+      } else if (total <= maxLag && ctx._lagThrottled) {
+        ctx._lagThrottled = false;
+        ctx.logger.log(
+          `lagThrottle: lag ${total} \u2264 ${maxLag} \u2014 producer sends resumed`
+        );
+      }
+    } catch {
+    }
+  };
+  ctx._lagThrottleTimer = setInterval(() => {
+    void poll();
+  }, pollIntervalMs);
+  ctx._lagThrottleTimer.unref?.();
+}
+async function recoverLamportClockImpl(ctx, topics) {
+  if (topics.length === 0) return;
+  ctx.logger.log(
+    `Clock recovery: scanning ${topics.length} topic(s) for Lamport clock...`
+  );
+  await ctx.adminOps.ensureConnected();
+  const partitionsToRead = [];
+  for (const t of topics) {
+    let offsets;
+    try {
+      offsets = await ctx.adminOps.admin.fetchTopicOffsets(t);
+    } catch {
+      ctx.logger.warn(
+        `Clock recovery: could not fetch offsets for "${t}", skipping`
+      );
+      continue;
+    }
+    for (const { partition, high, low } of offsets) {
+      if (Number.parseInt(high, 10) > Number.parseInt(low, 10)) {
+        partitionsToRead.push({
+          topic: t,
+          partition,
+          lastOffset: String(Number.parseInt(high, 10) - 1)
+        });
+      }
+    }
+  }
+  if (partitionsToRead.length === 0) {
+    ctx.logger.log(
+      "Clock recovery: all topics empty \u2014 keeping Lamport clock at 0"
+    );
+    return;
+  }
+  const recoveryGroupId = `${ctx.clientId}-clock-recovery-${Date.now()}`;
+  let maxClock = -1;
+  await new Promise((resolve, reject) => {
+    const consumer = ctx.transport.consumer({ groupId: recoveryGroupId });
+    const remaining = new Set(
+      partitionsToRead.map((p) => `${p.topic}:${p.partition}`)
+    );
+    let settled = false;
+    const cleanup = () => {
+      consumer.disconnect().catch(() => {
+      }).finally(() => {
+        ctx.adminOps.deleteGroups([recoveryGroupId]).catch(() => {
+        });
+      });
+    };
+    const timeoutTimer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      ctx.logger.warn(
+        `Clock recovery: timed out after ${ctx.clockRecoveryTimeoutMs} ms with ${remaining.size} partition(s) unread \u2014 proceeding with partial result`
+      );
+      cleanup();
+      resolve();
+    }, ctx.clockRecoveryTimeoutMs);
+    timeoutTimer.unref?.();
+    consumer.connect().then(async () => {
+      const uniqueTopics = [
+        ...new Set(partitionsToRead.map((p) => p.topic))
+      ];
+      await consumer.subscribe({ topics: uniqueTopics });
+      for (const { topic: t, partition, lastOffset } of partitionsToRead) {
+        consumer.seek({ topic: t, partition, offset: lastOffset });
+      }
+    }).then(
+      () => consumer.run({
+        eachMessage: async ({ topic: t, partition, message }) => {
+          const key = `${t}:${partition}`;
+          if (!remaining.has(key)) return;
+          remaining.delete(key);
+          const clockHeader = message.headers?.[HEADER_LAMPORT_CLOCK];
+          if (clockHeader !== void 0) {
+            const raw = Buffer.isBuffer(clockHeader) ? clockHeader.toString() : String(clockHeader);
+            const clock = Number(raw);
+            if (!Number.isNaN(clock) && clock > maxClock) maxClock = clock;
+          }
+          if (remaining.size === 0 && !settled) {
+            settled = true;
+            clearTimeout(timeoutTimer);
+            cleanup();
+            resolve();
+          }
+        }
+      })
+    ).catch((err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
+      cleanup();
+      reject(err);
+    });
+  });
+  if (maxClock >= 0) {
+    ctx._lamportClock = maxClock;
+    ctx.logger.log(
+      `Clock recovery: Lamport clock restored \u2014 next clock will be ${maxClock + 1}`
+    );
+  } else {
+    ctx.logger.log(
+      "Clock recovery: no x-lamport-clock headers found \u2014 keeping clock at 0"
+    );
+  }
+}
+function wrapWithTimeoutWarning(logger, fn, timeoutMs, topic2) {
+  let timer;
+  const promise = fn().finally(() => {
+    if (timer !== void 0) clearTimeout(timer);
+  });
+  timer = setTimeout(() => {
+    logger.warn(
+      `Handler for topic "${topic2}" has not resolved after ${timeoutMs}ms \u2014 possible stuck handler`
+    );
+  }, timeoutMs);
+  return promise;
+}
+
+// src/client/kafka.client/producer/send.ts
+async function preparePayload(ctx, topicOrDesc, messages, compression) {
+  registerSchema(topicOrDesc, ctx.schemaRegistry, ctx.logger);
+  const payload = await buildSendPayload(
+    topicOrDesc,
+    messages,
+    ctx.producerOpsDeps,
+    compression
+  );
+  await ensureTopic(ctx, payload.topic);
+  return payload;
+}
+async function redirectToDelayed(ctx, payload, deliverAfterMs) {
+  const until = String(Date.now() + deliverAfterMs);
+  for (const m of payload.messages) {
+    m.headers[HEADER_DELAYED_UNTIL] = until;
+    m.headers[HEADER_DELAYED_TARGET] = payload.topic;
+  }
+  payload.topic = `${payload.topic}.delayed`;
+  await ensureTopic(ctx, payload.topic);
+}
+async function sendMessageImpl(ctx, topicOrDesc, message, options = {}) {
+  await waitIfThrottled(ctx);
+  const payload = await preparePayload(
+    ctx,
+    topicOrDesc,
+    [
+      {
+        value: message,
+        key: options.key,
+        headers: options.headers,
+        correlationId: options.correlationId,
+        schemaVersion: options.schemaVersion,
+        eventId: options.eventId
+      }
+    ],
+    options.compression
+  );
+  if (options.deliverAfterMs && options.deliverAfterMs > 0) {
+    await redirectToDelayed(ctx, payload, options.deliverAfterMs);
+  }
+  await ctx.producer.send(payload);
+  ctx.metrics.notifyAfterSend(payload.topic, payload.messages.length);
+}
+async function sendBatchImpl(ctx, topicOrDesc, messages, options) {
+  await waitIfThrottled(ctx);
+  const payload = await preparePayload(
+    ctx,
+    topicOrDesc,
+    messages,
+    options?.compression
+  );
+  if (options?.deliverAfterMs && options.deliverAfterMs > 0) {
+    await redirectToDelayed(ctx, payload, options.deliverAfterMs);
+  }
+  await ctx.producer.send(payload);
+  ctx.metrics.notifyAfterSend(payload.topic, payload.messages.length);
+}
+async function sendTombstoneImpl(ctx, topic2, key, headers) {
+  await waitIfThrottled(ctx);
+  const hdrs = { ...headers };
+  for (const inst of ctx.instrumentation) inst.beforeSend?.(topic2, hdrs);
+  await ensureTopic(ctx, topic2);
+  await ctx.producer.send({
+    topic: topic2,
+    messages: [{ value: null, key, headers: hdrs }]
+  });
+  for (const inst of ctx.instrumentation) inst.afterSend?.(topic2);
+}
+async function transactionImpl(ctx, fn) {
+  if (!ctx.txProducerInitPromise) {
+    if (_activeTransactionalIds.has(ctx.txId)) {
+      ctx.logger.warn(
+        `transactionalId "${ctx.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 = ctx.transport.producer({
+        idempotent: true,
+        transactionalId: ctx.txId
+      });
+      await p.connect();
+      _activeTransactionalIds.add(ctx.txId);
+      return p;
+    })();
+    ctx.txProducerInitPromise = initPromise.catch((err) => {
+      ctx.txProducerInitPromise = void 0;
+      throw err;
+    });
+  }
+  ctx.txProducer = await ctx.txProducerInitPromise;
+  const prev = ctx._txChain;
+  let release;
+  ctx._txChain = new Promise((r) => release = r);
+  await prev;
+  try {
+    await runTransaction(ctx, fn);
+  } finally {
+    release();
+  }
+}
+async function runTransaction(ctx, fn) {
+  const tx = await ctx.txProducer.transaction();
+  try {
+    const txCtx = {
+      send: async (topicOrDesc, message, sendOpts = {}) => {
+        const payload = await preparePayload(ctx, topicOrDesc, [
+          {
+            value: message,
+            key: sendOpts.key,
+            headers: sendOpts.headers,
+            correlationId: sendOpts.correlationId,
+            schemaVersion: sendOpts.schemaVersion,
+            eventId: sendOpts.eventId
+          }
+        ]);
+        await tx.send(payload);
+        ctx.metrics.notifyAfterSend(payload.topic, payload.messages.length);
+      },
+      sendBatch: async (topicOrDesc, messages, batchOpts) => {
+        const payload = await preparePayload(
+          ctx,
+          topicOrDesc,
+          messages,
+          batchOpts?.compression
+        );
+        await tx.send(payload);
+        ctx.metrics.notifyAfterSend(payload.topic, payload.messages.length);
+      }
+    };
+    await fn(txCtx);
+    await tx.commit();
+  } catch (error) {
+    try {
+      await tx.abort();
+    } catch (abortError) {
+      ctx.logger.error(
+        "Failed to abort transaction:",
+        (abortError instanceof Error ? abortError : new Error(String(abortError))).message
+      );
+    }
+    throw error;
+  }
+}
+async function waitIfThrottled(ctx) {
+  if (!ctx._lagThrottled) return;
+  const maxWait = ctx.lagThrottleOpts?.maxWaitMs ?? 3e4;
+  const start = Date.now();
+  while (ctx._lagThrottled) {
+    if (Date.now() - start >= maxWait) {
+      ctx.logger.warn(
+        `lagThrottle: maxWaitMs (${maxWait} ms) exceeded \u2014 sending anyway`
+      );
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+}
+
+// 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;
+  while (Date.now() < deadline) {
+    try {
+      const assigned = consumer.assignment();
+      if (assigned.some((a) => topicSet.has(a.topic))) return;
+    } catch {
+    }
+    await sleep(200);
+  }
+  logger.warn(
+    `Retry consumer did not receive partition assignments for [${topics.join(", ")}] within ${timeoutMs}ms`
+  );
+}
+async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopics, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs, serdeMap) {
+  const {
+    logger,
+    producer,
+    instrumentation,
+    onMessageLost,
+    onRetry,
+    onDlq,
+    onMessage,
+    ensureTopic: ensureTopic2,
+    getOrCreateConsumer: getOrCreateConsumer2,
+    runningConsumers,
+    createRetryTxProducer: createRetryTxProducer2
+  } = deps;
+  const backoffMs = retry.backoffMs ?? 1e3;
+  const maxBackoffMs = retry.maxBackoffMs ?? 3e4;
+  const pipelineDeps = { logger, producer, instrumentation, onMessageLost };
+  for (const lt of levelTopics) {
+    await ensureTopic2(lt);
+  }
+  const levelTxProducer = await createRetryTxProducer2(`${levelGroupId}-tx`);
+  const consumer = getOrCreateConsumer2(levelGroupId, false, false);
+  await consumer.connect();
+  await subscribeWithRetry(consumer, levelTopics, logger);
+  await consumer.run({
+    eachMessage: async ({ topic: levelTopic, partition, message }) => {
+      const nextOffset = {
+        topic: levelTopic,
+        partition,
+        offset: (parseInt(message.offset, 10) + 1).toString()
+      };
+      if (!message.value) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const headers = decodeHeaders(message.headers);
+      const retryAfter = parseInt(
+        headers[RETRY_HEADER_AFTER] ?? "0",
+        10
+      );
+      const remaining = retryAfter - Date.now();
+      if (remaining > 0) {
+        consumer.pause([{ topic: levelTopic, partitions: [partition] }]);
+        await sleep(remaining);
+        consumer.resume([{ topic: levelTopic, partitions: [partition] }]);
+      }
+      const rawBytes = message.value;
+      const currentMaxRetries = parseInt(
+        headers[RETRY_HEADER_MAX_RETRIES] ?? String(retry.maxRetries),
+        10
+      );
+      const originalTopic = headers[RETRY_HEADER_ORIGINAL_TOPIC] ?? levelTopic.replace(/\.retry\.\d+$/, "");
+      const serde = serdeMap?.get(originalTopic) ?? deps.serde;
+      let parsed;
+      try {
+        parsed = await serde.deserialize(rawBytes, {
+          topic: originalTopic,
+          headers,
+          isKey: false
+        });
+      } catch (err) {
+        logger.error(
+          `Failed to deserialize retry message from topic ${levelTopic}:`,
+          toError(err).stack
+        );
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      if (parsed === null) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const validated = await validateWithSchema(
+        parsed,
+        rawBytes,
+        originalTopic,
+        schemaMap,
+        interceptors,
+        dlq,
+        { ...pipelineDeps, originalHeaders: headers }
+      );
+      if (validated === null) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const envelope = extractEnvelope(
+        validated,
+        headers,
+        originalTopic,
+        partition,
+        message.offset
+      );
+      const error = await runHandlerWithPipeline(
+        () => runWithEnvelopeContext(
+          {
+            correlationId: envelope.correlationId,
+            traceparent: envelope.traceparent
+          },
+          () => handleMessage(envelope)
+        ),
+        [envelope],
+        interceptors,
+        instrumentation
+      );
+      if (!error) {
+        onMessage?.(envelope);
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      deps.onFailure?.(envelope);
+      const exhausted = level >= currentMaxRetries;
+      const reportedError = exhausted && currentMaxRetries > 1 ? new KafkaRetryExhaustedError(
+        originalTopic,
+        [envelope.payload],
+        currentMaxRetries,
+        { cause: error }
+      ) : error;
+      await notifyInterceptorsOnError([envelope], interceptors, reportedError);
+      logger.error(
+        `Retry consumer error for ${originalTopic} (level ${level}/${currentMaxRetries}):`,
+        error.stack
+      );
+      if (!exhausted) {
+        const nextLevel = level + 1;
+        const cap = Math.min(backoffMs * 2 ** level, maxBackoffMs);
+        const delay = Math.floor(Math.random() * cap);
+        const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
+          originalTopic,
+          [rawBytes],
+          nextLevel,
+          currentMaxRetries,
+          delay,
+          headers
+        );
+        const tx = await levelTxProducer.transaction();
+        try {
+          await tx.send({ topic: rtTopic, messages: rtMsgs });
+          await tx.sendOffsets({
+            consumer,
+            topics: [
+              {
+                topic: nextOffset.topic,
+                partitions: [
+                  {
+                    partition: nextOffset.partition,
+                    offset: nextOffset.offset
+                  }
+                ]
+              }
+            ]
+          });
+          await tx.commit();
+          logger.warn(
+            `Message routed to ${rtTopic} (EOS, level ${nextLevel}/${currentMaxRetries})`
+          );
+          onRetry?.(envelope, nextLevel, currentMaxRetries);
+        } catch (txErr) {
+          try {
+            await tx.abort();
+          } catch {
+          }
+          logger.error(
+            `EOS routing to ${rtTopic} failed \u2014 message will be redelivered:`,
+            toError(txErr).stack
+          );
+          return;
+        }
+      } else if (dlq) {
+        const { topic: dTopic, messages: dMsgs } = buildDlqPayload(
+          originalTopic,
+          rawBytes,
+          {
+            error,
+            // +1 to account for the main consumer's initial attempt before routing.
+            attempt: level + 1,
+            originalHeaders: headers
+          }
+        );
+        const tx = await levelTxProducer.transaction();
+        try {
+          await tx.send({ topic: dTopic, messages: dMsgs });
+          await tx.sendOffsets({
+            consumer,
+            topics: [
+              {
+                topic: nextOffset.topic,
+                partitions: [
+                  {
+                    partition: nextOffset.partition,
+                    offset: nextOffset.offset
+                  }
+                ]
+              }
+            ]
+          });
+          await tx.commit();
+          logger.warn(`Message sent to DLQ: ${dTopic} (EOS)`);
+          onDlq?.(envelope, "handler-error");
+        } catch (txErr) {
+          try {
+            await tx.abort();
+          } catch {
+          }
+          logger.error(
+            `EOS DLQ routing to ${dTopic} failed \u2014 message will be redelivered:`,
+            toError(txErr).stack
+          );
+          return;
+        }
+      } else {
+        await onMessageLost?.({
+          topic: originalTopic,
+          error,
+          attempt: level,
+          headers
+        });
+        await consumer.commitOffsets([nextOffset]);
+      }
+    }
+  });
+  runningConsumers.set(levelGroupId, "eachMessage");
+  await waitForPartitionAssignment(
+    consumer,
+    levelTopics,
+    logger,
+    assignmentTimeoutMs
+  );
+  deps.onLevelStarted?.(levelGroupId);
+  logger.log(
+    `Retry level ${level}/${retry.maxRetries} consumer started for: ${originalTopics.join(", ")} (group: ${levelGroupId})`
+  );
+}
+async function startRetryTopicConsumers(originalTopics, originalGroupId, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs, serdeMap) {
+  const levelGroupIds = new Array(retry.maxRetries);
+  await Promise.all(
+    Array.from({ length: retry.maxRetries }, async (_, i) => {
+      const level = i + 1;
+      const levelTopics = originalTopics.map((t) => `${t}.retry.${level}`);
+      const levelGroupId = `${originalGroupId}-retry.${level}`;
+      await startLevelConsumer(
+        level,
+        levelTopics,
+        levelGroupId,
+        originalTopics,
+        handleMessage,
+        retry,
+        dlq,
+        interceptors,
+        schemaMap,
+        deps,
+        assignmentTimeoutMs,
+        serdeMap
+      );
+      levelGroupIds[i] = levelGroupId;
+    })
+  );
+  return levelGroupIds;
+}
+
+// src/client/kafka.client/consumer/setup.ts
+function 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."
+    );
+  }
+}
+async function ensureConsumerTopics(ctx, topicNames, dlq, deduplication) {
+  for (const t of topicNames) await ensureTopic(ctx, t);
+  if (dlq) {
+    for (const t of topicNames) await ensureTopic(ctx, `${t}.dlq`);
+    if (!ctx.autoCreateTopicsEnabled && topicNames.length > 0) {
+      await ctx.adminOps.validateDlqTopicsExist(topicNames);
+    }
+  }
+  if (deduplication?.strategy === "topic") {
+    const dest = deduplication.duplicatesTopic;
+    if (ctx.autoCreateTopicsEnabled) {
+      for (const t of topicNames)
+        await ensureTopic(ctx, dest ?? `${t}.duplicates`);
+    } else if (topicNames.length > 0) {
+      await ctx.adminOps.validateDuplicatesTopicsExist(topicNames, dest);
+    }
+  }
+}
+async function setupConsumer(ctx, topics, mode, options) {
+  const {
+    groupId: optGroupId,
+    fromBeginning = false,
+    retry,
+    dlq = false,
+    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 || ctx.defaultGroupId;
+  const existingMode = ctx.runningConsumers.get(gid);
+  const oppositeMode = mode === "eachMessage" ? "eachBatch" : "eachMessage";
+  if (existingMode === oppositeMode) {
+    throw new Error(
+      `Cannot use ${mode} on consumer group "${gid}" \u2014 it is already running with ${oppositeMode}. Use a different groupId for this consumer.`
+    );
+  }
+  if (existingMode === mode) {
+    const callerName = mode === "eachMessage" ? "startConsumer" : "startBatchConsumer";
+    throw new Error(
+      `${callerName}("${gid}") called twice \u2014 this group is already consuming. Call stopConsumer("${gid}") first or pass a different groupId.`
+    );
+  }
+  let resolveReady;
+  const readyPromise = new Promise((resolve) => {
+    resolveReady = resolve;
+  });
+  const consumer = getOrCreateConsumer(
+    gid,
+    fromBeginning,
+    options.autoCommit ?? true,
+    ctx.consumerOpsDeps,
+    options.partitionAssigner,
+    resolveReady,
+    options.groupInstanceId
+  );
+  const schemaMap = buildSchemaMap(
+    stringTopics,
+    ctx.schemaRegistry,
+    optionSchemas,
+    ctx.logger
+  );
+  const serdeMap = buildSerdeMap(stringTopics);
+  const topicNames = stringTopics.map((t) => resolveTopicName(t));
+  const subscribeTopics = [...topicNames, ...regexTopics];
+  await ensureConsumerTopics(ctx, topicNames, dlq, options.deduplication);
+  await consumer.connect();
+  if (dlq || options.retryTopics || options.deduplication) {
+    await ctx.producer.connect();
+  }
+  await subscribeWithRetry(
+    consumer,
+    subscribeTopics,
+    ctx.logger,
+    options.subscribeRetry
+  );
+  const displayTopics = subscribeTopics.map((t) => t instanceof RegExp ? t.toString() : t).join(", ");
+  ctx.logger.log(
+    `${mode === "eachBatch" ? "Batch consumer" : "Consumer"} subscribed to topics: ${displayTopics}`
+  );
+  return { consumer, schemaMap, serdeMap, topicNames, gid, dlq, interceptors, retry, hasRegex, readyPromise };
+}
+function resolveDeduplicationContext(ctx, groupId, options) {
+  if (!options) return void 0;
+  const store = options.store ?? new InMemoryDedupStore(ctx.dedupStates);
+  return { options, store, groupId };
+}
+function messageDepsFor(ctx, gid, options) {
+  const notifyRetry = ctx.metrics.notifyRetry.bind(ctx.metrics);
+  return {
+    logger: ctx.logger,
+    producer: ctx.producer,
+    serde: ctx.serde,
+    instrumentation: ctx.instrumentation,
+    onMessageLost: options?.onMessageLost ?? ctx.onMessageLost,
+    onTtlExpired: ctx.onTtlExpired,
+    onRetry: options?.onRetry ? (envelope, attempt, max) => {
+      notifyRetry(envelope, attempt, max);
+      return options.onRetry(envelope, attempt, max);
+    } : notifyRetry,
+    onDlq: (envelope, reason) => ctx.metrics.notifyDlq(envelope, reason),
+    onDuplicate: ctx.metrics.notifyDuplicate.bind(ctx.metrics),
+    onMessage: (envelope) => ctx.metrics.notifyMessage(envelope, gid),
+    onFailure: (envelope) => ctx.metrics.notifyFailure(envelope, gid)
+  };
+}
+function buildRetryTopicDeps(ctx) {
+  return {
+    logger: ctx.logger,
+    producer: ctx.producer,
+    serde: ctx.serde,
+    instrumentation: ctx.instrumentation,
+    onMessageLost: ctx.onMessageLost,
+    onRetry: ctx.metrics.notifyRetry.bind(ctx.metrics),
+    onDlq: ctx.metrics.notifyDlq.bind(ctx.metrics),
+    onMessage: ctx.metrics.notifyMessage.bind(ctx.metrics),
+    ensureTopic: (t) => ensureTopic(ctx, t),
+    getOrCreateConsumer: (gid, fb, ac) => getOrCreateConsumer(gid, fb, ac, ctx.consumerOpsDeps),
+    runningConsumers: ctx.runningConsumers,
+    createRetryTxProducer: (txId) => createRetryTxProducer(ctx, txId)
+  };
+}
+async function makeEosMainContext(ctx, gid, consumer, options) {
+  if (!options.retryTopics || !options.retry) return void 0;
+  const txProducer = await createRetryTxProducer(ctx, `${gid}-main-tx`);
+  return { txProducer, consumer };
+}
+async function launchRetryChain(ctx, gid, topicNames, handleMessage, opts) {
+  const { retry, dlq, interceptors, schemaMap, serdeMap, assignmentTimeoutMs } = opts;
+  if (!ctx.autoCreateTopicsEnabled) {
+    await ctx.adminOps.validateRetryTopicsExist(topicNames, retry.maxRetries);
+  }
+  ctx.companionGroupIds.set(gid, []);
+  await startRetryTopicConsumers(
+    topicNames,
+    gid,
+    handleMessage,
+    retry,
+    dlq,
+    interceptors,
+    schemaMap,
+    {
+      ...ctx.retryTopicDeps,
+      // Bind circuit breaker events to the MAIN consumer group so failures and
+      // successes inside the retry chain drive the same breaker as the main
+      // consumer (the retry chain has no breaker config of its own).
+      onFailure: (envelope) => ctx.metrics.notifyFailure(envelope, gid),
+      onMessage: (envelope) => ctx.metrics.notifyMessage(envelope, gid),
+      onLevelStarted: (levelGroupId) => {
+        ctx.companionGroupIds.get(gid).push(levelGroupId);
+      }
+    },
+    assignmentTimeoutMs,
+    serdeMap
+  );
+}
+
+// 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;
+  const incomingClock = Number(clockRaw);
+  if (Number.isNaN(incomingClock)) return false;
+  const stateKey = `${envelope.topic}:${envelope.partition}`;
+  let lastProcessedClock;
+  try {
+    lastProcessedClock = await dedup.store.getLastClock(dedup.groupId, stateKey) ?? -1;
+  } catch (err) {
+    deps.logger.error(
+      `Dedup store getLastClock failed on ${envelope.topic}[${envelope.partition}] \u2014 treating message as not a duplicate (fail-open): ${err.message}`
+    );
+    return false;
+  }
+  if (incomingClock <= lastProcessedClock) {
+    const meta = {
+      incomingClock,
+      lastProcessedClock,
+      originalHeaders: envelope.headers
+    };
+    const strategy = dedup.options.strategy ?? "drop";
+    deps.logger.warn(
+      `Duplicate message on ${envelope.topic}[${envelope.partition}]: clock=${incomingClock} <= last=${lastProcessedClock} \u2014 strategy=${strategy}`
+    );
+    deps.onDuplicate?.(envelope, strategy);
+    if (strategy === "dlq" && dlq) {
+      const augmentedHeaders = {
+        ...envelope.headers,
+        "x-dlq-reason": "lamport-clock-duplicate",
+        "x-dlq-duplicate-incoming-clock": String(incomingClock),
+        "x-dlq-duplicate-last-processed-clock": String(lastProcessedClock)
+      };
+      await sendToDlq(envelope.topic, raw, deps, {
+        error: new Error("Lamport Clock duplicate detected"),
+        attempt: 0,
+        originalHeaders: augmentedHeaders
+      });
+    } else if (strategy === "topic") {
+      const destination = dedup.options.duplicatesTopic ?? `${envelope.topic}.duplicates`;
+      await sendToDuplicatesTopic(envelope.topic, raw, destination, deps, meta);
+    }
+    return true;
+  }
+  try {
+    await dedup.store.setLastClock(dedup.groupId, stateKey, incomingClock);
+  } catch (err) {
+    deps.logger.error(
+      `Dedup store setLastClock failed on ${envelope.topic}[${envelope.partition}] \u2014 processing message anyway (fail-open): ${err.message}`
+    );
+  }
+  return false;
+}
+async function parseSingleMessage(message, topic2, partition, schemaMap, interceptors, dlq, deps, serdeMap) {
+  if (!message.value) {
+    deps.logger.warn(`Received empty message from topic ${topic2}`);
+    return null;
+  }
+  const bytes = message.value;
+  const headers = decodeHeaders(message.headers);
+  const serde = serdeMap?.get(topic2) ?? deps.serde;
+  let parsed;
+  try {
+    parsed = await serde.deserialize(bytes, { topic: topic2, headers, isKey: false });
+  } catch (error) {
+    deps.logger.error(
+      `Failed to deserialize message from topic ${topic2}:`,
+      toError(error).stack
+    );
+    return null;
+  }
+  if (parsed === null) return null;
+  const validated = await validateWithSchema(
+    parsed,
+    // Forward the ORIGINAL bytes to DLQ on validation failure (binary-safe).
+    bytes,
+    topic2,
+    schemaMap,
+    interceptors,
+    dlq,
+    { ...deps, originalHeaders: headers }
+  );
+  if (validated === null) return null;
+  return extractEnvelope(validated, headers, topic2, partition, message.offset);
+}
+async function handleEachMessage(payload, opts, deps) {
+  const { topic: topic2, partition, message } = payload;
+  const {
+    schemaMap,
+    serdeMap,
+    handleMessage,
+    interceptors,
+    dlq,
+    retry,
+    retryTopics,
+    timeoutMs,
+    wrapWithTimeout
+  } = opts;
+  const rawBytes = message.value;
+  const eos = opts.eosMainContext;
+  const nextOffsetStr = (parseInt(message.offset, 10) + 1).toString();
+  const commitOffset = eos ? async () => {
+    await eos.consumer.commitOffsets([
+      { topic: topic2, partition, offset: nextOffsetStr }
+    ]);
+  } : void 0;
+  const eosRouteToRetry = eos && retry ? async (rawMsgs, envelopes, delay) => {
+    const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
+      topic2,
+      rawMsgs,
+      1,
+      retry.maxRetries,
+      delay,
+      envelopes[0]?.headers ?? {}
+    );
+    const tx = await eos.txProducer.transaction();
+    try {
+      await tx.send({ topic: rtTopic, messages: rtMsgs });
+      await tx.sendOffsets({
+        consumer: eos.consumer,
+        topics: [
+          {
+            topic: topic2,
+            partitions: [{ partition, offset: nextOffsetStr }]
+          }
+        ]
+      });
+      await tx.commit();
+    } catch (txErr) {
+      try {
+        await tx.abort();
+      } catch {
+      }
+      throw txErr;
+    }
+  } : void 0;
+  const envelope = await parseSingleMessage(
+    message,
+    topic2,
+    partition,
+    schemaMap,
+    interceptors,
+    dlq,
+    deps,
+    serdeMap
+  );
+  if (envelope === null) {
+    await commitOffset?.();
+    return;
+  }
+  if (opts.deduplication) {
+    const isDuplicate = await applyDeduplication(
+      envelope,
+      rawBytes,
+      opts.deduplication,
+      dlq,
+      deps
+    );
+    if (isDuplicate) {
+      await commitOffset?.();
+      return;
+    }
+  }
+  if (opts.messageTtlMs !== void 0) {
+    const ageMs = Date.now() - new Date(envelope.timestamp).getTime();
+    if (ageMs > opts.messageTtlMs) {
+      deps.logger.warn(
+        `[KafkaClient] TTL expired on ${topic2}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
+      );
+      if (dlq) {
+        await sendToDlq(topic2, rawBytes, deps, {
+          error: new Error(`Message TTL expired: age ${ageMs}ms`),
+          attempt: 0,
+          originalHeaders: envelope.headers
+        });
+        deps.onDlq?.(envelope, "ttl-expired");
+      } else {
+        const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
+        await ttlHandler?.({
+          topic: topic2,
+          ageMs,
+          messageTtlMs: opts.messageTtlMs,
+          headers: envelope.headers
+        });
+      }
+      await commitOffset?.();
+      return;
+    }
+  }
+  await executeWithRetry(
+    () => {
+      const fn = () => runWithEnvelopeContext(
+        {
+          correlationId: envelope.correlationId,
+          traceparent: envelope.traceparent
+        },
+        () => handleMessage(envelope)
+      );
+      return timeoutMs ? wrapWithTimeout(fn, timeoutMs, topic2) : fn();
+    },
+    {
+      envelope,
+      rawMessages: [rawBytes],
+      interceptors,
+      dlq,
+      retry,
+      retryTopics
+    },
+    { ...deps, eosRouteToRetry, eosCommitOnSuccess: commitOffset }
+  );
+}
+async function handleEachBatch(payload, opts, deps) {
+  const { batch, heartbeat, resolveOffset, commitOffsetsIfNecessary } = payload;
+  const {
+    schemaMap,
+    serdeMap,
+    handleBatch,
+    interceptors,
+    dlq,
+    retry,
+    retryTopics,
+    timeoutMs,
+    wrapWithTimeout
+  } = opts;
+  const eos = opts.eosMainContext;
+  const lastRawOffset = batch.messages.length > 0 ? batch.messages[batch.messages.length - 1].offset : void 0;
+  const batchNextOffsetStr = lastRawOffset ? (parseInt(lastRawOffset, 10) + 1).toString() : void 0;
+  const commitBatchOffset = eos && batchNextOffsetStr ? async () => {
+    await eos.consumer.commitOffsets([
+      {
+        topic: batch.topic,
+        partition: batch.partition,
+        offset: batchNextOffsetStr
+      }
+    ]);
+  } : void 0;
+  const eosRouteToRetry = eos && retry && batchNextOffsetStr ? async (rawMsgs, envelopes2, delay) => {
+    const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
+      batch.topic,
+      rawMsgs,
+      1,
+      retry.maxRetries,
+      delay,
+      envelopes2.map((e) => e.headers)
+    );
+    const tx = await eos.txProducer.transaction();
+    try {
+      await tx.send({ topic: rtTopic, messages: rtMsgs });
+      await tx.sendOffsets({
+        consumer: eos.consumer,
+        topics: [
+          {
+            topic: batch.topic,
+            partitions: [
+              { partition: batch.partition, offset: batchNextOffsetStr }
+            ]
+          }
+        ]
+      });
+      await tx.commit();
+    } catch (txErr) {
+      try {
+        await tx.abort();
+      } catch {
+      }
+      throw txErr;
+    }
+  } : void 0;
+  const envelopes = [];
+  const rawMessages = [];
+  for (const message of batch.messages) {
+    const rawBytes = message.value;
+    const envelope = await parseSingleMessage(
+      message,
+      batch.topic,
+      batch.partition,
+      schemaMap,
+      interceptors,
+      dlq,
+      deps,
+      serdeMap
+    );
+    if (envelope === null) continue;
+    if (opts.deduplication) {
+      const isDuplicate = await applyDeduplication(
+        envelope,
+        rawBytes,
+        opts.deduplication,
+        dlq,
+        deps
+      );
+      if (isDuplicate) continue;
+    }
+    if (opts.messageTtlMs !== void 0) {
+      const ageMs = Date.now() - new Date(envelope.timestamp).getTime();
+      if (ageMs > opts.messageTtlMs) {
+        deps.logger.warn(
+          `[KafkaClient] TTL expired on ${batch.topic}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
+        );
+        if (dlq) {
+          await sendToDlq(batch.topic, rawBytes, deps, {
+            error: new Error(`Message TTL expired: age ${ageMs}ms`),
+            attempt: 0,
+            originalHeaders: envelope.headers
+          });
+          deps.onDlq?.(envelope, "ttl-expired");
+        } else {
+          const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
+          await ttlHandler?.({
+            topic: batch.topic,
+            ageMs,
+            messageTtlMs: opts.messageTtlMs,
+            headers: envelope.headers
+          });
+        }
+        continue;
+      }
+    }
+    envelopes.push(envelope);
+    rawMessages.push(rawBytes);
+  }
+  if (envelopes.length === 0) {
+    await commitBatchOffset?.();
+    return;
+  }
+  const meta = {
+    partition: batch.partition,
+    highWatermark: batch.highWatermark,
+    heartbeat,
+    resolveOffset,
+    commitOffsetsIfNecessary
+  };
+  await executeWithRetry(
+    () => {
+      const fn = () => handleBatch(envelopes, meta);
+      return timeoutMs ? wrapWithTimeout(fn, timeoutMs, batch.topic) : fn();
+    },
+    {
+      envelope: envelopes,
+      rawMessages,
+      interceptors,
+      dlq,
+      retry,
+      isBatch: true,
+      retryTopics
+    },
+    { ...deps, eosRouteToRetry, eosCommitOnSuccess: commitBatchOffset }
+  );
+}
+
+// src/client/kafka.client/consumer/stop.ts
+async function stopConsumerImpl(ctx, groupId) {
+  if (groupId === void 0) {
+    const tasks = [
+      ...Array.from(ctx.consumers.values()).map(
+        (c) => c.disconnect().catch(() => {
+        })
+      ),
+      ...Array.from(ctx.retryTxProducers.values()).map(
+        (p) => p.disconnect().catch(() => {
+        })
+      )
+    ];
+    await Promise.allSettled(tasks);
+    ctx.consumers.clear();
+    ctx.runningConsumers.clear();
+    ctx.consumerCreationOptions.clear();
+    ctx.companionGroupIds.clear();
+    ctx.retryTxProducers.clear();
+    ctx.dedupStates.clear();
+    ctx.circuitBreaker.clear();
+    ctx.logger.log("All consumers disconnected");
+    return;
+  }
+  const consumer = ctx.consumers.get(groupId);
+  if (!consumer) {
+    ctx.logger.warn(
+      `stopConsumer: no active consumer for group "${groupId}"`
+    );
+    return;
+  }
+  await consumer.disconnect().catch(
+    (e) => ctx.logger.warn(
+      `Error disconnecting consumer "${groupId}":`,
+      toError(e).message
+    )
+  );
+  ctx.consumers.delete(groupId);
+  ctx.runningConsumers.delete(groupId);
+  ctx.consumerCreationOptions.delete(groupId);
+  ctx.dedupStates.delete(groupId);
+  ctx.circuitBreaker.removeGroup(groupId);
+  ctx.logger.log(`Consumer disconnected: group "${groupId}"`);
+  const mainTxId = `${groupId}-main-tx`;
+  const mainTxProducer = ctx.retryTxProducers.get(mainTxId);
+  if (mainTxProducer) {
+    await mainTxProducer.disconnect().catch(
+      (e) => ctx.logger.warn(
+        `Error disconnecting main tx producer "${mainTxId}":`,
+        toError(e).message
+      )
+    );
+    _activeTransactionalIds.delete(mainTxId);
+    ctx.retryTxProducers.delete(mainTxId);
+  }
+  const companions = ctx.companionGroupIds.get(groupId) ?? [];
+  for (const cGroupId of companions) {
+    const cConsumer = ctx.consumers.get(cGroupId);
+    if (cConsumer) {
+      await cConsumer.disconnect().catch(
+        (e) => ctx.logger.warn(
+          `Error disconnecting retry consumer "${cGroupId}":`,
+          toError(e).message
+        )
+      );
+      ctx.consumers.delete(cGroupId);
+      ctx.runningConsumers.delete(cGroupId);
+      ctx.consumerCreationOptions.delete(cGroupId);
+      ctx.logger.log(`Retry consumer disconnected: group "${cGroupId}"`);
+    }
+    const txId = `${cGroupId}-tx`;
+    const txProducer = ctx.retryTxProducers.get(txId);
+    if (txProducer) {
+      await txProducer.disconnect().catch(
+        (e) => ctx.logger.warn(
+          `Error disconnecting retry tx producer "${txId}":`,
+          toError(e).message
+        )
+      );
+      _activeTransactionalIds.delete(txId);
+      ctx.retryTxProducers.delete(txId);
+    }
+  }
+  ctx.companionGroupIds.delete(groupId);
+}
+function pauseConsumerImpl(ctx, groupId, assignments) {
+  const gid = groupId ?? ctx.defaultGroupId;
+  const consumer = ctx.consumers.get(gid);
+  if (!consumer) {
+    ctx.logger.warn(`pauseConsumer: no active consumer for group "${gid}"`);
+    return;
+  }
+  consumer.pause(
+    assignments.flatMap(
+      ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
+    )
+  );
+}
+function resumeConsumerImpl(ctx, groupId, assignments) {
+  const gid = groupId ?? ctx.defaultGroupId;
+  const consumer = ctx.consumers.get(gid);
+  if (!consumer) {
+    ctx.logger.warn(`resumeConsumer: no active consumer for group "${gid}"`);
+    return;
+  }
+  consumer.resume(
+    assignments.flatMap(
+      ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
+    )
+  );
+}
+function pauseTopicAllPartitions(ctx, gid, topic2) {
+  const consumer = ctx.consumers.get(gid);
+  if (!consumer) return;
+  const assignment = consumer.assignment();
+  const partitions = assignment.filter((a) => a.topic === topic2).map((a) => a.partition);
+  if (partitions.length > 0)
+    consumer.pause(partitions.map((p) => ({ topic: topic2, partitions: [p] })));
+}
+function resumeTopicAllPartitions(ctx, gid, topic2) {
+  const consumer = ctx.consumers.get(gid);
+  if (!consumer) return;
+  const assignment = consumer.assignment();
+  const partitions = assignment.filter((a) => a.topic === topic2).map((a) => a.partition);
+  if (partitions.length > 0)
+    consumer.resume(partitions.map((p) => ({ topic: topic2, partitions: [p] })));
+}
+
+// src/client/kafka.client/consumer/start.ts
+async function startConsumerImpl(ctx, topics, handleMessage, options = {}) {
+  validateTopicConsumerOpts(topics, options);
+  const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
+  const { consumer, schemaMap, serdeMap, topicNames, gid, dlq, interceptors, retry, readyPromise } = await setupConsumer(ctx, topics, "eachMessage", setupOptions);
+  if (options.circuitBreaker)
+    ctx.circuitBreaker.setConfig(gid, options.circuitBreaker);
+  const deps = messageDepsFor(ctx, gid, options);
+  const eosMainContext = await makeEosMainContext(ctx, gid, consumer, options);
+  await consumer.run({
+    eachMessage: (payload) => ctx.inFlight.track(
+      () => handleEachMessage(
+        payload,
+        {
+          schemaMap,
+          serdeMap,
+          handleMessage,
+          interceptors,
+          dlq,
+          retry,
+          retryTopics: options.retryTopics,
+          timeoutMs: options.handlerTimeoutMs,
+          wrapWithTimeout: (fn, ms, topic2) => wrapWithTimeoutWarning(ctx.logger, fn, ms, topic2),
+          deduplication: resolveDeduplicationContext(
+            ctx,
+            gid,
+            options.deduplication
+          ),
+          messageTtlMs: options.messageTtlMs,
+          onTtlExpired: options.onTtlExpired,
+          eosMainContext
+        },
+        deps
+      )
+    )
+  });
+  ctx.runningConsumers.set(gid, "eachMessage");
+  if (options.retryTopics && retry) {
+    await launchRetryChain(ctx, gid, topicNames, handleMessage, {
+      retry,
+      dlq,
+      interceptors,
+      schemaMap,
+      serdeMap,
+      assignmentTimeoutMs: options.retryTopicAssignmentTimeoutMs
+    });
+  }
+  return { groupId: gid, stop: () => stopConsumerByGid(ctx, gid), ready: () => readyPromise };
+}
+async function startBatchConsumerImpl(ctx, topics, handleBatch, options = {}) {
+  validateTopicConsumerOpts(topics, options);
+  if (!options.retryTopics && options.autoCommit !== false) {
+    ctx.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, serdeMap, topicNames, gid, dlq, interceptors, retry, readyPromise } = await setupConsumer(ctx, topics, "eachBatch", setupOptions);
+  if (options.circuitBreaker)
+    ctx.circuitBreaker.setConfig(gid, options.circuitBreaker);
+  const deps = messageDepsFor(ctx, gid, options);
+  const eosMainContext = await makeEosMainContext(ctx, gid, consumer, options);
+  await consumer.run({
+    eachBatch: (payload) => ctx.inFlight.track(
+      () => handleEachBatch(
+        payload,
+        {
+          schemaMap,
+          serdeMap,
+          handleBatch,
+          interceptors,
+          dlq,
+          retry,
+          retryTopics: options.retryTopics,
+          timeoutMs: options.handlerTimeoutMs,
+          wrapWithTimeout: (fn, ms, topic2) => wrapWithTimeoutWarning(ctx.logger, fn, ms, topic2),
+          deduplication: resolveDeduplicationContext(
+            ctx,
+            gid,
+            options.deduplication
+          ),
+          messageTtlMs: options.messageTtlMs,
+          onTtlExpired: options.onTtlExpired,
+          eosMainContext
+        },
+        deps
+      )
+    )
+  });
+  ctx.runningConsumers.set(gid, "eachBatch");
+  if (options.retryTopics && retry) {
+    const handleMessageForRetry = (env) => handleBatch([env], {
+      partition: env.partition,
+      highWatermark: null,
+      heartbeat: async () => {
+      },
+      resolveOffset: () => {
+      },
+      commitOffsetsIfNecessary: async () => {
+      }
+    });
+    await launchRetryChain(ctx, gid, topicNames, handleMessageForRetry, {
+      retry,
+      dlq,
+      interceptors,
+      schemaMap,
+      serdeMap,
+      assignmentTimeoutMs: options.retryTopicAssignmentTimeoutMs
+    });
+  }
+  return { groupId: gid, stop: () => stopConsumerByGid(ctx, gid), ready: () => readyPromise };
+}
+async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}) {
+  if (options.retryTopics) {
+    throw new Error(
+      "startTransactionalConsumer: retryTopics is not supported. EOS is already guaranteed by the transaction \u2014 redelivery on failure is handled automatically."
+    );
+  }
+  const setupOptions = { ...options, autoCommit: false };
+  const { consumer, schemaMap, serdeMap, gid, readyPromise } = await setupConsumer(
+    ctx,
+    topics,
+    "eachMessage",
+    setupOptions
+  );
+  const txProducer = await createRetryTxProducer(ctx, `${gid}-txc`);
+  const deps = messageDepsFor(ctx, gid);
+  await consumer.run({
+    eachMessage: ({ topic: topic2, partition, message }) => ctx.inFlight.track(async () => {
+      const envelope = await parseSingleMessage(
+        message,
+        topic2,
+        partition,
+        schemaMap,
+        options.interceptors ?? [],
+        false,
+        deps,
+        serdeMap
+      );
+      const nextOffset = String(Number.parseInt(message.offset, 10) + 1);
+      if (envelope === null) {
+        await consumer.commitOffsets([
+          { topic: topic2, partition, offset: nextOffset }
+        ]);
+        return;
+      }
+      const tx = await txProducer.transaction();
+      const txCtx = {
+        send: async (t, msg, sendOpts) => {
+          const payload = await preparePayload(ctx, t, [
+            {
+              value: msg,
+              key: sendOpts?.key,
+              headers: sendOpts?.headers,
+              correlationId: sendOpts?.correlationId,
+              schemaVersion: sendOpts?.schemaVersion,
+              eventId: sendOpts?.eventId
+            }
+          ]);
+          await tx.send(payload);
+        },
+        sendBatch: async (t, msgs, batchOpts) => {
+          const payload = await preparePayload(
+            ctx,
+            t,
+            msgs,
+            batchOpts?.compression
+          );
+          await tx.send(payload);
+        }
+      };
+      try {
+        await runWithEnvelopeContext(
+          {
+            correlationId: envelope.correlationId,
+            traceparent: envelope.traceparent
+          },
+          () => handler(envelope, txCtx)
+        );
+        await tx.sendOffsets({
+          consumer,
+          topics: [
+            { topic: topic2, partitions: [{ partition, offset: nextOffset }] }
+          ]
+        });
+        await tx.commit();
+        deps.onMessage?.(envelope);
+      } catch (err) {
+        try {
+          await tx.abort();
+        } catch {
+        }
+        ctx.logger.warn(
+          `startTransactionalConsumer: handler failed on ${topic2}[${partition}]@${message.offset} \u2014 tx aborted, message will be redelivered (${toError(err).message})`
+        );
+        throw err;
+      }
+    })
+  });
+  ctx.runningConsumers.set(gid, "eachMessage");
+  return { groupId: gid, stop: () => stopConsumerByGid(ctx, gid), ready: () => readyPromise };
+}
+function stopConsumerByGid(ctx, gid) {
+  return stopConsumerImpl(ctx, gid);
+}
+
+// src/client/kafka.client/consumer/features/window.ts
+async function startWindowConsumerImpl(ctx, topic2, handler, options) {
+  const { maxMessages, maxMs, ...consumerOptions } = options;
+  if (maxMessages <= 0)
+    throw new Error("startWindowConsumer: maxMessages must be > 0");
+  if (maxMs <= 0) throw new Error("startWindowConsumer: maxMs must be > 0");
+  if (consumerOptions.retryTopics) {
+    throw new Error(
+      "startWindowConsumer() does not support retryTopics. Use startConsumer() with retryTopics: true for guaranteed retry delivery."
+    );
+  }
+  const buffer = [];
+  let flushTimer = null;
+  let windowStart = 0;
+  const onLost = consumerOptions.onMessageLost ?? ctx.onMessageLost;
+  const flush = async (trigger) => {
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    if (buffer.length === 0) return;
+    const envelopes = buffer.splice(0);
+    try {
+      await handler(envelopes, { trigger, windowStart, windowEnd: Date.now() });
+    } catch (err) {
+      const error = toError(err);
+      ctx.logger.error(
+        `startWindowConsumer: ${trigger}-triggered flush failed \u2014 window of ${envelopes.length} message(s) lost:`,
+        error.stack
+      );
+      for (const envelope of envelopes) {
+        await Promise.resolve(
+          onLost?.({
+            topic: envelope.topic,
+            error,
+            attempt: 0,
+            headers: envelope.headers
+          })
+        ).catch(() => {
+        });
+      }
+    }
+  };
+  const scheduleFlush = () => {
+    if (flushTimer !== null) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush("time");
+    }, maxMs);
+  };
+  const handle = await startConsumerImpl(
+    ctx,
+    [topic2],
+    async (envelope) => {
+      if (buffer.length === 0) windowStart = Date.now();
+      buffer.push(envelope);
+      scheduleFlush();
+      if (buffer.length >= maxMessages) await flush("size");
+    },
+    consumerOptions
+  );
+  const originalStop = handle.stop.bind(handle);
+  handle.stop = async () => {
+    await flush("time");
+    return originalStop();
+  };
+  return handle;
+}
+
+// src/client/kafka.client/consumer/features/routed.ts
+async function startRoutedConsumerImpl(ctx, topics, routing, options) {
+  const { header, routes, fallback } = routing;
+  const handleMessage = async (envelope) => {
+    const headerValue = envelope.headers[header];
+    const routeHandler = headerValue === void 0 ? void 0 : routes[headerValue];
+    if (routeHandler) {
+      await routeHandler(envelope);
+    } else {
+      await fallback?.(envelope);
+    }
+  };
+  return startConsumerImpl(ctx, topics, handleMessage, options);
+}
+
+// src/client/kafka.client/consumer/features/delayed.ts
+function delayedTopicName(topic2) {
+  return `${topic2}.delayed`;
+}
+async function startDelayedRelayImpl(ctx, topics, options) {
+  if (topics.length === 0) {
+    throw new Error("startDelayedRelay: at least one topic is required");
+  }
+  const gid = options?.groupId ?? `${ctx.defaultGroupId}-delayed-relay`;
+  if (ctx.runningConsumers.has(gid)) {
+    throw new Error(
+      `startDelayedRelay("${gid}") called twice \u2014 this group is already consuming. Call stopConsumer("${gid}") first or pass a different groupId.`
+    );
+  }
+  const delayedTopics = topics.map(delayedTopicName);
+  for (const t of delayedTopics) await ensureTopic(ctx, t);
+  const txProducer = await createRetryTxProducer(ctx, `${gid}-tx`);
+  let resolveReady;
+  const readyPromise = new Promise((resolve) => {
+    resolveReady = resolve;
+  });
+  const consumer = getOrCreateConsumer(
+    gid,
+    false,
+    false,
+    ctx.consumerOpsDeps,
+    void 0,
+    resolveReady
+  );
+  await consumer.connect();
+  await subscribeWithRetry(consumer, delayedTopics, ctx.logger);
+  await consumer.run({
+    eachMessage: async ({ topic: stagingTopic, partition, message }) => {
+      const nextOffset = {
+        topic: stagingTopic,
+        partition,
+        offset: (parseInt(message.offset, 10) + 1).toString()
+      };
+      if (!message.value) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const headers = decodeHeaders(message.headers);
+      const target = headers[HEADER_DELAYED_TARGET] ?? stagingTopic.replace(/\.delayed$/, "");
+      const until = parseInt(
+        headers[HEADER_DELAYED_UNTIL] ?? "0",
+        10
+      );
+      const remaining = until - Date.now();
+      if (remaining > 0) {
+        consumer.pause([{ topic: stagingTopic, partitions: [partition] }]);
+        await sleep(remaining);
+        consumer.resume([{ topic: stagingTopic, partitions: [partition] }]);
+      }
+      const forwardHeaders = Object.fromEntries(
+        Object.entries(headers).filter(
+          ([k]) => k !== HEADER_DELAYED_UNTIL && k !== HEADER_DELAYED_TARGET
+        )
+      );
+      const tx = await txProducer.transaction();
+      try {
+        await tx.send({
+          topic: target,
+          messages: [
+            {
+              // Forward the ORIGINAL wire bytes unchanged — no re-serialization,
+              // so binary payloads (Avro/Protobuf) are relayed losslessly.
+              value: message.value,
+              key: message.key ? message.key.toString() : null,
+              headers: forwardHeaders
+            }
+          ]
+        });
+        await tx.sendOffsets({
+          consumer,
+          topics: [
+            {
+              topic: nextOffset.topic,
+              partitions: [
+                { partition: nextOffset.partition, offset: nextOffset.offset }
+              ]
+            }
+          ]
+        });
+        await tx.commit();
+        ctx.logger.debug?.(
+          `Delayed message relayed to "${target}" (deadline ${new Date(until).toISOString()})`
+        );
+      } catch (txErr) {
+        try {
+          await tx.abort();
+        } catch {
+        }
+        ctx.logger.error(
+          `Delayed relay to "${target}" failed \u2014 message will be redelivered:`,
+          toError(txErr).stack
+        );
+      }
+    }
+  });
+  ctx.runningConsumers.set(gid, "eachMessage");
+  ctx.logger.log(
+    `Delayed relay started for: ${delayedTopics.join(", ")} (group: ${gid})`
+  );
+  return {
+    groupId: gid,
+    ready: () => readyPromise,
+    stop: async () => {
+      await stopConsumerImpl(ctx, gid);
+    }
+  };
+}
+
+// src/client/kafka.client/consumer/features/snapshot.ts
+async function readSnapshotImpl(ctx, topic2, options = {}) {
+  await ctx.adminOps.ensureConnected();
+  let offsets;
+  try {
+    offsets = await ctx.adminOps.admin.fetchTopicOffsets(topic2);
+  } catch {
+    ctx.logger.warn(
+      `readSnapshot: could not fetch offsets for "${String(topic2)}", returning empty snapshot`
+    );
+    return /* @__PURE__ */ new Map();
+  }
+  const targets = /* @__PURE__ */ new Map();
+  for (const { partition, high, low } of offsets) {
+    const highN = Number.parseInt(high, 10);
+    const lowN = Number.parseInt(low, 10);
+    if (highN > lowN) targets.set(partition, highN - 1);
+  }
+  if (targets.size === 0) {
+    ctx.logger.debug?.(
+      `readSnapshot: topic "${String(topic2)}" is empty \u2014 returning empty snapshot`
+    );
+    return /* @__PURE__ */ new Map();
+  }
+  const snapshot = /* @__PURE__ */ new Map();
+  const remaining = new Set(targets.keys());
+  const snapshotGroupId = `${ctx.clientId}-snapshot-${Date.now()}`;
+  await new Promise((resolve, reject) => {
+    const consumer = ctx.transport.consumer({
+      groupId: snapshotGroupId,
+      fromBeginning: true
+    });
+    const cleanup = () => {
+      consumer.disconnect().catch(() => {
+      }).finally(() => {
+        ctx.adminOps.deleteGroups([snapshotGroupId]).catch(() => {
+        });
+      });
+    };
+    consumer.connect().then(() => consumer.subscribe({ topics: [topic2] })).then(
+      () => consumer.run({
+        eachMessage: async ({ topic: t, partition, message }) => {
+          if (!remaining.has(partition)) return;
+          const msgOffsetN = Number.parseInt(message.offset, 10);
+          applySnapshotMessage(snapshot, options, ctx, t, partition, message);
+          if (msgOffsetN >= targets.get(partition)) {
+            remaining.delete(partition);
+            if (remaining.size === 0) {
+              cleanup();
+              resolve();
+            }
+          }
+        }
+      })
+    ).catch((err) => {
+      cleanup();
+      reject(err);
+    });
+  });
+  ctx.logger.log(
+    `readSnapshot: ${snapshot.size} key(s) from "${String(topic2)}"`
+  );
+  return snapshot;
+}
+function applySnapshotMessage(snapshot, options, ctx, t, partition, message) {
+  let key = null;
+  if (message.key) {
+    key = Buffer.isBuffer(message.key) ? message.key.toString() : String(message.key);
+  }
+  if (message.value === null || message.value === void 0) {
+    if (key !== null) {
+      snapshot.delete(key);
+      options.onTombstone?.(key);
+    }
+    return;
+  }
+  if (key === null) return;
+  const rawValue = Buffer.isBuffer(message.value) ? message.value.toString() : String(message.value);
+  try {
+    const jsonValue = JSON.parse(rawValue);
+    const headers = decodeHeaders(message.headers);
+    const parsed = options.schema ? options.schema.parse(jsonValue) : jsonValue;
+    snapshot.set(
+      key,
+      extractEnvelope(parsed, headers, t, partition, message.offset)
+    );
+  } catch (err) {
+    ctx.logger.warn(
+      `readSnapshot: skipping ${t}:${partition}@${message.offset} \u2014 ${toError(err).message}`
+    );
+  }
+}
+async function checkpointOffsetsImpl(ctx, groupId, checkpointTopic) {
+  const gid = groupId ?? ctx.defaultGroupId;
+  await ctx.adminOps.ensureConnected();
+  const committed = await ctx.adminOps.admin.fetchOffsets({ groupId: gid });
+  const offsets = [];
+  for (const { topic: topic2, partitions } of committed) {
+    for (const { partition, offset } of partitions) {
+      offsets.push({ topic: topic2, partition, offset });
+    }
+  }
+  const savedAt = Date.now();
+  const payload = JSON.stringify({ groupId: gid, offsets, savedAt });
+  await ctx.producer.send({
+    topic: checkpointTopic,
+    messages: [
+      {
+        key: gid,
+        value: payload,
+        headers: {
+          "x-checkpoint-group-id": [gid],
+          "x-checkpoint-timestamp": [String(savedAt)]
+        }
+      }
+    ]
+  });
+  const topics = [...new Set(offsets.map((e) => e.topic))];
+  ctx.logger.log(
+    `checkpointOffsets: saved ${offsets.length} partition(s) for group "${gid}" \u2192 "${checkpointTopic}"`
+  );
+  return { groupId: gid, topics, partitionCount: offsets.length, savedAt };
+}
+async function restoreFromCheckpointImpl(ctx, groupId, checkpointTopic, options = {}) {
+  const gid = groupId ?? ctx.defaultGroupId;
+  if (ctx.runningConsumers.has(gid)) {
+    throw new Error(
+      `restoreFromCheckpoint: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before restoring offsets.`
+    );
+  }
+  await ctx.adminOps.ensureConnected();
+  const checkpoints = [];
+  let hwmOffsets;
+  try {
+    hwmOffsets = await ctx.adminOps.admin.fetchTopicOffsets(checkpointTopic);
+  } catch {
+    throw new Error(
+      `restoreFromCheckpoint: could not fetch offsets for "${checkpointTopic}" \u2014 does the topic exist?`
+    );
+  }
+  const targets = /* @__PURE__ */ new Map();
+  for (const { partition, high, low } of hwmOffsets) {
+    const highN = Number.parseInt(high, 10);
+    if (highN > Number.parseInt(low, 10)) targets.set(partition, highN - 1);
+  }
+  if (targets.size > 0) {
+    const checkpointGroupId = `${ctx.clientId}-checkpoint-restore-${Date.now()}`;
+    await new Promise((resolve, reject) => {
+      const consumer = ctx.transport.consumer({
+        groupId: checkpointGroupId,
+        fromBeginning: true
+      });
+      const cleanup = () => {
+        consumer.disconnect().catch(() => {
+        }).finally(() => {
+          ctx.adminOps.deleteGroups([checkpointGroupId]).catch(() => {
+          });
+        });
+      };
+      const remaining = new Set(targets.keys());
+      consumer.connect().then(() => consumer.subscribe({ topics: [checkpointTopic] })).then(
+        () => consumer.run({
+          eachMessage: async ({ partition, message }) => {
+            if (!remaining.has(partition)) return;
+            let msgKey = null;
+            if (message.key) {
+              msgKey = Buffer.isBuffer(message.key) ? message.key.toString() : String(message.key);
+            }
+            if (msgKey === gid && message.value) {
+              try {
+                const raw = Buffer.isBuffer(message.value) ? message.value.toString() : String(message.value);
+                const parsed = JSON.parse(raw);
+                checkpoints.push({
+                  savedAt: parsed.savedAt,
+                  offsets: parsed.offsets
+                });
+              } catch {
+                ctx.logger.warn(
+                  `restoreFromCheckpoint: skipping malformed checkpoint at partition ${partition}@${message.offset}`
+                );
+              }
+            }
+            if (Number.parseInt(message.offset, 10) >= targets.get(partition)) {
+              remaining.delete(partition);
+              if (remaining.size === 0) {
+                cleanup();
+                resolve();
+              }
+            }
+          }
+        })
+      ).catch((err) => {
+        cleanup();
+        reject(err);
+      });
+    });
+  }
+  if (checkpoints.length === 0) {
+    throw new Error(
+      `restoreFromCheckpoint: no checkpoints found for group "${gid}" in "${checkpointTopic}"`
+    );
+  }
+  const target = options.timestamp;
+  let best;
+  if (target === void 0) {
+    best = checkpoints.reduce(
+      (acc, c) => c.savedAt > acc.savedAt ? c : acc,
+      checkpoints[0]
+    );
+  } else {
+    const candidates = checkpoints.filter((c) => c.savedAt <= target);
+    if (candidates.length > 0) {
+      best = candidates.reduce(
+        (acc, c) => c.savedAt > acc.savedAt ? c : acc,
+        candidates[0]
+      );
+    } else {
+      best = checkpoints.reduce(
+        (acc, c) => c.savedAt < acc.savedAt ? c : acc,
+        checkpoints[0]
+      );
+      ctx.logger.warn(
+        `restoreFromCheckpoint: no checkpoint at or before ${new Date(target).toISOString()} \u2014 using oldest available (${new Date(best.savedAt).toISOString()})`
+      );
+    }
+  }
+  await ctx.adminOps.seekToOffset(gid, best.offsets);
+  const checkpointAge = Date.now() - best.savedAt;
+  ctx.logger.log(
+    `restoreFromCheckpoint: restored ${best.offsets.length} partition(s) for group "${gid}" from checkpoint at ${new Date(best.savedAt).toISOString()} (age: ${checkpointAge}ms)`
+  );
+  return {
+    groupId: gid,
+    offsets: best.offsets,
+    restoredAt: best.savedAt,
+    checkpointAge
+  };
+}
+
+// src/client/kafka.client/index.ts
+var 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"
+]);
+var KafkaClient = class {
+  clientId;
+  ctx;
+  /**
+   * Create a new KafkaClient.
+   * @param clientId Unique client identifier (used in Kafka metadata and logs).
+   * @param groupId Default consumer group ID for this client.
+   * @param brokers Array of broker addresses, e.g. `['localhost:9092']`.
+   * @param options Optional client-wide configuration.
+   * @example
+   * ```ts
+   * const kafka = new KafkaClient('my-service', 'my-service-group', ['localhost:9092'], {
+   *   lagThrottle: { maxLag: 10_000 },
+   *   onMessageLost: (ctx) => logger.error('Message lost', ctx),
+   * });
+   * await kafka.connectProducer();
+   * ```
+   */
+  constructor(clientId, groupId, brokers, options) {
+    validateClientOptions(clientId, groupId, brokers, options);
+    this.clientId = clientId;
+    const 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)
+    };
+    const security = resolveSecurityOptions(options?.security, brokers, logger);
+    const transport = options?.transport ?? new ConfluentTransport(clientId, brokers, security);
+    const producer = transport.producer();
+    const runningConsumers = /* @__PURE__ */ new Map();
+    const consumers = /* @__PURE__ */ new Map();
+    const consumerCreationOptions = /* @__PURE__ */ new Map();
+    const schemaRegistry = /* @__PURE__ */ new Map();
+    const serde = options?.serde ?? new JsonSerde();
+    const adminOps = new AdminOps({
+      admin: transport.admin(),
+      logger,
+      runningConsumers,
+      defaultGroupId: groupId,
+      clientId
+    });
+    const circuitBreaker = new CircuitBreakerManager({
+      pauseConsumer: (gid, assignments) => pauseConsumerImpl(this.ctx, gid, assignments),
+      resumeConsumer: (gid, assignments) => resumeConsumerImpl(this.ctx, gid, assignments),
+      logger,
+      instrumentation: options?.instrumentation ?? []
+    });
+    const metrics = new MetricsManager({
+      instrumentation: options?.instrumentation ?? [],
+      onCircuitFailure: (envelope, gid) => circuitBreaker.onFailure(envelope, gid),
+      onCircuitSuccess: (envelope, gid) => circuitBreaker.onSuccess(envelope, gid)
+    });
+    const inFlight = new InFlightTracker((msg) => logger.warn(msg));
+    const ctx = {
+      clientId,
+      defaultGroupId: groupId,
+      logger,
+      autoCreateTopicsEnabled: options?.autoCreateTopics ?? false,
+      strictSchemasEnabled: options?.strictSchemas ?? true,
+      numPartitions: options?.numPartitions ?? 1,
+      serde,
+      txId: options?.transactionalId ?? `${clientId}-tx`,
+      clockRecoveryTopics: options?.clockRecovery?.topics ?? [],
+      clockRecoveryTimeoutMs: options?.clockRecovery?.timeoutMs ?? 3e4,
+      lagThrottleOpts: options?.lagThrottle,
+      instrumentation: options?.instrumentation ?? [],
+      onMessageLost: options?.onMessageLost,
+      onTtlExpired: options?.onTtlExpired,
+      onRebalance: options?.onRebalance,
+      transport,
+      producer,
+      txProducer: void 0,
+      txProducerInitPromise: void 0,
+      _txChain: Promise.resolve(),
+      retryTxProducers: /* @__PURE__ */ new Map(),
+      consumers,
+      runningConsumers,
+      consumerCreationOptions,
+      companionGroupIds: /* @__PURE__ */ new Map(),
+      dedupStates: /* @__PURE__ */ new Map(),
+      ensuredTopics: /* @__PURE__ */ new Set(),
+      ensureTopicPromises: /* @__PURE__ */ new Map(),
+      schemaRegistry,
+      _lagThrottled: false,
+      _lagThrottleTimer: void 0,
+      _lamportClock: 0,
+      circuitBreaker,
+      adminOps,
+      metrics,
+      inFlight,
+      producerOpsDeps: {
+        schemaRegistry,
+        strictSchemasEnabled: options?.strictSchemas ?? true,
+        instrumentation: options?.instrumentation ?? [],
+        logger,
+        serde,
+        nextLamportClock: () => 0
+        // patched below
+      },
+      consumerOpsDeps: {
+        consumers,
+        consumerCreationOptions,
+        transport,
+        onRebalance: options?.onRebalance,
+        logger
+      },
+      retryTopicDeps: {}
+      // patched below
+    };
+    ctx.producerOpsDeps = {
+      schemaRegistry,
+      strictSchemasEnabled: options?.strictSchemas ?? true,
+      instrumentation: options?.instrumentation ?? [],
+      logger,
+      serde,
+      nextLamportClock: () => ++ctx._lamportClock
+    };
+    ctx.retryTopicDeps = buildRetryTopicDeps(ctx);
+    this.ctx = ctx;
+  }
+  async sendMessage(topicOrDesc, message, options = {}) {
+    return sendMessageImpl(this.ctx, topicOrDesc, message, options);
+  }
+  /** @inheritDoc */
+  async sendTombstone(topic2, key, headers) {
+    return sendTombstoneImpl(this.ctx, topic2, key, headers);
+  }
+  async sendBatch(topicOrDesc, messages, options) {
+    return sendBatchImpl(this.ctx, topicOrDesc, messages, options);
+  }
+  /** @inheritDoc */
+  async transaction(fn) {
+    return transactionImpl(this.ctx, fn);
+  }
+  // ── Producer lifecycle ────────────────────────────────────────────
+  /** @inheritDoc */
+  async connectProducer() {
+    return connectProducerImpl(this.ctx);
+  }
+  /** @internal */
+  async disconnectProducer() {
+    if (this.ctx._lagThrottleTimer) {
+      clearInterval(this.ctx._lagThrottleTimer);
+      this.ctx._lagThrottleTimer = void 0;
+    }
+    await this.ctx.producer.disconnect();
+    this.ctx.logger.log("Producer disconnected");
+  }
+  async startConsumer(topics, handleMessage, options = {}) {
+    return startConsumerImpl(this.ctx, topics, handleMessage, options);
+  }
+  async startBatchConsumer(topics, handleBatch, options = {}) {
+    return startBatchConsumerImpl(this.ctx, topics, handleBatch, options);
+  }
+  // ── Consumer: AsyncIterableIterator ──────────────────────────────
+  /** @inheritDoc */
+  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.ctx.defaultGroupId;
+    const queue = new AsyncQueue(
+      options?.queueHighWaterMark,
+      () => pauseTopicAllPartitions(this.ctx, gid, topic2),
+      () => resumeTopicAllPartitions(this.ctx, gid, topic2)
+    );
+    const handlePromise = this.startConsumer(
+      [topic2],
+      async (envelope) => {
+        queue.push(envelope);
+      },
+      options
+    );
+    handlePromise.catch((err) => queue.fail(err));
+    return {
+      [Symbol.asyncIterator]() {
+        return this;
+      },
+      next: () => queue.next(),
+      return: async () => {
+        queue.close();
+        const handle = await handlePromise;
+        await handle.stop();
+        return { value: void 0, done: true };
+      }
+    };
+  }
+  // ── Consumer: windowed ────────────────────────────────────────────
+  /** @inheritDoc */
+  startWindowConsumer(topic2, handler, options) {
+    return startWindowConsumerImpl(this.ctx, topic2, handler, options);
+  }
+  // ── Consumer: header routing ──────────────────────────────────────
+  /** @inheritDoc */
+  startRoutedConsumer(topics, routing, options) {
+    return startRoutedConsumerImpl(this.ctx, topics, routing, options);
+  }
+  // ── Consumer: delayed delivery relay ──────────────────────────────
+  /**
+   * Start a relay that delivers messages produced with
+   * `SendOptions.deliverAfterMs` from `<topic>.delayed` to their target topic
+   * once their deadline passes.
+   *
+   * Forwarding is transactional (produce + source-offset commit are atomic),
+   * so no duplicates are relayed even if the relay crashes mid-forward.
+   * Delivery time is a lower bound — the relay must be running for delayed
+   * messages to be delivered at all.
+   *
+   * @param topics Target topic name(s) whose `<topic>.delayed` staging topics to relay.
+   * @param options Optional `groupId` override (default: `<defaultGroupId>-delayed-relay`).
+   *
+   * @example
+   * ```ts
+   * await kafka.startDelayedRelay(['orders.reminder']);
+   * await kafka.sendMessage('orders.reminder', payload, { deliverAfterMs: 60_000 });
+   * // → delivered to orders.reminder ~60 s later
+   * ```
+   */
+  async startDelayedRelay(topics, options) {
+    const list = Array.isArray(topics) ? topics : [topics];
+    return startDelayedRelayImpl(this.ctx, list, options);
+  }
+  // ── Consumer: transactional EOS ───────────────────────────────────
+  /** @inheritDoc */
+  async startTransactionalConsumer(topics, handler, options = {}) {
+    return startTransactionalConsumerImpl(this.ctx, topics, handler, options);
+  }
+  // ── Consumer lifecycle ────────────────────────────────────────────
+  /** @inheritDoc */
+  async stopConsumer(groupId) {
+    return stopConsumerImpl(this.ctx, groupId);
+  }
+  /** @inheritDoc */
+  pauseConsumer(groupId, assignments) {
+    return pauseConsumerImpl(this.ctx, groupId, assignments);
+  }
+  /** @inheritDoc */
+  resumeConsumer(groupId, assignments) {
+    return resumeConsumerImpl(this.ctx, groupId, assignments);
+  }
+  // ── DLQ replay ────────────────────────────────────────────────────
+  /** @inheritDoc */
+  async replayDlq(topic2, options = {}) {
+    await this.ctx.adminOps.ensureConnected();
+    return replayDlqTopic(
+      topic2,
+      {
+        logger: this.ctx.logger,
+        fetchTopicOffsets: (t) => this.ctx.adminOps.admin.fetchTopicOffsets(t),
+        send: async (t, messages) => {
+          await this.ctx.producer.send({ topic: t, messages });
+        },
+        createConsumer: (gid, fromBeginning) => getOrCreateConsumer(gid, fromBeginning, true, this.ctx.consumerOpsDeps),
+        cleanupConsumer: (consumer, gid, deleteGroup) => {
+          consumer.disconnect().catch(() => {
+          }).finally(() => {
+            this.ctx.consumers.delete(gid);
+            this.ctx.runningConsumers.delete(gid);
+            this.ctx.consumerCreationOptions.delete(gid);
+            if (deleteGroup) {
+              this.ctx.adminOps.deleteGroups([gid]).catch(() => {
+              });
+            }
+          });
+        },
+        dlqHeaderKeys: DLQ_HEADER_KEYS
+      },
+      options
+    );
+  }
+  // ── Snapshot & checkpoint ─────────────────────────────────────────
+  /** @inheritDoc */
+  async readSnapshot(topic2, options = {}) {
+    return readSnapshotImpl(this.ctx, topic2, options);
+  }
+  /** @inheritDoc */
+  async checkpointOffsets(groupId, checkpointTopic) {
+    return checkpointOffsetsImpl(this.ctx, groupId, checkpointTopic);
+  }
+  /** @inheritDoc */
+  async restoreFromCheckpoint(groupId, checkpointTopic, options = {}) {
+    return restoreFromCheckpointImpl(this.ctx, groupId, checkpointTopic, options);
+  }
+  // ── Admin ─────────────────────────────────────────────────────────
+  /** @inheritDoc */
+  async resetOffsets(groupId, topic2, position) {
+    return this.ctx.adminOps.resetOffsets(groupId, topic2, position);
+  }
+  /** @inheritDoc */
+  async seekToOffset(groupId, assignments) {
+    return this.ctx.adminOps.seekToOffset(groupId, assignments);
+  }
+  /** @inheritDoc */
+  async seekToTimestamp(groupId, assignments) {
+    return this.ctx.adminOps.seekToTimestamp(groupId, assignments);
+  }
+  /** @inheritDoc */
+  async getConsumerLag(groupId) {
+    return this.ctx.adminOps.getConsumerLag(groupId);
+  }
+  /** @inheritDoc */
+  async checkStatus() {
+    return this.ctx.adminOps.checkStatus();
+  }
+  /** @inheritDoc */
+  async listConsumerGroups() {
+    return this.ctx.adminOps.listConsumerGroups();
+  }
+  /** @inheritDoc */
+  async describeTopics(topics) {
+    return this.ctx.adminOps.describeTopics(topics);
+  }
+  /** @inheritDoc */
+  async deleteRecords(topic2, partitions) {
+    return this.ctx.adminOps.deleteRecords(topic2, partitions);
+  }
+  // ── Circuit breaker ───────────────────────────────────────────────
+  /** @inheritDoc */
+  getCircuitState(topic2, partition, groupId) {
+    return this.ctx.circuitBreaker.getState(
+      topic2,
+      partition,
+      groupId ?? this.ctx.defaultGroupId
+    );
+  }
+  // ── Metrics ───────────────────────────────────────────────────────
+  /** @inheritDoc */
+  getMetrics(topic2) {
+    return this.ctx.metrics.getMetrics(topic2);
+  }
+  /** @inheritDoc */
+  resetMetrics(topic2) {
+    this.ctx.metrics.resetMetrics(topic2);
+  }
+  getClientId() {
+    return this.clientId;
+  }
+  // ── Lifecycle ─────────────────────────────────────────────────────
+  /** @inheritDoc */
+  async disconnect(drainTimeoutMs = 3e4) {
+    return disconnectImpl(this.ctx, drainTimeoutMs);
+  }
+  /** NestJS lifecycle hook — called automatically on module teardown. */
+  async onModuleDestroy() {
+    await this.disconnect();
+  }
+  /** @inheritDoc */
+  enableGracefulShutdown(signals = ["SIGTERM", "SIGINT"], drainTimeoutMs = 3e4) {
+    const handler = () => {
+      this.ctx.logger.log(
+        "Shutdown signal received \u2014 draining in-flight handlers..."
+      );
+      this.disconnect(drainTimeoutMs).catch(
+        (err) => this.ctx.logger.error(
+          "Error during graceful shutdown:",
+          toError(err).message
+        )
+      ).finally(() => process.exit(0));
+    };
+    for (const signal of signals) process.once(signal, handler);
+  }
+};
+
+// src/client/message/topic.ts
+function topic(name) {
+  return {
+    /** Provide an explicit message type without a runtime schema. */
+    type: () => keyable({
+      __topic: name,
+      __type: void 0
+    }),
+    schema: (schema) => keyable({
+      __topic: name,
+      __type: void 0,
+      __schema: schema
+    })
+  };
+}
+function keyable(desc) {
+  return {
+    ...desc,
+    key: (extractor) => keyable({ ...desc, __key: extractor }),
+    serde: (serde) => keyable({ ...desc, __serde: serde })
+  };
+}
+
+// src/client/message/versioned-schema.ts
+function versionedSchema(versions, options) {
+  const registered = Object.keys(versions).map(Number).filter((v) => Number.isInteger(v) && v > 0).sort((a, b) => a - b);
+  if (registered.length === 0) {
+    throw new Error(
+      "versionedSchema: at least one schema version must be registered (keys must be positive integers)"
+    );
+  }
+  const latestVersion = registered[registered.length - 1];
+  return {
+    async parse(data, ctx) {
+      const version = ctx?.version ?? latestVersion;
+      const schema = versions[version];
+      if (!schema) {
+        throw new Error(
+          `versionedSchema: no schema registered for version ${version}${ctx?.topic ? ` (topic "${ctx.topic}")` : ""} \u2014 registered versions: ${registered.join(", ")}`
+        );
+      }
+      const parsed = await schema.parse(data, ctx);
+      if (version < latestVersion && options?.migrate) {
+        return options.migrate(parsed, version, latestVersion);
+      }
+      return parsed;
+    }
+  };
+}
+
+// src/client/outbox/outbox.store.ts
+var InMemoryOutboxStore = class {
+  /** Insertion-ordered rows. `published` flips to true after `markPublished`. */
+  rows = [];
+  /**
+   * Append a message to the outbox. In a real store this INSERT would run inside
+   * the same DB transaction as the corresponding business write.
+   */
+  add(message) {
+    this.rows.push({ message, published: false });
+  }
+  async fetchUnpublished(limit) {
+    const out = [];
+    for (const row of this.rows) {
+      if (row.published) continue;
+      out.push(row.message);
+      if (out.length >= limit) break;
+    }
+    return out;
+  }
+  async markPublished(ids) {
+    const idSet = new Set(ids);
+    for (const row of this.rows) {
+      if (idSet.has(row.message.id)) row.published = true;
+    }
+  }
+  /** Test helper: count of rows not yet marked published. */
+  get pendingCount() {
+    return this.rows.filter((r) => !r.published).length;
+  }
+  /** Test helper: count of rows marked published. */
+  get publishedCount() {
+    return this.rows.filter((r) => r.published).length;
+  }
+};
+
+// src/client/outbox/outbox.relay.ts
+function toError2(e) {
+  return e instanceof Error ? e : new Error(String(e));
+}
+function startOutboxRelay(kafka, store, options = {}) {
+  const pollIntervalMs = options.pollIntervalMs ?? 1e3;
+  const batchSize = options.batchSize ?? 100;
+  const onError = options.onError ?? ((error, batch) => {
+    console.error(
+      `[outbox] batch of ${batch.length} message(s) failed \u2014 will retry:`,
+      error
+    );
+  });
+  const onPublished = options.onPublished;
+  let stopped = false;
+  let running = false;
+  let inFlight = Promise.resolve();
+  const iterate = async () => {
+    let batch = [];
+    try {
+      batch = await store.fetchUnpublished(batchSize);
+      if (batch.length === 0) return;
+      await kafka.transaction(async (tx) => {
+        for (const msg of batch) {
+          await tx.send(msg.topic, msg.payload, {
+            key: msg.key,
+            headers: msg.headers,
+            correlationId: msg.correlationId,
+            eventId: msg.eventId
+          });
+        }
+      });
+      await store.markPublished(batch.map((m) => m.id));
+      onPublished?.(batch.length);
+    } catch (err) {
+      onError(toError2(err), batch);
+    }
+  };
+  const tick = () => {
+    if (stopped || running) return;
+    running = true;
+    inFlight = iterate().finally(() => {
+      running = false;
+    });
+  };
+  const timer = setInterval(tick, pollIntervalMs);
+  timer.unref?.();
+  return {
+    stop: async () => {
+      stopped = true;
+      clearInterval(timer);
+      await inFlight;
+    }
+  };
+}
+
+// src/client/security/providers.ts
+var defaultImport = (specifier) => import(specifier);
+function awsMskIamProvider(options) {
+  const importFn = options.importFn ?? defaultImport;
+  return async () => {
+    let signer;
+    try {
+      signer = await importFn("aws-msk-iam-sasl-signer-js");
+    } catch {
+      throw new Error(
+        "awsMskIamProvider: package 'aws-msk-iam-sasl-signer-js' is not installed. Run `npm install aws-msk-iam-sasl-signer-js` to enable MSK IAM authentication."
+      );
+    }
+    const { token, expiryTime } = await signer.generateAuthToken({
+      region: options.region
+    });
+    return {
+      value: token,
+      principal: "msk-iam",
+      // expiryTime is epoch ms per the signer's contract
+      lifetimeMs: expiryTime
+    };
+  };
+}
+function gcpAccessTokenProvider(options = {}) {
+  const importFn = options.importFn ?? defaultImport;
+  const ttlMs = options.tokenTtlMs ?? 50 * 6e4;
+  return async () => {
+    let lib;
+    try {
+      lib = await importFn("google-auth-library");
+    } catch {
+      throw new Error(
+        "gcpAccessTokenProvider: package 'google-auth-library' is not installed. Run `npm install google-auth-library` to enable GCP authentication."
+      );
+    }
+    const auth = new lib.GoogleAuth({
+      scopes: options.scopes ?? ["https://www.googleapis.com/auth/cloud-platform"]
+    });
+    const token = await auth.getAccessToken();
+    if (!token) {
+      throw new Error(
+        "gcpAccessTokenProvider: google-auth-library returned no access token \u2014 check Application Default Credentials."
+      );
+    }
+    return {
+      value: token,
+      principal: options.principal ?? "gcp",
+      lifetimeMs: Date.now() + ttlMs
+    };
+  };
+}
+
+// src/client/security/acl.ts
+function addResource(out, r) {
+  const key = `${r.resourceType}:${r.patternType}:${r.name}`;
+  const existing = out.get(key);
+  if (existing) {
+    for (const op of r.operations)
+      if (!existing.operations.includes(op)) existing.operations.push(op);
+    if (!existing.reason.includes(r.reason))
+      existing.reason += `; ${r.reason}`;
+  } else {
+    out.set(key, { ...r, operations: [...r.operations] });
+  }
+}
+function describeRequiredAcls(input) {
+  const out = /* @__PURE__ */ new Map();
+  const f = input.features ?? {};
+  const produce = input.produceTopics ?? [];
+  const consume = input.consumeTopics ?? [];
+  const groups = input.groupIds ?? [];
+  for (const t of produce) {
+    addResource(out, {
+      resourceType: "topic",
+      patternType: "literal",
+      name: t,
+      operations: ["WRITE", "DESCRIBE"],
+      reason: "sendMessage/sendBatch"
+    });
+  }
+  for (const t of consume) {
+    addResource(out, {
+      resourceType: "topic",
+      patternType: "literal",
+      name: t,
+      operations: ["READ", "DESCRIBE"],
+      reason: "startConsumer"
+    });
+  }
+  for (const g of groups) {
+    addResource(out, {
+      resourceType: "group",
+      patternType: "literal",
+      name: g,
+      operations: ["READ", "DESCRIBE"],
+      reason: "consumer group membership + offset commits"
+    });
+  }
+  if (f.dlq) {
+    for (const t of consume) {
+      addResource(out, {
+        resourceType: "topic",
+        patternType: "literal",
+        name: `${t}.dlq`,
+        operations: ["WRITE", "DESCRIBE"],
+        reason: "dlq: true \u2014 failed messages routed to DLQ"
+      });
+    }
+  }
+  if (f.retryTopics) {
+    for (const t of consume) {
+      for (let level = 1; level <= f.retryTopics.maxRetries; level++) {
+        addResource(out, {
+          resourceType: "topic",
+          patternType: "literal",
+          name: `${t}.retry.${level}`,
+          operations: ["READ", "WRITE", "DESCRIBE"],
+          reason: "retryTopics \u2014 retry chain produce + companion consume"
+        });
+      }
+    }
+    for (const g of groups) {
+      addResource(out, {
+        resourceType: "group",
+        patternType: "prefixed",
+        name: `${g}-retry.`,
+        operations: ["READ", "DESCRIBE"],
+        reason: "retryTopics \u2014 companion retry-level consumer groups"
+      });
+      addResource(out, {
+        resourceType: "transactional-id",
+        patternType: "prefixed",
+        name: `${g}-`,
+        operations: ["WRITE", "DESCRIBE"],
+        reason: "retryTopics \u2014 EOS routing transactions per retry level"
+      });
+    }
+  }
+  if (f.delayedDelivery) {
+    for (const t of [.../* @__PURE__ */ new Set([...produce, ...consume])]) {
+      addResource(out, {
+        resourceType: "topic",
+        patternType: "literal",
+        name: `${t}.delayed`,
+        operations: ["READ", "WRITE", "DESCRIBE"],
+        reason: "deliverAfterMs staging + startDelayedRelay consume"
+      });
+    }
+    for (const g of groups) {
+      addResource(out, {
+        resourceType: "group",
+        patternType: "literal",
+        name: `${g}-delayed-relay`,
+        operations: ["READ", "DESCRIBE"],
+        reason: "startDelayedRelay consumer group"
+      });
+      addResource(out, {
+        resourceType: "transactional-id",
+        patternType: "literal",
+        name: `${g}-delayed-relay-tx`,
+        operations: ["WRITE", "DESCRIBE"],
+        reason: "startDelayedRelay transactional forwarding"
+      });
+    }
+  }
+  if (f.duplicatesTopic) {
+    if (typeof f.duplicatesTopic === "string") {
+      addResource(out, {
+        resourceType: "topic",
+        patternType: "literal",
+        name: f.duplicatesTopic,
+        operations: ["WRITE", "DESCRIBE"],
+        reason: "deduplication.strategy 'topic' \u2014 custom duplicates topic"
+      });
+    } else {
+      for (const t of consume) {
+        addResource(out, {
+          resourceType: "topic",
+          patternType: "literal",
+          name: `${t}.duplicates`,
+          operations: ["WRITE", "DESCRIBE"],
+          reason: "deduplication.strategy 'topic'"
+        });
+      }
+    }
+  }
+  if (f.dlqReplay) {
+    for (const t of consume) {
+      addResource(out, {
+        resourceType: "group",
+        patternType: "prefixed",
+        name: `${t}.dlq-replay`,
+        operations: ["READ", "DESCRIBE", "DELETE"],
+        reason: "replayDlq \u2014 ephemeral/stable replay groups (deleted after use)"
+      });
+      addResource(out, {
+        resourceType: "topic",
+        patternType: "literal",
+        name: `${t}.dlq`,
+        operations: ["READ", "DESCRIBE"],
+        reason: "replayDlq \u2014 reads the DLQ"
+      });
+    }
+  }
+  if (f.snapshots) {
+    addResource(out, {
+      resourceType: "group",
+      patternType: "prefixed",
+      name: `${input.clientId}-snapshot-`,
+      operations: ["READ", "DESCRIBE", "DELETE"],
+      reason: "readSnapshot \u2014 timestamped ephemeral groups (deleted after use)"
+    });
+  }
+  if (f.clockRecovery) {
+    addResource(out, {
+      resourceType: "group",
+      patternType: "prefixed",
+      name: `${input.clientId}-clock-recovery-`,
+      operations: ["READ", "DESCRIBE", "DELETE"],
+      reason: "clockRecovery \u2014 timestamped ephemeral groups (deleted after use)"
+    });
+  }
+  if (f.transactions) {
+    addResource(out, {
+      resourceType: "transactional-id",
+      patternType: "literal",
+      name: `${input.clientId}-tx`,
+      operations: ["WRITE", "DESCRIBE"],
+      reason: "transaction() \u2014 default transactionalId (override-aware: adjust if you set one)"
+    });
+  }
+  if (f.autoCreateTopics) {
+    addResource(out, {
+      resourceType: "cluster",
+      patternType: "literal",
+      name: "kafka-cluster",
+      operations: ["CREATE"],
+      reason: "autoCreateTopics: true \u2014 not recommended in production"
+    });
+  }
+  return [...out.values()];
+}
+function toKafkaAclCommands(resources, principal, bootstrapServer = "<bootstrap-server>") {
+  return resources.map((r) => {
+    const ops = r.operations.map((o) => `--operation ${o}`).join(" ");
+    const resourceFlag = r.resourceType === "topic" ? `--topic '${r.name}'` : r.resourceType === "group" ? `--group '${r.name}'` : r.resourceType === "transactional-id" ? `--transactional-id '${r.name}'` : "--cluster";
+    const pattern = r.patternType === "prefixed" ? " --resource-pattern-type prefixed" : "";
+    return `kafka-acls.sh --bootstrap-server ${bootstrapServer} --add --allow-principal '${principal}' ${ops} ${resourceFlag}${pattern}  # ${r.reason}`;
+  });
+}
+var MSK_TOPIC_ACTIONS = {
+  READ: ["kafka-cluster:ReadData", "kafka-cluster:DescribeTopic"],
+  WRITE: ["kafka-cluster:WriteData", "kafka-cluster:DescribeTopic"],
+  DESCRIBE: ["kafka-cluster:DescribeTopic"],
+  CREATE: ["kafka-cluster:CreateTopic"],
+  DELETE: ["kafka-cluster:DeleteTopic"]
+};
+var MSK_GROUP_ACTIONS = {
+  READ: ["kafka-cluster:AlterGroup", "kafka-cluster:DescribeGroup"],
+  DESCRIBE: ["kafka-cluster:DescribeGroup"],
+  DELETE: ["kafka-cluster:DeleteGroup"]
+};
+var MSK_TX_ACTIONS = {
+  WRITE: [
+    "kafka-cluster:AlterTransactionalId",
+    "kafka-cluster:DescribeTransactionalId"
+  ],
+  DESCRIBE: ["kafka-cluster:DescribeTransactionalId"]
+};
+function toMskIamPolicy(resources, cluster) {
+  const { region, accountId, clusterName, clusterUuid } = cluster;
+  const arn = (type, name) => `arn:aws:kafka:${region}:${accountId}:${type}/${clusterName}/${clusterUuid}/${name}`;
+  const statements = [
+    {
+      Sid: "Connect",
+      Effect: "Allow",
+      Action: ["kafka-cluster:Connect"],
+      Resource: [
+        `arn:aws:kafka:${region}:${accountId}:cluster/${clusterName}/${clusterUuid}`
+      ]
+    }
+  ];
+  let sid = 0;
+  for (const r of resources) {
+    const suffix = r.patternType === "prefixed" ? `${r.name}*` : r.name;
+    let actions = [];
+    let resource;
+    if (r.resourceType === "topic") {
+      actions = [...new Set(r.operations.flatMap((o) => MSK_TOPIC_ACTIONS[o] ?? []))];
+      resource = arn("topic", suffix);
+    } else if (r.resourceType === "group") {
+      actions = [...new Set(r.operations.flatMap((o) => MSK_GROUP_ACTIONS[o] ?? []))];
+      resource = arn("group", suffix);
+    } else if (r.resourceType === "transactional-id") {
+      actions = [...new Set(r.operations.flatMap((o) => MSK_TX_ACTIONS[o] ?? []))];
+      resource = arn("transactional-id", suffix);
+    } else {
+      actions = ["kafka-cluster:CreateTopic"];
+      resource = `arn:aws:kafka:${region}:${accountId}:topic/${clusterName}/${clusterUuid}/*`;
+    }
+    if (actions.length === 0 || !resource) continue;
+    statements.push({
+      Sid: `Acl${sid++}`,
+      Effect: "Allow",
+      Action: actions,
+      Resource: [resource]
+    });
+  }
+  return { Version: "2012-10-17", Statement: statements };
+}
+
+// src/client/config/from-env.ts
+var TRUE_VALUES = /* @__PURE__ */ new Set(["true", "1", "yes"]);
+var FALSE_VALUES = /* @__PURE__ */ new Set(["false", "0", "no"]);
+function parseBool(name, raw) {
+  const normalized = raw.trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) return true;
+  if (FALSE_VALUES.has(normalized)) return false;
+  throw new Error(
+    `Invalid boolean for ${name}: "${raw}". Use one of true/false, 1/0, yes/no (case-insensitive).`
+  );
+}
+function parseNum(name, raw) {
+  const value = Number(raw.trim());
+  if (Number.isNaN(value)) {
+    throw new Error(`Invalid number for ${name}: "${raw}".`);
+  }
+  return value;
+}
+function parseList(raw) {
+  return raw.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+}
+function parseEnum(name, raw, allowed) {
+  const value = raw.trim();
+  if (!allowed.includes(value)) {
+    throw new Error(
+      `Invalid value for ${name}: "${raw}". Allowed: ${allowed.join(", ")}.`
+    );
+  }
+  return value;
+}
+function readVar(env, key, apply) {
+  const raw = env[key];
+  if (raw === void 0 || raw.trim() === "") return;
+  apply(raw);
+}
+function kafkaClientConfigFromEnv(env = process.env, prefix = "KAFKA_") {
+  const options = {};
+  const result = { options };
+  readVar(env, `${prefix}CLIENT_ID`, (raw) => {
+    result.clientId = raw.trim();
+  });
+  readVar(env, `${prefix}GROUP_ID`, (raw) => {
+    result.groupId = raw.trim();
+  });
+  readVar(env, `${prefix}BROKERS`, (raw) => {
+    result.brokers = parseList(raw);
+  });
+  readVar(env, `${prefix}AUTO_CREATE_TOPICS`, (raw) => {
+    options.autoCreateTopics = parseBool(`${prefix}AUTO_CREATE_TOPICS`, raw);
+  });
+  readVar(env, `${prefix}STRICT_SCHEMAS`, (raw) => {
+    options.strictSchemas = parseBool(`${prefix}STRICT_SCHEMAS`, raw);
+  });
+  readVar(env, `${prefix}NUM_PARTITIONS`, (raw) => {
+    options.numPartitions = parseNum(`${prefix}NUM_PARTITIONS`, raw);
+  });
+  readVar(env, `${prefix}TRANSACTIONAL_ID`, (raw) => {
+    options.transactionalId = raw.trim();
+  });
+  readVar(env, `${prefix}CLOCK_RECOVERY_TOPICS`, (raw) => {
+    const topics = parseList(raw);
+    if (topics.length === 0) return;
+    options.clockRecovery = { topics };
+  });
+  readVar(env, `${prefix}CLOCK_RECOVERY_TIMEOUT_MS`, (raw) => {
+    const timeoutMs = parseNum(`${prefix}CLOCK_RECOVERY_TIMEOUT_MS`, raw);
+    if (options.clockRecovery) {
+      options.clockRecovery.timeoutMs = timeoutMs;
+    }
+  });
+  readVar(env, `${prefix}LAG_THROTTLE_MAX_LAG`, (raw) => {
+    options.lagThrottle = {
+      maxLag: parseNum(`${prefix}LAG_THROTTLE_MAX_LAG`, raw)
+    };
+  });
+  readVar(env, `${prefix}LAG_THROTTLE_GROUP_ID`, (raw) => {
+    if (options.lagThrottle) options.lagThrottle.groupId = raw.trim();
+  });
+  readVar(env, `${prefix}LAG_THROTTLE_POLL_INTERVAL_MS`, (raw) => {
+    if (options.lagThrottle) {
+      options.lagThrottle.pollIntervalMs = parseNum(
+        `${prefix}LAG_THROTTLE_POLL_INTERVAL_MS`,
+        raw
+      );
+    }
+  });
+  readVar(env, `${prefix}LAG_THROTTLE_MAX_WAIT_MS`, (raw) => {
+    if (options.lagThrottle) {
+      options.lagThrottle.maxWaitMs = parseNum(
+        `${prefix}LAG_THROTTLE_MAX_WAIT_MS`,
+        raw
+      );
+    }
+  });
+  const security = securityFromEnv(env, prefix);
+  if (security) options.security = security;
+  return result;
+}
+function securityFromEnv(env, prefix) {
+  let ssl;
+  let allowInsecure;
+  let mechanism;
+  let username;
+  let password;
+  readVar(env, `${prefix}SSL`, (raw) => {
+    ssl = parseBool(`${prefix}SSL`, raw);
+  });
+  readVar(env, `${prefix}ALLOW_INSECURE`, (raw) => {
+    allowInsecure = parseBool(`${prefix}ALLOW_INSECURE`, raw);
+  });
+  readVar(env, `${prefix}SASL_MECHANISM`, (raw) => {
+    mechanism = parseEnum(`${prefix}SASL_MECHANISM`, raw, [
+      "plain",
+      "scram-sha-256",
+      "scram-sha-512"
+    ]);
+  });
+  readVar(env, `${prefix}SASL_USERNAME`, (raw) => {
+    username = raw.trim();
+  });
+  readVar(env, `${prefix}SASL_PASSWORD`, (raw) => {
+    password = raw;
+  });
+  if (ssl === void 0 && allowInsecure === void 0 && mechanism === void 0 && username === void 0 && password === void 0) {
+    return void 0;
+  }
+  const security = {};
+  if (ssl !== void 0) security.ssl = ssl;
+  if (allowInsecure !== void 0) security.allowInsecure = allowInsecure;
+  if (mechanism !== void 0 || username !== void 0 || password !== void 0) {
+    if (mechanism === void 0 || username === void 0 || password === void 0) {
+      throw new Error(
+        `Incomplete SASL configuration: ${prefix}SASL_MECHANISM, ${prefix}SASL_USERNAME, and ${prefix}SASL_PASSWORD must all be set together (oauthbearer must be configured in code).`
+      );
+    }
+    const sasl = { mechanism, username, password };
+    security.sasl = sasl;
+  }
+  return security;
+}
+function consumerOptionsFromEnv(env = process.env, prefix = "KAFKA_CONSUMER_") {
+  const options = {};
+  readVar(env, `${prefix}GROUP_ID`, (raw) => {
+    options.groupId = raw.trim();
+  });
+  readVar(env, `${prefix}FROM_BEGINNING`, (raw) => {
+    options.fromBeginning = parseBool(`${prefix}FROM_BEGINNING`, raw);
+  });
+  readVar(env, `${prefix}AUTO_COMMIT`, (raw) => {
+    options.autoCommit = parseBool(`${prefix}AUTO_COMMIT`, raw);
+  });
+  readVar(env, `${prefix}DLQ`, (raw) => {
+    options.dlq = parseBool(`${prefix}DLQ`, raw);
+  });
+  readVar(env, `${prefix}RETRY_MAX_RETRIES`, (raw) => {
+    const retry = {
+      maxRetries: parseNum(`${prefix}RETRY_MAX_RETRIES`, raw)
+    };
+    options.retry = retry;
+  });
+  readVar(env, `${prefix}RETRY_BACKOFF_MS`, (raw) => {
+    if (options.retry) {
+      options.retry.backoffMs = parseNum(`${prefix}RETRY_BACKOFF_MS`, raw);
+    }
+  });
+  readVar(env, `${prefix}RETRY_MAX_BACKOFF_MS`, (raw) => {
+    if (options.retry) {
+      options.retry.maxBackoffMs = parseNum(`${prefix}RETRY_MAX_BACKOFF_MS`, raw);
+    }
+  });
+  readVar(env, `${prefix}RETRY_TOPICS`, (raw) => {
+    options.retryTopics = parseBool(`${prefix}RETRY_TOPICS`, raw);
+  });
+  readVar(env, `${prefix}RETRY_TOPIC_ASSIGNMENT_TIMEOUT_MS`, (raw) => {
+    options.retryTopicAssignmentTimeoutMs = parseNum(
+      `${prefix}RETRY_TOPIC_ASSIGNMENT_TIMEOUT_MS`,
+      raw
+    );
+  });
+  readVar(env, `${prefix}HANDLER_TIMEOUT_MS`, (raw) => {
+    options.handlerTimeoutMs = parseNum(`${prefix}HANDLER_TIMEOUT_MS`, raw);
+  });
+  readVar(env, `${prefix}MESSAGE_TTL_MS`, (raw) => {
+    options.messageTtlMs = parseNum(`${prefix}MESSAGE_TTL_MS`, raw);
+  });
+  readVar(env, `${prefix}DEDUPLICATION_STRATEGY`, (raw) => {
+    const strategy = parseEnum(`${prefix}DEDUPLICATION_STRATEGY`, raw, [
+      "drop",
+      "dlq",
+      "topic"
+    ]);
+    const dedup = { strategy };
+    options.deduplication = dedup;
+  });
+  readVar(env, `${prefix}DEDUPLICATION_TOPIC`, (raw) => {
+    if (options.deduplication) {
+      options.deduplication.duplicatesTopic = raw.trim();
+    }
+  });
+  readVar(env, `${prefix}CIRCUIT_BREAKER_THRESHOLD`, (raw) => {
+    const cb = {
+      threshold: parseNum(`${prefix}CIRCUIT_BREAKER_THRESHOLD`, raw)
+    };
+    options.circuitBreaker = cb;
+  });
+  readVar(env, `${prefix}CIRCUIT_BREAKER_RECOVERY_MS`, (raw) => {
+    if (options.circuitBreaker) {
+      options.circuitBreaker.recoveryMs = parseNum(
+        `${prefix}CIRCUIT_BREAKER_RECOVERY_MS`,
+        raw
+      );
+    }
+  });
+  readVar(env, `${prefix}CIRCUIT_BREAKER_WINDOW_SIZE`, (raw) => {
+    if (options.circuitBreaker) {
+      options.circuitBreaker.windowSize = parseNum(
+        `${prefix}CIRCUIT_BREAKER_WINDOW_SIZE`,
+        raw
+      );
+    }
+  });
+  readVar(env, `${prefix}CIRCUIT_BREAKER_HALF_OPEN_SUCCESSES`, (raw) => {
+    if (options.circuitBreaker) {
+      options.circuitBreaker.halfOpenSuccesses = parseNum(
+        `${prefix}CIRCUIT_BREAKER_HALF_OPEN_SUCCESSES`,
+        raw
+      );
+    }
+  });
+  readVar(env, `${prefix}QUEUE_HIGH_WATER_MARK`, (raw) => {
+    options.queueHighWaterMark = parseNum(`${prefix}QUEUE_HIGH_WATER_MARK`, raw);
+  });
+  readVar(env, `${prefix}PARTITION_ASSIGNER`, (raw) => {
+    options.partitionAssigner = parseEnum(`${prefix}PARTITION_ASSIGNER`, raw, [
+      "roundrobin",
+      "range",
+      "cooperative-sticky"
+    ]);
+  });
+  readVar(env, `${prefix}GROUP_INSTANCE_ID`, (raw) => {
+    options.groupInstanceId = raw.trim();
+  });
+  readVar(env, `${prefix}SUBSCRIBE_RETRY_RETRIES`, (raw) => {
+    const subscribeRetry = {
+      retries: parseNum(`${prefix}SUBSCRIBE_RETRY_RETRIES`, raw)
+    };
+    options.subscribeRetry = subscribeRetry;
+  });
+  readVar(env, `${prefix}SUBSCRIBE_RETRY_DELAY_MS`, (raw) => {
+    if (options.subscribeRetry) {
+      options.subscribeRetry.backoffMs = parseNum(
+        `${prefix}SUBSCRIBE_RETRY_DELAY_MS`,
+        raw
+      );
+    }
+  });
+  return options;
+}
+var NESTED_CONSUMER_KEYS = [
+  "retry",
+  "deduplication",
+  "circuitBreaker",
+  "subscribeRetry"
+];
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeConsumerOptions(...layers) {
+  const result = {};
+  for (const layer of layers) {
+    if (!layer) continue;
+    for (const [key, value] of Object.entries(layer)) {
+      if (value === void 0) continue;
+      if (NESTED_CONSUMER_KEYS.includes(key) && isPlainObject(value) && isPlainObject(result[key])) {
+        result[key] = {
+          ...result[key],
+          ...value
+        };
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+  return result;
+}
+
+export {
+  ConfluentTransport,
+  InMemoryDedupStore,
+  HEADER_EVENT_ID,
+  HEADER_CORRELATION_ID,
+  HEADER_TIMESTAMP,
+  HEADER_SCHEMA_VERSION,
+  HEADER_TRACEPARENT,
+  HEADER_LAMPORT_CLOCK,
+  HEADER_DELAYED_UNTIL,
+  HEADER_DELAYED_TARGET,
+  getEnvelopeContext,
+  runWithEnvelopeContext,
+  buildEnvelopeHeaders,
+  decodeHeaders,
+  extractEnvelope,
+  toError,
+  KafkaProcessingError,
+  KafkaValidationError,
+  KafkaRetryExhaustedError,
+  resolveSecurityOptions,
+  KafkaClient,
+  topic,
+  versionedSchema,
+  InMemoryOutboxStore,
+  startOutboxRelay,
+  awsMskIamProvider,
+  gcpAccessTokenProvider,
+  describeRequiredAcls,
+  toKafkaAclCommands,
+  toMskIamPolicy,
+  kafkaClientConfigFromEnv,
+  consumerOptionsFromEnv,
+  mergeConsumerOptions
+};
+//# sourceMappingURL=chunk-OR7TPAAE.mjs.map