@drarzter/kafka-client 0.6.4 → 0.6.7

package/dist/{chunk-7IX4AKQX.mjs → chunk-ISYOEX4W.mjs}

@@ -9,6 +9,7 @@ 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();
 function getEnvelopeContext() {
   return envelopeStorage.getStore();
@@ -149,6 +150,9 @@ async function buildSendPayload(topicOrDesc, messages, deps) {
         eventId: m.eventId,
         headers: m.headers
       });
+      if (deps.nextLamportClock) {
+        envelopeHeaders[HEADER_LAMPORT_CLOCK] = String(deps.nextLamportClock());
+      }
       for (const inst of deps.instrumentation) {
         inst.beforeSend?.(topic2, envelopeHeaders);
       }
@@ -286,6 +290,9 @@ async function validateWithSchema(message, raw, topic2, schemaMap, interceptors,
       -1,
       ""
     );
+    for (const inst of deps.instrumentation ?? []) {
+      inst.onConsumeError?.(errorEnvelope, validationError);
+    }
     for (const interceptor of interceptors) {
       await interceptor.onError?.(errorEnvelope, validationError);
     }
@@ -311,7 +318,10 @@ async function sendToDlq(topic2, rawMessage, deps, meta) {
     deps.logger.warn(`Message sent to DLQ: ${payload.topic}`);
   } catch (error) {
     const err = toError(error);
-    deps.logger.error(`Failed to send message to DLQ ${payload.topic}:`, err.stack);
+    deps.logger.error(
+      `Failed to send message to DLQ ${payload.topic}:`,
+      err.stack
+    );
     await deps.onMessageLost?.({
       topic: topic2,
       error: err,
@@ -326,14 +336,9 @@ var RETRY_HEADER_MAX_RETRIES = "x-retry-max-retries";
 var RETRY_HEADER_ORIGINAL_TOPIC = "x-retry-original-topic";
 function buildRetryTopicPayload(originalTopic, rawMessages, attempt, maxRetries, delayMs, originalHeaders) {
   const retryTopic = `${originalTopic}.retry.${attempt}`;
+  const STRIP = /* @__PURE__ */ new Set([RETRY_HEADER_ATTEMPT, RETRY_HEADER_AFTER, RETRY_HEADER_MAX_RETRIES, RETRY_HEADER_ORIGINAL_TOPIC]);
   function buildHeaders(hdr) {
-    const {
-      [RETRY_HEADER_ATTEMPT]: _a,
-      [RETRY_HEADER_AFTER]: _b,
-      [RETRY_HEADER_MAX_RETRIES]: _c,
-      [RETRY_HEADER_ORIGINAL_TOPIC]: _d,
-      ...userHeaders
-    } = hdr;
+    const userHeaders = Object.fromEntries(Object.entries(hdr).filter(([k]) => !STRIP.has(k)));
     return {
       ...userHeaders,
       [RETRY_HEADER_ATTEMPT]: String(attempt),
@@ -380,6 +385,37 @@ async function sendToRetryTopic(originalTopic, rawMessages, attempt, maxRetries,
     });
   }
 }
+function buildDuplicateTopicPayload(sourceTopic, rawMessage, destinationTopic, meta) {
+  const headers = {
+    ...meta?.originalHeaders ?? {},
+    "x-duplicate-original-topic": sourceTopic,
+    "x-duplicate-detected-at": (/* @__PURE__ */ new Date()).toISOString(),
+    "x-duplicate-reason": "lamport-clock-duplicate",
+    "x-duplicate-incoming-clock": String(meta?.incomingClock ?? 0),
+    "x-duplicate-last-processed-clock": String(meta?.lastProcessedClock ?? 0)
+  };
+  return {
+    topic: destinationTopic,
+    messages: [{ value: rawMessage, headers }]
+  };
+}
+async function sendToDuplicatesTopic(sourceTopic, rawMessage, destinationTopic, deps, meta) {
+  const payload = buildDuplicateTopicPayload(
+    sourceTopic,
+    rawMessage,
+    destinationTopic,
+    meta
+  );
+  try {
+    await deps.producer.send(payload);
+    deps.logger.warn(`Duplicate message forwarded to ${destinationTopic}`);
+  } catch (error) {
+    deps.logger.error(
+      `Failed to forward duplicate to ${destinationTopic}:`,
+      toError(error).stack
+    );
+  }
+}
 async function broadcastToInterceptors(envelopes, interceptors, cb) {
   for (const env of envelopes) {
     for (const interceptor of interceptors) {
@@ -461,7 +497,10 @@ async function executeWithRetry(fn, ctx, deps) {
       interceptors,
       deps.instrumentation
     );
-    if (!error) return;
+    if (!error) {
+      for (const env of envelopes) deps.onMessage?.(env);
+      return;
+    }
     const isLastAttempt = attempt === maxAttempts;
     const reportedError = isLastAttempt && maxAttempts > 1 ? new KafkaRetryExhaustedError(
       topic2,
@@ -486,15 +525,16 @@ async function executeWithRetry(fn, ctx, deps) {
         isBatch ? envelopes.map((e) => e.headers) : envelopes[0]?.headers ?? {},
         deps
       );
+      deps.onRetry?.(envelopes[0], 1, retry.maxRetries);
     } else if (isLastAttempt) {
       if (dlq) {
-        const dlqMeta = {
-          error,
-          attempt,
-          originalHeaders: envelopes[0]?.headers
-        };
-        for (const raw of rawMessages) {
-          await sendToDlq(topic2, raw, deps, dlqMeta);
+        for (let i = 0; i < rawMessages.length; i++) {
+          await sendToDlq(topic2, rawMessages[i], deps, {
+            error,
+            attempt,
+            originalHeaders: envelopes[i]?.headers
+          });
+          deps.onDlq?.(envelopes[i] ?? envelopes[0], "handler-error");
         }
       } else {
         await deps.onMessageLost?.({
@@ -506,12 +546,52 @@ async function executeWithRetry(fn, ctx, deps) {
       }
     } else {
       const cap = Math.min(backoffMs * 2 ** (attempt - 1), maxBackoffMs);
+      deps.onRetry?.(envelopes[0], attempt, maxAttempts - 1);
       await sleep(Math.floor(Math.random() * cap));
     }
   }
 }
 
 // src/client/kafka.client/message-handler.ts
+async function applyDeduplication(envelope, raw, dedup, dlq, deps) {
+  const clockRaw = envelope.headers[HEADER_LAMPORT_CLOCK];
+  if (clockRaw === void 0) return false;
+  const incomingClock = Number(clockRaw);
+  if (Number.isNaN(incomingClock)) return false;
+  const stateKey = `${envelope.topic}:${envelope.partition}`;
+  const lastProcessedClock = dedup.state.get(stateKey) ?? -1;
+  if (incomingClock <= lastProcessedClock) {
+    const meta = {
+      incomingClock,
+      lastProcessedClock,
+      originalHeaders: envelope.headers
+    };
+    const strategy = dedup.options.strategy ?? "drop";
+    deps.logger.warn(
+      `Duplicate message on ${envelope.topic}[${envelope.partition}]: clock=${incomingClock} <= last=${lastProcessedClock} \u2014 strategy=${strategy}`
+    );
+    deps.onDuplicate?.(envelope, strategy);
+    if (strategy === "dlq" && dlq) {
+      const augmentedHeaders = {
+        ...envelope.headers,
+        "x-dlq-reason": "lamport-clock-duplicate",
+        "x-dlq-duplicate-incoming-clock": String(incomingClock),
+        "x-dlq-duplicate-last-processed-clock": String(lastProcessedClock)
+      };
+      await sendToDlq(envelope.topic, raw, deps, {
+        error: new Error("Lamport Clock duplicate detected"),
+        attempt: 0,
+        originalHeaders: augmentedHeaders
+      });
+    } else if (strategy === "topic") {
+      const destination = dedup.options.duplicatesTopic ?? `${envelope.topic}.duplicates`;
+      await sendToDuplicatesTopic(envelope.topic, raw, destination, deps, meta);
+    }
+    return true;
+  }
+  dedup.state.set(stateKey, incomingClock);
+  return false;
+}
 async function parseSingleMessage(message, topic2, partition, schemaMap, interceptors, dlq, deps) {
   if (!message.value) {
     deps.logger.warn(`Received empty message from topic ${topic2}`);
@@ -555,6 +635,16 @@ async function handleEachMessage(payload, opts, deps) {
     deps
   );
   if (envelope === null) return;
+  if (opts.deduplication) {
+    const isDuplicate = await applyDeduplication(
+      envelope,
+      message.value.toString(),
+      opts.deduplication,
+      dlq,
+      deps
+    );
+    if (isDuplicate) return;
+  }
   await executeWithRetry(
     () => {
       const fn = () => runWithEnvelopeContext(
@@ -602,6 +692,17 @@ async function handleEachBatch(payload, opts, deps) {
       deps
     );
     if (envelope === null) continue;
+    if (opts.deduplication) {
+      const raw = message.value.toString();
+      const isDuplicate = await applyDeduplication(
+        envelope,
+        raw,
+        opts.deduplication,
+        dlq,
+        deps
+      );
+      if (isDuplicate) continue;
+    }
     envelopes.push(envelope);
     rawMessages.push(message.value.toString());
   }
@@ -673,6 +774,9 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
     producer,
     instrumentation,
     onMessageLost,
+    onRetry,
+    onDlq,
+    onMessage,
     ensureTopic,
     getOrCreateConsumer: getOrCreateConsumer2,
     runningConsumers,
@@ -754,6 +858,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
         instrumentation
       );
       if (!error) {
+        onMessage?.(envelope);
         await consumer.commitOffsets([nextOffset]);
         return;
       }
@@ -786,12 +891,23 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
           await tx.send({ topic: rtTopic, messages: rtMsgs });
           await tx.sendOffsets({
             consumer,
-            topics: [{ topic: nextOffset.topic, partitions: [{ partition: nextOffset.partition, offset: nextOffset.offset }] }]
+            topics: [
+              {
+                topic: nextOffset.topic,
+                partitions: [
+                  {
+                    partition: nextOffset.partition,
+                    offset: nextOffset.offset
+                  }
+                ]
+              }
+            ]
           });
           await tx.commit();
           logger.warn(
             `Message routed to ${rtTopic} (EOS, level ${nextLevel}/${currentMaxRetries})`
           );
+          onRetry?.(envelope, nextLevel, currentMaxRetries);
         } catch (txErr) {
           try {
             await tx.abort();
@@ -819,10 +935,21 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
           await tx.send({ topic: dTopic, messages: dMsgs });
           await tx.sendOffsets({
             consumer,
-            topics: [{ topic: nextOffset.topic, partitions: [{ partition: nextOffset.partition, offset: nextOffset.offset }] }]
+            topics: [
+              {
+                topic: nextOffset.topic,
+                partitions: [
+                  {
+                    partition: nextOffset.partition,
+                    offset: nextOffset.offset
+                  }
+                ]
+              }
+            ]
           });
           await tx.commit();
           logger.warn(`Message sent to DLQ: ${dTopic} (EOS)`);
+          onDlq?.(envelope, "handler-error");
         } catch (txErr) {
           try {
             await tx.abort();
@@ -846,7 +973,12 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
     }
   });
   runningConsumers.set(levelGroupId, "eachMessage");
-  await waitForPartitionAssignment(consumer, levelTopics, logger, assignmentTimeoutMs);
+  await waitForPartitionAssignment(
+    consumer,
+    levelTopics,
+    logger,
+    assignmentTimeoutMs
+  );
   logger.log(
     `Retry level ${level}/${retry.maxRetries} consumer started for: ${originalTopics.join(", ")} (group: ${levelGroupId})`
   );
@@ -876,10 +1008,12 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
 
 // src/client/kafka.client/index.ts
 var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = KafkaJS;
+var _activeTransactionalIds = /* @__PURE__ */ new Set();
 var KafkaClient = class {
   kafka;
   producer;
   txProducer;
+  txProducerInitPromise;
   /** Maps transactionalId → Producer for each active retry level consumer. */
   retryTxProducers = /* @__PURE__ */ new Map();
   consumers = /* @__PURE__ */ new Map();
@@ -889,6 +1023,8 @@ var KafkaClient = class {
   strictSchemasEnabled;
   numPartitions;
   ensuredTopics = /* @__PURE__ */ new Set();
+  /** Pending topic-creation promises keyed by topic name. Prevents duplicate createTopics calls. */
+  ensureTopicPromises = /* @__PURE__ */ new Map();
   defaultGroupId;
   schemaRegistry = /* @__PURE__ */ new Map();
   runningConsumers = /* @__PURE__ */ new Map();
@@ -898,6 +1034,19 @@ var KafkaClient = class {
   instrumentation;
   onMessageLost;
   onRebalance;
+  /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
+  txId;
+  /** Internal event counters exposed via `getMetrics()`. */
+  _metrics = {
+    processedCount: 0,
+    retryCount: 0,
+    dlqCount: 0,
+    dedupCount: 0
+  };
+  /** Monotonically increasing Lamport clock stamped on every outgoing message. */
+  _lamportClock = 0;
+  /** Per-groupId deduplication state: `"topic:partition"` → last processed clock. */
+  dedupStates = /* @__PURE__ */ new Map();
   isAdminConnected = false;
   inFlightTotal = 0;
   drainResolvers = [];
@@ -917,6 +1066,7 @@ var KafkaClient = class {
     this.instrumentation = options?.instrumentation ?? [];
     this.onMessageLost = options?.onMessageLost;
     this.onRebalance = options?.onRebalance;
+    this.txId = options?.transactionalId ?? `${clientId}-tx`;
     this.kafka = new KafkaClass({
       kafkaJS: {
         clientId: this.clientId,
@@ -952,18 +1102,31 @@ var KafkaClient = class {
   }
   /** Execute multiple sends atomically. Commits on success, aborts on error. */
   async transaction(fn) {
-    if (!this.txProducer) {
-      const p = this.kafka.producer({
-        kafkaJS: {
-          acks: -1,
-          idempotent: true,
-          transactionalId: `${this.clientId}-tx`,
-          maxInFlightRequests: 1
-        }
+    if (!this.txProducerInitPromise) {
+      if (_activeTransactionalIds.has(this.txId)) {
+        this.logger.warn(
+          `transactionalId "${this.txId}" is already in use by another KafkaClient in this process. Kafka will fence one of the producers. Set a unique \`transactionalId\` (or distinct \`clientId\`) per instance.`
+        );
+      }
+      const initPromise = (async () => {
+        const p = this.kafka.producer({
+          kafkaJS: {
+            acks: -1,
+            idempotent: true,
+            transactionalId: this.txId,
+            maxInFlightRequests: 1
+          }
+        });
+        await p.connect();
+        _activeTransactionalIds.add(this.txId);
+        return p;
+      })();
+      this.txProducerInitPromise = initPromise.catch((err) => {
+        this.txProducerInitPromise = void 0;
+        throw err;
       });
-      await p.connect();
-      this.txProducer = p;
     }
+    this.txProducer = await this.txProducerInitPromise;
     const tx = await this.txProducer.transaction();
     try {
       const ctx = {
@@ -1002,11 +1165,17 @@ var KafkaClient = class {
     }
   }
   // ── Producer lifecycle ───────────────────────────────────────────
-  /** Connect the idempotent producer. Called automatically by `KafkaModule.register()`. */
+  /**
+   * Connect the idempotent producer. Called automatically by `KafkaModule.register()`.
+   * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
+   */
   async connectProducer() {
     await this.producer.connect();
     this.logger.log("Producer connected");
   }
+  /**
+   * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
+   */
   async disconnectProducer() {
     await this.producer.disconnect();
     this.logger.log("Producer disconnected");
@@ -1020,6 +1189,10 @@ var KafkaClient = class {
     const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", options);
     const deps = this.messageDeps;
     const timeoutMs = options.handlerTimeoutMs;
+    const deduplication = this.resolveDeduplicationContext(
+      gid,
+      options.deduplication
+    );
     await consumer.run({
       eachMessage: (payload) => this.trackInFlight(
         () => handleEachMessage(
@@ -1032,7 +1205,8 @@ var KafkaClient = class {
             retry,
             retryTopics: options.retryTopics,
             timeoutMs,
-            wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this)
+            wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
+            deduplication
           },
           deps
         )
@@ -1072,6 +1246,10 @@ var KafkaClient = class {
     const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachBatch", options);
     const deps = this.messageDeps;
     const timeoutMs = options.handlerTimeoutMs;
+    const deduplication = this.resolveDeduplicationContext(
+      gid,
+      options.deduplication
+    );
     await consumer.run({
       eachBatch: (payload) => this.trackInFlight(
         () => handleEachBatch(
@@ -1084,7 +1262,8 @@ var KafkaClient = class {
             retry,
             retryTopics: options.retryTopics,
             timeoutMs,
-            wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this)
+            wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
+            deduplication
           },
           deps
         )
@@ -1097,7 +1276,7 @@ var KafkaClient = class {
       }
       const handleMessageForRetry = (env) => handleBatch([env], {
         partition: env.partition,
-        highWatermark: env.offset,
+        highWatermark: null,
         heartbeat: async () => {
         },
         resolveOffset: () => {
@@ -1130,18 +1309,27 @@ var KafkaClient = class {
         );
         return;
       }
-      await consumer.disconnect().catch(() => {
-      });
+      await consumer.disconnect().catch(
+        (e) => this.logger.warn(
+          `Error disconnecting consumer "${groupId}":`,
+          toError(e).message
+        )
+      );
       this.consumers.delete(groupId);
       this.runningConsumers.delete(groupId);
       this.consumerCreationOptions.delete(groupId);
+      this.dedupStates.delete(groupId);
       this.logger.log(`Consumer disconnected: group "${groupId}"`);
       const companions = this.companionGroupIds.get(groupId) ?? [];
       for (const cGroupId of companions) {
         const cConsumer = this.consumers.get(cGroupId);
         if (cConsumer) {
-          await cConsumer.disconnect().catch(() => {
-          });
+          await cConsumer.disconnect().catch(
+            (e) => this.logger.warn(
+              `Error disconnecting retry consumer "${cGroupId}":`,
+              toError(e).message
+            )
+          );
           this.consumers.delete(cGroupId);
           this.runningConsumers.delete(cGroupId);
           this.consumerCreationOptions.delete(cGroupId);
@@ -1150,8 +1338,13 @@ var KafkaClient = class {
         const txId = `${cGroupId}-tx`;
         const txProducer = this.retryTxProducers.get(txId);
         if (txProducer) {
-          await txProducer.disconnect().catch(() => {
-          });
+          await txProducer.disconnect().catch(
+            (e) => this.logger.warn(
+              `Error disconnecting retry tx producer "${txId}":`,
+              toError(e).message
+            )
+          );
+          _activeTransactionalIds.delete(txId);
           this.retryTxProducers.delete(txId);
         }
       }
@@ -1173,6 +1366,7 @@ var KafkaClient = class {
       this.consumerCreationOptions.clear();
       this.companionGroupIds.clear();
       this.retryTxProducers.clear();
+      this.dedupStates.clear();
       this.logger.log("All consumers disconnected");
     }
   }
@@ -1226,13 +1420,27 @@ var KafkaClient = class {
   getClientId() {
     return this.clientId;
   }
+  getMetrics() {
+    return { ...this._metrics };
+  }
+  resetMetrics() {
+    this._metrics.processedCount = 0;
+    this._metrics.retryCount = 0;
+    this._metrics.dlqCount = 0;
+    this._metrics.dedupCount = 0;
+  }
   /** Gracefully disconnect producer, all consumers, and admin. */
   async disconnect(drainTimeoutMs = 3e4) {
     await this.waitForDrain(drainTimeoutMs);
     const tasks = [this.producer.disconnect()];
     if (this.txProducer) {
       tasks.push(this.txProducer.disconnect());
+      _activeTransactionalIds.delete(this.txId);
       this.txProducer = void 0;
+      this.txProducerInitPromise = void 0;
+    }
+    for (const txId of this.retryTxProducers.keys()) {
+      _activeTransactionalIds.delete(txId);
     }
     for (const p of this.retryTxProducers.values()) {
       tasks.push(p.disconnect());
@@ -1329,6 +1537,30 @@ var KafkaClient = class {
       }
     }
   }
+  notifyRetry(envelope, attempt, maxRetries) {
+    this._metrics.retryCount++;
+    for (const inst of this.instrumentation) {
+      inst.onRetry?.(envelope, attempt, maxRetries);
+    }
+  }
+  notifyDlq(envelope, reason) {
+    this._metrics.dlqCount++;
+    for (const inst of this.instrumentation) {
+      inst.onDlq?.(envelope, reason);
+    }
+  }
+  notifyDuplicate(envelope, strategy) {
+    this._metrics.dedupCount++;
+    for (const inst of this.instrumentation) {
+      inst.onDuplicate?.(envelope, strategy);
+    }
+  }
+  notifyMessage(envelope) {
+    this._metrics.processedCount++;
+    for (const inst of this.instrumentation) {
+      inst.onMessage?.(envelope);
+    }
+  }
   /**
    * Start a timer that logs a warning if `fn` hasn't resolved within `timeoutMs`.
    * The handler itself is not cancelled — the warning is diagnostic only.
@@ -1381,6 +1613,22 @@ var KafkaClient = class {
       );
     }
   }
+  /**
+   * When `deduplication.strategy: 'topic'` and `autoCreateTopics: false`, verify
+   * that every `<topic>.duplicates` destination topic already exists. Throws a
+   * clear error at startup rather than silently dropping duplicates on first hit.
+   */
+  async validateDuplicatesTopicsExist(topicNames, customDestination) {
+    await this.ensureAdminConnected();
+    const existing = new Set(await this.admin.listTopics());
+    const toCheck = customDestination ? [customDestination] : topicNames.map((t) => `${t}.duplicates`);
+    const missing = toCheck.filter((t) => !existing.has(t));
+    if (missing.length > 0) {
+      throw new Error(
+        `deduplication.strategy: 'topic' but the following duplicate-routing topics do not exist: ${missing.join(", ")}. Create them manually or set autoCreateTopics: true.`
+      );
+    }
+  }
   /**
    * Connect the admin client if not already connected.
    * The flag is only set to `true` after a successful connect — if `admin.connect()`
@@ -1402,6 +1650,11 @@ var KafkaClient = class {
    * so Kafka can fence stale producers on restart without affecting other levels.
    */
   async createRetryTxProducer(transactionalId) {
+    if (_activeTransactionalIds.has(transactionalId)) {
+      this.logger.warn(
+        `transactionalId "${transactionalId}" is already in use by another KafkaClient in this process. Kafka will fence one of the producers. Set a unique \`transactionalId\` (or distinct \`clientId\`) per instance.`
+      );
+    }
     const p = this.kafka.producer({
       kafkaJS: {
         acks: -1,
@@ -1411,16 +1664,24 @@ var KafkaClient = class {
       }
     });
     await p.connect();
+    _activeTransactionalIds.add(transactionalId);
     this.retryTxProducers.set(transactionalId, p);
     return p;
   }
   async ensureTopic(topic2) {
     if (!this.autoCreateTopicsEnabled || this.ensuredTopics.has(topic2)) return;
-    await this.ensureAdminConnected();
-    await this.admin.createTopics({
-      topics: [{ topic: topic2, numPartitions: this.numPartitions }]
-    });
-    this.ensuredTopics.add(topic2);
+    let p = this.ensureTopicPromises.get(topic2);
+    if (!p) {
+      p = (async () => {
+        await this.ensureAdminConnected();
+        await this.admin.createTopics({
+          topics: [{ topic: topic2, numPartitions: this.numPartitions }]
+        });
+        this.ensuredTopics.add(topic2);
+      })().finally(() => this.ensureTopicPromises.delete(topic2));
+      this.ensureTopicPromises.set(topic2, p);
+    }
+    await p;
   }
   /** Shared consumer setup: groupId check, schema map, connect, subscribe. */
   async setupConsumer(topics, mode, options) {
@@ -1470,6 +1731,16 @@ var KafkaClient = class {
         await this.validateDlqTopicsExist(topicNames);
       }
     }
+    if (options.deduplication?.strategy === "topic") {
+      const dest = options.deduplication.duplicatesTopic;
+      if (this.autoCreateTopicsEnabled) {
+        for (const t of topicNames) {
+          await this.ensureTopic(dest ?? `${t}.duplicates`);
+        }
+      } else {
+        await this.validateDuplicatesTopicsExist(topicNames, dest);
+      }
+    }
     await consumer.connect();
     await subscribeWithRetry(
       consumer,
@@ -1482,13 +1753,22 @@ var KafkaClient = class {
     );
     return { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry };
   }
+  /** Create or retrieve the deduplication context for a consumer group. */
+  resolveDeduplicationContext(groupId, options) {
+    if (!options) return void 0;
+    if (!this.dedupStates.has(groupId)) {
+      this.dedupStates.set(groupId, /* @__PURE__ */ new Map());
+    }
+    return { options, state: this.dedupStates.get(groupId) };
+  }
   // ── Deps object getters ──────────────────────────────────────────
   get producerOpsDeps() {
     return {
       schemaRegistry: this.schemaRegistry,
       strictSchemasEnabled: this.strictSchemasEnabled,
       instrumentation: this.instrumentation,
-      logger: this.logger
+      logger: this.logger,
+      nextLamportClock: () => ++this._lamportClock
     };
   }
   get consumerOpsDeps() {
@@ -1505,7 +1785,11 @@ var KafkaClient = class {
       logger: this.logger,
       producer: this.producer,
       instrumentation: this.instrumentation,
-      onMessageLost: this.onMessageLost
+      onMessageLost: this.onMessageLost,
+      onRetry: this.notifyRetry.bind(this),
+      onDlq: this.notifyDlq.bind(this),
+      onDuplicate: this.notifyDuplicate.bind(this),
+      onMessage: this.notifyMessage.bind(this)
     };
   }
   get retryTopicDeps() {
@@ -1514,6 +1798,9 @@ var KafkaClient = class {
       producer: this.producer,
       instrumentation: this.instrumentation,
       onMessageLost: this.onMessageLost,
+      onRetry: this.notifyRetry.bind(this),
+      onDlq: this.notifyDlq.bind(this),
+      onMessage: this.notifyMessage.bind(this),
       ensureTopic: (t) => this.ensureTopic(t),
       getOrCreateConsumer: (gid, fb, ac) => getOrCreateConsumer(gid, fb, ac, this.consumerOpsDeps),
       runningConsumers: this.runningConsumers,
@@ -1544,6 +1831,7 @@ export {
   HEADER_TIMESTAMP,
   HEADER_SCHEMA_VERSION,
   HEADER_TRACEPARENT,
+  HEADER_LAMPORT_CLOCK,
   getEnvelopeContext,
   runWithEnvelopeContext,
   buildEnvelopeHeaders,
@@ -1555,4 +1843,4 @@ export {
   KafkaClient,
   topic
 };
-//# sourceMappingURL=chunk-7IX4AKQX.mjs.map
+//# sourceMappingURL=chunk-ISYOEX4W.mjs.map