@zdavison/matador 2.0.1

package/dist/index.cjs

@@ -0,0 +1,3156 @@
+'use strict';
+
+var amqplib = require('amqplib');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var amqplib__default = /*#__PURE__*/_interopDefault(amqplib);
+
+// src/errors/has-description.ts
+function hasDescription(error) {
+  return typeof error === "object" && error !== null && "description" in error && typeof error.description === "string";
+}
+
+// src/errors/retry-errors.ts
+var RetryControlError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.defineProperty(this, "name", {
+      value: this.constructor.name,
+      enumerable: true,
+      configurable: false,
+      writable: false
+    });
+  }
+  /**
+   * Returns a serializable representation for logging/monitoring.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      description: this.description,
+      stack: this.stack
+    };
+  }
+};
+var DoRetry = class extends RetryControlError {
+  description = "A subscriber explicitly requested retry by throwing DoRetry. ACTION: Check the subscriber code to understand why retry was forced. This overrides the default retry behavior based on idempotency settings.";
+  constructor(message = "Forced retry requested") {
+    super(message);
+  }
+};
+var DontRetry = class extends RetryControlError {
+  description = "A subscriber explicitly prevented retry by throwing DontRetry. ACTION: Check the subscriber code to understand why retry was disabled. Typically used for permanent failures like invalid data or business rule violations. The message will be sent to the dead-letter queue for manual review.";
+  constructor(message = "Retry explicitly disabled") {
+    super(message);
+  }
+};
+var EventAssertionError = class extends Error {
+  description = "An event assertion failed, indicating a programming error or invariant violation. ACTION: Review the assertion failure message to identify the bug in the event payload or subscriber logic. These errors are never retried and go directly to the dead-letter queue.";
+  constructor(message) {
+    super(message);
+    this.name = "EventAssertionError";
+    Object.defineProperty(this, "name", {
+      value: "EventAssertionError",
+      enumerable: true,
+      configurable: false,
+      writable: false
+    });
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      description: this.description,
+      stack: this.stack
+    };
+  }
+};
+function isDoRetry(error) {
+  return error instanceof DoRetry;
+}
+function isDontRetry(error) {
+  return error instanceof DontRetry;
+}
+function isAssertionError(error) {
+  return error instanceof EventAssertionError;
+}
+
+// src/errors/matador-errors.ts
+var MatadorError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.defineProperty(this, "name", {
+      value: this.constructor.name,
+      enumerable: true,
+      configurable: false,
+      writable: false
+    });
+  }
+  /**
+   * Returns a serializable representation for logging/monitoring.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      description: this.description,
+      stack: this.stack
+    };
+  }
+};
+var NotStartedError = class extends MatadorError {
+  description = "Matador has not been started. ACTION: Call matador.start() before dispatching events or performing other operations. Ensure start() completes successfully before using other methods.";
+  constructor(operation = "operation") {
+    super(
+      `Cannot perform ${operation}: Matador has not been started. Call start() first.`
+    );
+  }
+};
+var ShutdownInProgressError = class extends MatadorError {
+  description = "Matador is shutting down and will not accept new events. ACTION: Do not dispatch events after calling shutdown(). If you need to send events, do so before initiating shutdown. Consider implementing a pre-shutdown event flush if needed.";
+  constructor() {
+    super("Cannot dispatch events: Matador is shutting down.");
+  }
+};
+var TransportNotConnectedError = class extends MatadorError {
+  constructor(transportName, operation = "operation") {
+    super(
+      `Cannot perform ${operation}: Transport "${transportName}" is not connected. Ensure connect() was called and the broker is accessible.`
+    );
+    this.transportName = transportName;
+  }
+  description = "The transport is not connected to the message broker. ACTION: Ensure the transport is connected by calling transport.connect() or matador.start(). Check that the broker (e.g., RabbitMQ) is running and accessible. Verify connection settings (URL, credentials, network access).";
+};
+var TransportClosedError = class extends MatadorError {
+  constructor(transportName) {
+    super(
+      `Transport "${transportName}" has been closed and will not accept new operations.`
+    );
+    this.transportName = transportName;
+  }
+  description = "The transport has been closed and will not accept new operations. ACTION: This typically occurs during application shutdown. If unexpected, check for early shutdown triggers. Events sent after transport closure will be lost.";
+};
+var AllTransportsFailedError = class extends MatadorError {
+  constructor(queue, errors) {
+    super(
+      `All transports failed to send message to queue "${queue}". Errors: ${errors.map((e) => e.message).join("; ")}`
+    );
+    this.queue = queue;
+    this.errors = errors;
+  }
+  description = "All transports failed to send the message. ACTION: Check the health of all configured transports (primary and fallbacks). Review the errors array for specific failure reasons. Ensure at least one transport is properly configured and reachable. Consider adding a LocalTransport as a last-resort fallback.";
+};
+var TransportSendError = class extends MatadorError {
+  constructor(queue, cause) {
+    super(`Failed to send message to queue "${queue}": ${cause.message}`);
+    this.queue = queue;
+    this.cause = cause;
+  }
+  description = "Failed to send a message through the transport. ACTION: Check the underlying error for details. Common causes: (1) Transport disconnected during send, (2) Network issues between application and broker, (3) Broker rejected the message (size, permissions, queue limits). The message was NOT delivered and should be retried or logged.";
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      queue: this.queue,
+      cause: {
+        name: this.cause.name,
+        message: this.cause.message
+      }
+    };
+  }
+};
+var DelayedMessagesNotSupportedError = class extends MatadorError {
+  constructor(transportName) {
+    super(
+      `Delayed messages require the RabbitMQ delayed message exchange plugin. Install rabbitmq_delayed_message_exchange or remove delayMs from event options.`
+    );
+    this.transportName = transportName;
+  }
+  description = "Delayed messages were requested but the transport does not support them. ACTION: For RabbitMQ, install the rabbitmq_delayed_message_exchange plugin. Run: rabbitmq-plugins enable rabbitmq_delayed_message_exchange Then restart RabbitMQ and reconnect. Alternatively, remove delayMs from your event options if delays are not required.";
+};
+var EventNotRegisteredError = class extends MatadorError {
+  constructor(eventKey) {
+    super(
+      `Event "${eventKey}" is not registered in schema. Register it using matador.register(EventClass, subscribers).`
+    );
+    this.eventKey = eventKey;
+  }
+  description = "The event type is not registered in the schema. ACTION: Register the event using matador.register(EventClass, subscribers) before dispatching. If this occurs during message consumption, it may indicate schema drift between services. Ensure all services have matching schema registrations for shared events.";
+};
+var SubscriberNotRegisteredError = class extends MatadorError {
+  constructor(subscriberName, eventKey) {
+    super(
+      `Subscriber "${subscriberName}" is not registered` + (eventKey ? ` for event "${eventKey}"` : "") + ". Check schema registration."
+    );
+    this.subscriberName = subscriberName;
+    this.eventKey = eventKey;
+  }
+  description = "The subscriber is not registered for this event in the schema. ACTION: Ensure the subscriber is included in the registration for this event. This may occur if: (1) The subscriber was removed from the schema but messages still exist, (2) Schema drift between producer and consumer services, (3) A deployment is in progress with different schema versions. Check the dead-letter queue for affected messages.";
+};
+var NoSubscribersExistError = class extends MatadorError {
+  constructor(eventKey) {
+    super(
+      `No subscribers registered for event "${eventKey}". Add subscribers using matador.register(EventClass, [subscriber1, subscriber2]).`
+    );
+    this.eventKey = eventKey;
+  }
+  description = "The event has no subscribers registered. ACTION: Register at least one subscriber for this event type. If subscribers were intentionally removed, consider also removing the event dispatch. Events without subscribers are not useful and may indicate configuration issues.";
+};
+var InvalidSchemaError = class extends MatadorError {
+  constructor(message, cause) {
+    super(`Invalid schema: ${message}` + (cause ? `. Cause: ${cause}` : ""));
+    this.cause = cause;
+  }
+  description = "The schema configuration is invalid. ACTION: Review the schema registration for issues. Common problems: (1) Duplicate subscriber names for the same event, (2) Missing required fields on event class (key, description), (3) Invalid alias configuration. Check the cause property for specific details.";
+};
+var SubscriberIsStubError = class extends MatadorError {
+  constructor(subscriberName) {
+    super(
+      `Subscriber "${subscriberName}" is a stub and cannot be processed locally. Replace with a full Subscriber implementation in the consumer schema.`
+    );
+    this.subscriberName = subscriberName;
+  }
+  description = "A SubscriberStub was registered in a consuming schema. ACTION: SubscriberStubs should only be used in producer schemas to declare that a subscriber exists in another service. In the consumer service, provide a full Subscriber with a callback function. Remove the stub from the consumer schema and add the actual implementation.";
+};
+var LocalTransportCannotProcessStubError = class extends MatadorError {
+  constructor(subscriberName) {
+    super(
+      `LocalTransport cannot process stub subscriber "${subscriberName}". Stub subscribers require a distributed transport like RabbitMQ.`
+    );
+    this.subscriberName = subscriberName;
+  }
+  description = "The LocalTransport cannot process events for SubscriberStubs. ACTION: SubscriberStubs represent remote implementations that only RabbitMQ can route. If using LocalTransport for testing, provide mock implementations instead of stubs. For production fallback scenarios, be aware that stub-targeted events will be dropped.";
+};
+var QueueNotFoundError = class extends MatadorError {
+  constructor(queueName) {
+    super(
+      `Queue "${queueName}" not found. Ensure it is defined in topology and applyTopology() was called.`
+    );
+    this.queueName = queueName;
+  }
+  description = "The specified queue does not exist or has not been created. ACTION: Ensure the queue is defined in the topology configuration. Call transport.applyTopology() or matador.start() to create queues. Check that the queue name matches the topology definition.";
+};
+var InvalidEventError = class extends MatadorError {
+  constructor(message, cause) {
+    super(`Invalid event: ${message}` + (cause ? `. Cause: ${cause}` : ""));
+    this.cause = cause;
+  }
+  description = "The event is invalid or missing required fields. ACTION: Ensure the event has all required properties. Common issues: missing targetSubscriber during processing, null/undefined data when the event type requires data, malformed event structure from codec decode failure.";
+};
+var MessageMaybePoisonedError = class extends MatadorError {
+  constructor(eventId, deliveryCount, maxDeliveries) {
+    super(
+      `Message "${eventId}" delivered ${deliveryCount} times (max: ${maxDeliveries}). Possible poison message - will not be retried.`
+    );
+    this.eventId = eventId;
+    this.deliveryCount = deliveryCount;
+    this.maxDeliveries = maxDeliveries;
+  }
+  description = "A message was redelivered multiple times without successful processing. This usually indicates the message causes a crash or timeout during processing. ACTION: (1) Check application logs for errors/crashes during message processing, (2) Inspect the message in the dead-letter queue for malformed data, (3) Review the subscriber code for bugs that cause crashes, (4) Consider increasing processing timeout if the operation is legitimately slow. This message will NOT be retried to prevent crash loops.";
+};
+var IdempotentMessageCannotRetryError = class extends MatadorError {
+  constructor(eventId, subscriberName) {
+    super(
+      `Non-idempotent subscriber "${subscriberName}" cannot retry redelivered message "${eventId}". Mark subscriber as idempotent='yes' or implement idempotency handling.`
+    );
+    this.eventId = eventId;
+    this.subscriberName = subscriberName;
+  }
+  description = "A non-idempotent subscriber received a redelivered message. Retrying would risk duplicate side effects (e.g., double payments, duplicate emails). ACTION: (1) Mark the subscriber as idempotent if it safely handles duplicates, (2) Implement idempotency keys in the subscriber logic, (3) Manually inspect and replay the message from the dead-letter queue after verification. The message will be sent to the dead-letter queue for manual review.";
+};
+var TimeoutError = class extends MatadorError {
+  constructor(operation, timeoutMs) {
+    super(`Operation "${operation}" timed out after ${timeoutMs}ms.`);
+    this.operation = operation;
+    this.timeoutMs = timeoutMs;
+  }
+  description = "An operation timed out before completing. ACTION: (1) Increase the timeout if the operation legitimately needs more time, (2) Optimize the operation to complete faster, (3) Check for deadlocks or blocking operations, (4) Verify external service dependencies are responsive.";
+};
+function isMatadorError(error) {
+  return error instanceof MatadorError;
+}
+function isNotStartedError(error) {
+  return error instanceof NotStartedError;
+}
+function isTransportNotConnectedError(error) {
+  return error instanceof TransportNotConnectedError;
+}
+function isEventNotRegisteredError(error) {
+  return error instanceof EventNotRegisteredError;
+}
+function isSubscriberNotRegisteredError(error) {
+  return error instanceof SubscriberNotRegisteredError;
+}
+function isMessageMaybePoisonedError(error) {
+  return error instanceof MessageMaybePoisonedError;
+}
+function isIdempotentMessageCannotRetryError(error) {
+  return error instanceof IdempotentMessageCannotRetryError;
+}
+
+// src/errors/checkpoint-errors.ts
+var DuplicateIoKeyError = class extends MatadorError {
+  constructor(key, subscriberName) {
+    super(
+      `Duplicate io key "${key}" in subscriber "${subscriberName}". Each io() call must have a unique key.`
+    );
+    this.key = key;
+    this.subscriberName = subscriberName;
+  }
+  description = "The same io() key was used multiple times in a single subscriber execution. Each io() call must have a unique key to ensure correct checkpoint behavior. ACTION: Ensure all io() keys are unique within the subscriber. For dynamic operations (e.g., loops), include a unique identifier in the key (e.g., `process-item-${item.id}`).";
+};
+var CheckpointStoreError = class extends MatadorError {
+  constructor(operation, envelopeId, cause) {
+    super(
+      `Checkpoint store ${operation} failed for envelope "${envelopeId}": ${cause.message}`
+    );
+    this.operation = operation;
+    this.envelopeId = envelopeId;
+    this.cause = cause;
+  }
+  description = "A checkpoint store operation failed. This may cause issues with resumable subscribers. ACTION: Check the underlying storage system (Redis, etc.) for connectivity issues. The subscriber may re-execute operations that were already completed.";
+};
+function isDuplicateIoKeyError(error) {
+  return error instanceof DuplicateIoKeyError;
+}
+function isCheckpointStoreError(error) {
+  return error instanceof CheckpointStoreError;
+}
+
+// src/topology/types.ts
+function getQualifiedQueueName(namespace, queueName) {
+  return `${namespace}.${queueName}`;
+}
+function getDeadLetterQueueName(namespace, queueName, dlqType) {
+  return `${namespace}.${queueName}.${dlqType}`;
+}
+function getRetryQueueName(namespace, queueName) {
+  return `${namespace}.${queueName}.retry`;
+}
+
+// src/topology/builder.ts
+var TopologyValidationError = class extends Error {
+  constructor(message, issues) {
+    super(message);
+    this.issues = issues;
+    this.name = "TopologyValidationError";
+  }
+  description = "The topology configuration is invalid. Check the issues array for specific validation failures such as missing namespace, invalid queue names, or conflicting settings. This error occurs during Matador initialization and must be fixed in the configuration.";
+};
+var TopologyBuilder = class _TopologyBuilder {
+  /**
+   * Creates a new TopologyBuilder instance.
+   */
+  static create() {
+    return new _TopologyBuilder();
+  }
+  namespace = "";
+  queues = [];
+  deadLetter = {
+    unhandled: { enabled: true },
+    undeliverable: { enabled: true }
+  };
+  retry = {
+    enabled: true,
+    defaultDelayMs: 1e3,
+    maxDelayMs: 3e5
+    // 5 minutes
+  };
+  /**
+   * Sets the namespace prefix for all queues.
+   */
+  withNamespace(namespace) {
+    this.namespace = namespace;
+    return this;
+  }
+  /**
+   * Adds a queue to the topology.
+   */
+  addQueue(name, options = {}) {
+    this.queues.push({ name, ...options });
+    return this;
+  }
+  /**
+   * Alias for addQueue().
+   */
+  queue(name, options = {}) {
+    return this.addQueue(name, options);
+  }
+  /**
+   * Configures dead-letter queue settings.
+   */
+  withDeadLetter(config) {
+    this.deadLetter = {
+      unhandled: config.unhandled ?? this.deadLetter.unhandled,
+      undeliverable: config.undeliverable ?? this.deadLetter.undeliverable
+    };
+    return this;
+  }
+  /**
+   * Configures retry settings.
+   */
+  withRetry(config) {
+    this.retry = {
+      enabled: config.enabled ?? this.retry.enabled,
+      defaultDelayMs: config.defaultDelayMs ?? this.retry.defaultDelayMs,
+      maxDelayMs: config.maxDelayMs ?? this.retry.maxDelayMs
+    };
+    return this;
+  }
+  /**
+   * Disables retry functionality.
+   */
+  withoutRetry() {
+    this.retry = { ...this.retry, enabled: false };
+    return this;
+  }
+  /**
+   * Disables dead-letter queues.
+   */
+  withoutDeadLetter() {
+    this.deadLetter = {
+      unhandled: { enabled: false },
+      undeliverable: { enabled: false }
+    };
+    return this;
+  }
+  /**
+   * Validates the topology configuration.
+   */
+  validate() {
+    const issues = [];
+    if (!this.namespace || this.namespace.trim() === "") {
+      issues.push("Namespace is required");
+    } else if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(this.namespace)) {
+      issues.push(
+        "Namespace must start with a letter and contain only alphanumeric characters, underscores, and hyphens"
+      );
+    }
+    if (this.queues.length === 0) {
+      issues.push("At least one queue is required");
+    }
+    const queueNames = /* @__PURE__ */ new Set();
+    for (const queue of this.queues) {
+      if (!queue.name || queue.name.trim() === "") {
+        issues.push("Queue name cannot be empty");
+      } else if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(queue.name)) {
+        issues.push(
+          `Queue name "${queue.name}" must start with a letter and contain only alphanumeric characters, underscores, and hyphens`
+        );
+      } else if (queueNames.has(queue.name)) {
+        issues.push(`Duplicate queue name: "${queue.name}"`);
+      } else {
+        queueNames.add(queue.name);
+      }
+      if (queue.concurrency !== void 0 && queue.concurrency < 1) {
+        issues.push(`Queue "${queue.name}" concurrency must be at least 1`);
+      }
+      if (queue.consumerTimeout !== void 0 && queue.consumerTimeout < 0) {
+        issues.push(
+          `Queue "${queue.name}" consumer timeout must be non-negative`
+        );
+      }
+    }
+    if (this.retry.enabled) {
+      if (this.retry.defaultDelayMs < 0) {
+        issues.push("Default retry delay must be non-negative");
+      }
+      if (this.retry.maxDelayMs < this.retry.defaultDelayMs) {
+        issues.push(
+          "Max retry delay must be greater than or equal to default delay"
+        );
+      }
+    }
+    return issues;
+  }
+  /**
+   * Builds the topology configuration.
+   * @throws TopologyValidationError if validation fails
+   */
+  build() {
+    const issues = this.validate();
+    if (issues.length > 0) {
+      throw new TopologyValidationError(
+        `Invalid topology: ${issues.join("; ")}`,
+        issues
+      );
+    }
+    return {
+      namespace: this.namespace,
+      queues: [...this.queues],
+      deadLetter: this.deadLetter,
+      retry: this.retry
+    };
+  }
+};
+
+// src/types/common.ts
+function validResult() {
+  return { valid: true, errors: [] };
+}
+function invalidResult(errors) {
+  return { valid: false, errors };
+}
+
+// src/types/envelope.ts
+function createEnvelope(options) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const mergedMetadata = options.universalMetadata || options.metadata ? { ...options.universalMetadata, ...options.metadata } : void 0;
+  return {
+    id: options.id ?? crypto.randomUUID(),
+    data: options.data,
+    docket: {
+      // Routing
+      eventKey: options.eventKey,
+      ...options.eventDescription !== void 0 && {
+        eventDescription: options.eventDescription
+      },
+      targetSubscriber: options.targetSubscriber,
+      ...options.delayMs !== void 0 && options.delayMs > 0 && {
+        scheduledFor: new Date(Date.now() + options.delayMs).toISOString()
+      },
+      // Processing state
+      attempts: 1,
+      createdAt: now,
+      // Observability
+      importance: options.importance,
+      ...options.correlationId !== void 0 && {
+        correlationId: options.correlationId
+      },
+      ...mergedMetadata !== void 0 && { metadata: mergedMetadata }
+    }
+  };
+}
+
+// src/types/event.ts
+var MatadorEvent = class {
+  static key;
+  static description;
+  static aliases;
+  /** Event-specific metadata */
+  metadata;
+};
+
+// src/types/subscriber.ts
+function isSubscriberStub(subscriber) {
+  return "isStub" in subscriber && subscriber.isStub === true;
+}
+function isSubscriber(subscriber) {
+  return "callback" in subscriber && typeof subscriber.callback === "function";
+}
+function isResumableSubscriber(subscriber) {
+  return isSubscriber(subscriber) && subscriber.idempotent === "resumable";
+}
+function createSubscriber(input) {
+  const base = {
+    name: input.name,
+    description: input.description,
+    callback: input.callback,
+    importance: input.importance ?? "should-investigate",
+    ...input.targetQueue !== void 0 && {
+      targetQueue: input.targetQueue
+    },
+    ...input.enabled !== void 0 && { enabled: input.enabled }
+  };
+  if (input.idempotent === "resumable") {
+    return {
+      ...base,
+      idempotent: "resumable",
+      callback: input.callback
+    };
+  }
+  return {
+    ...base,
+    idempotent: input.idempotent ?? "unknown",
+    callback: input.callback
+  };
+}
+function createSubscriberStub(input) {
+  return {
+    name: input.name,
+    description: input.description,
+    isStub: true,
+    idempotent: input.idempotent ?? "unknown",
+    importance: input.importance ?? "should-investigate",
+    ...input.targetQueue !== void 0 && {
+      targetQueue: input.targetQueue
+    },
+    ...input.enabled !== void 0 && { enabled: input.enabled }
+  };
+}
+
+// src/core/fanout.ts
+var FanoutEngine = class {
+  transport;
+  schema;
+  hooks;
+  namespace;
+  defaultQueue;
+  enqueuingCount = 0;
+  constructor(config) {
+    this.transport = config.transport;
+    this.schema = config.schema;
+    this.hooks = config.hooks;
+    this.namespace = config.namespace;
+    this.defaultQueue = config.defaultQueue;
+  }
+  /**
+   * Current count of events being enqueued.
+   */
+  get eventsBeingEnqueuedCount() {
+    return this.enqueuingCount;
+  }
+  /**
+   * Sends an event to all registered subscribers.
+   */
+  async send(eventClass, event, options = {}) {
+    const eventKey = eventClass.key;
+    const subscribers = this.schema.getSubscribers(eventKey);
+    const errors = [];
+    let sent = 0;
+    let skipped = 0;
+    const universalMetadata = await this.hooks.loadUniversalMetadata();
+    const mergedMetadata = event.metadata || options.metadata ? { ...event.metadata, ...options.metadata } : void 0;
+    for (const subscriber of subscribers) {
+      const enabled = await this.isSubscriberEnabled(subscriber);
+      if (!enabled) {
+        skipped++;
+        continue;
+      }
+      const targetQueue = subscriber.targetQueue ?? this.defaultQueue;
+      const qualifiedQueue = getQualifiedQueueName(this.namespace, targetQueue);
+      const envelope = createEnvelope({
+        eventKey,
+        eventDescription: eventClass.description,
+        targetSubscriber: subscriber.name,
+        data: event.data,
+        importance: subscriber.importance ?? "should-investigate",
+        correlationId: options.correlationId,
+        metadata: mergedMetadata,
+        universalMetadata,
+        delayMs: options.delayMs
+      });
+      this.enqueuingCount++;
+      try {
+        const usedTransport = await this.transport.send(
+          qualifiedQueue,
+          envelope,
+          options.delayMs !== void 0 ? { delay: options.delayMs } : void 0
+        );
+        sent++;
+        await this.hooks.onEnqueueSuccess({
+          envelope,
+          queue: qualifiedQueue,
+          transport: usedTransport
+        });
+      } catch (error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        const err = new TransportSendError(qualifiedQueue, cause);
+        errors.push({
+          subscriberName: subscriber.name,
+          queue: qualifiedQueue,
+          error: err
+        });
+        await this.hooks.onEnqueueError({
+          envelope,
+          error: err,
+          transport: this.transport.name
+        });
+      } finally {
+        this.enqueuingCount--;
+      }
+    }
+    return {
+      eventKey,
+      subscribersSent: sent,
+      subscribersSkipped: skipped,
+      errors
+    };
+  }
+  async isSubscriberEnabled(subscriber) {
+    if (!subscriber.enabled) {
+      return true;
+    }
+    try {
+      const result = await subscriber.enabled();
+      return result;
+    } catch {
+      return true;
+    }
+  }
+};
+
+// src/hooks/types.ts
+var consoleLogger = {
+  debug: (message, ...args) => console.debug(message, ...args),
+  info: (message, ...args) => console.info(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args)
+};
+
+// src/hooks/safe-hooks.ts
+var SafeHooks = class {
+  hooks;
+  /** The logger instance used by Matador. */
+  logger;
+  constructor(hooks = {}) {
+    this.hooks = hooks;
+    this.logger = hooks.logger ?? consoleLogger;
+  }
+  async onEnqueueSuccess(context) {
+    await this.safeCall(
+      "onEnqueueSuccess",
+      () => this.hooks.onEnqueueSuccess?.(context)
+    );
+  }
+  async onEnqueueWarning(context) {
+    await this.safeCall(
+      "onEnqueueWarning",
+      () => this.hooks.onEnqueueWarning?.(context)
+    );
+  }
+  async onEnqueueError(context) {
+    await this.safeCall(
+      "onEnqueueError",
+      () => this.hooks.onEnqueueError?.(context)
+    );
+  }
+  async onWorkerWrap(envelope, subscriber, execute) {
+    if (this.hooks.onWorkerWrap) {
+      try {
+        await this.hooks.onWorkerWrap(envelope, subscriber, execute);
+      } catch (error) {
+        this.logger.warn(
+          "[Matador] \u{1F7E1} Hook onWorkerWrap threw an error",
+          error
+        );
+        await execute();
+      }
+    } else {
+      await execute();
+    }
+  }
+  async onWorkerBeforeProcess(envelope, subscriber) {
+    await this.safeCall(
+      "onWorkerBeforeProcess",
+      () => this.hooks.onWorkerBeforeProcess?.(envelope, subscriber)
+    );
+  }
+  async onWorkerSuccess(context) {
+    await this.safeCall(
+      "onWorkerSuccess",
+      () => this.hooks.onWorkerSuccess?.(context)
+    );
+  }
+  async onWorkerError(context) {
+    await this.safeCall(
+      "onWorkerError",
+      () => this.hooks.onWorkerError?.(context)
+    );
+  }
+  async onDecodeError(context) {
+    await this.safeCall(
+      "onDecodeError",
+      () => this.hooks.onDecodeError?.(context)
+    );
+  }
+  async onConnectionStateChange(state) {
+    await this.safeCall(
+      "onConnectionStateChange",
+      () => this.hooks.onConnectionStateChange?.(state)
+    );
+  }
+  async loadUniversalMetadata() {
+    if (!this.hooks.loadUniversalMetadata) {
+      return {};
+    }
+    try {
+      const result = await this.hooks.loadUniversalMetadata();
+      return result ?? {};
+    } catch (error) {
+      this.logger.warn(
+        "[Matador] \u{1F7E1} Hook loadUniversalMetadata threw an error",
+        error
+      );
+      return {};
+    }
+  }
+  async getQueueConcurrency(queueName) {
+    if (!this.hooks.getQueueConcurrency) {
+      return void 0;
+    }
+    try {
+      return await this.hooks.getQueueConcurrency(queueName);
+    } catch (error) {
+      this.logger.warn(
+        "[Matador] \u{1F7E1} Hook getQueueConcurrency threw an error",
+        error
+      );
+      return void 0;
+    }
+  }
+  async getRetryDelay(envelope, attemptNumber) {
+    if (!this.hooks.getRetryDelay) {
+      return void 0;
+    }
+    try {
+      return await this.hooks.getRetryDelay(envelope, attemptNumber);
+    } catch (error) {
+      this.logger.warn("[Matador] \u{1F7E1} Hook getRetryDelay threw an error", error);
+      return void 0;
+    }
+  }
+  async getAttempts(envelope) {
+    if (!this.hooks.getAttempts) {
+      return void 0;
+    }
+    try {
+      return await this.hooks.getAttempts(envelope);
+    } catch (error) {
+      this.logger.warn("[Matador] \u{1F7E1} Hook getAttempts threw an error", error);
+      return void 0;
+    }
+  }
+  async getMaxDeliveries(envelope) {
+    if (!this.hooks.getMaxDeliveries) {
+      return void 0;
+    }
+    try {
+      return await this.hooks.getMaxDeliveries(envelope);
+    } catch (error) {
+      this.logger.warn(
+        "[Matador] \u{1F7E1} Hook getMaxDeliveries threw an error",
+        error
+      );
+      return void 0;
+    }
+  }
+  // === Checkpoint Hooks ===
+  async onCheckpointLoaded(context) {
+    await this.safeCall(
+      "onCheckpointLoaded",
+      () => this.hooks.onCheckpointLoaded?.(context)
+    );
+  }
+  async onCheckpointHit(context) {
+    await this.safeCall(
+      "onCheckpointHit",
+      () => this.hooks.onCheckpointHit?.(context)
+    );
+  }
+  async onCheckpointMiss(context) {
+    await this.safeCall(
+      "onCheckpointMiss",
+      () => this.hooks.onCheckpointMiss?.(context)
+    );
+  }
+  async onCheckpointCleared(context) {
+    await this.safeCall(
+      "onCheckpointCleared",
+      () => this.hooks.onCheckpointCleared?.(context)
+    );
+  }
+  async safeCall(hookName, fn) {
+    try {
+      await fn();
+    } catch (error) {
+      this.logger.warn(`[Matador] \u{1F7E1} Hook ${hookName} threw an error`, error);
+    }
+  }
+};
+
+// src/core/shutdown.ts
+var defaultShutdownConfig = {
+  gracefulShutdownTimeout: 3e4,
+  idlePollingInterval: 1e3,
+  logger: consoleLogger
+};
+var ShutdownManager = class {
+  constructor(getEnqueueCount, stopReceiving, disconnectTransport, config = {}) {
+    this.getEnqueueCount = getEnqueueCount;
+    this.stopReceiving = stopReceiving;
+    this.disconnectTransport = disconnectTransport;
+    this.config = { ...defaultShutdownConfig, ...config };
+  }
+  _state = "running";
+  config;
+  eventsBeingProcessed = 0;
+  acceptingEnqueue = true;
+  /**
+   * Current shutdown state.
+   */
+  get state() {
+    return this._state;
+  }
+  /**
+   * Whether enqueue is currently allowed.
+   */
+  get isEnqueueAllowed() {
+    return this.acceptingEnqueue;
+  }
+  /**
+   * Gets current handler state.
+   */
+  getHandlersState() {
+    const eventsBeingEnqueued = this.getEnqueueCount();
+    return {
+      eventsBeingProcessed: this.eventsBeingProcessed,
+      eventsBeingEnqueued,
+      isIdle: this.eventsBeingProcessed === 0 && eventsBeingEnqueued === 0
+    };
+  }
+  /**
+   * Increment processing counter.
+   */
+  incrementProcessing() {
+    this.eventsBeingProcessed++;
+  }
+  /**
+   * Decrement processing counter.
+   */
+  decrementProcessing() {
+    this.eventsBeingProcessed--;
+  }
+  /**
+   * Performs graceful shutdown.
+   */
+  async shutdown() {
+    if (this._state !== "running") {
+      return;
+    }
+    this._state = "stopping-receive";
+    await this.stopReceiving();
+    this._state = "waiting-handlers";
+    await this.waitForIdle();
+    this._state = "stopping-enqueue";
+    this.acceptingEnqueue = false;
+    this._state = "disconnecting";
+    await this.disconnectTransport();
+    this._state = "stopped";
+  }
+  /**
+   * Forcefully stops without waiting.
+   */
+  async forceStop() {
+    this.acceptingEnqueue = false;
+    await this.stopReceiving();
+    await this.disconnectTransport();
+    this._state = "stopped";
+  }
+  async waitForIdle() {
+    const deadline = Date.now() + this.config.gracefulShutdownTimeout;
+    while (!this.getHandlersState().isIdle) {
+      if (Date.now() > deadline) {
+        this.config.logger.warn(
+          `[Matador] \u26A0\uFE0F Shutdown timeout reached with ${this.eventsBeingProcessed} events still processing`
+        );
+        break;
+      }
+      await this.sleep(this.config.idlePollingInterval);
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/codec/codec.ts
+var CodecDecodeError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "CodecDecodeError";
+  }
+  description = "Failed to decode a message from the transport. This typically indicates corrupted data, incompatible codec versions, or messages from a different system. Check the cause property for the underlying parsing error. The message will be sent to the dead-letter queue for investigation.";
+};
+
+// src/codec/json-codec.ts
+var JsonCodec = class {
+  contentType = "application/json";
+  encode(envelope) {
+    const json = JSON.stringify(envelope);
+    return new TextEncoder().encode(json);
+  }
+  decode(buffer) {
+    if (buffer.length === 0) {
+      throw new CodecDecodeError("Cannot decode empty buffer");
+    }
+    let json;
+    try {
+      json = new TextDecoder("utf-8").decode(buffer);
+    } catch (error) {
+      throw new CodecDecodeError("Invalid UTF-8 encoding", error);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(json);
+    } catch (error) {
+      throw new CodecDecodeError("Invalid JSON", error);
+    }
+    if (!this.isValidEnvelope(parsed)) {
+      throw new CodecDecodeError("Invalid envelope structure");
+    }
+    return parsed;
+  }
+  isValidEnvelope(value) {
+    if (typeof value !== "object" || value === null) {
+      return false;
+    }
+    const envelope = value;
+    if (typeof envelope["id"] !== "string") return false;
+    if (!("data" in envelope)) return false;
+    if (typeof envelope["docket"] !== "object" || envelope["docket"] === null)
+      return false;
+    const docket = envelope["docket"];
+    if (typeof docket["eventKey"] !== "string") return false;
+    if (typeof docket["targetSubscriber"] !== "string") return false;
+    if (typeof docket["attempts"] !== "number") return false;
+    if (typeof docket["createdAt"] !== "string") return false;
+    if (typeof docket["importance"] !== "string") return false;
+    return true;
+  }
+};
+
+// src/codec/rabbitmq-codec.ts
+var HEADERS = {
+  // Routing
+  EVENT_KEY: "x-matador-event-key",
+  TARGET_SUBSCRIBER: "x-matador-subscriber",
+  SCHEDULED_FOR: "x-matador-scheduled-for",
+  ORIGINAL_QUEUE: "x-matador-original-queue",
+  // Processing state
+  ATTEMPTS: "x-matador-attempts",
+  CREATED_AT: "x-matador-created-at",
+  FIRST_ERROR: "x-matador-first-error",
+  LAST_ERROR: "x-matador-last-error",
+  // Observability
+  IMPORTANCE: "x-matador-importance",
+  CORRELATION_ID: "x-matador-correlation-id",
+  // v1 compatibility headers
+  V1_EVENT_ID: "x-event-id",
+  V1_CORRELATION_ID: "x-correlation-id"};
+var RabbitMQCodec = class {
+  contentType = "application/json";
+  encode(envelope) {
+    const { docket } = envelope;
+    const body = {
+      id: envelope.id,
+      data: envelope.data,
+      ...docket.metadata !== void 0 && { metadata: docket.metadata }
+    };
+    const headers = {
+      // Routing
+      [HEADERS.EVENT_KEY]: docket.eventKey,
+      [HEADERS.TARGET_SUBSCRIBER]: docket.targetSubscriber,
+      // Processing state
+      [HEADERS.ATTEMPTS]: docket.attempts,
+      [HEADERS.CREATED_AT]: docket.createdAt,
+      // Observability
+      [HEADERS.IMPORTANCE]: docket.importance
+    };
+    if (docket.scheduledFor !== void 0) {
+      headers[HEADERS.SCHEDULED_FOR] = docket.scheduledFor;
+    }
+    if (docket.originalQueue !== void 0) {
+      headers[HEADERS.ORIGINAL_QUEUE] = docket.originalQueue;
+    }
+    if (docket.firstError !== void 0) {
+      headers[HEADERS.FIRST_ERROR] = docket.firstError;
+    }
+    if (docket.lastError !== void 0) {
+      headers[HEADERS.LAST_ERROR] = docket.lastError;
+    }
+    if (docket.correlationId !== void 0) {
+      headers[HEADERS.CORRELATION_ID] = docket.correlationId;
+    }
+    return {
+      body: new TextEncoder().encode(JSON.stringify(body)),
+      headers,
+      contentType: this.contentType
+    };
+  }
+  decode(body, headers) {
+    if (body.length === 0) {
+      throw new CodecDecodeError("Cannot decode empty buffer");
+    }
+    let json;
+    try {
+      json = new TextDecoder("utf-8").decode(body);
+    } catch (error) {
+      throw new CodecDecodeError("Invalid UTF-8 encoding", error);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(json);
+    } catch (error) {
+      throw new CodecDecodeError("Invalid JSON", error);
+    }
+    if (this.isV1Body(parsed)) {
+      return this.decodeV1(parsed, headers);
+    }
+    if (!this.isV2Body(parsed)) {
+      throw new CodecDecodeError("Invalid message body structure");
+    }
+    return this.decodeV2(parsed, headers);
+  }
+  isV1Body(value) {
+    if (typeof value !== "object" || value === null) return false;
+    const obj = value;
+    return typeof obj["key"] === "string" && typeof obj["targetSubscriber"] === "string" && "data" in obj && !("payload" in obj);
+  }
+  isV2Body(value) {
+    if (typeof value !== "object" || value === null) return false;
+    const obj = value;
+    return typeof obj["id"] === "string" && "data" in obj && !("key" in obj);
+  }
+  decodeV2(body, headers) {
+    const eventKey = this.requireStringHeader(headers, HEADERS.EVENT_KEY);
+    const targetSubscriber = this.requireStringHeader(
+      headers,
+      HEADERS.TARGET_SUBSCRIBER
+    );
+    const attempts = this.requireNumberHeader(headers, HEADERS.ATTEMPTS);
+    const createdAt = this.requireStringHeader(headers, HEADERS.CREATED_AT);
+    const importance = this.requireStringHeader(headers, HEADERS.IMPORTANCE);
+    const scheduledFor = this.optionalStringHeader(
+      headers,
+      HEADERS.SCHEDULED_FOR
+    );
+    const originalQueue = this.optionalStringHeader(
+      headers,
+      HEADERS.ORIGINAL_QUEUE
+    );
+    const firstError = this.optionalStringHeader(headers, HEADERS.FIRST_ERROR);
+    const lastError = this.optionalStringHeader(headers, HEADERS.LAST_ERROR);
+    const correlationId = this.optionalStringHeader(
+      headers,
+      HEADERS.CORRELATION_ID
+    );
+    const docket = {
+      // Routing
+      eventKey,
+      targetSubscriber,
+      ...scheduledFor !== void 0 && { scheduledFor },
+      ...originalQueue !== void 0 && { originalQueue },
+      // Processing state
+      attempts,
+      createdAt,
+      ...firstError !== void 0 && { firstError },
+      ...lastError !== void 0 && { lastError },
+      // Observability
+      importance,
+      ...correlationId !== void 0 && { correlationId },
+      ...body.metadata !== void 0 && { metadata: body.metadata }
+    };
+    return {
+      id: body.id,
+      data: body.data,
+      docket
+    };
+  }
+  /**
+   * Decodes a v1 format message for backwards compatibility.
+   * v1 format: { key, data, metadata, universal, targetSubscriber, ... }
+   */
+  decodeV1(body, headers) {
+    const { event_id, user_id, correlation_id, ...otherUniversal } = body.universal ?? {};
+    const mergedMetadata = {};
+    if (body.metadata && typeof body.metadata === "object") {
+      Object.assign(mergedMetadata, body.metadata);
+    }
+    if (user_id !== void 0 && user_id !== null) {
+      mergedMetadata["user_id"] = user_id;
+    }
+    Object.assign(mergedMetadata, otherUniversal);
+    const attempts = typeof headers[HEADERS.ATTEMPTS] === "number" ? headers[HEADERS.ATTEMPTS] : 1;
+    const importance = typeof headers[HEADERS.IMPORTANCE] === "string" ? headers[HEADERS.IMPORTANCE] : "should-investigate";
+    const correlationId = headers[HEADERS.CORRELATION_ID] ?? headers[HEADERS.V1_CORRELATION_ID] ?? correlation_id ?? void 0;
+    const eventId = headers[HEADERS.V1_EVENT_ID] ?? event_id ?? crypto.randomUUID();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    let scheduledFor;
+    if (body.options?.delayMs) {
+      scheduledFor = new Date(Date.now() + body.options.delayMs).toISOString();
+    }
+    const docket = {
+      // Routing
+      eventKey: body.key,
+      targetSubscriber: body.targetSubscriber,
+      ...scheduledFor !== void 0 && { scheduledFor },
+      // Processing state
+      attempts,
+      createdAt: now,
+      // Observability
+      importance,
+      ...correlationId !== void 0 && { correlationId },
+      ...Object.keys(mergedMetadata).length > 0 && {
+        metadata: mergedMetadata
+      }
+    };
+    return {
+      id: eventId,
+      data: body.data,
+      docket
+    };
+  }
+  requireStringHeader(headers, name) {
+    const value = headers[name];
+    if (value === void 0) {
+      throw new CodecDecodeError(`Missing required header: ${name}`);
+    }
+    if (typeof value !== "string") {
+      throw new CodecDecodeError(
+        `Header ${name} must be string, got ${typeof value}`
+      );
+    }
+    return value;
+  }
+  requireNumberHeader(headers, name) {
+    const value = headers[name];
+    if (value === void 0) {
+      throw new CodecDecodeError(`Missing required header: ${name}`);
+    }
+    if (typeof value !== "number") {
+      throw new CodecDecodeError(
+        `Header ${name} must be number, got ${typeof value}`
+      );
+    }
+    return value;
+  }
+  optionalStringHeader(headers, name) {
+    const value = headers[name];
+    if (value === void 0) return void 0;
+    if (typeof value !== "string") return void 0;
+    return value;
+  }
+};
+
+// src/checkpoint/context.ts
+var ResumableContext = class {
+  checkpoint;
+  usedKeys = /* @__PURE__ */ new Set();
+  store;
+  envelope;
+  subscriber;
+  hooks;
+  constructor(config) {
+    this.store = config.store;
+    this.envelope = config.envelope;
+    this.subscriber = config.subscriber;
+    this.hooks = config.hooks;
+    this.checkpoint = config.existingCheckpoint ?? {
+      envelopeId: config.envelope.id,
+      subscriberName: config.subscriber.name,
+      completedSteps: {}
+    };
+  }
+  get attempt() {
+    return this.envelope.docket.attempts;
+  }
+  get isRetry() {
+    return this.attempt > 1;
+  }
+  async io(key, fn) {
+    if (this.usedKeys.has(key)) {
+      throw new DuplicateIoKeyError(key, this.subscriber.name);
+    }
+    this.usedKeys.add(key);
+    if (key in this.checkpoint.completedSteps) {
+      await this.hooks?.onCheckpointHit?.({
+        envelope: this.envelope,
+        subscriber: this.subscriber,
+        stepKey: key
+      });
+      return this.checkpoint.completedSteps[key];
+    }
+    await this.hooks?.onCheckpointMiss?.({
+      envelope: this.envelope,
+      subscriber: this.subscriber,
+      stepKey: key
+    });
+    const result = await fn();
+    this.checkpoint = {
+      ...this.checkpoint,
+      completedSteps: {
+        ...this.checkpoint.completedSteps,
+        [key]: result
+      }
+    };
+    await this.store.set(this.envelope.id, this.checkpoint);
+    return result;
+  }
+  async all(ops) {
+    const keysInThisCall = /* @__PURE__ */ new Set();
+    for (const [key] of ops) {
+      if (keysInThisCall.has(key)) {
+        throw new DuplicateIoKeyError(key, this.subscriber.name);
+      }
+      keysInThisCall.add(key);
+    }
+    for (const [key] of ops) {
+      if (this.usedKeys.has(key)) {
+        throw new DuplicateIoKeyError(key, this.subscriber.name);
+      }
+    }
+    for (const [key] of ops) {
+      this.usedKeys.add(key);
+    }
+    const results = await Promise.all(
+      ops.map(async ([key, fn]) => {
+        if (key in this.checkpoint.completedSteps) {
+          await this.hooks?.onCheckpointHit?.({
+            envelope: this.envelope,
+            subscriber: this.subscriber,
+            stepKey: key
+          });
+          return this.checkpoint.completedSteps[key];
+        }
+        await this.hooks?.onCheckpointMiss?.({
+          envelope: this.envelope,
+          subscriber: this.subscriber,
+          stepKey: key
+        });
+        const result = await fn();
+        this.checkpoint = {
+          ...this.checkpoint,
+          completedSteps: {
+            ...this.checkpoint.completedSteps,
+            [key]: result
+          }
+        };
+        return result;
+      })
+    );
+    await this.store.set(this.envelope.id, this.checkpoint);
+    return results;
+  }
+  /**
+   * Clears the checkpoint from storage.
+   * Called after successful completion or dead-letter.
+   */
+  async clear() {
+    await this.store.delete(this.envelope.id);
+  }
+  /**
+   * Gets the current checkpoint state.
+   * Useful for debugging and testing.
+   */
+  getCheckpoint() {
+    return this.checkpoint;
+  }
+  /**
+   * Gets the number of cached steps.
+   */
+  get cachedStepCount() {
+    return Object.keys(this.checkpoint.completedSteps).length;
+  }
+};
+
+// src/checkpoint/stores/memory.ts
+var MemoryCheckpointStore = class {
+  checkpoints = /* @__PURE__ */ new Map();
+  async get(envelopeId) {
+    return this.checkpoints.get(envelopeId);
+  }
+  async set(envelopeId, checkpoint) {
+    this.checkpoints.set(envelopeId, checkpoint);
+  }
+  async delete(envelopeId) {
+    this.checkpoints.delete(envelopeId);
+  }
+  /**
+   * Gets the number of stored checkpoints.
+   * Useful for testing.
+   */
+  get size() {
+    return this.checkpoints.size;
+  }
+  /**
+   * Clears all stored checkpoints.
+   * Useful for testing.
+   */
+  clear() {
+    this.checkpoints.clear();
+  }
+  /**
+   * Gets all stored checkpoint IDs.
+   * Useful for testing.
+   */
+  keys() {
+    return [...this.checkpoints.keys()];
+  }
+};
+
+// src/checkpoint/stores/noop.ts
+var NoOpCheckpointStore = class {
+  async get(_envelopeId) {
+    return void 0;
+  }
+  async set(_envelopeId, _checkpoint) {
+  }
+  async delete(_envelopeId) {
+  }
+};
+
+// src/pipeline/pipeline.ts
+var ProcessingPipeline = class {
+  transport;
+  schema;
+  codec;
+  retryPolicy;
+  hooks;
+  checkpointStore;
+  constructor(config) {
+    this.transport = config.transport;
+    this.schema = config.schema;
+    this.codec = config.codec;
+    this.retryPolicy = config.retryPolicy;
+    this.hooks = config.hooks;
+    this.checkpointStore = config.checkpointStore ?? new NoOpCheckpointStore();
+  }
+  /**
+   * Processes a raw message from the transport.
+   */
+  async process(rawMessage, receipt) {
+    const startTime = performance.now();
+    let envelope;
+    try {
+      envelope = this.codec.decode(rawMessage);
+    } catch (error2) {
+      const decodeError = error2 instanceof CodecDecodeError ? error2 : new CodecDecodeError("Unknown decode error", error2);
+      await this.transport.complete(receipt);
+      await this.hooks.onDecodeError({
+        error: decodeError,
+        rawMessage,
+        sourceQueue: receipt.sourceQueue,
+        transport: receipt.sourceTransport
+      });
+      return {
+        success: false,
+        error: decodeError,
+        durationMs: performance.now() - startTime
+      };
+    }
+    const subscriberDef = this.schema.getSubscriberDefinition(
+      envelope.docket.eventKey,
+      envelope.docket.targetSubscriber
+    );
+    if (!subscriberDef) {
+      const error2 = new SubscriberNotRegisteredError(
+        envelope.docket.targetSubscriber,
+        envelope.docket.eventKey
+      );
+      const decision2 = this.getUnhandledRetryDecision(envelope, receipt, error2);
+      await this.handleRetryDecision(receipt, envelope, decision2);
+      return {
+        success: false,
+        envelope,
+        error: error2,
+        decision: decision2,
+        durationMs: performance.now() - startTime
+      };
+    }
+    const subscriber = this.schema.getExecutableSubscriber(
+      envelope.docket.eventKey,
+      envelope.docket.targetSubscriber
+    );
+    if (!subscriber) {
+      const error2 = new SubscriberIsStubError(envelope.docket.targetSubscriber);
+      const decision2 = this.getUnhandledRetryDecision(envelope, receipt, error2);
+      await this.handleRetryDecision(receipt, envelope, decision2);
+      return {
+        success: false,
+        envelope,
+        subscriber: subscriberDef,
+        error: error2,
+        decision: decision2,
+        durationMs: performance.now() - startTime
+      };
+    }
+    let result;
+    let error;
+    let context;
+    const isResumable = isResumableSubscriber(subscriber);
+    let existingCheckpoint;
+    if (isResumable) {
+      existingCheckpoint = await this.checkpointStore.get(envelope.id);
+      if (existingCheckpoint) {
+        await this.hooks.onCheckpointLoaded?.({
+          envelope,
+          subscriber: subscriberDef,
+          checkpoint: existingCheckpoint,
+          cachedSteps: Object.keys(existingCheckpoint.completedSteps).length
+        });
+      }
+      context = new ResumableContext({
+        store: this.checkpointStore,
+        envelope,
+        subscriber: subscriberDef,
+        existingCheckpoint,
+        hooks: {
+          onCheckpointHit: (ctx) => this.hooks.onCheckpointHit?.(ctx),
+          onCheckpointMiss: (ctx) => this.hooks.onCheckpointMiss?.(ctx)
+        }
+      });
+    }
+    await this.hooks.onWorkerWrap(envelope, subscriberDef, async () => {
+      await this.hooks.onWorkerBeforeProcess(envelope, subscriberDef);
+      try {
+        if (isResumable && context) {
+          const resumableCallback = subscriber.callback;
+          result = await resumableCallback(envelope, context);
+        } else {
+          const standardCallback = subscriber.callback;
+          result = await standardCallback(envelope);
+        }
+      } catch (e) {
+        error = e instanceof Error ? e : new Error(String(e));
+      }
+    });
+    const durationMs = performance.now() - startTime;
+    if (!error) {
+      if (context) {
+        await context.clear();
+        await this.hooks.onCheckpointCleared?.({
+          envelope,
+          subscriber: subscriberDef,
+          reason: "success"
+        });
+      }
+      await this.transport.complete(receipt);
+      await this.hooks.onWorkerSuccess({
+        envelope,
+        subscriber: subscriberDef,
+        result,
+        durationMs,
+        transport: receipt.sourceTransport
+      });
+      return {
+        success: true,
+        envelope,
+        subscriber: subscriberDef,
+        durationMs
+      };
+    }
+    const decision = this.retryPolicy.shouldRetry({
+      envelope,
+      error,
+      subscriber: subscriberDef,
+      receipt
+    });
+    envelope.docket.lastError = error.message;
+    envelope.docket.firstError ??= error.message;
+    if (decision.action === "dead-letter" && context) {
+      await context.clear();
+      await this.hooks.onCheckpointCleared?.({
+        envelope,
+        subscriber: subscriberDef,
+        reason: "dead-letter"
+      });
+    }
+    await this.handleRetryDecision(receipt, envelope, decision);
+    await this.hooks.onWorkerError({
+      envelope,
+      subscriber: subscriberDef,
+      error,
+      durationMs,
+      decision,
+      transport: receipt.sourceTransport
+    });
+    return {
+      success: false,
+      envelope,
+      subscriber: subscriberDef,
+      error,
+      decision,
+      durationMs
+    };
+  }
+  async handleRetryDecision(receipt, envelope, decision) {
+    switch (decision.action) {
+      case "retry": {
+        envelope.docket.attempts++;
+        envelope.docket.scheduledFor = new Date(
+          Date.now() + decision.delay
+        ).toISOString();
+        await this.transport.send(receipt.sourceQueue, envelope, {
+          delay: decision.delay
+        });
+        await this.transport.complete(receipt);
+        break;
+      }
+      case "dead-letter": {
+        await this.sendToDeadLetter(
+          receipt,
+          envelope,
+          decision.queue,
+          decision.reason
+        );
+        break;
+      }
+      case "discard": {
+        await this.transport.complete(receipt);
+        break;
+      }
+    }
+  }
+  async sendToDeadLetter(receipt, envelope, dlqName, reason) {
+    envelope.docket.originalQueue ??= receipt.sourceQueue;
+    if (this.transport.sendToDeadLetter) {
+      await this.transport.sendToDeadLetter(receipt, dlqName, envelope, reason);
+    } else {
+      const fullDlqName = `${receipt.sourceQueue}.${dlqName}`;
+      await this.transport.send(fullDlqName, envelope);
+      await this.transport.complete(receipt);
+    }
+  }
+  /**
+   * Gets retry decision for unhandled messages (subscriber not found).
+   * Uses same retry policy logic but sends to 'unhandled' DLQ after max attempts.
+   */
+  getUnhandledRetryDecision(envelope, receipt, error) {
+    const syntheticSubscriber = {
+      name: envelope.docket.targetSubscriber,
+      description: "Synthetic subscriber for unhandled message retry",
+      idempotent: "yes",
+      // Safe to retry unhandled messages
+      importance: envelope.docket.importance ?? "should-investigate"
+    };
+    const decision = this.retryPolicy.shouldRetry({
+      envelope,
+      error,
+      subscriber: syntheticSubscriber,
+      receipt
+    });
+    if (decision.action === "dead-letter") {
+      return {
+        action: "dead-letter",
+        queue: "unhandled",
+        reason: decision.reason
+      };
+    }
+    return decision;
+  }
+};
+
+// src/retry/standard-policy.ts
+var defaultRetryConfig = {
+  maxAttempts: 3,
+  baseDelay: 1e3,
+  maxDelay: 3e5,
+  // 5 minutes
+  backoffMultiplier: 2,
+  maxDeliveries: 5
+};
+var StandardRetryPolicy = class {
+  config;
+  constructor(config = {}) {
+    this.config = { ...defaultRetryConfig, ...config };
+  }
+  shouldRetry(context) {
+    const { envelope, error, subscriber, receipt } = context;
+    const errorMessage = error.message;
+    if (receipt.deliveryCount >= this.config.maxDeliveries) {
+      const poisonError = new MessageMaybePoisonedError(
+        envelope.id,
+        receipt.deliveryCount,
+        this.config.maxDeliveries
+      );
+      return {
+        action: "dead-letter",
+        queue: "undeliverable",
+        reason: poisonError.message
+      };
+    }
+    if (isAssertionError(error)) {
+      return {
+        action: "dead-letter",
+        queue: "undeliverable",
+        reason: `assertion error: ${errorMessage}`
+      };
+    }
+    if (isDontRetry(error)) {
+      return {
+        action: "dead-letter",
+        queue: "undeliverable",
+        reason: errorMessage
+      };
+    }
+    if (isDoRetry(error)) {
+      if (receipt.attemptNumber >= this.config.maxAttempts) {
+        return {
+          action: "dead-letter",
+          queue: "undeliverable",
+          reason: `max attempts exceeded (${this.config.maxAttempts}) with forced retry`
+        };
+      }
+      return {
+        action: "retry",
+        delay: this.getDelay(context)
+      };
+    }
+    if (receipt.attemptNumber >= this.config.maxAttempts) {
+      return {
+        action: "dead-letter",
+        queue: "undeliverable",
+        reason: `max attempts exceeded (${this.config.maxAttempts})`
+      };
+    }
+    if (receipt.redelivered && (subscriber.idempotent === "no" || subscriber.idempotent === "unknown")) {
+      const idempotentError = new IdempotentMessageCannotRetryError(
+        envelope.id,
+        subscriber.name
+      );
+      return {
+        action: "dead-letter",
+        queue: "undeliverable",
+        reason: idempotentError.message
+      };
+    }
+    return {
+      action: "retry",
+      delay: this.getDelay(context)
+    };
+  }
+  getDelay(context) {
+    const attempt = context.receipt.attemptNumber;
+    const delay = this.config.baseDelay * Math.pow(this.config.backoffMultiplier, attempt - 1);
+    return Math.min(delay, this.config.maxDelay);
+  }
+};
+
+// src/schema/types.ts
+function bind(eventClass, subscribers) {
+  return [eventClass, subscribers];
+}
+function isSchemaEntryTuple(entry) {
+  return Array.isArray(entry);
+}
+function installPlugins(schema, plugins) {
+  const result = {};
+  for (const [eventKey, entry] of Object.entries(schema)) {
+    const [eventClass, existingSubscribers] = isSchemaEntryTuple(entry) ? [entry[0], entry[1]] : [entry.eventClass, entry.subscribers];
+    const pluginSubscribers = [];
+    for (const plugin of plugins) {
+      if (!plugin.exclusions?.includes(eventKey)) {
+        pluginSubscribers.push(plugin.subscriber);
+      }
+    }
+    result[eventKey] = [
+      eventClass,
+      [...existingSubscribers, ...pluginSubscribers]
+    ];
+  }
+  return result;
+}
+
+// src/schema/registry.ts
+var SchemaError = class extends Error {
+  description = "A schema operation failed, such as registering a duplicate event or conflicting alias. This is a configuration error that should be fixed during development. Review the event and subscriber registrations to resolve the conflict.";
+  constructor(message) {
+    super(message);
+    this.name = "SchemaError";
+  }
+};
+var SchemaRegistry = class {
+  entries = /* @__PURE__ */ new Map();
+  aliases = /* @__PURE__ */ new Map();
+  /**
+   * Registers an event class with its subscribers.
+   */
+  register(eventClass, subscribers, options = {}) {
+    const key = eventClass.key;
+    if (this.entries.has(key) && !options.override) {
+      throw new SchemaError(`Event "${key}" is already registered`);
+    }
+    this.entries.set(key, {
+      eventClass,
+      subscribers
+    });
+    if (eventClass.aliases) {
+      for (const alias of eventClass.aliases) {
+        if (this.aliases.has(alias) && this.aliases.get(alias) !== key && !options.override) {
+          throw new SchemaError(
+            `Alias "${alias}" is already registered for event "${this.aliases.get(alias)}"`
+          );
+        }
+        this.aliases.set(alias, key);
+      }
+    }
+  }
+  /**
+   * Gets the event class for a given key.
+   */
+  getEventClass(key) {
+    const entry = this.entries.get(key);
+    if (entry) return entry.eventClass;
+    const aliasKey = this.aliases.get(key);
+    if (aliasKey) {
+      return this.entries.get(aliasKey)?.eventClass;
+    }
+    return void 0;
+  }
+  /**
+   * Gets all subscribers for an event key.
+   */
+  getSubscribers(eventKey) {
+    const entry = this.getEntry(eventKey);
+    return entry?.subscribers ?? [];
+  }
+  /**
+   * Gets a specific subscriber by event key and subscriber name.
+   */
+  getSubscriber(eventKey, subscriberName) {
+    const subscribers = this.getSubscribers(eventKey);
+    return subscribers.find((s) => s.name === subscriberName);
+  }
+  /**
+   * Gets a subscriber definition for the pipeline.
+   */
+  getSubscriberDefinition(eventKey, subscriberName) {
+    const subscriber = this.getSubscriber(eventKey, subscriberName);
+    if (!subscriber) return void 0;
+    const def = {
+      name: subscriber.name,
+      description: subscriber.description,
+      idempotent: subscriber.idempotent ?? "unknown",
+      importance: subscriber.importance ?? "should-investigate"
+    };
+    if (subscriber.targetQueue !== void 0) {
+      def.targetQueue = subscriber.targetQueue;
+    }
+    return def;
+  }
+  /**
+   * Gets a subscriber with callback for execution.
+   */
+  getExecutableSubscriber(eventKey, subscriberName) {
+    const subscriber = this.getSubscriber(eventKey, subscriberName);
+    if (!subscriber || !isSubscriber(subscriber)) return void 0;
+    return subscriber;
+  }
+  /**
+   * Gets the event class by alias.
+   */
+  getEventByAlias(alias) {
+    const key = this.aliases.get(alias);
+    if (!key) return void 0;
+    return this.entries.get(key)?.eventClass;
+  }
+  /**
+   * Checks if an event key is registered.
+   */
+  hasEvent(key) {
+    return this.entries.has(key) || this.aliases.has(key);
+  }
+  /**
+   * Gets all registered event keys.
+   */
+  getEventKeys() {
+    return [...this.entries.keys()];
+  }
+  /**
+   * Validates the schema for issues.
+   */
+  validate() {
+    const issues = [];
+    for (const [key, entry] of this.entries) {
+      const names = /* @__PURE__ */ new Set();
+      for (const subscriber of entry.subscribers) {
+        if (names.has(subscriber.name)) {
+          issues.push({
+            severity: "error",
+            eventKey: key,
+            message: `Duplicate subscriber name: "${subscriber.name}"`
+          });
+        }
+        names.add(subscriber.name);
+      }
+      const stubs = entry.subscribers.filter((s) => !isSubscriber(s));
+      if (stubs.length === entry.subscribers.length && stubs.length > 0) {
+        issues.push({
+          severity: "warning",
+          eventKey: key,
+          message: "All subscribers are stubs, no local handlers"
+        });
+      }
+    }
+    return {
+      valid: issues.filter((i) => i.severity === "error").length === 0,
+      issues
+    };
+  }
+  /**
+   * Clears all registered entries.
+   */
+  clear() {
+    this.entries.clear();
+    this.aliases.clear();
+  }
+  getEntry(eventKey) {
+    const entry = this.entries.get(eventKey);
+    if (entry) return entry;
+    const aliasKey = this.aliases.get(eventKey);
+    if (aliasKey) {
+      return this.entries.get(aliasKey);
+    }
+    return void 0;
+  }
+};
+
+// src/core/matador.ts
+var Matador = class {
+  transport;
+  topology;
+  schema;
+  codec;
+  retryPolicy;
+  hooks;
+  pipeline;
+  fanout;
+  shutdownManager;
+  consumeFrom;
+  subscriptions = [];
+  started = false;
+  /**
+   * Creates a new Matador instance.
+   *
+   * @param config - Static configuration (transport, topology, schema, etc.)
+   * @param hooks - Lifecycle hooks for logging, monitoring, and dynamic configuration.
+   *                Passed separately to support NestJS dependency injection.
+   */
+  constructor(config, hooks) {
+    this.transport = config.transport;
+    this.topology = config.topology;
+    this.consumeFrom = config.consumeFrom ?? [];
+    this.schema = new SchemaRegistry();
+    this.codec = config.codec ?? new JsonCodec();
+    this.retryPolicy = config.retryPolicy ?? new StandardRetryPolicy();
+    this.hooks = new SafeHooks(hooks);
+    this.registerSchema(config.schema);
+    this.pipeline = new ProcessingPipeline({
+      transport: this.transport,
+      schema: this.schema,
+      codec: this.codec,
+      retryPolicy: this.retryPolicy,
+      hooks: this.hooks,
+      checkpointStore: config.checkpointStore
+    });
+    const defaultQueue = this.topology.queues[0]?.name ?? "default";
+    this.fanout = new FanoutEngine({
+      transport: this.transport,
+      schema: this.schema,
+      hooks: this.hooks,
+      namespace: this.topology.namespace,
+      defaultQueue
+    });
+    this.shutdownManager = new ShutdownManager(
+      () => this.fanout.eventsBeingEnqueuedCount,
+      () => this.stopReceiving(),
+      () => this.transport.disconnect(),
+      config.shutdownConfig
+    );
+  }
+  /**
+   * Registers an event class with its subscribers.
+   */
+  register(eventClass, subscribers) {
+    this.schema.register(eventClass, subscribers);
+    return this;
+  }
+  /**
+   * Registers events from a schema object.
+   * Supports both object format and tuple format entries.
+   *
+   * @example
+   * ```typescript
+   * // Tuple format
+   * matador.registerSchema({
+   *   [UserCreatedEvent.key]: [UserCreatedEvent, [emailSubscriber]],
+   *   [OrderPlacedEvent.key]: [OrderPlacedEvent, [invoiceSubscriber]],
+   * });
+   *
+   * // Object format
+   * matador.registerSchema({
+   *   [UserCreatedEvent.key]: { eventClass: UserCreatedEvent, subscribers: [emailSubscriber] },
+   * });
+   * ```
+   */
+  registerSchema(schema) {
+    for (const entry of Object.values(schema)) {
+      if (isSchemaEntryTuple(entry)) {
+        const [eventClass, subscribers] = entry;
+        this.schema.register(eventClass, subscribers);
+      } else {
+        this.schema.register(entry.eventClass, entry.subscribers);
+      }
+    }
+    return this;
+  }
+  /**
+   * Starts Matador - connects transport and begins consuming.
+   * This method is idempotent - calling it multiple times is safe.
+   */
+  async start() {
+    if (this.started) {
+      return;
+    }
+    const validation = this.schema.validate();
+    if (!validation.valid) {
+      const errors = validation.issues.filter((i) => i.severity === "error");
+      throw new InvalidSchemaError(
+        "Schema validation failed",
+        errors.map((e) => e.message).join(", ")
+      );
+    }
+    await this.transport.connect();
+    await this.transport.applyTopology(this.topology);
+    for (const queueName of this.consumeFrom) {
+      const qualifiedName = getQualifiedQueueName(
+        this.topology.namespace,
+        queueName
+      );
+      const queueDef = this.topology.queues.find((q) => q.name === queueName);
+      const subscription = await this.transport.subscribe(
+        qualifiedName,
+        async (envelope, receipt) => {
+          this.shutdownManager.incrementProcessing();
+          try {
+            const rawMessage = this.codec.encode(envelope);
+            await this.pipeline.process(rawMessage, receipt);
+          } finally {
+            this.shutdownManager.decrementProcessing();
+          }
+        },
+        queueDef?.concurrency !== void 0 ? { concurrency: queueDef.concurrency } : void 0
+      );
+      this.subscriptions.push(subscription);
+    }
+    this.started = true;
+  }
+  async send(eventOrClass, dataOrOptions, maybeOptions) {
+    if (!this.started) {
+      throw new NotStartedError("send");
+    }
+    if (!this.shutdownManager.isEnqueueAllowed) {
+      throw new ShutdownInProgressError();
+    }
+    const isEventClass = typeof eventOrClass === "function" && "key" in eventOrClass;
+    if (isEventClass) {
+      const eventClass = eventOrClass;
+      const data = dataOrOptions;
+      const options = maybeOptions;
+      const event = new eventClass(data);
+      return this.fanout.send(eventClass, event, options);
+    } else {
+      const event = eventOrClass;
+      const options = dataOrOptions;
+      const eventClass = event.constructor;
+      return this.fanout.send(eventClass, event, options);
+    }
+  }
+  /**
+   * Gets current handler state.
+   */
+  getHandlersState() {
+    return this.shutdownManager.getHandlersState();
+  }
+  /**
+   * Checks if Matador is idle (no processing or enqueuing).
+   */
+  isIdle() {
+    return this.shutdownManager.getHandlersState().isIdle;
+  }
+  /**
+   * Waits for all handlers to become idle.
+   */
+  async waitForIdle(timeoutMs = 3e4) {
+    const deadline = Date.now() + timeoutMs;
+    while (!this.isIdle()) {
+      if (Date.now() > deadline) {
+        return false;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return true;
+  }
+  /**
+   * Gracefully shuts down Matador.
+   */
+  async shutdown() {
+    if (!this.started) {
+      return;
+    }
+    await this.shutdownManager.shutdown();
+    this.started = false;
+  }
+  /**
+   * Checks if transport is connected.
+   */
+  isConnected() {
+    return this.transport.isConnected();
+  }
+  async stopReceiving() {
+    for (const subscription of this.subscriptions) {
+      await subscription.unsubscribe();
+    }
+    this.subscriptions.length = 0;
+  }
+};
+
+// src/transport/capabilities.ts
+function supportsDeliveryMode(capabilities, mode) {
+  return capabilities.deliveryModes.includes(mode);
+}
+function supportsDelayedMessages(capabilities) {
+  return capabilities.delayedMessages;
+}
+function hasNativeDeadLetter(capabilities) {
+  return capabilities.deadLetterRouting === "native";
+}
+
+// src/transport/connection-manager.ts
+var defaultConnectionConfig = {
+  maxReconnectAttempts: 0,
+  // Infinite
+  initialReconnectDelay: 1e3,
+  maxReconnectDelay: 3e4,
+  backoffMultiplier: 2
+};
+var ConnectionManager = class {
+  constructor(connectFn, disconnectFn, config = {}) {
+    this.connectFn = connectFn;
+    this.disconnectFn = disconnectFn;
+    this.config = { ...defaultConnectionConfig, ...config };
+  }
+  _state = { status: "disconnected" };
+  listeners = /* @__PURE__ */ new Set();
+  reconnectTimer = null;
+  config;
+  /**
+   * Current connection state.
+   */
+  get state() {
+    return this._state;
+  }
+  /**
+   * Whether currently connected.
+   */
+  isConnected() {
+    return this._state.status === "connected";
+  }
+  /**
+   * Register a callback for connection state changes.
+   */
+  onStateChange(callback) {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+  /**
+   * Attempt to establish connection.
+   */
+  async connect() {
+    if (this._state.status === "connected") {
+      return;
+    }
+    this.setState({ status: "connecting", attempt: 1 });
+    try {
+      await this.connectFn();
+      this.setState({ status: "connected" });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      await this.handleConnectionFailure(err, 1);
+    }
+  }
+  /**
+   * Gracefully disconnect.
+   */
+  async disconnect() {
+    this.clearReconnectTimer();
+    if (this._state.status === "disconnected") {
+      return;
+    }
+    try {
+      await this.disconnectFn();
+    } finally {
+      this.setState({ status: "disconnected" });
+    }
+  }
+  /**
+   * Called by transport when connection is lost unexpectedly.
+   */
+  async handleConnectionLost(error) {
+    if (this._state.status === "disconnected") {
+      return;
+    }
+    this.setState({ status: "reconnecting", attempt: 1, lastError: error });
+    await this.attemptReconnect(1);
+  }
+  /**
+   * Calculate delay for a given attempt using exponential backoff.
+   */
+  calculateDelay(attempt) {
+    const delay = this.config.initialReconnectDelay * Math.pow(this.config.backoffMultiplier, attempt - 1);
+    return Math.min(delay, this.config.maxReconnectDelay);
+  }
+  setState(state) {
+    this._state = state;
+    for (const listener of this.listeners) {
+      try {
+        listener(state);
+      } catch {
+      }
+    }
+  }
+  async handleConnectionFailure(error, attempt) {
+    if (this.shouldGiveUp(attempt)) {
+      this.setState({ status: "failed", error });
+      throw error;
+    }
+    this.setState({
+      status: "reconnecting",
+      attempt: attempt + 1,
+      lastError: error
+    });
+    await this.attemptReconnect(attempt + 1);
+  }
+  shouldGiveUp(attempt) {
+    return this.config.maxReconnectAttempts > 0 && attempt >= this.config.maxReconnectAttempts;
+  }
+  async attemptReconnect(attempt) {
+    const delay = this.calculateDelay(attempt);
+    await new Promise((resolve) => {
+      this.reconnectTimer = setTimeout(resolve, delay);
+    });
+    if (this._state.status === "disconnected") {
+      return;
+    }
+    try {
+      await this.connectFn();
+      this.setState({ status: "connected" });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      await this.handleConnectionFailure(err, attempt);
+    }
+  }
+  clearReconnectTimer() {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+};
+
+// src/transport/local/local-transport.ts
+var localCapabilities = {
+  deliveryModes: ["at-least-once", "at-most-once"],
+  delayedMessages: true,
+  // Implemented with setTimeout
+  deadLetterRouting: "manual",
+  attemptTracking: false,
+  concurrencyModel: "none",
+  ordering: "queue",
+  priorities: false
+};
+var LocalTransport = class {
+  name = "local";
+  capabilities = localCapabilities;
+  connected = false;
+  queues = /* @__PURE__ */ new Map();
+  subscriptions = /* @__PURE__ */ new Map();
+  completedMessages = [];
+  delayedTimers = /* @__PURE__ */ new Set();
+  messageIdCounter = 0;
+  logger;
+  constructor(logger) {
+    this.logger = logger ?? consoleLogger;
+  }
+  async connect() {
+    this.connected = true;
+  }
+  async disconnect() {
+    for (const timer of this.delayedTimers) {
+      clearTimeout(timer);
+    }
+    this.delayedTimers.clear();
+    for (const subs of this.subscriptions.values()) {
+      for (const sub of subs) {
+        sub.active = false;
+      }
+    }
+    this.connected = false;
+  }
+  isConnected() {
+    return this.connected;
+  }
+  async applyTopology(topology) {
+    if (!this.connected) {
+      throw new TransportNotConnectedError(this.name, "applyTopology");
+    }
+    for (const queueDef of topology.queues) {
+      const queueName = `${topology.namespace}.${queueDef.name}`;
+      if (!this.queues.has(queueName)) {
+        this.queues.set(queueName, []);
+      }
+    }
+  }
+  async send(queue, envelope, options) {
+    if (!this.connected) {
+      throw new TransportNotConnectedError(this.name, "send");
+    }
+    if (options?.delay !== void 0 && options.delay > 0) {
+      this.scheduleDelayedMessage(queue, envelope, options.delay);
+      return this.name;
+    }
+    await this.enqueue(queue, envelope);
+    return this.name;
+  }
+  /**
+   * Schedules a message for delayed delivery.
+   * Returns immediately (non-blocking) to match real transport behavior.
+   */
+  scheduleDelayedMessage(queue, envelope, delayMs) {
+    const timer = setTimeout(() => {
+      this.delayedTimers.delete(timer);
+      this.enqueue(queue, envelope).catch((error) => {
+        this.logger.error(
+          "[Matador] \u{1F534} Failed to enqueue delayed message",
+          error
+        );
+      });
+    }, delayMs);
+    this.delayedTimers.add(timer);
+  }
+  async enqueue(queue, envelope) {
+    const messages = this.getOrCreateQueue(queue);
+    const messageId = `${++this.messageIdCounter}`;
+    const queuedMessage = {
+      envelope,
+      id: messageId,
+      completed: false
+    };
+    messages.push(queuedMessage);
+    await this.deliverToSubscribers(queue, queuedMessage);
+  }
+  async deliverToSubscribers(queue, message) {
+    const subs = this.subscriptions.get(queue);
+    if (!subs) return;
+    for (const sub of subs) {
+      if (!sub.active || message.completed) continue;
+      const receipt = {
+        handle: message,
+        redelivered: false,
+        attemptNumber: message.envelope.docket.attempts,
+        deliveryCount: message.envelope.docket.attempts,
+        sourceQueue: queue,
+        sourceTransport: this.name
+      };
+      try {
+        await sub.handler(message.envelope, receipt);
+      } catch (error) {
+        this.logger.error("\u{1F534} Handler error in message processing", error);
+      }
+    }
+  }
+  async subscribe(queue, handler, options = {}) {
+    if (!this.connected) {
+      throw new TransportNotConnectedError(this.name, "subscribe");
+    }
+    const subscription = {
+      handler,
+      options,
+      active: true
+    };
+    const subs = this.subscriptions.get(queue) ?? [];
+    subs.push(subscription);
+    this.subscriptions.set(queue, subs);
+    const messages = this.queues.get(queue) ?? [];
+    for (const message of messages) {
+      if (message.completed) continue;
+      await this.deliverToSubscribers(queue, message);
+    }
+    return {
+      unsubscribe: async () => {
+        subscription.active = false;
+        const remaining = subs.filter((s) => s !== subscription);
+        if (remaining.length > 0) {
+          this.subscriptions.set(queue, remaining);
+        } else {
+          this.subscriptions.delete(queue);
+        }
+      },
+      get isActive() {
+        return subscription.active;
+      }
+    };
+  }
+  async complete(receipt) {
+    const message = receipt.handle;
+    message.completed = true;
+    this.completedMessages.push(receipt);
+  }
+  async sendToDeadLetter(receipt, dlqName, envelope, _reason) {
+    const dlqQueueName = `${receipt.sourceQueue}.${dlqName}`;
+    await this.enqueue(dlqQueueName, envelope);
+    await this.complete(receipt);
+  }
+  // Test helpers
+  /**
+   * Gets the current size of a queue.
+   */
+  getQueueSize(queue) {
+    const messages = this.queues.get(queue);
+    if (!messages) return 0;
+    return messages.filter((m) => !m.completed).length;
+  }
+  /**
+   * Gets all completed message receipts.
+   */
+  getCompleted() {
+    return this.completedMessages;
+  }
+  /**
+   * Gets pending (uncompleted) messages from a queue.
+   */
+  getPendingMessages(queue) {
+    const messages = this.queues.get(queue);
+    if (!messages) return [];
+    return messages.filter((m) => !m.completed).map((m) => m.envelope);
+  }
+  /**
+   * Clears all state (for test isolation).
+   */
+  clear() {
+    this.queues.clear();
+    this.subscriptions.clear();
+    this.completedMessages.length = 0;
+    this.messageIdCounter = 0;
+    for (const timer of this.delayedTimers) {
+      clearTimeout(timer);
+    }
+    this.delayedTimers.clear();
+  }
+  /**
+   * Receives one message from the queue without a subscription.
+   * Useful for testing.
+   */
+  async receiveOne(queue) {
+    const messages = this.queues.get(queue);
+    if (!messages) return null;
+    const pending = messages.find((m) => !m.completed);
+    if (!pending) return null;
+    const receipt = {
+      handle: pending,
+      redelivered: false,
+      attemptNumber: pending.envelope.docket.attempts,
+      deliveryCount: pending.envelope.docket.attempts,
+      sourceQueue: queue,
+      sourceTransport: this.name
+    };
+    return { envelope: pending.envelope, receipt };
+  }
+  getOrCreateQueue(queue) {
+    let messages = this.queues.get(queue);
+    if (!messages) {
+      messages = [];
+      this.queues.set(queue, messages);
+    }
+    return messages;
+  }
+};
+
+// src/transport/multi/multi-transport.ts
+var SOURCE_TRANSPORT = /* @__PURE__ */ Symbol("sourceTransport");
+function getSourceTransport(receipt) {
+  return receipt[SOURCE_TRANSPORT];
+}
+function mergeCapabilities(transports) {
+  const primary = transports[0];
+  if (!primary) {
+    throw new Error("At least one transport is required");
+  }
+  return primary.capabilities;
+}
+var MultiTransport = class {
+  name;
+  capabilities;
+  primary;
+  /** All available transports, in order of preference (primary first). */
+  transports;
+  /** Whether fallback to secondary transports is enabled. */
+  fallbackEnabled;
+  hooks;
+  connected = false;
+  constructor(config, hooks = {}) {
+    const primary = config.transports[0];
+    if (!primary) {
+      throw new Error("At least one transport is required");
+    }
+    this.primary = primary;
+    this.transports = config.transports;
+    this.fallbackEnabled = config.fallbackEnabled ?? true;
+    this.hooks = hooks;
+    this.name = `multi(${this.transports.map((t) => t.name).join(",")})`;
+    this.capabilities = mergeCapabilities(this.transports);
+  }
+  async connect() {
+    await Promise.all(this.transports.map((t) => t.connect()));
+    this.connected = true;
+  }
+  async disconnect() {
+    await Promise.all(this.transports.map((t) => t.disconnect()));
+    this.connected = false;
+  }
+  isConnected() {
+    return this.connected && this.primary.isConnected();
+  }
+  async applyTopology(topology) {
+    await Promise.all(this.transports.map((t) => t.applyTopology(topology)));
+  }
+  async send(queue, envelope, options) {
+    const selectedTransport = await this.selectTransport();
+    if (!this.fallbackEnabled) {
+      return selectedTransport.send(queue, envelope, options);
+    }
+    const transportOrder = this.getTransportOrder(selectedTransport);
+    const errors = [];
+    for (let i = 0; i < transportOrder.length; i++) {
+      const transport = transportOrder[i];
+      try {
+        return await transport.send(queue, envelope, options);
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        errors.push(err);
+        const nextTransport = transportOrder[i + 1];
+        if (nextTransport && this.hooks.onEnqueueFallback) {
+          this.hooks.onEnqueueFallback({
+            envelope,
+            queue,
+            failedTransport: transport.name,
+            nextTransport: nextTransport.name,
+            error: err
+          });
+        }
+      }
+    }
+    throw new AllTransportsFailedError(queue, errors);
+  }
+  /**
+   * Selects the transport to use based on the getDesiredBackend hook.
+   */
+  async selectTransport() {
+    if (!this.hooks.getDesiredBackend) {
+      return this.primary;
+    }
+    try {
+      const desiredBackend = await this.hooks.getDesiredBackend();
+      if (!desiredBackend) {
+        return this.primary;
+      }
+      const selected = this.transports.find((t) => t.name === desiredBackend);
+      if (selected) {
+        return selected;
+      }
+      return this.primary;
+    } catch {
+      return this.primary;
+    }
+  }
+  /**
+   * Returns transports in order, with the selected transport first.
+   */
+  getTransportOrder(selected) {
+    if (selected === this.primary) {
+      return this.transports;
+    }
+    return [selected, ...this.transports.filter((t) => t !== selected)];
+  }
+  async subscribe(queue, handler, options) {
+    const subscriptions = await Promise.all(
+      this.transports.map((transport) => {
+        const wrappedHandler = (envelope, receipt) => {
+          const taggedReceipt = Object.assign(receipt, {
+            [SOURCE_TRANSPORT]: transport
+          });
+          return handler(envelope, taggedReceipt);
+        };
+        return transport.subscribe(queue, wrappedHandler, options);
+      })
+    );
+    return {
+      unsubscribe: async () => {
+        await Promise.all(subscriptions.map((s) => s.unsubscribe()));
+      },
+      get isActive() {
+        return subscriptions.some((s) => s.isActive);
+      }
+    };
+  }
+  async complete(receipt) {
+    const transport = getSourceTransport(receipt) ?? this.primary;
+    return transport.complete(receipt);
+  }
+  async sendToDeadLetter(receipt, dlqName, envelope, reason) {
+    const transport = getSourceTransport(receipt) ?? this.primary;
+    if (transport.sendToDeadLetter) {
+      return transport.sendToDeadLetter(receipt, dlqName, envelope, reason);
+    }
+    throw new Error("Transport does not support dead letter routing");
+  }
+};
+var RabbitMQTransport = class {
+  name = "rabbitmq";
+  _capabilities = {
+    deliveryModes: ["at-least-once"],
+    delayedMessages: false,
+    deadLetterRouting: "native",
+    attemptTracking: true,
+    concurrencyModel: "prefetch",
+    ordering: "none",
+    priorities: true
+  };
+  get capabilities() {
+    return this._capabilities;
+  }
+  connection = null;
+  publishChannel = null;
+  connectionManager;
+  queueChannels = /* @__PURE__ */ new Map();
+  topology = null;
+  codec = new RabbitMQCodec();
+  config;
+  logger;
+  delayedExchangeAvailable = false;
+  constructor(config) {
+    this.logger = config.logger ?? consoleLogger;
+    this.config = {
+      url: config.url,
+      connection: config.connection ?? {},
+      quorumQueues: config.quorumQueues ?? true,
+      defaultPrefetch: config.defaultPrefetch ?? 10,
+      enableDelayedMessages: config.enableDelayedMessages ?? true
+    };
+    this.connectionManager = new ConnectionManager(
+      () => this.doConnect(),
+      () => this.doDisconnect(),
+      this.config.connection
+    );
+  }
+  async connect() {
+    await this.connectionManager.connect();
+  }
+  async disconnect() {
+    await this.connectionManager.disconnect();
+  }
+  isConnected() {
+    return this.connectionManager.isConnected();
+  }
+  async applyTopology(topology) {
+    this.topology = topology;
+    if (!this.publishChannel) {
+      throw new TransportNotConnectedError(this.name, "applyTopology");
+    }
+    const channel = this.publishChannel;
+    const mainExchange = this.getMainExchangeName(topology.namespace);
+    await channel.assertExchange(mainExchange, "direct", { durable: true });
+    const dlxExchange = this.getDLXExchangeName(topology.namespace);
+    if (topology.deadLetter.unhandled.enabled || topology.deadLetter.undeliverable.enabled) {
+      await channel.assertExchange(dlxExchange, "direct", { durable: true });
+    }
+    if (this.config.enableDelayedMessages) {
+      await this.setupDelayedExchange(topology.namespace);
+    }
+    for (const queueDef of topology.queues) {
+      await this.assertWorkQueue(channel, topology, queueDef);
+    }
+    if (topology.deadLetter.unhandled.enabled) {
+      await this.assertDeadLetterQueues(channel, topology, "unhandled");
+    }
+    if (topology.deadLetter.undeliverable.enabled) {
+      await this.assertDeadLetterQueues(channel, topology, "undeliverable");
+    }
+  }
+  async send(queue, envelope, options) {
+    if (!this.publishChannel || !this.topology) {
+      throw new TransportNotConnectedError(this.name, "send");
+    }
+    const encoded = this.codec.encode(envelope);
+    const buffer = Buffer.from(encoded.body);
+    const publishOptions = {
+      persistent: true,
+      contentType: encoded.contentType,
+      messageId: envelope.id,
+      timestamp: Date.now(),
+      headers: encoded.headers
+    };
+    if (options?.priority !== void 0) {
+      publishOptions.priority = options.priority;
+    }
+    if (options?.delay !== void 0 && options.delay > 0) {
+      if (!this.delayedExchangeAvailable) {
+        throw new DelayedMessagesNotSupportedError(this.name);
+      }
+      const delayedExchange = this.getDelayedExchangeName(
+        this.topology.namespace
+      );
+      publishOptions.headers = {
+        ...publishOptions.headers,
+        "x-delay": options.delay
+      };
+      this.publishChannel.publish(
+        delayedExchange,
+        queue,
+        buffer,
+        publishOptions
+      );
+      return this.name;
+    }
+    if (options?.transport?.rabbitmq?.expiration !== void 0) {
+      publishOptions.expiration = String(options.transport.rabbitmq.expiration);
+    }
+    if (options?.transport?.rabbitmq?.persistent !== void 0) {
+      publishOptions.persistent = options.transport.rabbitmq.persistent;
+    }
+    const routingKey = options?.transport?.rabbitmq?.routingKey ?? queue;
+    const exchange = this.getMainExchangeName(this.topology.namespace);
+    this.publishChannel.publish(exchange, routingKey, buffer, publishOptions);
+    return this.name;
+  }
+  async subscribe(queue, handler, options = {}) {
+    if (!this.connection || !this.topology) {
+      throw new TransportNotConnectedError(this.name, "subscribe");
+    }
+    const queueChannel = await this.getOrCreateQueueChannel(queue, options);
+    const { channel } = queueChannel;
+    const consumer = {
+      consumerTag: "",
+      queue,
+      active: true
+    };
+    const { consumerTag } = await channel.consume(
+      queue,
+      async (msg) => {
+        if (!msg || !consumer.active) return;
+        const attemptNumber = this.getAttemptNumber(msg);
+        const receipt = {
+          handle: { channel, msg },
+          redelivered: msg.fields.redelivered,
+          attemptNumber,
+          deliveryCount: this.getDeliveryCount(msg, attemptNumber),
+          sourceQueue: queue,
+          sourceTransport: this.name
+        };
+        try {
+          const headers = msg.properties.headers ?? {};
+          const envelope = this.codec.decode(
+            new Uint8Array(msg.content),
+            headers
+          );
+          await handler(envelope, receipt);
+        } catch (error) {
+          this.logger.error(
+            "[Matador] \u{1F534} Handler error in message processing",
+            error
+          );
+        }
+      },
+      { noAck: false }
+      // Always manually ack
+    );
+    consumer.consumerTag = consumerTag;
+    queueChannel.consumers.push(consumer);
+    return {
+      unsubscribe: async () => {
+        consumer.active = false;
+        try {
+          await channel.cancel(consumerTag);
+        } catch {
+        }
+        const idx = queueChannel.consumers.indexOf(consumer);
+        if (idx !== -1) {
+          queueChannel.consumers.splice(idx, 1);
+        }
+        if (queueChannel.consumers.length === 0) {
+          try {
+            await channel.close();
+          } catch {
+          }
+          this.queueChannels.delete(queue);
+        }
+      },
+      get isActive() {
+        return consumer.active;
+      }
+    };
+  }
+  async complete(receipt) {
+    const { channel, msg } = receipt.handle;
+    try {
+      channel.ack(msg);
+    } catch {
+    }
+  }
+  async sendToDeadLetter(receipt, dlqName, envelope, reason) {
+    if (!this.publishChannel || !this.topology) {
+      throw new TransportNotConnectedError(this.name, "sendToDeadLetter");
+    }
+    const dlqEnvelope = {
+      ...envelope,
+      docket: {
+        ...envelope.docket,
+        lastError: reason,
+        firstError: envelope.docket.firstError ?? reason,
+        originalQueue: receipt.sourceQueue
+      }
+    };
+    const encoded = this.codec.encode(dlqEnvelope);
+    const buffer = Buffer.from(encoded.body);
+    const dlxExchange = this.getDLXExchangeName(this.topology.namespace);
+    const dlqQueueName = `${receipt.sourceQueue}.${dlqName}`;
+    const publishOptions = {
+      persistent: true,
+      contentType: encoded.contentType,
+      messageId: envelope.id,
+      timestamp: Date.now(),
+      headers: {
+        ...encoded.headers,
+        "x-matador-dead-letter-reason": reason
+      }
+    };
+    this.publishChannel.publish(
+      dlxExchange,
+      dlqQueueName,
+      buffer,
+      publishOptions
+    );
+    await this.complete(receipt);
+  }
+  // Private methods
+  /**
+   * Gets or creates a dedicated channel for a queue subscription.
+   *
+   * We create separate channels per subscribed queue to enable independent
+   * prefetch/concurrency control.
+   */
+  async getOrCreateQueueChannel(queue, options) {
+    const existing = this.queueChannels.get(queue);
+    if (existing) {
+      return existing;
+    }
+    if (!this.connection) {
+      throw new TransportNotConnectedError(
+        this.name,
+        "getOrCreateQueueChannel"
+      );
+    }
+    const channel = await this.connection.createChannel();
+    const prefetch = options.transport?.rabbitmq?.prefetch ?? options.concurrency ?? this.config.defaultPrefetch ?? 10;
+    await channel.prefetch(prefetch);
+    const queueChannel = {
+      channel,
+      consumers: []
+    };
+    this.queueChannels.set(queue, queueChannel);
+    return queueChannel;
+  }
+  async doConnect() {
+    const connection = await amqplib__default.default.connect(this.config.url);
+    this.connection = connection;
+    connection.on("error", (err) => {
+      this.logger.error("[Matador] \u{1F534} RabbitMQ connection error", err);
+    });
+    connection.on("close", () => {
+      if (this.connectionManager.isConnected()) {
+        this.connectionManager.handleConnectionLost(
+          new Error("Connection closed unexpectedly")
+        );
+      }
+    });
+    this.publishChannel = await connection.createChannel();
+    this.publishChannel.on("error", (err) => {
+      this.logger.error("[Matador] \u{1F534} RabbitMQ publish channel error", err);
+    });
+    if (this.topology) {
+      await this.applyTopology(this.topology);
+    }
+  }
+  async doDisconnect() {
+    for (const queueChannel of this.queueChannels.values()) {
+      for (const consumer of queueChannel.consumers) {
+        consumer.active = false;
+        try {
+          await queueChannel.channel.cancel(consumer.consumerTag);
+        } catch {
+        }
+      }
+      try {
+        await queueChannel.channel.close();
+      } catch {
+      }
+    }
+    this.queueChannels.clear();
+    if (this.publishChannel) {
+      try {
+        await this.publishChannel.close();
+      } catch {
+      }
+      this.publishChannel = null;
+    }
+    if (this.connection) {
+      try {
+        await this.connection.close();
+      } catch {
+      }
+      this.connection = null;
+    }
+    this.delayedExchangeAvailable = false;
+    this._capabilities = {
+      ...this._capabilities,
+      delayedMessages: false
+    };
+  }
+  async setupDelayedExchange(namespace) {
+    if (!this.connection) {
+      return;
+    }
+    this.delayedExchangeAvailable = false;
+    const delayedExchange = this.getDelayedExchangeName(namespace);
+    const connection = this.connection;
+    return new Promise((resolve) => {
+      let resolved = false;
+      const safeResolve = () => {
+        if (!resolved) {
+          resolved = true;
+          resolve();
+        }
+      };
+      connection.createChannel().then((probeChannel) => {
+        probeChannel.on("error", () => {
+          safeResolve();
+        });
+        probeChannel.on("close", () => {
+          safeResolve();
+        });
+        probeChannel.assertExchange(delayedExchange, "x-delayed-message", {
+          durable: true,
+          arguments: { "x-delayed-type": "direct" }
+        }).then(() => {
+          this.delayedExchangeAvailable = true;
+          this._capabilities = {
+            ...this._capabilities,
+            delayedMessages: true
+          };
+          this.logger.debug(
+            "[Matador] \u{1F50C} Delayed message exchange plugin detected"
+          );
+          probeChannel.close().catch(() => {
+          });
+          safeResolve();
+        }).catch(() => {
+          this.logger.warn(
+            "[Matador] \u{1F7E1} RabbitMQ delayed message exchange plugin not available. Delayed messages will not be supported."
+          );
+          safeResolve();
+        });
+      }).catch(() => {
+        safeResolve();
+      });
+    });
+  }
+  async assertWorkQueue(channel, topology, queueDef) {
+    const queueName = queueDef.exact ? queueDef.name : `${topology.namespace}.${queueDef.name}`;
+    const queueOptions = {
+      durable: true,
+      arguments: {}
+    };
+    if (this.config.quorumQueues && !queueDef.exact) {
+      queueOptions.arguments["x-queue-type"] = "quorum";
+    }
+    const dlxExchange = this.getDLXExchangeName(topology.namespace);
+    if (topology.deadLetter.unhandled.enabled || topology.deadLetter.undeliverable.enabled) {
+      queueOptions.arguments["x-dead-letter-exchange"] = dlxExchange;
+    }
+    if (queueDef.priorities) {
+      queueOptions.arguments["x-max-priority"] = 10;
+    }
+    if (queueDef.consumerTimeout) {
+      queueOptions.arguments["x-consumer-timeout"] = queueDef.consumerTimeout;
+    }
+    await channel.assertQueue(queueName, queueOptions);
+    const mainExchange = this.getMainExchangeName(topology.namespace);
+    await channel.bindQueue(queueName, mainExchange, queueName);
+    if (this.delayedExchangeAvailable) {
+      const delayedExchange = this.getDelayedExchangeName(topology.namespace);
+      await channel.bindQueue(queueName, delayedExchange, queueName);
+    }
+    if (topology.retry.enabled) {
+      await this.assertRetryQueue(channel, topology, queueName);
+    }
+  }
+  async assertRetryQueue(channel, topology, workQueueName) {
+    const retryQueueName = `${workQueueName}.retry`;
+    const mainExchange = this.getMainExchangeName(topology.namespace);
+    const retryQueueOptions = {
+      durable: true,
+      arguments: {
+        "x-dead-letter-exchange": mainExchange,
+        "x-dead-letter-routing-key": workQueueName,
+        "x-message-ttl": topology.retry.defaultDelayMs
+      }
+    };
+    if (this.config.quorumQueues) {
+      retryQueueOptions.arguments["x-queue-type"] = "quorum";
+    }
+    await channel.assertQueue(retryQueueName, retryQueueOptions);
+    await channel.bindQueue(retryQueueName, mainExchange, retryQueueName);
+  }
+  async assertDeadLetterQueues(channel, topology, dlqType) {
+    const dlxExchange = this.getDLXExchangeName(topology.namespace);
+    const dlConfig = topology.deadLetter[dlqType];
+    for (const queueDef of topology.queues) {
+      if (queueDef.exact) continue;
+      const workQueueName = `${topology.namespace}.${queueDef.name}`;
+      const dlqName = `${workQueueName}.${dlqType}`;
+      const dlqOptions = {
+        durable: true,
+        arguments: {}
+      };
+      if (dlConfig.maxLength) {
+        dlqOptions.arguments["x-max-length"] = dlConfig.maxLength;
+      }
+      await channel.assertQueue(dlqName, dlqOptions);
+      await channel.bindQueue(dlqName, dlxExchange, dlqName);
+    }
+  }
+  getMainExchangeName(namespace) {
+    return `${namespace}.exchange`;
+  }
+  getDLXExchangeName(namespace) {
+    return `${namespace}.dlx`;
+  }
+  getDelayedExchangeName(namespace) {
+    return `${namespace}.delayed`;
+  }
+  getAttemptNumber(msg) {
+    const headerValue = msg.properties.headers?.["x-matador-attempts"];
+    if (typeof headerValue === "number") {
+      return headerValue;
+    }
+    const xDeath = msg.properties.headers?.["x-death"];
+    if (Array.isArray(xDeath) && xDeath.length > 0) {
+      const deathCount = xDeath.reduce(
+        (sum, death) => sum + (death.count ?? 0),
+        0
+      );
+      return deathCount + 1;
+    }
+    return 1;
+  }
+  /**
+   * Gets the native delivery count for poison message detection.
+   * This tracks how many times the message was delivered without acknowledgment,
+   * which helps detect crash loops.
+   */
+  getDeliveryCount(msg, attemptNumber) {
+    const deliveryCount = msg.properties.headers?.["x-delivery-count"];
+    if (typeof deliveryCount === "number") {
+      return deliveryCount;
+    }
+    const xDeath = msg.properties.headers?.["x-death"];
+    if (Array.isArray(xDeath) && xDeath.length > 0) {
+      const deathCount = xDeath.reduce(
+        (sum, death) => sum + (death.count ?? 0),
+        0
+      );
+      return deathCount + 1;
+    }
+    if (msg.fields.redelivered) {
+      return Math.max(2, attemptNumber);
+    }
+    return attemptNumber;
+  }
+};
+
+exports.AllTransportsFailedError = AllTransportsFailedError;
+exports.CheckpointStoreError = CheckpointStoreError;
+exports.CodecDecodeError = CodecDecodeError;
+exports.ConnectionManager = ConnectionManager;
+exports.DelayedMessagesNotSupportedError = DelayedMessagesNotSupportedError;
+exports.DoRetry = DoRetry;
+exports.DontRetry = DontRetry;
+exports.DuplicateIoKeyError = DuplicateIoKeyError;
+exports.EventAssertionError = EventAssertionError;
+exports.EventNotRegisteredError = EventNotRegisteredError;
+exports.FanoutEngine = FanoutEngine;
+exports.IdempotentMessageCannotRetryError = IdempotentMessageCannotRetryError;
+exports.InvalidEventError = InvalidEventError;
+exports.InvalidSchemaError = InvalidSchemaError;
+exports.JsonCodec = JsonCodec;
+exports.LocalTransport = LocalTransport;
+exports.LocalTransportCannotProcessStubError = LocalTransportCannotProcessStubError;
+exports.Matador = Matador;
+exports.MatadorError = MatadorError;
+exports.MatadorEvent = MatadorEvent;
+exports.MemoryCheckpointStore = MemoryCheckpointStore;
+exports.MessageMaybePoisonedError = MessageMaybePoisonedError;
+exports.MultiTransport = MultiTransport;
+exports.NoOpCheckpointStore = NoOpCheckpointStore;
+exports.NoSubscribersExistError = NoSubscribersExistError;
+exports.NotStartedError = NotStartedError;
+exports.ProcessingPipeline = ProcessingPipeline;
+exports.QueueNotFoundError = QueueNotFoundError;
+exports.RabbitMQCodec = RabbitMQCodec;
+exports.RabbitMQTransport = RabbitMQTransport;
+exports.ResumableContext = ResumableContext;
+exports.RetryControlError = RetryControlError;
+exports.SafeHooks = SafeHooks;
+exports.SchemaError = SchemaError;
+exports.SchemaRegistry = SchemaRegistry;
+exports.ShutdownInProgressError = ShutdownInProgressError;
+exports.ShutdownManager = ShutdownManager;
+exports.StandardRetryPolicy = StandardRetryPolicy;
+exports.SubscriberIsStubError = SubscriberIsStubError;
+exports.SubscriberNotRegisteredError = SubscriberNotRegisteredError;
+exports.TimeoutError = TimeoutError;
+exports.TopologyBuilder = TopologyBuilder;
+exports.TopologyValidationError = TopologyValidationError;
+exports.TransportClosedError = TransportClosedError;
+exports.TransportNotConnectedError = TransportNotConnectedError;
+exports.TransportSendError = TransportSendError;
+exports.bind = bind;
+exports.consoleLogger = consoleLogger;
+exports.createEnvelope = createEnvelope;
+exports.createSubscriber = createSubscriber;
+exports.createSubscriberStub = createSubscriberStub;
+exports.defaultConnectionConfig = defaultConnectionConfig;
+exports.defaultRetryConfig = defaultRetryConfig;
+exports.defaultShutdownConfig = defaultShutdownConfig;
+exports.getDeadLetterQueueName = getDeadLetterQueueName;
+exports.getQualifiedQueueName = getQualifiedQueueName;
+exports.getRetryQueueName = getRetryQueueName;
+exports.hasDescription = hasDescription;
+exports.hasNativeDeadLetter = hasNativeDeadLetter;
+exports.installPlugins = installPlugins;
+exports.invalidResult = invalidResult;
+exports.isAssertionError = isAssertionError;
+exports.isCheckpointStoreError = isCheckpointStoreError;
+exports.isDoRetry = isDoRetry;
+exports.isDontRetry = isDontRetry;
+exports.isDuplicateIoKeyError = isDuplicateIoKeyError;
+exports.isEventNotRegisteredError = isEventNotRegisteredError;
+exports.isIdempotentMessageCannotRetryError = isIdempotentMessageCannotRetryError;
+exports.isMatadorError = isMatadorError;
+exports.isMessageMaybePoisonedError = isMessageMaybePoisonedError;
+exports.isNotStartedError = isNotStartedError;
+exports.isSchemaEntryTuple = isSchemaEntryTuple;
+exports.isSubscriber = isSubscriber;
+exports.isSubscriberNotRegisteredError = isSubscriberNotRegisteredError;
+exports.isSubscriberStub = isSubscriberStub;
+exports.isTransportNotConnectedError = isTransportNotConnectedError;
+exports.supportsDelayedMessages = supportsDelayedMessages;
+exports.supportsDeliveryMode = supportsDeliveryMode;
+exports.validResult = validResult;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map