@drarzter/kafka-client 0.9.4 → 0.10.0

package/dist/{chunk-SM4FZKAZ.mjs → cli/index.js}

@@ -1,10 +1,14 @@
-// src/client/kafka.client/confluent-transport.ts
-import { KafkaJS } from "@confluentinc/kafka-javascript";
-var { Kafka: KafkaClass, logLevel: KafkaLogLevel, PartitionAssigners } = KafkaJS;
+#!/usr/bin/env node
+"use strict";
+
+// src/client/transport/confluent.transport.ts
+var import_kafka_javascript = require("@confluentinc/kafka-javascript");
+var { Kafka: KafkaClass, logLevel: KafkaLogLevel, PartitionAssigners } = import_kafka_javascript.KafkaJS;
 var ConfluentTransaction = class {
   constructor(tx) {
     this.tx = tx;
   }
+  tx;
   async send(record) {
     await this.tx.send(record);
   }
@@ -26,10 +30,17 @@ var ConfluentProducer = class {
   constructor(producer) {
     this.producer = producer;
   }
+  producer;
+  connectPromise;
   async connect() {
-    await this.producer.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) {
@@ -44,6 +55,7 @@ var ConfluentConsumer = class {
   constructor(consumer) {
     this.consumer = consumer;
   }
+  consumer;
   /** Returns the underlying KafkaJS.Consumer — used by ConfluentTransaction.sendOffsets. */
   getNative() {
     return this.consumer;
@@ -83,6 +95,7 @@ var ConfluentAdmin = class {
   constructor(admin) {
     this.admin = admin;
   }
+  admin;
   async connect() {
     await this.admin.connect();
   }
@@ -92,11 +105,11 @@ var ConfluentAdmin = class {
   async createTopics(options) {
     await this.admin.createTopics(options);
   }
-  async fetchTopicOffsets(topic2) {
-    return this.admin.fetchTopicOffsets(topic2);
+  async fetchTopicOffsets(topic) {
+    return this.admin.fetchTopicOffsets(topic);
   }
-  async fetchTopicOffsetsByTimestamp(topic2, timestamp) {
-    return this.admin.fetchTopicOffsetsByTime(topic2, timestamp);
+  async fetchTopicOffsetsByTimestamp(topic, timestamp) {
+    return this.admin.fetchTopicOffsetsByTimestamp(topic, timestamp);
   }
   async fetchOffsets(options) {
     return this.admin.fetchOffsets(options);
@@ -122,10 +135,29 @@ var ConfluentAdmin = class {
 };
 var ConfluentTransport = class {
   kafka;
-  constructor(clientId, brokers) {
-    this.kafka = new KafkaClass({
-      kafkaJS: { clientId, brokers, logLevel: KafkaLogLevel.ERROR }
-    });
+  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({
@@ -152,6 +184,9 @@ var ConfluentTransport = class {
         partitionAssigners: [assigner]
       }
     };
+    if (options.groupInstanceId) {
+      config["group.instance.id"] = options.groupInstanceId;
+    }
     if (options.onRebalance) {
       const cb = options.onRebalance;
       config.rebalance_cb = (err, assignment) => {
@@ -169,16 +204,37 @@ var ConfluentTransport = class {
   }
 };
 
+// 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 import_node_async_hooks = require("async_hooks");
+var import_node_crypto = require("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 envelopeStorage = new AsyncLocalStorage();
+var HEADER_DELAYED_UNTIL = "x-delayed-until";
+var HEADER_DELAYED_TARGET = "x-delayed-target";
+var envelopeStorage = new import_node_async_hooks.AsyncLocalStorage();
 function getEnvelopeContext() {
   return envelopeStorage.getStore();
 }
@@ -187,8 +243,8 @@ function runWithEnvelopeContext(ctx, fn) {
 }
 function buildEnvelopeHeaders(options = {}) {
   const ctx = getEnvelopeContext();
-  const correlationId = options.correlationId ?? ctx?.correlationId ?? randomUUID();
-  const eventId = options.eventId ?? randomUUID();
+  const correlationId = options.correlationId ?? ctx?.correlationId ?? (0, import_node_crypto.randomUUID)();
+  const eventId = options.eventId ?? (0, import_node_crypto.randomUUID)();
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   const schemaVersion = String(options.schemaVersion ?? 1);
   const envelope = {
@@ -216,14 +272,14 @@ function decodeHeaders(raw) {
   }
   return result;
 }
-function extractEnvelope(payload, headers, topic2, partition, offset) {
+function extractEnvelope(payload, headers, topic, partition, offset) {
   return {
     payload,
-    topic: topic2,
+    topic,
     partition,
     offset,
-    eventId: headers[HEADER_EVENT_ID] ?? randomUUID(),
-    correlationId: headers[HEADER_CORRELATION_ID] ?? randomUUID(),
+    eventId: headers[HEADER_EVENT_ID] ?? (0, import_node_crypto.randomUUID)(),
+    correlationId: headers[HEADER_CORRELATION_ID] ?? (0, import_node_crypto.randomUUID)(),
     timestamp: headers[HEADER_TIMESTAMP] ?? (/* @__PURE__ */ new Date()).toISOString(),
     schemaVersion: Number(headers[HEADER_SCHEMA_VERSION] ?? 1),
     traceparent: headers[HEADER_TRACEPARENT],
@@ -232,35 +288,43 @@ function extractEnvelope(payload, headers, topic2, partition, offset) {
 }
 
 // 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) {
+  constructor(message, topic, originalMessage, options) {
     super(message, options);
-    this.topic = topic2;
+    this.topic = topic;
     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;
+  constructor(topic, originalMessage, options) {
+    super(`Schema validation failed for topic "${topic}"`, options);
+    this.topic = topic;
     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) {
+  constructor(topic, originalMessage, attempts, options) {
     super(
-      `Message processing failed after ${attempts} attempts on topic "${topic2}"`,
-      topic2,
+      `Message processing failed after ${attempts} attempts on topic "${topic}"`,
+      topic,
       originalMessage,
       options
     );
     this.attempts = attempts;
     this.name = "KafkaRetryExhaustedError";
   }
+  attempts;
 };
 
 // src/client/kafka.client/producer/ops.ts
@@ -273,14 +337,14 @@ function resolveTopicName(topicOrDescriptor) {
 }
 function registerSchema(topicOrDesc, schemaRegistry, logger) {
   if (topicOrDesc?.__schema) {
-    const topic2 = resolveTopicName(topicOrDesc);
-    const existing = schemaRegistry.get(topic2);
+    const topic = resolveTopicName(topicOrDesc);
+    const existing = schemaRegistry.get(topic);
     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.`
+        `Schema conflict for topic "${topic}": a different schema is already registered. Using the new schema \u2014 ensure consistent schemas to avoid silent validation mismatches.`
       );
     }
-    schemaRegistry.set(topic2, topicOrDesc.__schema);
+    schemaRegistry.set(topic, topicOrDesc.__schema);
   }
 }
 async function validateMessage(topicOrDesc, message, deps, ctx) {
@@ -309,7 +373,7 @@ async function validateMessage(topicOrDesc, message, deps, ctx) {
   return message;
 }
 async function buildSendPayload(topicOrDesc, messages, deps, compression) {
-  const topic2 = resolveTopicName(topicOrDesc);
+  const topic = resolveTopicName(topicOrDesc);
   const builtMessages = await Promise.all(
     messages.map(async (m) => {
       const envelopeHeaders = buildEnvelopeHeaders({
@@ -322,10 +386,10 @@ async function buildSendPayload(topicOrDesc, messages, deps, compression) {
         envelopeHeaders[HEADER_LAMPORT_CLOCK] = String(deps.nextLamportClock());
       }
       for (const inst of deps.instrumentation) {
-        inst.beforeSend?.(topic2, envelopeHeaders);
+        inst.beforeSend?.(topic, envelopeHeaders);
       }
       const sendCtx = {
-        topic: topic2,
+        topic,
         headers: envelopeHeaders,
         version: m.schemaVersion ?? 1
       };
@@ -333,16 +397,18 @@ async function buildSendPayload(topicOrDesc, messages, deps, compression) {
         value: JSON.stringify(
           await validateMessage(topicOrDesc, m.value, deps, sendCtx)
         ),
-        key: m.key ?? null,
+        // 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 } };
+  return { topic, messages: builtMessages, ...compression && { compression } };
 }
 
 // src/client/kafka.client/consumer/ops.ts
-function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps, partitionAssigner, onFirstAssignment) {
+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);
@@ -375,6 +441,7 @@ function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps, partition
     fromBeginning,
     autoCommit,
     partitionAssigner: partitionAssigner ?? "cooperative-sticky",
+    groupInstanceId,
     onRebalance: (type, assignments) => {
       if (type === "assign") fireOnAssignment();
       else if (type === "revoke") scheduleSettle();
@@ -420,6 +487,7 @@ var AdminOps = class {
   constructor(deps) {
     this.deps = deps;
   }
+  deps;
   isConnected = false;
   /** Underlying admin client — used by index.ts for topic validation. */
   get admin() {
@@ -450,7 +518,7 @@ var AdminOps = class {
     await this.deps.admin.disconnect();
     this.isConnected = false;
   }
-  async resetOffsets(groupId, topic2, position) {
+  async resetOffsets(groupId, topic, position) {
     const gid = groupId ?? this.deps.defaultGroupId;
     if (this.deps.runningConsumers.has(gid)) {
       throw new Error(
@@ -458,14 +526,14 @@ var AdminOps = class {
       );
     }
     await this.ensureConnected();
-    const partitionOffsets = await this.deps.admin.fetchTopicOffsets(topic2);
+    const partitionOffsets = await this.deps.admin.fetchTopicOffsets(topic);
     const partitions = partitionOffsets.map(({ partition, low, high }) => ({
       partition,
       offset: position === "earliest" ? low : high
     }));
-    await this.deps.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
+    await this.deps.admin.setOffsets({ groupId: gid, topic, partitions });
     this.deps.logger.log(
-      `Offsets reset to ${position} for group "${gid}" on topic "${topic2}"`
+      `Offsets reset to ${position} for group "${gid}" on topic "${topic}"`
     );
   }
   /**
@@ -482,15 +550,15 @@ var AdminOps = class {
     }
     await this.ensureConnected();
     const byTopic = /* @__PURE__ */ new Map();
-    for (const { topic: topic2, partition, offset } of assignments) {
-      const list = byTopic.get(topic2) ?? [];
+    for (const { topic, partition, offset } of assignments) {
+      const list = byTopic.get(topic) ?? [];
       list.push({ partition, offset });
-      byTopic.set(topic2, list);
+      byTopic.set(topic, list);
     }
-    for (const [topic2, partitions] of byTopic) {
-      await this.deps.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
+    for (const [topic, partitions] of byTopic) {
+      await this.deps.admin.setOffsets({ groupId: gid, topic, partitions });
       this.deps.logger.log(
-        `Offsets set for group "${gid}" on "${topic2}": ${JSON.stringify(partitions)}`
+        `Offsets set for group "${gid}" on "${topic}": ${JSON.stringify(partitions)}`
       );
     }
   }
@@ -511,27 +579,30 @@ var AdminOps = class {
     }
     await this.ensureConnected();
     const byTopic = /* @__PURE__ */ new Map();
-    for (const { topic: topic2, partition, timestamp } of assignments) {
-      const list = byTopic.get(topic2) ?? [];
+    for (const { topic, partition, timestamp } of assignments) {
+      const list = byTopic.get(topic) ?? [];
       list.push({ partition, timestamp });
-      byTopic.set(topic2, list);
+      byTopic.set(topic, list);
     }
-    for (const [topic2, parts] of byTopic) {
+    for (const [topic, parts] of byTopic) {
       const offsets = await Promise.all(
         parts.map(async ({ partition, timestamp }) => {
           const results = await this.deps.admin.fetchTopicOffsetsByTimestamp(
-            topic2,
+            topic,
             timestamp
           );
           const found = results.find(
             (r) => r.partition === partition
           );
-          return { partition, offset: found?.offset ?? "-1" };
+          if (found) return { partition, offset: found.offset };
+          const topicOffsets = await this.deps.admin.fetchTopicOffsets(topic);
+          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 });
+      await this.deps.admin.setOffsets({ groupId: gid, topic, partitions: offsets });
       this.deps.logger.log(
-        `Offsets set by timestamp for group "${gid}" on "${topic2}": ${JSON.stringify(offsets)}`
+        `Offsets set by timestamp for group "${gid}" on "${topic}": ${JSON.stringify(offsets)}`
       );
     }
   }
@@ -551,11 +622,11 @@ var AdminOps = class {
     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))
+      committedByTopic.map(({ topic }) => this.deps.admin.fetchTopicOffsets(topic))
     );
     const result = [];
     for (let i = 0; i < committedByTopic.length; i++) {
-      const { topic: topic2, partitions } = committedByTopic[i];
+      const { topic, partitions } = committedByTopic[i];
       const brokerOffsets = brokerOffsetsAll[i];
       for (const { partition, offset } of partitions) {
         const broker = brokerOffsets.find((o) => o.partition === partition);
@@ -563,7 +634,7 @@ var AdminOps = class {
         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 });
+        result.push({ topic, partition, lag });
       }
     }
     return result;
@@ -607,7 +678,8 @@ var AdminOps = class {
       name: t.name,
       partitions: t.partitions.map((p) => ({
         partition: p.partitionId ?? p.partition ?? 0,
-        leader: p.leader ?? 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
         ),
@@ -632,9 +704,9 @@ var AdminOps = class {
    * 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) {
+  async deleteRecords(topic, partitions) {
     await this.ensureConnected();
-    await this.deps.admin.deleteTopicRecords({ topic: topic2, partitions });
+    await this.deps.admin.deleteTopicRecords({ topic, partitions });
   }
   /**
    * When `retryTopics: true` and `autoCreateTopics: false`, verify that every
@@ -691,28 +763,25 @@ var AdminOps = class {
 };
 
 // src/client/kafka.client/consumer/pipeline.ts
-function toError(error) {
-  return error instanceof Error ? error : new Error(String(error));
-}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function parseJsonMessage(raw, topic2, logger) {
+function parseJsonMessage(raw, topic, logger) {
   try {
     return JSON.parse(raw);
   } catch (error) {
     logger.error(
-      `Failed to parse message from topic ${topic2}:`,
+      `Failed to parse message from topic ${topic}:`,
       toError(error).stack
     );
     return null;
   }
 }
-async function validateWithSchema(message, raw, topic2, schemaMap, interceptors, dlq, deps) {
-  const schema = schemaMap.get(topic2);
+async function validateWithSchema(message, raw, topic, schemaMap, interceptors, dlq, deps) {
+  const schema = schemaMap.get(topic);
   if (!schema) return message;
   const ctx = {
-    topic: topic2,
+    topic,
     headers: deps.originalHeaders ?? {},
     version: Number(deps.originalHeaders?.["x-schema-version"] ?? 1)
   };
@@ -720,22 +789,22 @@ async function validateWithSchema(message, raw, topic2, schemaMap, interceptors,
     return await schema.parse(message, ctx);
   } catch (error) {
     const err = toError(error);
-    const validationError = new KafkaValidationError(topic2, message, {
+    const validationError = new KafkaValidationError(topic, message, {
       cause: err
     });
     deps.logger.error(
-      `Schema validation failed for topic ${topic2}:`,
+      `Schema validation failed for topic ${topic}:`,
       err.message
     );
     if (dlq) {
-      await sendToDlq(topic2, raw, deps, {
+      await sendToDlq(topic, raw, deps, {
         error: validationError,
         attempt: 0,
         originalHeaders: deps.originalHeaders
       });
     } else {
       await deps.onMessageLost?.({
-        topic: topic2,
+        topic,
         error: validationError,
         attempt: 0,
         headers: deps.originalHeaders ?? {}
@@ -744,7 +813,7 @@ async function validateWithSchema(message, raw, topic2, schemaMap, interceptors,
     const errorEnvelope = extractEnvelope(
       message,
       deps.originalHeaders ?? {},
-      topic2,
+      topic,
       -1,
       ""
     );
@@ -757,11 +826,11 @@ async function validateWithSchema(message, raw, topic2, schemaMap, interceptors,
     return null;
   }
 }
-function buildDlqPayload(topic2, rawMessage, meta) {
-  const dlqTopic = `${topic2}.dlq`;
+function buildDlqPayload(topic, rawMessage, meta) {
+  const dlqTopic = `${topic}.dlq`;
   const headers = {
     ...meta?.originalHeaders ?? {},
-    "x-dlq-original-topic": topic2,
+    "x-dlq-original-topic": topic,
     "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) ?? "",
@@ -769,8 +838,8 @@ function buildDlqPayload(topic2, rawMessage, meta) {
   };
   return { topic: dlqTopic, messages: [{ value: rawMessage, headers }] };
 }
-async function sendToDlq(topic2, rawMessage, deps, meta) {
-  const payload = buildDlqPayload(topic2, rawMessage, meta);
+async function sendToDlq(topic, rawMessage, deps, meta) {
+  const payload = buildDlqPayload(topic, rawMessage, meta);
   try {
     await deps.producer.send(payload);
     deps.logger.warn(`Message sent to DLQ: ${payload.topic}`);
@@ -781,7 +850,7 @@ async function sendToDlq(topic2, rawMessage, deps, meta) {
       err.stack
     );
     await deps.onMessageLost?.({
-      topic: topic2,
+      topic,
       error: err,
       attempt: meta?.attempt ?? 0,
       headers: meta?.originalHeaders ?? {}
@@ -954,7 +1023,7 @@ async function executeWithRetry(fn, ctx, deps) {
   const backoffMs = retry?.backoffMs ?? 1e3;
   const maxBackoffMs = retry?.maxBackoffMs ?? 3e4;
   const envelopes = Array.isArray(envelope) ? envelope : [envelope];
-  const topic2 = envelopes[0]?.topic ?? "unknown";
+  const topic = envelopes[0]?.topic ?? "unknown";
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     const error = await runHandlerWithPipeline(
       fn,
@@ -977,16 +1046,17 @@ async function executeWithRetry(fn, ctx, deps) {
       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,
+      topic,
       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 processing ${isBatch ? "batch" : "message"} from topic ${topic} (attempt ${attempt}/${maxAttempts}):`,
       error.stack
     );
     if (retryTopics && retry) {
@@ -1004,7 +1074,7 @@ async function executeWithRetry(fn, ctx, deps) {
         }
       } else {
         await sendToRetryTopic(
-          topic2,
+          topic,
           rawMessages,
           1,
           retry.maxRetries,
@@ -1017,7 +1087,7 @@ async function executeWithRetry(fn, ctx, deps) {
     } else if (isLastAttempt) {
       if (dlq) {
         for (let i = 0; i < rawMessages.length; i++) {
-          await sendToDlq(topic2, rawMessages[i], deps, {
+          await sendToDlq(topic, rawMessages[i], deps, {
             error,
             attempt,
             originalHeaders: envelopes[i]?.headers
@@ -1026,7 +1096,7 @@ async function executeWithRetry(fn, ctx, deps) {
         }
       } else {
         await deps.onMessageLost?.({
-          topic: topic2,
+          topic,
           error,
           attempt,
           headers: envelopes[0]?.headers ?? {}
@@ -1061,9 +1131,14 @@ async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
   }
 }
 
-// src/client/kafka.client/consumer/dlq-replay.ts
-async function replayDlqTopic(topic2, deps, options = {}) {
-  const dlqTopic = `${topic2}.dlq`;
+// src/client/kafka.client/consumer/features/dlq-replay.ts
+async function replayDlqTopic(topic, deps, options = {}) {
+  if (topic.endsWith(".dlq")) {
+    throw new Error(
+      `replayDlq: pass the ORIGINAL topic name \u2014 "${topic}" already ends in ".dlq" (the ".dlq" suffix is appended internally, so this would read "${topic}.dlq")`
+    );
+  }
+  const dlqTopic = `${topic}.dlq`;
   const partitionOffsets = await deps.fetchTopicOffsets(dlqTopic);
   const activePartitions = partitionOffsets.filter(
     (p) => Number.parseInt(p.high, 10) > Number.parseInt(p.low, 10)
@@ -1128,19 +1203,20 @@ var MetricsManager = class {
   constructor(deps) {
     this.deps = deps;
   }
+  deps;
   topicMetrics = /* @__PURE__ */ new Map();
-  metricsFor(topic2) {
-    let m = this.topicMetrics.get(topic2);
+  metricsFor(topic) {
+    let m = this.topicMetrics.get(topic);
     if (!m) {
       m = { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
-      this.topicMetrics.set(topic2, m);
+      this.topicMetrics.set(topic, m);
     }
     return m;
   }
   /** Fire `afterSend` instrumentation hooks for each message in a batch. */
-  notifyAfterSend(topic2, count) {
+  notifyAfterSend(topic, count) {
     for (let i = 0; i < count; i++)
-      for (const inst of this.deps.instrumentation) inst.afterSend?.(topic2);
+      for (const inst of this.deps.instrumentation) inst.afterSend?.(topic);
   }
   /**
    * Increment the retry counter for the envelope's topic and fire all `onRetry` instrumentation hooks.
@@ -1153,16 +1229,25 @@ var MetricsManager = class {
     for (const inst of this.deps.instrumentation) inst.onRetry?.(envelope, attempt, maxRetries);
   }
   /**
-   * Increment the DLQ counter for the envelope's topic, fire all `onDlq` instrumentation hooks,
-   * and notify the circuit breaker of a failure (when `gid` is provided).
+   * 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.
-   * @param gid Consumer group ID — used to drive circuit breaker state.
    */
-  notifyDlq(envelope, reason, gid) {
+  notifyDlq(envelope, reason) {
     this.metricsFor(envelope.topic).dlqCount++;
     for (const inst of this.deps.instrumentation) inst.onDlq?.(envelope, reason);
-    if (gid) this.deps.onCircuitFailure(envelope, gid);
+  }
+  /**
+   * 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.
@@ -1189,9 +1274,9 @@ var MetricsManager = class {
    * @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);
+  getMetrics(topic) {
+    if (topic !== void 0) {
+      const m = this.topicMetrics.get(topic);
       return m ? { ...m } : { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
     }
     const agg = { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
@@ -1207,9 +1292,9 @@ var MetricsManager = class {
    * 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);
+  resetMetrics(topic) {
+    if (topic !== void 0) {
+      this.topicMetrics.delete(topic);
       return;
     }
     this.topicMetrics.clear();
@@ -1221,6 +1306,7 @@ var InFlightTracker = class {
   constructor(warn) {
     this.warn = warn;
   }
+  warn;
   inFlightTotal = 0;
   drainResolvers = [];
   /**
@@ -1231,10 +1317,16 @@ var InFlightTracker = class {
    */
   track(fn) {
     this.inFlightTotal++;
-    return fn().finally(() => {
+    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.
@@ -1268,6 +1360,7 @@ var CircuitBreakerManager = class {
   constructor(deps) {
     this.deps = deps;
   }
+  deps;
   states = /* @__PURE__ */ new Map();
   configs = /* @__PURE__ */ new Map();
   /**
@@ -1283,8 +1376,8 @@ var CircuitBreakerManager = class {
    * 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}`);
+  getState(topic, partition, gid) {
+    const state = this.states.get(`${gid}:${topic}:${partition}`);
     if (!state) return void 0;
     return {
       status: state.status,
@@ -1412,6 +1505,9 @@ var AsyncQueue = class {
     this.onFull = onFull;
     this.onDrained = onDrained;
   }
+  highWaterMark;
+  onFull;
+  onDrained;
   items = [];
   waiting = [];
   closed = false;
@@ -1423,6 +1519,7 @@ var AsyncQueue = class {
    * @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 {
@@ -1473,20 +1570,115 @@ var AsyncQueue = class {
   }
 };
 
+// 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);
+async function ensureTopic(ctx, topic) {
+  if (!ctx.autoCreateTopicsEnabled || ctx.ensuredTopics.has(topic)) return;
+  let p = ctx.ensureTopicPromises.get(topic);
   if (!p) {
     p = (async () => {
       await ctx.adminOps.ensureConnected();
       await ctx.adminOps.admin.createTopics({
-        topics: [{ topic: topic2, numPartitions: ctx.numPartitions }]
+        topics: [{ topic, numPartitions: ctx.numPartitions }]
       });
-      ctx.ensuredTopics.add(topic2);
-    })().finally(() => ctx.ensureTopicPromises.delete(topic2));
-    ctx.ensureTopicPromises.set(topic2, p);
+      ctx.ensuredTopics.add(topic);
+    })().finally(() => ctx.ensureTopicPromises.delete(topic));
+    ctx.ensureTopicPromises.set(topic, p);
   }
   await p;
 }
@@ -1606,6 +1798,7 @@ async function recoverLamportClockImpl(ctx, topics) {
     const remaining = new Set(
       partitionsToRead.map((p) => `${p.topic}:${p.partition}`)
     );
+    let settled = false;
     const cleanup = () => {
       consumer.disconnect().catch(() => {
       }).finally(() => {
@@ -1613,6 +1806,16 @@ async function recoverLamportClockImpl(ctx, topics) {
         });
       });
     };
+    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))
@@ -1633,13 +1836,18 @@ async function recoverLamportClockImpl(ctx, topics) {
             const clock = Number(raw);
             if (!Number.isNaN(clock) && clock > maxClock) maxClock = clock;
           }
-          if (remaining.size === 0) {
+          if (remaining.size === 0 && !settled) {
+            settled = true;
+            clearTimeout(timeoutTimer);
             cleanup();
             resolve();
           }
         }
       })
     ).catch((err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
       cleanup();
       reject(err);
     });
@@ -1655,14 +1863,14 @@ async function recoverLamportClockImpl(ctx, topics) {
     );
   }
 }
-function wrapWithTimeoutWarning(logger, fn, timeoutMs, topic2) {
+function wrapWithTimeoutWarning(logger, fn, timeoutMs, topic) {
   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`
+      `Handler for topic "${topic}" has not resolved after ${timeoutMs}ms \u2014 possible stuck handler`
     );
   }, timeoutMs);
   return promise;
@@ -1680,6 +1888,15 @@ async function preparePayload(ctx, topicOrDesc, messages, 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(
@@ -1697,6 +1914,9 @@ async function sendMessageImpl(ctx, topicOrDesc, message, options = {}) {
     ],
     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);
 }
@@ -1708,19 +1928,22 @@ async function sendBatchImpl(ctx, topicOrDesc, messages, options) {
     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) {
+async function sendTombstoneImpl(ctx, topic, key, headers) {
   await waitIfThrottled(ctx);
   const hdrs = { ...headers };
-  for (const inst of ctx.instrumentation) inst.beforeSend?.(topic2, hdrs);
-  await ensureTopic(ctx, topic2);
+  for (const inst of ctx.instrumentation) inst.beforeSend?.(topic, hdrs);
+  await ensureTopic(ctx, topic);
   await ctx.producer.send({
-    topic: topic2,
+    topic,
     messages: [{ value: null, key, headers: hdrs }]
   });
-  for (const inst of ctx.instrumentation) inst.afterSend?.(topic2);
+  for (const inst of ctx.instrumentation) inst.afterSend?.(topic);
 }
 async function transactionImpl(ctx, fn) {
   if (!ctx.txProducerInitPromise) {
@@ -1744,6 +1967,17 @@ async function transactionImpl(ctx, fn) {
     });
   }
   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 = {
@@ -1911,6 +2145,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
         await consumer.commitOffsets([nextOffset]);
         return;
       }
+      deps.onFailure?.(envelope);
       const exhausted = level >= currentMaxRetries;
       const reportedError = exhausted && currentMaxRetries > 1 ? new KafkaRetryExhaustedError(
         originalTopic,
@@ -2126,7 +2361,8 @@ async function setupConsumer(ctx, topics, mode, options) {
     options.autoCommit ?? true,
     ctx.consumerOpsDeps,
     options.partitionAssigner,
-    resolveReady
+    resolveReady,
+    options.groupInstanceId
   );
   const schemaMap = buildSchemaMap(
     stringTopics,
@@ -2138,6 +2374,9 @@ async function setupConsumer(ctx, topics, mode, options) {
   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,
@@ -2152,9 +2391,8 @@ async function setupConsumer(ctx, topics, mode, options) {
 }
 function resolveDeduplicationContext(ctx, groupId, options) {
   if (!options) return void 0;
-  if (!ctx.dedupStates.has(groupId))
-    ctx.dedupStates.set(groupId, /* @__PURE__ */ new Map());
-  return { options, state: ctx.dedupStates.get(groupId) };
+  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);
@@ -2168,9 +2406,10 @@ function messageDepsFor(ctx, gid, options) {
       notifyRetry(envelope, attempt, max);
       return options.onRetry(envelope, attempt, max);
     } : notifyRetry,
-    onDlq: (envelope, reason) => ctx.metrics.notifyDlq(envelope, reason, gid),
+    onDlq: (envelope, reason) => ctx.metrics.notifyDlq(envelope, reason),
     onDuplicate: ctx.metrics.notifyDuplicate.bind(ctx.metrics),
-    onMessage: (envelope) => ctx.metrics.notifyMessage(envelope, gid)
+    onMessage: (envelope) => ctx.metrics.notifyMessage(envelope, gid),
+    onFailure: (envelope) => ctx.metrics.notifyFailure(envelope, gid)
   };
 }
 function buildRetryTopicDeps(ctx) {
@@ -2209,6 +2448,11 @@ async function launchRetryChain(ctx, gid, topicNames, handleMessage, opts) {
     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);
       }
@@ -2224,7 +2468,15 @@ async function applyDeduplication(envelope, raw, dedup, dlq, deps) {
   const incomingClock = Number(clockRaw);
   if (Number.isNaN(incomingClock)) return false;
   const stateKey = `${envelope.topic}:${envelope.partition}`;
-  const lastProcessedClock = dedup.state.get(stateKey) ?? -1;
+  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,
@@ -2254,32 +2506,38 @@ async function applyDeduplication(envelope, raw, dedup, dlq, deps) {
     }
     return true;
   }
-  dedup.state.set(stateKey, incomingClock);
+  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) {
+async function parseSingleMessage(message, topic, partition, schemaMap, interceptors, dlq, deps) {
   if (!message.value) {
-    deps.logger.warn(`Received empty message from topic ${topic2}`);
+    deps.logger.warn(`Received empty message from topic ${topic}`);
     return null;
   }
   const raw = message.value.toString();
-  const parsed = parseJsonMessage(raw, topic2, deps.logger);
+  const parsed = parseJsonMessage(raw, topic, deps.logger);
   if (parsed === null) return null;
   const headers = decodeHeaders(message.headers);
   const validated = await validateWithSchema(
     parsed,
     raw,
-    topic2,
+    topic,
     schemaMap,
     interceptors,
     dlq,
     { ...deps, originalHeaders: headers }
   );
   if (validated === null) return null;
-  return extractEnvelope(validated, headers, topic2, partition, message.offset);
+  return extractEnvelope(validated, headers, topic, partition, message.offset);
 }
 async function handleEachMessage(payload, opts, deps) {
-  const { topic: topic2, partition, message } = payload;
+  const { topic, partition, message } = payload;
   const {
     schemaMap,
     handleMessage,
@@ -2294,12 +2552,12 @@ async function handleEachMessage(payload, opts, deps) {
   const nextOffsetStr = (parseInt(message.offset, 10) + 1).toString();
   const commitOffset = eos ? async () => {
     await eos.consumer.commitOffsets([
-      { topic: topic2, partition, offset: nextOffsetStr }
+      { topic, partition, offset: nextOffsetStr }
     ]);
   } : void 0;
   const eosRouteToRetry = eos && retry ? async (rawMsgs, envelopes, delay) => {
     const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
-      topic2,
+      topic,
       rawMsgs,
       1,
       retry.maxRetries,
@@ -2313,7 +2571,7 @@ async function handleEachMessage(payload, opts, deps) {
         consumer: eos.consumer,
         topics: [
           {
-            topic: topic2,
+            topic,
             partitions: [{ partition, offset: nextOffsetStr }]
           }
         ]
@@ -2329,7 +2587,7 @@ async function handleEachMessage(payload, opts, deps) {
   } : void 0;
   const envelope = await parseSingleMessage(
     message,
-    topic2,
+    topic,
     partition,
     schemaMap,
     interceptors,
@@ -2357,10 +2615,10 @@ async function handleEachMessage(payload, opts, deps) {
     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`
+        `[KafkaClient] TTL expired on ${topic}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
       );
       if (dlq) {
-        await sendToDlq(topic2, message.value.toString(), deps, {
+        await sendToDlq(topic, message.value.toString(), deps, {
           error: new Error(`Message TTL expired: age ${ageMs}ms`),
           attempt: 0,
           originalHeaders: envelope.headers
@@ -2369,7 +2627,7 @@ async function handleEachMessage(payload, opts, deps) {
       } else {
         const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
         await ttlHandler?.({
-          topic: topic2,
+          topic,
           ageMs,
           messageTtlMs: opts.messageTtlMs,
           headers: envelope.headers
@@ -2388,7 +2646,7 @@ async function handleEachMessage(payload, opts, deps) {
         },
         () => handleMessage(envelope)
       );
-      return timeoutMs ? wrapWithTimeout(fn, timeoutMs, topic2) : fn();
+      return timeoutMs ? wrapWithTimeout(fn, timeoutMs, topic) : fn();
     },
     {
       envelope,
@@ -2632,7 +2890,7 @@ function pauseConsumerImpl(ctx, groupId, assignments) {
   }
   consumer.pause(
     assignments.flatMap(
-      ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
+      ({ topic, partitions }) => partitions.map((p) => ({ topic, partitions: [p] }))
     )
   );
 }
@@ -2645,25 +2903,25 @@ function resumeConsumerImpl(ctx, groupId, assignments) {
   }
   consumer.resume(
     assignments.flatMap(
-      ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
+      ({ topic, partitions }) => partitions.map((p) => ({ topic, partitions: [p] }))
     )
   );
 }
-function pauseTopicAllPartitions(ctx, gid, topic2) {
+function pauseTopicAllPartitions(ctx, gid, topic) {
   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);
+  const partitions = assignment.filter((a) => a.topic === topic).map((a) => a.partition);
   if (partitions.length > 0)
-    consumer.pause(partitions.map((p) => ({ topic: topic2, partitions: [p] })));
+    consumer.pause(partitions.map((p) => ({ topic, partitions: [p] })));
 }
-function resumeTopicAllPartitions(ctx, gid, topic2) {
+function resumeTopicAllPartitions(ctx, gid, topic) {
   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);
+  const partitions = assignment.filter((a) => a.topic === topic).map((a) => a.partition);
   if (partitions.length > 0)
-    consumer.resume(partitions.map((p) => ({ topic: topic2, partitions: [p] })));
+    consumer.resume(partitions.map((p) => ({ topic, partitions: [p] })));
 }
 
 // src/client/kafka.client/consumer/start.ts
@@ -2687,7 +2945,7 @@ async function startConsumerImpl(ctx, topics, handleMessage, options = {}) {
           retry,
           retryTopics: options.retryTopics,
           timeoutMs: options.handlerTimeoutMs,
-          wrapWithTimeout: (fn, ms, topic2) => wrapWithTimeoutWarning(ctx.logger, fn, ms, topic2),
+          wrapWithTimeout: (fn, ms, topic) => wrapWithTimeoutWarning(ctx.logger, fn, ms, topic),
           deduplication: resolveDeduplicationContext(
             ctx,
             gid,
@@ -2738,7 +2996,7 @@ async function startBatchConsumerImpl(ctx, topics, handleBatch, options = {}) {
           retry,
           retryTopics: options.retryTopics,
           timeoutMs: options.handlerTimeoutMs,
-          wrapWithTimeout: (fn, ms, topic2) => wrapWithTimeoutWarning(ctx.logger, fn, ms, topic2),
+          wrapWithTimeout: (fn, ms, topic) => wrapWithTimeoutWarning(ctx.logger, fn, ms, topic),
           deduplication: resolveDeduplicationContext(
             ctx,
             gid,
@@ -2790,10 +3048,10 @@ async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}
   const txProducer = await createRetryTxProducer(ctx, `${gid}-txc`);
   const deps = messageDepsFor(ctx, gid);
   await consumer.run({
-    eachMessage: ({ topic: topic2, partition, message }) => ctx.inFlight.track(async () => {
+    eachMessage: ({ topic, partition, message }) => ctx.inFlight.track(async () => {
       const envelope = await parseSingleMessage(
         message,
-        topic2,
+        topic,
         partition,
         schemaMap,
         options.interceptors ?? [],
@@ -2803,7 +3061,7 @@ async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}
       const nextOffset = String(Number.parseInt(message.offset, 10) + 1);
       if (envelope === null) {
         await consumer.commitOffsets([
-          { topic: topic2, partition, offset: nextOffset }
+          { topic, partition, offset: nextOffset }
         ]);
         return;
       }
@@ -2843,7 +3101,7 @@ async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}
         await tx.sendOffsets({
           consumer,
           topics: [
-            { topic: topic2, partitions: [{ partition, offset: nextOffset }] }
+            { topic, partitions: [{ partition, offset: nextOffset }] }
           ]
         });
         await tx.commit();
@@ -2854,7 +3112,7 @@ async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}
         } catch {
         }
         ctx.logger.warn(
-          `startTransactionalConsumer: handler failed on ${topic2}[${partition}]@${message.offset} \u2014 tx aborted, message will be redelivered (${toError(err).message})`
+          `startTransactionalConsumer: handler failed on ${topic}[${partition}]@${message.offset} \u2014 tx aborted, message will be redelivered (${toError(err).message})`
         );
         throw err;
       }
@@ -2867,8 +3125,8 @@ function stopConsumerByGid(ctx, gid) {
   return stopConsumerImpl(ctx, gid);
 }
 
-// src/client/kafka.client/consumer/window.ts
-async function startWindowConsumerImpl(ctx, topic2, handler, options) {
+// src/client/kafka.client/consumer/features/window.ts
+async function startWindowConsumerImpl(ctx, topic, handler, options) {
   const { maxMessages, maxMs, ...consumerOptions } = options;
   if (maxMessages <= 0)
     throw new Error("startWindowConsumer: maxMessages must be > 0");
@@ -2881,6 +3139,7 @@ async function startWindowConsumerImpl(ctx, topic2, handler, options) {
   const buffer = [];
   let flushTimer = null;
   let windowStart = 0;
+  const onLost = consumerOptions.onMessageLost ?? ctx.onMessageLost;
   const flush = async (trigger) => {
     if (flushTimer !== null) {
       clearTimeout(flushTimer);
@@ -2888,22 +3147,37 @@ async function startWindowConsumerImpl(ctx, topic2, handler, options) {
     }
     if (buffer.length === 0) return;
     const envelopes = buffer.splice(0);
-    await handler(envelopes, { trigger, windowStart, windowEnd: Date.now() });
+    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;
-      flush("time").catch((err) => {
-        ctx.logger.warn(
-          `startWindowConsumer: time-triggered flush error \u2014 ${toError(err).message}`
-        );
-      });
+      void flush("time");
     }, maxMs);
   };
   const handle = await startConsumerImpl(
     ctx,
-    [topic2],
+    [topic],
     async (envelope) => {
       if (buffer.length === 0) windowStart = Date.now();
       buffer.push(envelope);
@@ -2914,40 +3188,13 @@ async function startWindowConsumerImpl(ctx, topic2, handler, options) {
   );
   const originalStop = handle.stop.bind(handle);
   handle.stop = async () => {
-    if (flushTimer !== null) {
-      clearTimeout(flushTimer);
-      flushTimer = null;
-    }
-    if (buffer.length > 0) {
-      const envelopes = buffer.splice(0);
-      await handler(envelopes, {
-        trigger: "time",
-        windowStart,
-        windowEnd: Date.now()
-      }).catch(async (err) => {
-        const error = toError(err);
-        ctx.logger.warn(
-          `startWindowConsumer: shutdown flush error \u2014 ${error.message}`
-        );
-        for (const envelope of envelopes) {
-          await Promise.resolve(
-            ctx.onMessageLost?.({
-              topic: envelope.topic,
-              error,
-              attempt: 0,
-              headers: envelope.headers
-            })
-          ).catch(() => {
-          });
-        }
-      });
-    }
+    await flush("time");
     return originalStop();
   };
   return handle;
 }
 
-// src/client/kafka.client/consumer/routed.ts
+// src/client/kafka.client/consumer/features/routed.ts
 async function startRoutedConsumerImpl(ctx, topics, routing, options) {
   const { header, routes, fallback } = routing;
   const handleMessage = async (envelope) => {
@@ -2962,15 +3209,126 @@ async function startRoutedConsumerImpl(ctx, topics, routing, options) {
   return startConsumerImpl(ctx, topics, handleMessage, options);
 }
 
-// src/client/kafka.client/consumer/snapshot.ts
-async function readSnapshotImpl(ctx, topic2, options = {}) {
+// src/client/kafka.client/consumer/features/delayed.ts
+function delayedTopicName(topic) {
+  return `${topic}.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: [
+            {
+              value: message.value.toString(),
+              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, topic, options = {}) {
   await ctx.adminOps.ensureConnected();
   let offsets;
   try {
-    offsets = await ctx.adminOps.admin.fetchTopicOffsets(topic2);
+    offsets = await ctx.adminOps.admin.fetchTopicOffsets(topic);
   } catch {
     ctx.logger.warn(
-      `readSnapshot: could not fetch offsets for "${String(topic2)}", returning empty snapshot`
+      `readSnapshot: could not fetch offsets for "${String(topic)}", returning empty snapshot`
     );
     return /* @__PURE__ */ new Map();
   }
@@ -2982,7 +3340,7 @@ async function readSnapshotImpl(ctx, topic2, options = {}) {
   }
   if (targets.size === 0) {
     ctx.logger.debug?.(
-      `readSnapshot: topic "${String(topic2)}" is empty \u2014 returning empty snapshot`
+      `readSnapshot: topic "${String(topic)}" is empty \u2014 returning empty snapshot`
     );
     return /* @__PURE__ */ new Map();
   }
@@ -3001,7 +3359,7 @@ async function readSnapshotImpl(ctx, topic2, options = {}) {
         });
       });
     };
-    consumer.connect().then(() => consumer.subscribe({ topics: [topic2] })).then(
+    consumer.connect().then(() => consumer.subscribe({ topics: [topic] })).then(
       () => consumer.run({
         eachMessage: async ({ topic: t, partition, message }) => {
           if (!remaining.has(partition)) return;
@@ -3022,7 +3380,7 @@ async function readSnapshotImpl(ctx, topic2, options = {}) {
     });
   });
   ctx.logger.log(
-    `readSnapshot: ${snapshot.size} key(s) from "${String(topic2)}"`
+    `readSnapshot: ${snapshot.size} key(s) from "${String(topic)}"`
   );
   return snapshot;
 }
@@ -3059,9 +3417,9 @@ async function checkpointOffsetsImpl(ctx, groupId, checkpointTopic) {
   await ctx.adminOps.ensureConnected();
   const committed = await ctx.adminOps.admin.fetchOffsets({ groupId: gid });
   const offsets = [];
-  for (const { topic: topic2, partitions } of committed) {
+  for (const { topic, partitions } of committed) {
     for (const { partition, offset } of partitions) {
-      offsets.push({ topic: topic2, partition, offset });
+      offsets.push({ topic, partition, offset });
     }
   }
   const savedAt = Date.now();
@@ -3228,6 +3586,7 @@ var KafkaClient = class {
    * ```
    */
   constructor(clientId, groupId, brokers, options) {
+    validateClientOptions(clientId, groupId, brokers, options);
     this.clientId = clientId;
     const logger = options?.logger ?? {
       log: (msg) => console.log(`[KafkaClient:${clientId}] ${msg}`),
@@ -3235,7 +3594,8 @@ var KafkaClient = class {
       error: (msg, ...args) => console.error(`[KafkaClient:${clientId}] ${msg}`, ...args),
       debug: (msg, ...args) => console.debug(`[KafkaClient:${clientId}] ${msg}`, ...args)
     };
-    const transport = options?.transport ?? new ConfluentTransport(clientId, brokers);
+    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();
@@ -3269,6 +3629,7 @@ var KafkaClient = class {
       numPartitions: options?.numPartitions ?? 1,
       txId: options?.transactionalId ?? `${clientId}-tx`,
       clockRecoveryTopics: options?.clockRecovery?.topics ?? [],
+      clockRecoveryTimeoutMs: options?.clockRecovery?.timeoutMs ?? 3e4,
       lagThrottleOpts: options?.lagThrottle,
       instrumentation: options?.instrumentation ?? [],
       onMessageLost: options?.onMessageLost,
@@ -3278,6 +3639,7 @@ var KafkaClient = class {
       producer,
       txProducer: void 0,
       txProducerInitPromise: void 0,
+      _txChain: Promise.resolve(),
       retryTxProducers: /* @__PURE__ */ new Map(),
       consumers,
       runningConsumers,
@@ -3326,8 +3688,8 @@ var KafkaClient = class {
     return sendMessageImpl(this.ctx, topicOrDesc, message, options);
   }
   /** @inheritDoc */
-  async sendTombstone(topic2, key, headers) {
-    return sendTombstoneImpl(this.ctx, topic2, key, headers);
+  async sendTombstone(topic, key, headers) {
+    return sendTombstoneImpl(this.ctx, topic, key, headers);
   }
   async sendBatch(topicOrDesc, messages, options) {
     return sendBatchImpl(this.ctx, topicOrDesc, messages, options);
@@ -3358,7 +3720,7 @@ var KafkaClient = class {
   }
   // ── Consumer: AsyncIterableIterator ──────────────────────────────
   /** @inheritDoc */
-  consume(topic2, options) {
+  consume(topic, options) {
     if (options?.retryTopics) {
       throw new Error(
         "consume() does not support retryTopics (EOS retry chains). Use startConsumer() with retryTopics: true for guaranteed retry delivery."
@@ -3367,11 +3729,11 @@ var KafkaClient = class {
     const gid = options?.groupId ?? this.ctx.defaultGroupId;
     const queue = new AsyncQueue(
       options?.queueHighWaterMark,
-      () => pauseTopicAllPartitions(this.ctx, gid, topic2),
-      () => resumeTopicAllPartitions(this.ctx, gid, topic2)
+      () => pauseTopicAllPartitions(this.ctx, gid, topic),
+      () => resumeTopicAllPartitions(this.ctx, gid, topic)
     );
     const handlePromise = this.startConsumer(
-      [topic2],
+      [topic],
       async (envelope) => {
         queue.push(envelope);
       },
@@ -3393,14 +3755,39 @@ var KafkaClient = class {
   }
   // ── Consumer: windowed ────────────────────────────────────────────
   /** @inheritDoc */
-  startWindowConsumer(topic2, handler, options) {
-    return startWindowConsumerImpl(this.ctx, topic2, handler, options);
+  startWindowConsumer(topic, handler, options) {
+    return startWindowConsumerImpl(this.ctx, topic, 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 = {}) {
@@ -3421,10 +3808,10 @@ var KafkaClient = class {
   }
   // ── DLQ replay ────────────────────────────────────────────────────
   /** @inheritDoc */
-  async replayDlq(topic2, options = {}) {
+  async replayDlq(topic, options = {}) {
     await this.ctx.adminOps.ensureConnected();
     return replayDlqTopic(
-      topic2,
+      topic,
       {
         logger: this.ctx.logger,
         fetchTopicOffsets: (t) => this.ctx.adminOps.admin.fetchTopicOffsets(t),
@@ -3451,8 +3838,8 @@ var KafkaClient = class {
   }
   // ── Snapshot & checkpoint ─────────────────────────────────────────
   /** @inheritDoc */
-  async readSnapshot(topic2, options = {}) {
-    return readSnapshotImpl(this.ctx, topic2, options);
+  async readSnapshot(topic, options = {}) {
+    return readSnapshotImpl(this.ctx, topic, options);
   }
   /** @inheritDoc */
   async checkpointOffsets(groupId, checkpointTopic) {
@@ -3464,8 +3851,8 @@ var KafkaClient = class {
   }
   // ── Admin ─────────────────────────────────────────────────────────
   /** @inheritDoc */
-  async resetOffsets(groupId, topic2, position) {
-    return this.ctx.adminOps.resetOffsets(groupId, topic2, position);
+  async resetOffsets(groupId, topic, position) {
+    return this.ctx.adminOps.resetOffsets(groupId, topic, position);
   }
   /** @inheritDoc */
   async seekToOffset(groupId, assignments) {
@@ -3492,26 +3879,26 @@ var KafkaClient = class {
     return this.ctx.adminOps.describeTopics(topics);
   }
   /** @inheritDoc */
-  async deleteRecords(topic2, partitions) {
-    return this.ctx.adminOps.deleteRecords(topic2, partitions);
+  async deleteRecords(topic, partitions) {
+    return this.ctx.adminOps.deleteRecords(topic, partitions);
   }
   // ── Circuit breaker ───────────────────────────────────────────────
   /** @inheritDoc */
-  getCircuitState(topic2, partition, groupId) {
+  getCircuitState(topic, partition, groupId) {
     return this.ctx.circuitBreaker.getState(
-      topic2,
+      topic,
       partition,
       groupId ?? this.ctx.defaultGroupId
     );
   }
   // ── Metrics ───────────────────────────────────────────────────────
   /** @inheritDoc */
-  getMetrics(topic2) {
-    return this.ctx.metrics.getMetrics(topic2);
+  getMetrics(topic) {
+    return this.ctx.metrics.getMetrics(topic);
   }
   /** @inheritDoc */
-  resetMetrics(topic2) {
-    this.ctx.metrics.resetMetrics(topic2);
+  resetMetrics(topic) {
+    this.ctx.metrics.resetMetrics(topic);
   }
   getClientId() {
     return this.clientId;
@@ -3542,38 +3929,351 @@ var KafkaClient = class {
   }
 };
 
-// src/client/message/topic.ts
-function topic(name) {
+// src/cli/dlq.ts
+var DLQ_SUFFIX = ".dlq";
+var DlqUsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DlqUsageError";
+  }
+};
+var USAGE = `kafka-client-dlq \u2014 dead-letter queue operations
+
+Usage:
+  kafka-client-dlq ls     --brokers <b1,b2> [--prefix <name>]
+  kafka-client-dlq peek   --brokers <b1,b2> --topic <name> [--limit <n>]
+  kafka-client-dlq replay --brokers <b1,b2> --topic <name> [--target <t>] [--dry-run] [--from-beginning | --incremental]
+
+Commands:
+  ls       List DLQ topics (ending in .dlq) with per-topic message counts.
+  peek     Print up to N messages from <topic>.dlq (offset, x-dlq-* headers, value).
+  replay   Re-publish <topic>.dlq messages to their original topic (or --target).
+
+Options:
+  --brokers <list>    Comma-separated broker addresses (required).       e.g. localhost:9092
+  --prefix <name>     ls: only show DLQ topics whose base name starts with <name>.
+  --topic <name>      peek/replay: base topic name (the CLI uses <name>.dlq).
+  --limit <n>         peek: max messages to print (default 10).
+  --target <t>        replay: override destination topic.
+  --dry-run           replay: log without publishing.
+  --from-beginning    replay: full replay every call (default).
+  --incremental       replay: only messages added since the previous replay.
+  -h, --help          Show this help.
+
+Examples:
+  kafka-client-dlq ls --brokers localhost:9092
+  kafka-client-dlq ls --brokers localhost:9092 --prefix orders
+  kafka-client-dlq peek --brokers localhost:9092 --topic orders.created --limit 5
+  kafka-client-dlq replay --brokers localhost:9092 --topic orders.created --dry-run
+  kafka-client-dlq replay --brokers localhost:9092 --topic orders.created --target orders.manual --incremental
+`;
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--brokers",
+  "--prefix",
+  "--topic",
+  "--limit",
+  "--target"
+]);
+var BOOL_FLAGS = /* @__PURE__ */ new Set(["--dry-run", "--from-beginning", "--incremental"]);
+function parseFlags(args) {
+  const values = {};
+  const bools = /* @__PURE__ */ new Set();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      throw new DlqUsageError(`Unexpected argument: "${arg}"`);
+    }
+    if (VALUE_FLAGS.has(arg)) {
+      const value = args[i + 1];
+      if (value === void 0 || value.startsWith("--")) {
+        throw new DlqUsageError(`Flag "${arg}" requires a value.`);
+      }
+      values[arg] = value;
+      i++;
+    } else if (BOOL_FLAGS.has(arg)) {
+      bools.add(arg);
+    } else {
+      throw new DlqUsageError(`Unknown flag: "${arg}"`);
+    }
+  }
+  return { values, bools };
+}
+function requireBrokers(flags) {
+  const raw = flags.values["--brokers"];
+  if (raw === void 0) {
+    throw new DlqUsageError("Missing required flag: --brokers");
+  }
+  const brokers = raw.split(",").map((b) => b.trim()).filter((b) => b.length > 0);
+  if (brokers.length === 0) {
+    throw new DlqUsageError("--brokers must list at least one broker address.");
+  }
+  return brokers;
+}
+function requireTopic(flags) {
+  const topic = flags.values["--topic"];
+  if (topic === void 0 || topic.length === 0) {
+    throw new DlqUsageError("Missing required flag: --topic");
+  }
+  return topic;
+}
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "-h" || command === "--help" || command === "help") {
+    return { command: "help" };
+  }
+  switch (command) {
+    case "ls": {
+      const flags = parseFlags(rest);
+      const brokers = requireBrokers(flags);
+      const prefix = flags.values["--prefix"];
+      return { command: "ls", brokers, prefix };
+    }
+    case "peek": {
+      const flags = parseFlags(rest);
+      const brokers = requireBrokers(flags);
+      const topic = requireTopic(flags);
+      const limit = parseLimit(flags.values["--limit"]);
+      return { command: "peek", brokers, topic, limit };
+    }
+    case "replay": {
+      const flags = parseFlags(rest);
+      const brokers = requireBrokers(flags);
+      const topic = requireTopic(flags);
+      const target = flags.values["--target"];
+      const dryRun = flags.bools.has("--dry-run");
+      if (flags.bools.has("--from-beginning") && flags.bools.has("--incremental")) {
+        throw new DlqUsageError(
+          "--from-beginning and --incremental are mutually exclusive."
+        );
+      }
+      const fromBeginning = !flags.bools.has("--incremental");
+      return { command: "replay", brokers, topic, target, dryRun, fromBeginning };
+    }
+    default:
+      throw new DlqUsageError(`Unknown command: "${command}"`);
+  }
+}
+function parseLimit(raw) {
+  if (raw === void 0) return 10;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new DlqUsageError(`--limit must be a positive integer, got "${raw}".`);
+  }
+  return n;
+}
+function countFromWatermarks(watermarks) {
+  let total = 0;
+  for (const { low, high } of watermarks) {
+    const width = Number(high) - Number(low);
+    total += width > 0 ? width : 0;
+  }
+  return total;
+}
+function truncate(value, max = 200) {
+  if (value.length <= max) return value;
+  return `${value.slice(0, max)}\u2026 (${value.length} chars)`;
+}
+async function runDlqCommand(cmd, deps) {
+  if (cmd.command === "help") {
+    deps.out(USAGE);
+    return { command: "help" };
+  }
+  const client = await deps.createClient(cmd.brokers);
+  try {
+    switch (cmd.command) {
+      case "ls":
+        return await runLs(cmd, client, deps);
+      case "peek":
+        return await runPeek(cmd, client, deps);
+      case "replay":
+        return await runReplay(cmd, client, deps);
+    }
+  } finally {
+    await client.close();
+  }
+}
+async function runLs(cmd, client, deps) {
+  const allTopics = await client.listTopics();
+  let dlqTopics = allTopics.filter((t) => t.endsWith(DLQ_SUFFIX));
+  if (cmd.prefix) {
+    const prefix = cmd.prefix;
+    dlqTopics = dlqTopics.filter(
+      (t) => t.slice(0, -DLQ_SUFFIX.length).startsWith(prefix)
+    );
+  }
+  dlqTopics.sort();
+  const counts = [];
+  for (const dlqTopic of dlqTopics) {
+    const watermarks = await client.fetchTopicOffsets(dlqTopic);
+    counts.push({
+      dlqTopic,
+      baseTopic: dlqTopic.slice(0, -DLQ_SUFFIX.length),
+      count: countFromWatermarks(watermarks)
+    });
+  }
+  if (counts.length === 0) {
+    deps.out(
+      cmd.prefix ? `No DLQ topics found matching prefix "${cmd.prefix}".` : "No DLQ topics found."
+    );
+  } else {
+    const width = Math.max(...counts.map((c) => c.dlqTopic.length));
+    deps.out(`${"TOPIC".padEnd(width)}  MESSAGES`);
+    for (const c of counts) {
+      deps.out(`${c.dlqTopic.padEnd(width)}  ${c.count}`);
+    }
+    const total = counts.reduce((s, c) => s + c.count, 0);
+    deps.out(`${counts.length} DLQ topic(s), ${total} message(s) total.`);
+  }
+  return { command: "ls", topics: counts };
+}
+async function runPeek(cmd, client, deps) {
+  const dlqTopic = `${cmd.topic}${DLQ_SUFFIX}`;
+  const messages = await client.peekMessages(dlqTopic, cmd.limit);
+  if (messages.length === 0) {
+    deps.out(`No messages in ${dlqTopic}.`);
+    return { command: "peek", printed: 0 };
+  }
+  deps.out(`Peeking up to ${cmd.limit} message(s) from ${dlqTopic}:`);
+  let printed = 0;
+  for (const env of messages) {
+    if (printed >= cmd.limit) break;
+    deps.out("");
+    deps.out(
+      `\u2500 offset ${env.offset} \xB7 partition ${env.partition} \xB7 ${env.timestamp}`
+    );
+    const dlqHeaders = Object.entries(env.headers).filter(([k]) => k.startsWith("x-dlq-")).sort(([a], [b]) => a.localeCompare(b));
+    for (const [k, v] of dlqHeaders) {
+      deps.out(`    ${k}: ${truncate(String(v), 500)}`);
+    }
+    deps.out(`    value: ${truncate(JSON.stringify(env.payload))}`);
+    printed++;
+  }
+  deps.out("");
+  deps.out(`Printed ${printed} message(s).`);
+  return { command: "peek", printed };
+}
+async function runReplay(cmd, client, deps) {
+  const options = {
+    dryRun: cmd.dryRun,
+    fromBeginning: cmd.fromBeginning
+  };
+  if (cmd.target !== void 0) options.targetTopic = cmd.target;
+  const mode = cmd.fromBeginning ? "full" : "incremental";
+  const targetDesc = cmd.target ? ` \u2192 ${cmd.target}` : " \u2192 original topic";
+  deps.out(
+    `Replaying ${cmd.topic}${DLQ_SUFFIX}${targetDesc} (${mode}${cmd.dryRun ? ", dry-run" : ""})\u2026`
+  );
+  const { replayed, skipped } = await client.replayDlq(cmd.topic, options);
+  deps.out(
+    cmd.dryRun ? `Dry-run: ${replayed} message(s) would be replayed, ${skipped} skipped.` : `Replayed ${replayed} message(s), ${skipped} skipped.`
+  );
+  return { command: "replay", replayed, skipped, dryRun: cmd.dryRun };
+}
+
+// src/cli/index.ts
+var CLIENT_ID = `dlq-cli-${process.pid}`;
+var GROUP_ID = `${CLIENT_ID}-peek`;
+function createRealClient(brokers) {
+  const transport = new ConfluentTransport(CLIENT_ID, brokers);
+  const kafka = new KafkaClient(
+    CLIENT_ID,
+    GROUP_ID,
+    brokers,
+    { transport, autoCreateTopics: false, strictSchemas: false }
+  );
+  const admin = transport.admin();
+  let adminConnected = false;
+  async function ensureAdmin() {
+    if (!adminConnected) {
+      await admin.connect();
+      adminConnected = true;
+    }
+  }
   return {
-    /** Provide an explicit message type without a runtime schema. */
-    type: () => ({
-      __topic: name,
-      __type: void 0
-    }),
-    schema: (schema) => ({
-      __topic: name,
-      __type: void 0,
-      __schema: schema
-    })
+    async listTopics() {
+      const status = await kafka.checkStatus();
+      if (status.status === "down") {
+        throw new Error(`Broker unreachable: ${status.error}`);
+      }
+      return status.topics;
+    },
+    async fetchTopicOffsets(topic) {
+      await ensureAdmin();
+      return admin.fetchTopicOffsets(topic);
+    },
+    async peekMessages(dlqTopic, limit) {
+      const collected = [];
+      const iterator = kafka.consume(dlqTopic, {
+        groupId: `${dlqTopic}.dlq-peek-${Date.now()}`,
+        fromBeginning: true
+      });
+      await ensureAdmin();
+      const watermarks = await admin.fetchTopicOffsets(dlqTopic);
+      const available = watermarks.reduce(
+        (sum, w) => sum + Math.max(0, Number(w.high) - Number(w.low)),
+        0
+      );
+      const target = Math.min(limit, available);
+      if (target === 0) {
+        await iterator.return?.();
+        return collected;
+      }
+      try {
+        for await (const env of iterator) {
+          collected.push(env);
+          if (collected.length >= target) break;
+        }
+      } finally {
+        await iterator.return?.();
+      }
+      return collected;
+    },
+    replayDlq(topic, options) {
+      return kafka.replayDlq(topic, options);
+    },
+    async close() {
+      if (adminConnected) {
+        await admin.disconnect().catch(() => {
+        });
+      }
+      await kafka.disconnect().catch(() => {
+      });
+    }
   };
 }
+async function main() {
+  let cmd;
+  try {
+    cmd = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof DlqUsageError) {
+      process.stderr.write(`Error: ${err.message}
 
-export {
-  HEADER_EVENT_ID,
-  HEADER_CORRELATION_ID,
-  HEADER_TIMESTAMP,
-  HEADER_SCHEMA_VERSION,
-  HEADER_TRACEPARENT,
-  HEADER_LAMPORT_CLOCK,
-  getEnvelopeContext,
-  runWithEnvelopeContext,
-  buildEnvelopeHeaders,
-  decodeHeaders,
-  extractEnvelope,
-  KafkaProcessingError,
-  KafkaValidationError,
-  KafkaRetryExhaustedError,
-  KafkaClient,
-  topic
-};
-//# sourceMappingURL=chunk-SM4FZKAZ.mjs.map
+`);
+      process.stderr.write(USAGE);
+      return 2;
+    }
+    throw err;
+  }
+  try {
+    await runDlqCommand(cmd, {
+      createClient: createRealClient,
+      out: (line) => process.stdout.write(`${line}
+`)
+    });
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Error: ${message}
+`);
+    return 1;
+  }
+}
+main().then((code) => {
+  process.exitCode = code;
+}).catch((err) => {
+  process.stderr.write(`Fatal: ${err?.stack ?? err}
+`);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map