@drarzter/kafka-client 0.9.4 → 0.11.0

package/dist/index.js

@@ -29,13 +29,19 @@ var __decorateParam = (index, decorator) => (target, key) => decorator(target, k
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ConfluentTransport: () => ConfluentTransport,
   HEADER_CORRELATION_ID: () => HEADER_CORRELATION_ID,
+  HEADER_DELAYED_TARGET: () => HEADER_DELAYED_TARGET,
+  HEADER_DELAYED_UNTIL: () => HEADER_DELAYED_UNTIL,
   HEADER_EVENT_ID: () => HEADER_EVENT_ID,
   HEADER_LAMPORT_CLOCK: () => HEADER_LAMPORT_CLOCK,
   HEADER_SCHEMA_VERSION: () => HEADER_SCHEMA_VERSION,
   HEADER_TIMESTAMP: () => HEADER_TIMESTAMP,
   HEADER_TRACEPARENT: () => HEADER_TRACEPARENT,
+  InMemoryDedupStore: () => InMemoryDedupStore,
+  InMemoryOutboxStore: () => InMemoryOutboxStore,
   InjectKafkaClient: () => InjectKafkaClient,
+  JsonSerde: () => JsonSerde,
   KAFKA_CLIENT: () => KAFKA_CLIENT,
   KAFKA_SUBSCRIBER_METADATA: () => KAFKA_SUBSCRIBER_METADATA,
   KafkaClient: () => KafkaClient,
@@ -45,24 +51,39 @@ __export(index_exports, {
   KafkaProcessingError: () => KafkaProcessingError,
   KafkaRetryExhaustedError: () => KafkaRetryExhaustedError,
   KafkaValidationError: () => KafkaValidationError,
+  SchemaRegistryClient: () => SchemaRegistryClient,
   SubscribeTo: () => SubscribeTo,
+  awsMskIamProvider: () => awsMskIamProvider,
   buildEnvelopeHeaders: () => buildEnvelopeHeaders,
+  consumerOptionsFromEnv: () => consumerOptionsFromEnv,
   decodeHeaders: () => decodeHeaders,
+  describeRequiredAcls: () => describeRequiredAcls,
   extractEnvelope: () => extractEnvelope,
+  gcpAccessTokenProvider: () => gcpAccessTokenProvider,
   getEnvelopeContext: () => getEnvelopeContext,
   getKafkaClientToken: () => getKafkaClientToken,
+  kafkaClientConfigFromEnv: () => kafkaClientConfigFromEnv,
+  mergeConsumerOptions: () => mergeConsumerOptions,
+  registrySchema: () => registrySchema,
+  resolveSecurityOptions: () => resolveSecurityOptions,
   runWithEnvelopeContext: () => runWithEnvelopeContext,
-  topic: () => topic
+  startOutboxRelay: () => startOutboxRelay,
+  toError: () => toError,
+  toKafkaAclCommands: () => toKafkaAclCommands,
+  toMskIamPolicy: () => toMskIamPolicy,
+  topic: () => topic,
+  versionedSchema: () => versionedSchema
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/client/kafka.client/confluent-transport.ts
+// 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);
   }
@@ -84,10 +105,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) {
@@ -102,6 +130,7 @@ var ConfluentConsumer = class {
   constructor(consumer) {
     this.consumer = consumer;
   }
+  consumer;
   /** Returns the underlying KafkaJS.Consumer — used by ConfluentTransaction.sendOffsets. */
   getNative() {
     return this.consumer;
@@ -141,6 +170,7 @@ var ConfluentAdmin = class {
   constructor(admin) {
     this.admin = admin;
   }
+  admin;
   async connect() {
     await this.admin.connect();
   }
@@ -154,7 +184,7 @@ var ConfluentAdmin = class {
     return this.admin.fetchTopicOffsets(topic2);
   }
   async fetchTopicOffsetsByTimestamp(topic2, timestamp) {
-    return this.admin.fetchTopicOffsetsByTime(topic2, timestamp);
+    return this.admin.fetchTopicOffsetsByTimestamp(topic2, timestamp);
   }
   async fetchOffsets(options) {
     return this.admin.fetchOffsets(options);
@@ -180,10 +210,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({
@@ -210,6 +259,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) => {
@@ -227,6 +279,37 @@ var ConfluentTransport = class {
   }
 };
 
+// src/client/message/serde.ts
+var JsonSerde = class {
+  /** JSON-stringify the validated payload. Returns a UTF-8 string. */
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  /** JSON-parse UTF-8 wire bytes into an object. */
+  deserialize(data) {
+    return JSON.parse(data.toString("utf8"));
+  }
+};
+
+// 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
 var import_node_async_hooks = require("async_hooks");
 var import_node_crypto = require("crypto");
@@ -236,6 +319,8 @@ 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 import_node_async_hooks.AsyncLocalStorage();
 function getEnvelopeContext() {
   return envelopeStorage.getStore();
@@ -290,6 +375,9 @@ 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) {
     super(message, options);
@@ -298,6 +386,8 @@ var KafkaProcessingError = class extends Error {
     this.name = "KafkaProcessingError";
     if (options?.cause) this.cause = options.cause;
   }
+  topic;
+  originalMessage;
 };
 var KafkaValidationError = class extends Error {
   constructor(topic2, originalMessage, options) {
@@ -307,6 +397,8 @@ var KafkaValidationError = class extends Error {
     this.name = "KafkaValidationError";
     if (options?.cause) this.cause = options.cause;
   }
+  topic;
+  originalMessage;
 };
 var KafkaRetryExhaustedError = class extends KafkaProcessingError {
   constructor(topic2, originalMessage, attempts, options) {
@@ -319,9 +411,13 @@ var KafkaRetryExhaustedError = class extends KafkaProcessingError {
     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) {
@@ -368,6 +464,7 @@ async function validateMessage(topicOrDesc, message, deps, ctx) {
 }
 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({
@@ -387,11 +484,16 @@ async function buildSendPayload(topicOrDesc, messages, deps, compression) {
         headers: envelopeHeaders,
         version: m.schemaVersion ?? 1
       };
+      const validated = await validateMessage(topicOrDesc, m.value, deps, sendCtx);
       return {
-        value: JSON.stringify(
-          await validateMessage(topicOrDesc, m.value, deps, sendCtx)
-        ),
-        key: m.key ?? null,
+        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
       };
     })
@@ -400,7 +502,7 @@ async function buildSendPayload(topicOrDesc, messages, deps, 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);
@@ -433,6 +535,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();
@@ -472,12 +575,22 @@ function buildSchemaMap(topics, schemaRegistry, optionSchemas, logger) {
   }
   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() {
@@ -584,7 +697,10 @@ var AdminOps = class {
           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(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 });
@@ -665,7 +781,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
         ),
@@ -749,23 +866,9 @@ 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) {
-  try {
-    return JSON.parse(raw);
-  } catch (error) {
-    logger.error(
-      `Failed to parse message from topic ${topic2}:`,
-      toError(error).stack
-    );
-    return null;
-  }
-}
 async function validateWithSchema(message, raw, topic2, schemaMap, interceptors, dlq, deps) {
   const schema = schemaMap.get(topic2);
   if (!schema) return message;
@@ -1035,6 +1138,7 @@ 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,
@@ -1119,8 +1223,13 @@ async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
   }
 }
 
-// src/client/kafka.client/consumer/dlq-replay.ts
+// 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(
@@ -1152,15 +1261,15 @@ async function replayDlqTopic(topic2, deps, options = {}) {
           const originalHeaders = Object.fromEntries(
             Object.entries(headers).filter(([k]) => !deps.dlqHeaderKeys.has(k))
           );
-          const value = message.value.toString();
-          const shouldProcess = !options.filter || options.filter(headers, value);
+          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, headers: originalHeaders }]);
+            await deps.send(targetTopic, [{ value: bytes, headers: originalHeaders }]);
             replayed++;
           }
           const allDone = Array.from(highWatermarks.entries()).every(
@@ -1186,6 +1295,7 @@ var MetricsManager = class {
   constructor(deps) {
     this.deps = deps;
   }
+  deps;
   topicMetrics = /* @__PURE__ */ new Map();
   metricsFor(topic2) {
     let m = this.topicMetrics.get(topic2);
@@ -1211,16 +1321,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.
@@ -1279,6 +1398,7 @@ var InFlightTracker = class {
   constructor(warn) {
     this.warn = warn;
   }
+  warn;
   inFlightTotal = 0;
   drainResolvers = [];
   /**
@@ -1289,10 +1409,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.
@@ -1326,6 +1452,7 @@ var CircuitBreakerManager = class {
   constructor(deps) {
     this.deps = deps;
   }
+  deps;
   states = /* @__PURE__ */ new Map();
   configs = /* @__PURE__ */ new Map();
   /**
@@ -1470,6 +1597,9 @@ var AsyncQueue = class {
     this.onFull = onFull;
     this.onDrained = onDrained;
   }
+  highWaterMark;
+  onFull;
+  onDrained;
   items = [];
   waiting = [];
   closed = false;
@@ -1481,6 +1611,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 {
@@ -1531,6 +1662,101 @@ 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) {
@@ -1664,6 +1890,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(() => {
@@ -1671,6 +1898,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))
@@ -1691,13 +1928,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);
     });
@@ -1738,6 +1980,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(
@@ -1755,6 +2006,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);
 }
@@ -1766,6 +2020,9 @@ 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);
 }
@@ -1802,6 +2059,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 = {
@@ -1875,7 +2143,7 @@ async function waitForPartitionAssignment(consumer, topics, logger, timeoutMs =
     `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) {
+async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopics, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs, serdeMap) {
   const {
     logger,
     producer,
@@ -1921,20 +2189,35 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
         await sleep(remaining);
         consumer.resume([{ topic: levelTopic, partitions: [partition] }]);
       }
-      const raw = message.value.toString();
-      const parsed = parseJsonMessage(raw, levelTopic, logger);
-      if (parsed === null) {
-        await consumer.commitOffsets([nextOffset]);
-        return;
-      }
+      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,
-        raw,
+        rawBytes,
         originalTopic,
         schemaMap,
         interceptors,
@@ -1969,6 +2252,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,
@@ -1987,7 +2271,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
         const delay = Math.floor(Math.random() * cap);
         const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
           originalTopic,
-          [raw],
+          [rawBytes],
           nextLevel,
           currentMaxRetries,
           delay,
@@ -2029,7 +2313,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
       } else if (dlq) {
         const { topic: dTopic, messages: dMsgs } = buildDlqPayload(
           originalTopic,
-          raw,
+          rawBytes,
           {
             error,
             // +1 to account for the main consumer's initial attempt before routing.
@@ -2091,7 +2375,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
     `Retry level ${level}/${retry.maxRetries} consumer started for: ${originalTopics.join(", ")} (group: ${levelGroupId})`
   );
 }
-async function startRetryTopicConsumers(originalTopics, originalGroupId, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs) {
+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) => {
@@ -2109,7 +2393,8 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
         interceptors,
         schemaMap,
         deps,
-        assignmentTimeoutMs
+        assignmentTimeoutMs,
+        serdeMap
       );
       levelGroupIds[i] = levelGroupId;
     })
@@ -2184,7 +2469,8 @@ async function setupConsumer(ctx, topics, mode, options) {
     options.autoCommit ?? true,
     ctx.consumerOpsDeps,
     options.partitionAssigner,
-    resolveReady
+    resolveReady,
+    options.groupInstanceId
   );
   const schemaMap = buildSchemaMap(
     stringTopics,
@@ -2192,10 +2478,14 @@ async function setupConsumer(ctx, topics, mode, options) {
     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,
@@ -2206,19 +2496,19 @@ async function setupConsumer(ctx, topics, mode, options) {
   ctx.logger.log(
     `${mode === "eachBatch" ? "Batch consumer" : "Consumer"} subscribed to topics: ${displayTopics}`
   );
-  return { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry, hasRegex, readyPromise };
+  return { consumer, schemaMap, serdeMap, topicNames, gid, dlq, interceptors, retry, hasRegex, readyPromise };
 }
 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);
   return {
     logger: ctx.logger,
     producer: ctx.producer,
+    serde: ctx.serde,
     instrumentation: ctx.instrumentation,
     onMessageLost: options?.onMessageLost ?? ctx.onMessageLost,
     onTtlExpired: ctx.onTtlExpired,
@@ -2226,15 +2516,17 @@ 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) {
   return {
     logger: ctx.logger,
     producer: ctx.producer,
+    serde: ctx.serde,
     instrumentation: ctx.instrumentation,
     onMessageLost: ctx.onMessageLost,
     onRetry: ctx.metrics.notifyRetry.bind(ctx.metrics),
@@ -2252,7 +2544,7 @@ async function makeEosMainContext(ctx, gid, consumer, options) {
   return { txProducer, consumer };
 }
 async function launchRetryChain(ctx, gid, topicNames, handleMessage, opts) {
-  const { retry, dlq, interceptors, schemaMap, assignmentTimeoutMs } = opts;
+  const { retry, dlq, interceptors, schemaMap, serdeMap, assignmentTimeoutMs } = opts;
   if (!ctx.autoCreateTopicsEnabled) {
     await ctx.adminOps.validateRetryTopicsExist(topicNames, retry.maxRetries);
   }
@@ -2267,11 +2559,17 @@ 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);
       }
     },
-    assignmentTimeoutMs
+    assignmentTimeoutMs,
+    serdeMap
   );
 }
 
@@ -2282,7 +2580,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,
@@ -2312,21 +2618,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, topic2, partition, schemaMap, interceptors, dlq, deps, serdeMap) {
   if (!message.value) {
     deps.logger.warn(`Received empty message from topic ${topic2}`);
     return null;
   }
-  const raw = message.value.toString();
-  const parsed = parseJsonMessage(raw, topic2, deps.logger);
-  if (parsed === null) 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,
-    raw,
+    // Forward the ORIGINAL bytes to DLQ on validation failure (binary-safe).
+    bytes,
     topic2,
     schemaMap,
     interceptors,
@@ -2340,6 +2663,7 @@ async function handleEachMessage(payload, opts, deps) {
   const { topic: topic2, partition, message } = payload;
   const {
     schemaMap,
+    serdeMap,
     handleMessage,
     interceptors,
     dlq,
@@ -2348,6 +2672,7 @@ async function handleEachMessage(payload, opts, deps) {
     timeoutMs,
     wrapWithTimeout
   } = opts;
+  const rawBytes = message.value;
   const eos = opts.eosMainContext;
   const nextOffsetStr = (parseInt(message.offset, 10) + 1).toString();
   const commitOffset = eos ? async () => {
@@ -2392,7 +2717,8 @@ async function handleEachMessage(payload, opts, deps) {
     schemaMap,
     interceptors,
     dlq,
-    deps
+    deps,
+    serdeMap
   );
   if (envelope === null) {
     await commitOffset?.();
@@ -2401,7 +2727,7 @@ async function handleEachMessage(payload, opts, deps) {
   if (opts.deduplication) {
     const isDuplicate = await applyDeduplication(
       envelope,
-      message.value.toString(),
+      rawBytes,
       opts.deduplication,
       dlq,
       deps
@@ -2418,7 +2744,7 @@ async function handleEachMessage(payload, opts, deps) {
         `[KafkaClient] TTL expired on ${topic2}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
       );
       if (dlq) {
-        await sendToDlq(topic2, message.value.toString(), deps, {
+        await sendToDlq(topic2, rawBytes, deps, {
           error: new Error(`Message TTL expired: age ${ageMs}ms`),
           attempt: 0,
           originalHeaders: envelope.headers
@@ -2450,7 +2776,7 @@ async function handleEachMessage(payload, opts, deps) {
     },
     {
       envelope,
-      rawMessages: [message.value.toString()],
+      rawMessages: [rawBytes],
       interceptors,
       dlq,
       retry,
@@ -2463,6 +2789,7 @@ async function handleEachBatch(payload, opts, deps) {
   const { batch, heartbeat, resolveOffset, commitOffsetsIfNecessary } = payload;
   const {
     schemaMap,
+    serdeMap,
     handleBatch,
     interceptors,
     dlq,
@@ -2518,6 +2845,7 @@ async function handleEachBatch(payload, opts, deps) {
   const envelopes = [];
   const rawMessages = [];
   for (const message of batch.messages) {
+    const rawBytes = message.value;
     const envelope = await parseSingleMessage(
       message,
       batch.topic,
@@ -2525,14 +2853,14 @@ async function handleEachBatch(payload, opts, deps) {
       schemaMap,
       interceptors,
       dlq,
-      deps
+      deps,
+      serdeMap
     );
     if (envelope === null) continue;
     if (opts.deduplication) {
-      const raw = message.value.toString();
       const isDuplicate = await applyDeduplication(
         envelope,
-        raw,
+        rawBytes,
         opts.deduplication,
         dlq,
         deps
@@ -2546,7 +2874,7 @@ async function handleEachBatch(payload, opts, deps) {
           `[KafkaClient] TTL expired on ${batch.topic}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
         );
         if (dlq) {
-          await sendToDlq(batch.topic, message.value.toString(), deps, {
+          await sendToDlq(batch.topic, rawBytes, deps, {
             error: new Error(`Message TTL expired: age ${ageMs}ms`),
             attempt: 0,
             originalHeaders: envelope.headers
@@ -2565,7 +2893,7 @@ async function handleEachBatch(payload, opts, deps) {
       }
     }
     envelopes.push(envelope);
-    rawMessages.push(message.value.toString());
+    rawMessages.push(rawBytes);
   }
   if (envelopes.length === 0) {
     await commitBatchOffset?.();
@@ -2728,7 +3056,7 @@ function resumeTopicAllPartitions(ctx, gid, topic2) {
 async function startConsumerImpl(ctx, topics, handleMessage, options = {}) {
   validateTopicConsumerOpts(topics, options);
   const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
-  const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry, readyPromise } = await setupConsumer(ctx, topics, "eachMessage", setupOptions);
+  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);
@@ -2739,6 +3067,7 @@ async function startConsumerImpl(ctx, topics, handleMessage, options = {}) {
         payload,
         {
           schemaMap,
+          serdeMap,
           handleMessage,
           interceptors,
           dlq,
@@ -2766,6 +3095,7 @@ async function startConsumerImpl(ctx, topics, handleMessage, options = {}) {
       dlq,
       interceptors,
       schemaMap,
+      serdeMap,
       assignmentTimeoutMs: options.retryTopicAssignmentTimeoutMs
     });
   }
@@ -2779,7 +3109,7 @@ async function startBatchConsumerImpl(ctx, topics, handleBatch, options = {}) {
     );
   }
   const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
-  const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry, readyPromise } = await setupConsumer(ctx, topics, "eachBatch", setupOptions);
+  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);
@@ -2790,6 +3120,7 @@ async function startBatchConsumerImpl(ctx, topics, handleBatch, options = {}) {
         payload,
         {
           schemaMap,
+          serdeMap,
           handleBatch,
           interceptors,
           dlq,
@@ -2827,6 +3158,7 @@ async function startBatchConsumerImpl(ctx, topics, handleBatch, options = {}) {
       dlq,
       interceptors,
       schemaMap,
+      serdeMap,
       assignmentTimeoutMs: options.retryTopicAssignmentTimeoutMs
     });
   }
@@ -2839,7 +3171,7 @@ async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}
     );
   }
   const setupOptions = { ...options, autoCommit: false };
-  const { consumer, schemaMap, gid, readyPromise } = await setupConsumer(
+  const { consumer, schemaMap, serdeMap, gid, readyPromise } = await setupConsumer(
     ctx,
     topics,
     "eachMessage",
@@ -2856,7 +3188,8 @@ async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}
         schemaMap,
         options.interceptors ?? [],
         false,
-        deps
+        deps,
+        serdeMap
       );
       const nextOffset = String(Number.parseInt(message.offset, 10) + 1);
       if (envelope === null) {
@@ -2925,7 +3258,7 @@ function stopConsumerByGid(ctx, gid) {
   return stopConsumerImpl(ctx, gid);
 }
 
-// src/client/kafka.client/consumer/window.ts
+// src/client/kafka.client/consumer/features/window.ts
 async function startWindowConsumerImpl(ctx, topic2, handler, options) {
   const { maxMessages, maxMs, ...consumerOptions } = options;
   if (maxMessages <= 0)
@@ -2939,6 +3272,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);
@@ -2946,17 +3280,32 @@ 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(
@@ -2972,40 +3321,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) => {
@@ -3020,7 +3342,120 @@ async function startRoutedConsumerImpl(ctx, topics, routing, options) {
   return startConsumerImpl(ctx, topics, handleMessage, options);
 }
 
-// src/client/kafka.client/consumer/snapshot.ts
+// 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;
@@ -3286,6 +3721,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}`),
@@ -3293,12 +3729,14 @@ 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();
     const consumerCreationOptions = /* @__PURE__ */ new Map();
     const schemaRegistry = /* @__PURE__ */ new Map();
+    const serde = options?.serde ?? new JsonSerde();
     const adminOps = new AdminOps({
       admin: transport.admin(),
       logger,
@@ -3325,8 +3763,10 @@ var KafkaClient = class {
       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,
@@ -3336,6 +3776,7 @@ var KafkaClient = class {
       producer,
       txProducer: void 0,
       txProducerInitPromise: void 0,
+      _txChain: Promise.resolve(),
       retryTxProducers: /* @__PURE__ */ new Map(),
       consumers,
       runningConsumers,
@@ -3357,6 +3798,7 @@ var KafkaClient = class {
         strictSchemasEnabled: options?.strictSchemas ?? true,
         instrumentation: options?.instrumentation ?? [],
         logger,
+        serde,
         nextLamportClock: () => 0
         // patched below
       },
@@ -3375,6 +3817,7 @@ var KafkaClient = class {
       strictSchemasEnabled: options?.strictSchemas ?? true,
       instrumentation: options?.instrumentation ?? [],
       logger,
+      serde,
       nextLamportClock: () => ++ctx._lamportClock
     };
     ctx.retryTopicDeps = buildRetryTopicDeps(ctx);
@@ -3459,6 +3902,31 @@ var KafkaClient = class {
   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 = {}) {
@@ -3604,17 +4072,872 @@ var KafkaClient = class {
 function topic(name) {
   return {
     /** Provide an explicit message type without a runtime schema. */
-    type: () => ({
+    type: () => keyable({
       __topic: name,
       __type: void 0
     }),
-    schema: (schema) => ({
+    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/message/schema-registry.ts
+var SchemaRegistryClient = class {
+  constructor(options) {
+    this.options = options;
+    if (!options.baseUrl) {
+      throw new Error("SchemaRegistryClient: baseUrl is required");
+    }
+    this.fetchFn = options.fetchFn ?? fetch;
+    this.cacheTtlMs = options.cacheTtlMs ?? 3e5;
+  }
+  options;
+  fetchFn;
+  cacheTtlMs;
+  latestCache = /* @__PURE__ */ new Map();
+  /**
+   * `id → schema` cache. Schema ids are immutable in a Confluent-compatible
+   * registry (a given id always maps to the same schema string), so entries
+   * are cached for the lifetime of the client with no TTL.
+   */
+  byIdCache = /* @__PURE__ */ new Map();
+  headers() {
+    const h = {
+      "Content-Type": "application/vnd.schemaregistry.v1+json"
+    };
+    if (this.options.auth) {
+      const { username, password } = this.options.auth;
+      h["Authorization"] = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+    }
+    return h;
+  }
+  async request(method, path, body) {
+    const url = `${this.options.baseUrl.replace(/\/$/, "")}${path}`;
+    const res = await this.fetchFn(url, {
+      method,
+      headers: this.headers(),
+      ...body !== void 0 && { body: JSON.stringify(body) }
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `SchemaRegistry ${method} ${path} failed: ${res.status} ${res.statusText}${text ? ` \u2014 ${text}` : ""}`
+      );
+    }
+    return await res.json();
+  }
+  /** Fetch the latest schema registered under `subject`. Cached for `cacheTtlMs`. */
+  async getLatestSchema(subject) {
+    const cached = this.latestCache.get(subject);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    const raw = await this.request("GET", `/subjects/${encodeURIComponent(subject)}/versions/latest`);
+    const value = {
+      id: raw.id,
+      version: raw.version,
+      schema: raw.schema
+    };
+    this.latestCache.set(subject, {
+      value,
+      expiresAt: Date.now() + this.cacheTtlMs
+    });
+    return value;
+  }
+  /**
+   * Fetch a schema by its globally unique registry id (`GET /schemas/ids/{id}`).
+   *
+   * Used by the Avro/Protobuf serdes on the deserialize path: the writer schema
+   * id is read from the Confluent wire-format prefix, then resolved here. Results
+   * are cached forever (schema ids are immutable), so a given id triggers exactly
+   * one registry round-trip regardless of how many messages reference it.
+   */
+  async getSchemaById(id) {
+    const cached = this.byIdCache.get(id);
+    if (cached) return cached;
+    const raw = await this.request(
+      "GET",
+      `/schemas/ids/${id}`
+    );
+    const value = { id, schema: raw.schema, schemaType: raw.schemaType };
+    this.byIdCache.set(id, value);
+    return value;
+  }
+  /** Fetch a specific schema version of a subject. */
+  async getSchemaVersion(subject, version) {
+    const raw = await this.request(
+      "GET",
+      `/subjects/${encodeURIComponent(subject)}/versions/${version}`
+    );
+    return { id: raw.id, version: raw.version, schema: raw.schema };
+  }
+  /**
+   * Register a schema under `subject` (idempotent — re-registering the same
+   * schema returns the existing id). Returns the registry-assigned schema id.
+   */
+  async registerSchema(subject, schema, schemaType = "JSON") {
+    this.latestCache.delete(subject);
+    return this.request(
+      "POST",
+      `/subjects/${encodeURIComponent(subject)}/versions`,
+      { schema, schemaType }
+    );
+  }
+  /**
+   * Test `schema` against the subject's compatibility policy without registering.
+   * Returns `true` when the registry reports the schema as compatible.
+   */
+  async checkCompatibility(subject, schema, schemaType = "JSON") {
+    const res = await this.request(
+      "POST",
+      `/compatibility/subjects/${encodeURIComponent(subject)}/versions/latest`,
+      { schema, schemaType }
+    );
+    return res.is_compatible;
+  }
+};
+function registrySchema(client, subject, options) {
+  const enforceVersion = options?.enforceVersion ?? true;
+  return {
+    async parse(data, ctx) {
+      const latest = await client.getLatestSchema(subject);
+      if (enforceVersion && ctx?.version !== void 0 && ctx.version > latest.version) {
+        throw new Error(
+          `registrySchema: message version ${ctx.version} for subject "${subject}" is newer than the latest registered version ${latest.version} \u2014 register the schema before producing with it`
+        );
+      }
+      if (options?.validator) {
+        return options.validator.parse(data, ctx);
+      }
+      return data;
+    }
+  };
+}
+
+// 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;
+}
 
 // src/nest/kafka.module.ts
 var import_common3 = require("@nestjs/common");
@@ -3663,11 +4986,14 @@ var SubscribeTo = (topics, options) => {
 };
 
 // src/nest/kafka.explorer.ts
+var wiredSubscriptions = /* @__PURE__ */ new WeakMap();
 var KafkaExplorer = class {
   constructor(discoveryService, moduleRef) {
     this.discoveryService = discoveryService;
     this.moduleRef = moduleRef;
   }
+  discoveryService;
+  moduleRef;
   logger = new import_common2.Logger(KafkaExplorer.name);
   /**
    * Scan all NestJS providers for `@SubscribeTo()` metadata and wire each decorated
@@ -3687,6 +5013,14 @@ var KafkaExplorer = class {
       if (!metadata || metadata.length === 0) continue;
       for (const entry of metadata) {
         const token = getKafkaClientToken(entry.clientName);
+        const entryKey = `${token}:${String(entry.methodName)}`;
+        let wired = wiredSubscriptions.get(instance);
+        if (!wired) {
+          wired = /* @__PURE__ */ new Set();
+          wiredSubscriptions.set(instance, wired);
+        }
+        if (wired.has(entryKey)) continue;
+        wired.add(entryKey);
         let client;
         try {
           client = this.moduleRef.get(token, { strict: false });
@@ -3776,6 +5110,12 @@ var KafkaModule = class {
         instrumentation: options.instrumentation,
         onMessageLost: options.onMessageLost,
         onRebalance: options.onRebalance,
+        transactionalId: options.transactionalId,
+        clockRecovery: options.clockRecovery,
+        lagThrottle: options.lagThrottle,
+        onTtlExpired: options.onTtlExpired,
+        transport: options.transport,
+        security: options.security,
         logger: new import_common3.Logger(`KafkaClient:${options.clientId}`)
       }
     );
@@ -3799,13 +5139,19 @@ KafkaHealthIndicator = __decorateClass([
 ], KafkaHealthIndicator);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ConfluentTransport,
   HEADER_CORRELATION_ID,
+  HEADER_DELAYED_TARGET,
+  HEADER_DELAYED_UNTIL,
   HEADER_EVENT_ID,
   HEADER_LAMPORT_CLOCK,
   HEADER_SCHEMA_VERSION,
   HEADER_TIMESTAMP,
   HEADER_TRACEPARENT,
+  InMemoryDedupStore,
+  InMemoryOutboxStore,
   InjectKafkaClient,
+  JsonSerde,
   KAFKA_CLIENT,
   KAFKA_SUBSCRIBER_METADATA,
   KafkaClient,
@@ -3815,13 +5161,27 @@ KafkaHealthIndicator = __decorateClass([
   KafkaProcessingError,
   KafkaRetryExhaustedError,
   KafkaValidationError,
+  SchemaRegistryClient,
   SubscribeTo,
+  awsMskIamProvider,
   buildEnvelopeHeaders,
+  consumerOptionsFromEnv,
   decodeHeaders,
+  describeRequiredAcls,
   extractEnvelope,
+  gcpAccessTokenProvider,
   getEnvelopeContext,
   getKafkaClientToken,
+  kafkaClientConfigFromEnv,
+  mergeConsumerOptions,
+  registrySchema,
+  resolveSecurityOptions,
   runWithEnvelopeContext,
-  topic
+  startOutboxRelay,
+  toError,
+  toKafkaAclCommands,
+  toMskIamPolicy,
+  topic,
+  versionedSchema
 });
 //# sourceMappingURL=index.js.map