@horizon-republic/nestjs-jetstream 2.9.1 → 2.11.0

package/dist/index.d.cts

@@ -1,7 +1,9 @@
-import { ModuleMetadata, FactoryProvider, Type, Logger, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
-import { MsgHdrs, ConnectionOptions, NatsConnection, Status, Msg } from '@nats-io/transport-node';
-import { StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, JetStreamManager, JetStreamClient, ConsumerInfo, JsMsg } from '@nats-io/jetstream';
-import { MessageHandler, Server, CustomTransportStrategy, ClientProxy, ReadPacket, WritePacket, BaseRpcContext } from '@nestjs/microservices';
+import { Logger, ModuleMetadata, FactoryProvider, Type, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
+import { MsgHdrs, NatsConnection, Status, ConnectionOptions, Msg } from '@nats-io/transport-node';
+import { JetStreamManager, JetStreamClient, StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, ConsumerInfo, JsMsg } from '@nats-io/jetstream';
+import { Registry } from 'prom-client';
+import { Span } from '@opentelemetry/api';
+import { ClientProxy, ReadPacket, WritePacket, MessageHandler, Server, CustomTransportStrategy, BaseRpcContext } from '@nestjs/microservices';
 import { Observable } from 'rxjs';
 
 /**
@@ -32,11 +34,47 @@ interface Codec {
     decode(data: Uint8Array): unknown;
 }
 
+/**
+ * Identifies a JetStream stream/consumer kind.
+ *
+ * - `Event`     — Workqueue events (at-least-once delivery to one consumer).
+ * - `Command`   — RPC commands (JetStream mode only).
+ * - `Broadcast` — Broadcast events (fan-out to all consumers).
+ * - `Ordered`   — Ordered events (strict sequential delivery, Limits retention).
+ */
+declare enum StreamKind {
+    Event = "ev",
+    Command = "cmd",
+    Broadcast = "broadcast",
+    Ordered = "ordered"
+}
+/**
+ * Subset of {@link StreamKind} used for direct subject building.
+ *
+ * Excludes `Broadcast` because broadcast subjects use a different
+ * naming convention (`broadcast.{pattern}` instead of `{service}.{kind}.{pattern}`).
+ */
+type SubjectKind = Exclude<StreamKind, StreamKind.Broadcast>;
+
 /** Discriminates the kind of message routed through the transport. */
 declare enum MessageKind {
     Event = "event",
     Rpc = "rpc"
 }
+/** Outcome of a handler invocation, used as a label on processing metrics. */
+type HandlerStatus = 'success' | 'error' | 'retried' | 'terminated';
+/**
+ * Outcome of a client publish (event emit or RPC publish leg). Outbound
+ * operations either acknowledge cleanly or surface a transport error — there
+ * is no retried/terminated dimension at the publish boundary.
+ */
+type PublishStatus = 'success' | 'error';
+/**
+ * Outcome of a full RPC round-trip from the caller's perspective. Adds the
+ * `timeout` dimension on top of {@link PublishStatus} so percentile analysis
+ * can distinguish slow successes from deadline-exceeded calls.
+ */
+type RpcOutcomeStatus = 'success' | 'error' | 'timeout';
 declare enum TransportEvent {
     Connect = "connect",
     Disconnect = "disconnect",
@@ -46,7 +84,11 @@ declare enum TransportEvent {
     MessageRouted = "messageRouted",
     ShutdownStart = "shutdownStart",
     ShutdownComplete = "shutdownComplete",
-    DeadLetter = "deadLetter"
+    DeadLetter = "deadLetter",
+    ConsumerRecovered = "consumerRecovered",
+    HandlerCompleted = "handlerCompleted",
+    Published = "published",
+    RpcCompleted = "rpcCompleted"
 }
 /**
  * Hook callbacks for transport lifecycle and operational events.
@@ -84,7 +126,59 @@ interface TransportHooks {
     [TransportEvent.ShutdownComplete](): void;
     /** Fired when a message exhausts all delivery attempts (dead letter). */
     [TransportEvent.DeadLetter](info: DeadLetterInfo): void;
+    /**
+     * Fired when a consumer's self-healing flow successfully recovers after
+     * one or more failed restart attempts. Useful for "service is back" alerts
+     * and to balance the noise from preceding error/restart logs.
+     *
+     * @param label   Stream kind label (`event`, `broadcast`, `ordered`, etc.)
+     *                or consumer name passed to `createSelfHealingFlow`.
+     * @param attempts How many consecutive failed attempts preceded the recovery.
+     */
+    [TransportEvent.ConsumerRecovered](label: string, attempts: number): void;
+    /**
+     * Fired immediately after a handler returns or throws.
+     *
+     * Used by built-in metrics; users can register their own handler for
+     * latency tracking, slow-handler alerting, or custom observability.
+     *
+     * @param subject  The declared NATS pattern (from `@EventPattern` / `@MessagePattern`).
+     * @param kind     Stream kind: `Event`, `Command`, `Broadcast`, `Ordered`.
+     * @param durationMs Wall-clock time in milliseconds from handler entry to settlement.
+     * @param status   Outcome: `success`, `error`, `retried`, or `terminated`.
+     */
+    [TransportEvent.HandlerCompleted](subject: string, kind: StreamKind, durationMs: number, status: HandlerStatus): void;
+    /**
+     * Fired after every client-side publish (event emit or RPC publish leg)
+     * completes, regardless of outcome.
+     *
+     * @param subject  Declared user pattern (e.g. `orders.created`) — bounded
+     *                 by handler registration, safe for high-cardinality labels.
+     * @param kind     Stream kind the publish targets: `Event`, `Broadcast`,
+     *                 `Ordered`, or `Command` (RPC publish leg).
+     * @param durationMs Wall-clock time from publish initiation to ack/error.
+     * @param status   `success` when the publish acked, `error` otherwise.
+     */
+    [TransportEvent.Published](subject: string, kind: StreamKind, durationMs: number, status: PublishStatus): void;
+    /**
+     * Fired after an RPC round-trip completes from the caller's perspective —
+     * either a reply is received, the call errors out, or the deadline expires.
+     *
+     * Distinct from {@link Published} which only covers the publish leg.
+     *
+     * @param subject  Declared command pattern (e.g. `orders.get`).
+     * @param durationMs Wall-clock time from request initiation to settlement.
+     * @param status   `success` for a successful reply, `error` for transport/
+     *                 handler errors, `timeout` when the deadline expired.
+     */
+    [TransportEvent.RpcCompleted](subject: string, durationMs: number, status: RpcOutcomeStatus): void;
 }
+/**
+ * Internal subscriber for a transport event. Multiple subscribers may be
+ * registered per event via `EventBus.subscribe()` — used by built-in
+ * observers (e.g. metrics) without overriding the user-provided hook.
+ */
+type TransportEventSubscriber<K extends keyof TransportHooks> = (...args: Parameters<TransportHooks[K]>) => unknown;
 /**
  * Context passed to the onDeadLetter callback when a message exhausts all delivery attempts.
  */
@@ -118,1372 +212,1758 @@ interface JetstreamHealthStatus {
 }
 
 /**
- * Stream config overrides exposed to users.
- *
- * `retention` is excluded because it is controlled by the transport layer
- * (Workqueue for events/commands, Limits for broadcast/ordered).
- * Any `retention` value provided at runtime is silently stripped.
+ * Labels (in seconds) for histogram bucket configuration.
+ * Override defaults via `JetstreamModuleOptions.metrics.buckets`.
  */
-type StreamConfigOverrides = Partial<Omit<StreamConfig, 'retention'>>;
+interface HistogramBuckets {
+    /** Buckets for `jetstream_handler_duration_seconds`. */
+    handlerDuration?: number[];
+    /** Buckets for `jetstream_publish_duration_seconds`. */
+    publishDuration?: number[];
+    /** Buckets for `jetstream_rpc_duration_seconds`. */
+    rpcDuration?: number[];
+}
 /**
- * RPC transport configuration.
+ * Configuration for built-in Prometheus metrics. All fields are optional;
+ * sensible production defaults are applied when missing.
+ */
+interface MetricsConfig {
+    /**
+     * `prom-client` registry to write metrics into. Defaults to the global
+     * `register` from `prom-client`, which is also what
+     * `@willsoto/nestjs-prometheus` exposes via `/metrics`.
+     */
+    register?: Registry;
+    /** Metric name prefix. Defaults to `'jetstream_'`. */
+    prefix?: string;
+    /** Labels merged into every metric. Useful for service/env tagging. */
+    defaultLabels?: Record<string, string>;
+    /**
+     * Polling interval (ms) for gauge metrics that query `JetStreamManager`
+     * (consumer pending, stream messages, etc.). Default `15_000`.
+     * Set to `0` to disable polling — counter/histogram metrics still update
+     * via the event bus.
+     */
+    pollInterval?: number;
+    /** Override default histogram buckets. */
+    buckets?: HistogramBuckets;
+}
+/**
+ * Shorthand for `MetricsConfig`. Pass `true` to enable with all defaults,
+ * `false` (or omit) to disable entirely.
+ */
+type MetricsOption = boolean | MetricsConfig;
+
+/**
+ * Instrumentation scope name reported on every span the library emits.
+ * Matches the npm package name — the convention used by
+ * `@opentelemetry/instrumentation-*` and most third-party instrumentations.
+ */
+declare const TRACER_NAME = "@horizon-republic/nestjs-jetstream";
+
+/**
+ * Enumeration of OpenTelemetry trace kinds this library can emit.
  *
- * Discriminated union on `mode`:
- * - `'core'`      — NATS native request/reply. Lowest latency.
- * - `'jetstream'`  — Commands persisted in JetStream. Responses via Core NATS inbox.
+ * Each identifier is toggleable via `otel.traces`. Functional kinds (publish,
+ * consume, RPC client round-trip, dead letter) are enabled by default;
+ * infrastructure kinds (connection lifecycle, self-healing, provisioning,
+ * migration, shutdown) are opt-in.
  *
- * When `mode` is `'core'`, only `timeout` is available.
- * When `mode` is `'jetstream'`, additional stream/consumer overrides are exposed.
+ * @example
+ *   JetstreamModule.forRoot({
+ *     otel: {
+ *       traces: [JetstreamTrace.Publish, JetstreamTrace.Consume, JetstreamTrace.ConnectionLifecycle],
+ *     },
+ *   })
  */
-type RpcConfig = {
-    mode: 'core';
-    /** Request timeout in ms. Default: 30_000. */
-    timeout?: number;
-} | {
-    mode: 'jetstream';
-    /** Handler timeout in ms. Default: 180_000 (3 min). */
-    timeout?: number;
-    /** Raw NATS StreamConfig overrides for the command stream. */
-    stream?: StreamConfigOverrides;
-    /** Raw NATS ConsumerConfig overrides for the command consumer. */
-    consumer?: Partial<ConsumerConfig>;
-    /** Options passed to the nats.js `consumer.consume()` call for the command consumer. */
-    consume?: Partial<ConsumeOptions>;
-    /** Maximum number of concurrent RPC handler executions. */
-    concurrency?: number;
+declare enum JetstreamTrace {
+    /** `PRODUCER` span around each `emit()` / `send()` publish operation. Default: ON. */
+    Publish = "publish",
     /**
-     * Auto-extend ack deadline via `msg.working()` during RPC handler execution.
-     * The RPC handler timeout (`setTimeout` + `msg.term()`) still acts as the hard cap.
+     * `CONSUMER` span around each message delivery to a handler. Retries
+     * produce separate spans with `messaging.nats.message.delivery_count > 1`.
+     * Default: ON.
      */
-    ackExtension?: boolean | number;
-};
-/** Overrides for JetStream stream and consumer configuration. */
-interface StreamConsumerOverrides {
-    stream?: StreamConfigOverrides;
-    consumer?: Partial<ConsumerConfig>;
+    Consume = "consume",
     /**
-     * Options passed to the nats.js `consumer.consume()` call.
-     * Controls prefetch buffer size, idle heartbeat interval, and auto-refill thresholds.
-     *
-     * nats.js supports two consumption modes (message-based and byte-based).
-     * Do not mix `max_bytes`/`threshold_bytes` with `threshold_messages` —
-     * use one mode or the other.
-     *
-     * @see https://github.com/nats-io/nats.js — ConsumeOptions
+     * `CLIENT` span covering a full RPC round-trip on the caller side
+     * (`client.send()` → reply received). Wraps the inner publish.
+     * Default: ON.
      */
-    consume?: Partial<ConsumeOptions>;
+    RpcClientSend = "rpc.client.send",
     /**
-     * Maximum number of concurrent handler executions (RxJS `mergeMap` limit).
-     *
-     * Default: `undefined` (unlimited — naturally bounded by `max_ack_pending`).
-     * Set this to protect downstream systems from overload.
-     *
-     * **Important:** if `concurrency < max_ack_pending`, messages buffer in RxJS
-     * while their NATS ack timer ticks. Increase `ack_wait` proportionally to
-     * prevent unnecessary redeliveries.
+     * `INTERNAL` span emitted when a message exhausts `maxDeliver` and is
+     * dead-lettered. Captures the duration of the `onDeadLetter` callback.
+     * Default: ON.
      */
-    concurrency?: number;
+    DeadLetter = "dead_letter",
     /**
-     * Auto-extend the NATS ack deadline via `msg.working()` during handler execution.
-     *
-     * - `false` (default): disabled — NATS redelivers after `ack_wait` if not acked.
-     * - `true`: auto-extend at `ack_wait / 2` interval (calculated from consumer config).
-     * - `number`: explicit extension interval in milliseconds.
+     * `INTERNAL` span spanning one NATS connection session. Emits events on
+     * connect, reconnect, disconnect. Default: OFF.
      */
-    ackExtension?: boolean | number;
+    ConnectionLifecycle = "connection.lifecycle",
+    /**
+     * `INTERNAL` span per consumer recovery attempt following a transient
+     * failure (deleted consumer, missed heartbeat). Default: OFF.
+     */
+    SelfHealing = "self_healing",
+    /** `INTERNAL` span per stream or consumer provisioning / update at startup. Default: OFF. */
+    Provisioning = "provisioning",
+    /** `INTERNAL` span covering a destructive migration flow. Default: OFF. */
+    Migration = "migration",
+    /** `INTERNAL` span covering the graceful shutdown sequence. Default: OFF. */
+    Shutdown = "shutdown"
 }
 /**
- * Configuration for ordered event consumers.
+ * The set of trace kinds enabled when `otel.traces` is not configured
+ * (or set to `'default'`). Covers message-flow operations; infrastructure
+ * spans are opt-in.
+ */
+declare const DEFAULT_TRACES: readonly JetstreamTrace[];
+
+/**
+ * Central event bus for transport lifecycle notifications.
  *
- * Ordered consumers use Limits retention and deliver messages in strict
- * sequential order with at-most-once delivery. No ack/nak/DLQ.
+ * Two emission paths:
+ *  - User hooks registered via `forRoot({ hooks })` — at most one per event.
+ *  - Internal subscribers added via `subscribe()` — many per event, used by
+ *    metrics and other built-in observers.
  *
- * Only a subset of consumer options applies — ordered consumers are
- * ephemeral and auto-managed by nats.js.
+ * Both fire on every `emit()` call. Subscriber failures are isolated and
+ * logged; they do not block other subscribers or the user hook.
  */
-interface OrderedEventOverrides {
-    /** Stream overrides (e.g. `max_age`, `max_bytes`). */
-    stream?: StreamConfigOverrides;
+declare class EventBus {
+    private readonly hooks;
+    private readonly logger;
+    private readonly subscribers;
+    constructor(logger: Logger, hooks?: Partial<TransportHooks>);
     /**
-     * Where to start reading when the consumer is (re)created.
-     * @default DeliverPolicy.All
+     * Subscribe to a transport event. Used by built-in observers (e.g. metrics).
+     * Multiple subscribers per event are supported; each is called independently.
      */
-    deliverPolicy?: DeliverPolicy;
+    subscribe<K extends keyof TransportHooks>(event: K, handler: TransportEventSubscriber<K>): void;
     /**
-     * Start sequence number. Only used when `deliverPolicy` is `StartSequence`.
+     * Emit a lifecycle event. Dispatches to all internal subscribers and the
+     * registered user hook (if any).
      */
-    optStartSeq?: number;
+    emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
     /**
-     * Start time (ISO string). Only used when `deliverPolicy` is `StartTime`.
+     * Hot-path optimized emit for MessageRouted events.
+     * Avoids rest/spread overhead of the generic `emit()`.
      */
-    optStartTime?: string;
+    emitMessageRouted(subject: string, kind: MessageKind): void;
     /**
-     * Replay policy for historical messages.
-     * @default ReplayPolicy.Instant
+     * Check whether any listener (user hook or internal subscriber) is registered
+     * for the given event. Used by routing hot path to elide the emit call when
+     * no one is listening.
      */
-    replayPolicy?: ReplayPolicy;
+    hasHook(event: keyof TransportHooks): boolean;
+    private dispatch;
+    private callHook;
 }
+
 /**
- * Configuration for the handler metadata KV registry.
+ * Manages the lifecycle of a single NATS connection shared across the application.
  *
- * When any handler has `meta` in its extras, the transport writes metadata
- * entries to a NATS KV bucket at startup. External services (API gateways,
- * dashboards) can watch the bucket for service discovery.
+ * Provides both Promise-based and Observable-based access to the connection:
+ * - `connect()` / `getConnection()` — async/await for one-time setup
+ * - `nc$` — cached observable (shareReplay) for reactive consumers
+ * - `status$` — live connection status event stream
  *
- * All fields are optional — sensible defaults are applied.
+ * One instance per application, created by `JetstreamModule.forRoot()`.
  */
-interface MetadataRegistryOptions {
+declare class ConnectionProvider {
+    private readonly options;
+    private readonly eventBus;
+    /** Cached observable that replays the established connection to new subscribers. */
+    readonly nc$: Observable<NatsConnection>;
+    /** Live stream of connection status events (no replay). */
+    readonly status$: Observable<Status>;
+    private readonly logger;
+    private connection;
+    private connectionPromise;
+    private jsClient;
+    private jsmInstance;
+    private jsmPromise;
+    private readonly otel;
+    private readonly otelServiceName;
+    private readonly otelEndpoint;
+    private lifecycleSpan;
+    constructor(options: JetstreamModuleOptions, eventBus: EventBus);
     /**
-     * KV bucket name.
-     * @default 'handler_registry'
+     * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
+     *
+     * @throws Error if connection is refused (fail fast).
      */
-    bucket?: string;
+    getConnection(): Promise<NatsConnection>;
     /**
-     * Number of KV bucket replicas. Must be an odd number (1, 3, 5, 7, ...).
-     * Requires a NATS cluster with at least this many nodes.
-     * @default 1
+     * Get the JetStream manager. Cached after first call.
+     *
+     * @returns The JetStreamManager for stream/consumer administration.
      */
-    replicas?: number;
+    getJetStreamManager(): Promise<JetStreamManager>;
     /**
-     * KV bucket TTL in milliseconds.
+     * Get a cached JetStream client.
      *
-     * Entries expire automatically unless refreshed by a heartbeat.
-     * The transport refreshes entries every `ttl / 2` while the pod is alive.
-     * When the pod stops (graceful or crash), entries expire after this duration.
+     * Invalidated automatically on reconnect and shutdown so consumers always
+     * operate against the live connection.
      *
-     * @default 30_000 (30 seconds)
+     * @returns The cached JetStreamClient.
+     * @throws Error if the connection has not been established yet.
      */
-    ttl?: number;
+    getJetStreamClient(): JetStreamClient;
+    /** Direct access to the raw NATS connection, or `null` if not yet connected. */
+    get unwrap(): NatsConnection | null;
+    /**
+     * Gracefully shut down the connection.
+     *
+     * Sequence: drain → wait for close. Falls back to force-close on error.
+     */
+    shutdown(): Promise<void>;
+    private initJetStreamManager;
+    /** Internal: establish the physical connection with reconnect monitoring. */
+    private establish;
+    /** Handle a single `nc.status()` event, emitting hooks and span events. */
+    private handleStatusEvent;
+    /** Subscribe to connection status events and emit hooks. */
+    private monitorStatus;
 }
+
 /**
- * Root module configuration for `JetstreamModule.forRoot()`.
+ * NestJS ClientProxy implementation for the JetStream transport.
  *
- * Minimal usage requires only `name` and `servers`.
- * All other fields have production-ready defaults.
+ * Supports two operational modes:
+ * - **Core mode** (default): Uses `nc.request()` for RPC, `nc.publish()` for events.
+ * - **JetStream mode**: Uses `js.publish()` for RPC commands + inbox for responses.
+ *
+ * Events always go through JetStream publish for guaranteed delivery.
+ * The mode only affects RPC (request/reply) behavior.
+ *
+ * Clients are lightweight — they share the NATS connection from `forRoot()`.
  */
-interface JetstreamModuleOptions {
-    /** Service name. Used for stream/consumer/subject naming. */
-    name: string;
-    /** NATS server URLs. */
-    servers: string[];
+declare class JetstreamClient extends ClientProxy {
+    private readonly rootOptions;
+    private readonly connection;
+    private readonly codec;
+    private readonly eventBus;
+    private readonly logger;
+    /** Target service name this client sends messages to. */
+    private readonly targetName;
+    /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
+    private readonly callerName;
     /**
-     * Global message codec.
-     * @default JsonCodec
+     * Subject prefixes of the form `{serviceName}__microservice.{kind}.` — one
+     * per stream kind this client may publish to. Built once in the constructor
+     * so producing a full subject is a single string concat with the user pattern.
      */
-    codec?: Codec;
+    private readonly eventSubjectPrefix;
+    private readonly commandSubjectPrefix;
+    private readonly orderedSubjectPrefix;
     /**
-     * RPC transport mode and configuration.
-     * @default { mode: 'core' }
+     * RPC configuration snapshots. The values are derived from rootOptions at
+     * construction time so the publish hot path never has to re-run
+     * isCoreRpcMode / getRpcTimeout on every call.
      */
-    rpc?: RpcConfig;
+    private readonly isCoreMode;
+    private readonly defaultRpcTimeout;
+    /** Resolved OpenTelemetry configuration, computed once in the constructor. */
+    private readonly otel;
+    /** Server endpoint parts used for `server.address` / `server.port` span attributes. */
+    private readonly serverEndpoint;
+    /** Shared inbox for JetStream-mode RPC responses. */
+    private inbox;
+    private inboxSubscription;
+    /** Pending JetStream-mode RPC callbacks, keyed by correlation ID. */
+    private readonly pendingMessages;
+    /** Pending JetStream-mode RPC timeouts, keyed by correlation ID. */
+    private readonly pendingTimeouts;
+    /** Subscription to connection status events for disconnect handling. */
+    private statusSubscription;
     /**
-     * Enable consumer infrastructure (streams, consumers, message routing).
-     * Set to `false` for publisher-only services (e.g., API gateways).
-     * @default true
+     * Cached readiness flag. Once `connect()` has wired the inbox and status
+     * subscription, subsequent publishes skip the `await connect()` microtask
+     * and reach for the underlying connection synchronously instead.
      */
-    consumer?: boolean;
-    /** Workqueue event stream/consumer overrides. */
-    events?: StreamConsumerOverrides;
-    /** Broadcast event stream/consumer overrides. */
-    broadcast?: StreamConsumerOverrides;
+    private readyForPublish;
+    constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
     /**
-     * Ordered event consumer configuration.
+     * Establish connection. Called automatically by NestJS on first use.
      *
-     * Ordered events use a separate stream with Limits retention and deliver
-     * messages in strict sequential order. Use `ordered:` prefix when publishing.
+     * Sets up the JetStream RPC inbox (if in JetStream mode) and subscribes
+     * to connection status events for fail-fast disconnect handling.
      *
-     * @see OrderedEventOverrides
-     */
-    ordered?: OrderedEventOverrides;
-    /**
-     * Transport lifecycle hook handlers.
-     * Unset hooks are silently ignored — no default logging.
+     * @returns The underlying NATS connection.
      */
-    hooks?: Partial<TransportHooks>;
+    connect(): Promise<NatsConnection>;
+    /** Clean up resources: reject pending RPCs, unsubscribe from status events. */
+    close(): Promise<void>;
     /**
-     * Async callback invoked when an event message exhausts all delivery attempts.
-     * Called before msg.term(). If it throws, the message is nak'd for retry.
-     *
-     * Use this to persist dead letters to an external store (DB, S3, another queue).
-     * The NATS connection is available via `JETSTREAM_CONNECTION` token in forRootAsync.
+     * Direct access to the raw NATS connection.
      *
-     * @example
-     * ```typescript
-     * JetstreamModule.forRootAsync({
-     *   name: 'my-service',
-     *   imports: [DlqModule],
-     *   inject: [DlqService, JETSTREAM_CONNECTION],
-     *   useFactory: (dlqService, connection) => ({
-     *     servers: ['nats://localhost:4222'],
-     *     onDeadLetter: async (info) => {
-     *       await dlqService.persist(info);
-     *     },
-     *   }),
-     * })
-     * ```
+     * @throws Error if not connected.
      */
-    onDeadLetter?(info: DeadLetterInfo): Promise<void>;
+    unwrap<T = NatsConnection>(): T;
     /**
-     * Dead-letter queue (DLQ) configuration.
-     * DLQ is a separate stream used to store messages that have exhausted all delivery attempts.
-     * @example
-     * ```typescript
-     * JetstreamModule.forRootAsync({
-     *   name: 'my-service',
-     *   servers: ['nats://localhost:4222'],
-     *   dlq: {
-     *     stream: {
-     *       max_age: toNanos(30, 'days'),
-     *     },
-     *   },
-     * })
-     * ```
+     * Publish a fire-and-forget event to JetStream.
+     *
+     * Events are published to either the workqueue stream or broadcast stream
+     * depending on the subject prefix. When a schedule is present the message
+     * is published to a `_sch` subject within the same stream, with the target
+     * set to the original event subject.
      */
-    dlq?: {
-        stream?: StreamConfigOverrides;
-    };
+    protected dispatchEvent<T = unknown>(packet: ReadPacket): Promise<T>;
     /**
-     * Graceful shutdown timeout in ms.
-     * Handlers exceeding this are abandoned.
-     * @default 10_000
+     * Publish an RPC command and register callback for response.
+     *
+     * Core mode: uses nc.request() with timeout.
+     * JetStream mode: publishes to stream + waits for inbox response.
      */
-    shutdownTimeout?: number;
+    protected publish(packet: ReadPacket, callback: (p: WritePacket) => void): () => void;
+    /** Core mode: nc.request() with timeout. */
+    private publishCoreRpc;
+    /** JetStream mode: publish to stream + wait for inbox response. */
+    private publishJetStreamRpc;
+    private reportPublished;
+    private reportRpcCompleted;
+    /** Fail-fast all pending JetStream RPC callbacks on connection loss. */
+    private handleDisconnect;
+    /** Reject all pending RPC callbacks, clear timeouts, and tear down inbox. */
+    private rejectPendingRpcs;
+    /** Setup shared inbox subscription for JetStream RPC responses. */
+    private setupInbox;
+    /** Route an inbox reply to the matching pending callback. */
+    private routeInboxReply;
     /**
-     * Allow destructive stream migration when immutable config changes are detected.
-     *
-     * When `true`, the transport will recreate streams (via blue-green sourcing)
-     * if immutable properties like `storage` differ from the running stream.
-     * Messages are preserved during migration.
-     *
-     * `retention` is NOT migratable — it is controlled by the transport
-     * (Workqueue for events, Limits for broadcast/ordered) and a mismatch
-     * is always treated as an error regardless of this flag.
-     *
-     * When `false` (default), immutable conflicts are logged as warnings and
-     * the stream continues with its existing configuration.
+     * Resolve a user pattern to a fully-qualified NATS subject, dispatching
+     * between the event, broadcast, and ordered prefixes.
      *
-     * @default false
+     * The leading-char check short-circuits the `startsWith` comparisons for
+     * patterns that cannot possibly carry a broadcast/ordered marker, which is
+     * the overwhelmingly common case.
      */
-    allowDestructiveMigration?: boolean;
+    private buildEventSubject;
+    /** Build NATS headers merging custom headers with transport headers. */
+    private buildHeaders;
+    /** Extract data, headers, timeout, and schedule from raw packet data or JetstreamRecord. */
+    private extractRecordData;
     /**
-     * Handler metadata KV registry configuration.
-     *
-     * When any handler has `meta` in its `@EventPattern` / `@MessagePattern` extras,
-     * the transport writes metadata to a NATS KV bucket at startup.
-     * External services (API gateways, dashboards, CLI tools) can read or watch
-     * the bucket for dynamic service discovery.
+     * Build a schedule-holder subject for NATS message scheduling.
      *
-     * Auto-enabled when any handler has `meta`. Set to customize bucket name,
-     * replicas, or TTL.
+     * The schedule-holder subject resides in the same stream as the target but
+     * uses a separate `_sch` namespace that is NOT matched by any consumer filter.
+     * NATS holds the message and publishes it to the target subject after the delay.
      *
-     * @see MetadataRegistryOptions
-     */
-    metadata?: MetadataRegistryOptions;
-    /**
-     * Raw NATS ConnectionOptions pass-through for advanced connection config.
-     * Allows setting tls, auth, reconnect behavior, maxReconnectAttempts, etc.
-     * Merged with `name` and `servers` — those take precedence.
-     */
-    connectionOptions?: Partial<ConnectionOptions>;
-}
-/** Options for `JetstreamModule.forFeature()`. */
-interface JetstreamFeatureOptions {
-    /** Target service name for subject construction. */
-    name: string;
-    /**
-     * Override the global codec for this client.
-     * Falls back to the root codec from `forRoot()` when omitted.
+     * Examples:
+     * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder`
+     * - `broadcast.config.updated` → `broadcast._sch.config.updated`
      */
-    codec?: Codec;
+    private buildScheduleSubject;
 }
-/**
- * Async configuration for `JetstreamModule.forRootAsync()`.
- *
- * Supports three patterns: `useFactory`, `useExisting`, `useClass`.
- */
-type JetstreamModuleAsyncOptions = {
-    /** Service name — required upfront for DI token generation. */
-    name: string;
-    /** Additional module imports (e.g., ConfigModule). */
-    imports?: ModuleMetadata['imports'];
-} & ({
-    useFactory(...args: unknown[]): Promise<Omit<JetstreamModuleOptions, 'name'>> | Omit<JetstreamModuleOptions, 'name'>;
-    inject?: FactoryProvider['inject'];
-    useExisting?: never;
-    useClass?: never;
-} | {
-    useExisting: Type<Omit<JetstreamModuleOptions, 'name'>>;
-    useFactory?: never;
-    inject?: never;
-    useClass?: never;
-} | {
-    useClass: Type<Omit<JetstreamModuleOptions, 'name'>>;
-    useFactory?: never;
-    inject?: never;
-    useExisting?: never;
-});
 
 /**
- * Identifies a JetStream stream/consumer kind.
+ * Immutable message record for JetStream transport.
  *
- * - `Event`     — Workqueue events (at-least-once delivery to one consumer).
- * - `Command`   — RPC commands (JetStream mode only).
- * - `Broadcast` — Broadcast events (fan-out to all consumers).
- * - `Ordered`   — Ordered events (strict sequential delivery, Limits retention).
+ * Compatible with NestJS record builder pattern (like RmqRecord, NatsRecord).
+ * Pass as the second argument to `client.send()` or `client.emit()`.
+ *
+ * @example
+ * ```typescript
+ * const record = new JetstreamRecordBuilder({ id: 1 })
+ *   .setHeader('x-tenant', 'acme')
+ *   .setTimeout(5000)
+ *   .build();
+ *
+ * client.send('get.user', record);
+ * ```
  */
-declare enum StreamKind {
-    Event = "ev",
-    Command = "cmd",
-    Broadcast = "broadcast",
-    Ordered = "ordered"
+declare class JetstreamRecord<TData = unknown> {
+    /** Message payload. */
+    readonly data: TData;
+    /** Custom headers set via {@link JetstreamRecordBuilder.setHeader}. */
+    readonly headers: ReadonlyMap<string, string>;
+    /** Per-request RPC timeout override in ms. */
+    readonly timeout?: number | undefined;
+    /** Custom message ID for JetStream deduplication. */
+    readonly messageId?: string | undefined;
+    /** Schedule options for delayed delivery. */
+    readonly schedule?: ScheduleRecordOptions | undefined;
+    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
+    readonly ttl?: string | undefined;
+    constructor(
+    /** Message payload. */
+    data: TData, 
+    /** Custom headers set via {@link JetstreamRecordBuilder.setHeader}. */
+    headers: ReadonlyMap<string, string>, 
+    /** Per-request RPC timeout override in ms. */
+    timeout?: number | undefined, 
+    /** Custom message ID for JetStream deduplication. */
+    messageId?: string | undefined, 
+    /** Schedule options for delayed delivery. */
+    schedule?: ScheduleRecordOptions | undefined, 
+    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
+    ttl?: string | undefined);
 }
 /**
- * Subset of {@link StreamKind} used for direct subject building.
+ * Fluent builder for constructing JetstreamRecord instances.
  *
- * Excludes `Broadcast` because broadcast subjects use a different
- * naming convention (`broadcast.{pattern}` instead of `{service}.{kind}.{pattern}`).
+ * Protected headers (`correlation-id`, `reply-to`, `error`) cannot be
+ * set by the user — attempting to do so throws an error at build time.
  */
-type SubjectKind = Exclude<StreamKind, StreamKind.Broadcast>;
-
-/** Options for one-shot delayed delivery via NATS 2.12 message scheduling. */
-interface ScheduleRecordOptions {
-    /** When to deliver the message. Must be in the future. */
-    at: Date;
-}
-
-/** @internal Grouped pattern lists by stream kind, used for stream/consumer setup. */
-interface PatternsByKind {
-    /** Workqueue event patterns. */
-    events: string[];
-    /** RPC command patterns. */
-    commands: string[];
-    /** Broadcast event patterns. */
-    broadcasts: string[];
-    /** Ordered event patterns (strict sequential delivery). */
-    ordered: string[];
-}
-/** Options for configuring event/broadcast processing behavior. */
-interface EventProcessingConfig {
-    events?: {
-        concurrency?: number;
-        ackExtension?: boolean | number;
-    };
-    broadcast?: {
-        concurrency?: number;
-        ackExtension?: boolean | number;
-    };
-}
-/** Options for dead letter queue handling. */
-interface DeadLetterConfig {
+declare class JetstreamRecordBuilder<TData = unknown> {
+    private data;
+    private readonly headers;
+    private timeout;
+    private messageId;
+    private scheduleOptions;
+    private ttlDuration;
+    constructor(data?: TData);
     /**
-     * Map of stream name -> max_deliver value.
-     * Used to detect when a message from a given stream has exhausted all delivery attempts.
+     * Set the message payload.
+     *
+     * @param data - Payload to serialize via the configured {@link Codec}.
      */
-    maxDeliverByStream: Map<string, number>;
-    /** Async callback invoked when a message exhausts all deliveries. */
-    onDeadLetter(info: DeadLetterInfo): Promise<void>;
-}
-/** Options for configuring RPC processing behavior. */
-interface RpcRouterOptions {
-    timeout?: number;
-    concurrency?: number;
-    ackExtension?: boolean | number;
-}
-
-/**
- * Central event bus for transport lifecycle notifications.
- *
- * Dispatches events to user-provided hooks. Events without a
- * registered hook are silently ignored — no default logging.
- *
- * @example
- * ```typescript
- * const bus = new EventBus(logger, {
- *   [TransportEvent.Error]: (err) => sentry.captureException(err),
- * });
- *
- * bus.emit(TransportEvent.Error, new Error('timeout'), 'rpc-router');
- * // → calls sentry
- *
- * bus.emit(TransportEvent.Connect, 'nats://localhost:4222');
- * // → no-op (no hook registered)
- * ```
- */
-declare class EventBus {
-    private readonly hooks;
-    private readonly logger;
-    constructor(logger: Logger, hooks?: Partial<TransportHooks>);
+    setData(data: TData): this;
     /**
-     * Emit a lifecycle event. Dispatches to custom hook if registered, otherwise no-op.
+     * Set a single custom header.
      *
-     * @param event - The {@link TransportEvent} to emit.
-     * @param args - Arguments matching the hook signature for this event.
+     * @param key - Header name (e.g. `'x-tenant'`).
+     * @param value - Header value.
+     * @throws Error if the header name is reserved by the transport.
      */
-    emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
+    setHeader(key: string, value: string): this;
     /**
-     * Hot-path optimized emit for MessageRouted events.
-     * Avoids rest/spread overhead of the generic `emit()`.
+     * Set multiple custom headers at once.
+     *
+     * @param headers - Key-value pairs to set as headers.
+     * @throws Error if any header name is reserved by the transport.
      */
-    emitMessageRouted(subject: string, kind: MessageKind): void;
+    setHeaders(headers: Record<string, string>): this;
     /**
-     * Check whether a hook is registered for the given event.
+     * Set a custom message ID for JetStream deduplication.
      *
-     * Used by the routing hot path to elide the emit call entirely when the
-     * transport owner did not register a listener.
+     * NATS JetStream uses this ID to detect duplicate publishes within the
+     * stream's `duplicate_window`. If two messages with the same ID arrive
+     * within the window, the second is silently dropped.
+     *
+     * When not set, a random UUID is generated automatically.
+     *
+     * @param id - Unique message identifier (e.g. order ID, idempotency key).
+     *
+     * @example
+     * ```typescript
+     * new JetstreamRecordBuilder(data)
+     *   .setMessageId(`order-${order.id}`)
+     *   .build();
+     * ```
      */
-    hasHook(event: keyof TransportHooks): boolean;
-    private callHook;
-}
-
-/**
- * Manages the lifecycle of a single NATS connection shared across the application.
- *
- * Provides both Promise-based and Observable-based access to the connection:
- * - `connect()` / `getConnection()` — async/await for one-time setup
- * - `nc$` — cached observable (shareReplay) for reactive consumers
- * - `status$` — live connection status event stream
- *
- * One instance per application, created by `JetstreamModule.forRoot()`.
- */
-declare class ConnectionProvider {
-    private readonly options;
-    private readonly eventBus;
-    /** Cached observable that replays the established connection to new subscribers. */
-    readonly nc$: Observable<NatsConnection>;
-    /** Live stream of connection status events (no replay). */
-    readonly status$: Observable<Status>;
-    private readonly logger;
-    private connection;
-    private connectionPromise;
-    private jsClient;
-    private jsmInstance;
-    private jsmPromise;
-    constructor(options: JetstreamModuleOptions, eventBus: EventBus);
+    setMessageId(id: string): this;
     /**
-     * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
+     * Set per-request RPC timeout.
      *
-     * @throws Error if connection is refused (fail fast).
+     * @param ms - Timeout in milliseconds. Overrides the global RPC timeout for this request only.
      */
-    getConnection(): Promise<NatsConnection>;
+    setTimeout(ms: number): this;
     /**
-     * Get the JetStream manager. Cached after first call.
+     * Schedule one-shot delayed delivery.
      *
-     * @returns The JetStreamManager for stream/consumer administration.
+     * The message is held by NATS and delivered to the event consumer
+     * at the specified time. Requires NATS >= 2.12 and `allow_msg_schedules: true`
+     * on the event stream (via `events: { stream: { allow_msg_schedules: true } }`).
+     *
+     * Only meaningful for events (`client.emit()`). If used with RPC
+     * (`client.send()`), a warning is logged and the schedule is ignored.
+     *
+     * @param date - Delivery time. Must be in the future.
+     * @throws Error if the date is not in the future.
      */
-    getJetStreamManager(): Promise<JetStreamManager>;
+    scheduleAt(date: Date): this;
     /**
-     * Get a cached JetStream client.
+     * Set per-message TTL (time-to-live).
      *
-     * Invalidated automatically on reconnect and shutdown so consumers always
-     * operate against the live connection.
+     * The message expires individually after the specified duration,
+     * independent of the stream's `max_age`. Requires NATS >= 2.11 and
+     * `allow_msg_ttl: true` on the stream.
      *
-     * @returns The cached JetStreamClient.
-     * @throws Error if the connection has not been established yet.
+     * Only meaningful for events (`client.emit()`). If used with RPC
+     * (`client.send()`), a warning is logged and the TTL is ignored.
+     *
+     * @param nanos - TTL in nanoseconds. Use {@link toNanos} for human-readable values.
+     *
+     * @example
+     * ```typescript
+     * import { toNanos } from '@horizon-republic/nestjs-jetstream';
+     *
+     * new JetstreamRecordBuilder(payload).ttl(toNanos(30, 'minutes')).build();
+     * new JetstreamRecordBuilder(payload).ttl(toNanos(24, 'hours')).build();
+     * ```
      */
-    getJetStreamClient(): JetStreamClient;
-    /** Direct access to the raw NATS connection, or `null` if not yet connected. */
-    get unwrap(): NatsConnection | null;
+    ttl(nanos: number): this;
     /**
-     * Gracefully shut down the connection.
+     * Build the immutable {@link JetstreamRecord}.
      *
-     * Sequence: drain → wait for close. Falls back to force-close on error.
+     * @returns A frozen record ready to pass to `client.send()` or `client.emit()`.
      */
-    shutdown(): Promise<void>;
-    private initJetStreamManager;
-    /** Internal: establish the physical connection with reconnect monitoring. */
-    private establish;
-    /** Subscribe to connection status events and emit hooks. */
-    private monitorStatus;
+    build(): JetstreamRecord<TData>;
+    /**
+     * Validate that a header key is not reserved. NATS treats header names
+     * case-insensitively, so the check is against the lowercase form to keep
+     * `'X-Correlation-ID'`, `'x-correlation-id'`, and any other casing in
+     * lockstep. `RESERVED_HEADERS` is defined as an all-lowercase set.
+     */
+    private validateHeaderKey;
 }
 
+/** Tag attached to every outgoing publish span so consumers can distinguish event / RPC / broadcast / ordered flows. */
+declare enum PublishKind {
+    Event = "event",
+    RpcRequest = "rpc.request",
+    Broadcast = "broadcast",
+    Ordered = "ordered"
+}
+/** Tag attached to every incoming consume span. `Rpc` covers both Core and JetStream RPC handlers. */
+declare enum ConsumeKind {
+    Event = "event",
+    Rpc = "rpc",
+    Broadcast = "broadcast",
+    Ordered = "ordered"
+}
 /**
- * Registry mapping NATS subjects to NestJS message handlers.
- *
- * Handles subject normalization and categorization:
- * - Detects broadcast handlers via `extras.broadcast` metadata
- * - Normalizes full NATS subjects back to user-facing patterns
- * - Provides lists of patterns by category for stream/consumer setup
+ * Handler metadata for the dispatched message. `pattern` is always set;
+ * `className` / `methodName` come from NestJS reflection when available.
  */
-declare class PatternRegistry {
-    private readonly options;
-    private readonly logger;
-    private readonly registry;
-    private cachedPatterns;
-    private _hasEvents;
-    private _hasCommands;
-    private _hasBroadcasts;
-    private _hasOrdered;
-    private _hasMetadata;
-    constructor(options: JetstreamModuleOptions);
+interface HandlerMetadata {
+    readonly pattern: string;
+    readonly className?: string;
+    readonly methodName?: string;
+}
+/**
+ * Host / port pair surfaced as `server.address` / `server.port` span
+ * attributes. `port` is optional — OTel semconv makes it conditional on
+ * being different from the protocol default, and we'd rather emit nothing
+ * than invent a number the user never configured.
+ */
+interface ServerEndpoint {
+    readonly host: string;
+    readonly port?: number;
+}
+/**
+ * Minimum message shape the consume span helper requires. Both `JsMsg`
+ * (JetStream) and Core NATS `Msg` satisfy it structurally; JetStream-only
+ * delivery metadata (`info`) is read separately and omitted on the Core
+ * RPC path.
+ */
+interface ConsumeSourceMsg {
+    readonly subject: string;
+    readonly data: Uint8Array;
+    readonly headers?: MsgHdrs;
+}
+/** Context passed to {@link OtelOptions.publishHook} for an outgoing publish. */
+interface JetstreamPublishContext {
+    /** Fully-resolved subject the message is being published to. */
+    readonly subject: string;
+    /** The record being published (payload, headers, builder-supplied options). */
+    readonly record: JetstreamRecord;
+    /** Classification of the outgoing operation. */
+    readonly kind: PublishKind;
+}
+/** Context passed to {@link OtelOptions.consumeHook} for an incoming dispatch. */
+interface JetstreamConsumeContext {
+    /** Fully-resolved subject of the incoming message. */
+    readonly subject: string;
+    /**
+     * The incoming NATS message. JetStream messages (events, broadcast,
+     * ordered, JetStream RPC) satisfy `JsMsg`; Core RPC messages satisfy
+     * the looser {@link ConsumeSourceMsg} shape only. Narrow on `kind` to
+     * decide which fields are safe to access.
+     */
+    readonly msg: ConsumeSourceMsg;
+    /** Handler metadata; see {@link HandlerMetadata}. */
+    readonly handlerMetadata: HandlerMetadata;
+    /** Classification of the incoming operation. */
+    readonly kind: ConsumeKind;
+}
+/** Context passed to {@link OtelOptions.responseHook} once an outcome is known, just before the span ends. */
+interface JetstreamResponseContext {
+    /** Subject the operation targeted. */
+    readonly subject: string;
+    /** Wall-clock duration of the operation in milliseconds. */
+    readonly durationMs: number;
+    /** Decoded reply payload for RPC client spans when available. */
+    readonly reply?: unknown;
+    /** Error instance if the operation failed. */
+    readonly error?: Error;
+}
+/**
+ * Classification outcome for a thrown error. Affects span status and
+ * attributes only — reply envelopes and internal logging are unchanged.
+ */
+type ErrorClassification = 'expected' | 'unexpected';
+/** Object form of {@link OtelOptions.captureBody}. */
+interface CaptureBodyOptions {
     /**
-     * Register all handlers from the NestJS strategy.
+     * Maximum number of bytes to capture. Payloads longer than this are
+     * truncated; a `messaging.nats.message.body.truncated` attribute is
+     * added to indicate truncation occurred.
      *
-     * @param handlers Map of pattern -> MessageHandler from `Server.getHandlers()`.
+     * @default 4096
      */
-    registerHandlers(handlers: Map<string, MessageHandler>): void;
-    /** Find handler for a full NATS subject. */
-    getHandler(subject: string): MessageHandler | null;
-    /** Get all registered broadcast patterns (for consumer filter_subject setup). */
-    getBroadcastPatterns(): string[];
-    hasBroadcastHandlers(): boolean;
-    hasRpcHandlers(): boolean;
-    hasEventHandlers(): boolean;
-    hasOrderedHandlers(): boolean;
-    /** Get fully-qualified NATS subjects for ordered handlers. */
-    getOrderedSubjects(): string[];
-    /** Check if any registered handler has metadata. */
-    hasMetadata(): boolean;
+    readonly maxBytes?: number;
     /**
-     * Get handler metadata entries for KV publishing.
-     *
-     * Returns a map of KV key -> metadata object for all handlers that have `meta`.
-     * Key format: `{serviceName}.{kind}.{pattern}`.
+     * Only capture body for subjects matching these glob patterns. Each
+     * pattern supports `*` wildcards and an optional leading `!` for
+     * exclusion. When omitted, body capture applies to all subjects.
      */
-    getMetadataEntries(): Map<string, Record<string, unknown>>;
-    /** Get patterns grouped by kind (cached after registration). */
-    getPatternsByKind(): PatternsByKind;
-    /** Normalize a full NATS subject back to the user-facing pattern. */
-    normalizeSubject(subject: string): string;
-    private buildPatternsByKind;
-    private resolveStreamKind;
-    private logSummary;
+    readonly subjectAllowlist?: readonly string[];
 }
-
 /**
- * Handles RPC via NATS Core request/reply pattern.
- *
- * Subscribes to `{service}.cmd.>` with a queue group for load balancing.
- * Each request is processed and replied to directly via `msg.respond()`.
- *
- * This is the default RPC mode — lowest latency, no persistence overhead.
+ * OpenTelemetry configuration for `JetstreamModule.forRoot({ otel: … })`.
+ * All fields are optional; when the host app has not registered an OTel
+ * SDK, every call made by the library is a no-op regardless of config.
  */
-declare class CoreRpcServer {
-    private readonly options;
-    private readonly connection;
-    private readonly patternRegistry;
-    private readonly codec;
-    private readonly eventBus;
-    private readonly logger;
-    private subscription;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus);
-    /** Start listening for RPC requests on the command subject. */
-    start(): Promise<void>;
-    /** Stop listening and clean up the subscription. */
-    stop(): void;
-    /** Handle an incoming Core NATS request. */
-    private handleRequest;
-    /** Send an error response back to the caller with x-error header. */
-    private respondWithError;
+interface OtelOptions {
+    /**
+     * Global kill switch. When `false`, no spans are emitted, no propagation
+     * is attempted, and no hooks fire.
+     *
+     * @default true
+     */
+    readonly enabled?: boolean;
+    /**
+     * Which trace kinds to emit.
+     *
+     * - `'default'` — publish, consume, RPC client round-trip, dead letter
+     * - `'all'` — every trace kind defined in {@link JetstreamTrace}
+     * - `'none'` — emit no spans at all (useful with `enabled: true` for
+     *   pure trace-context propagation without the span overhead)
+     * - `JetstreamTrace[]` — explicit selection
+     *
+     * @default 'default'
+     */
+    readonly traces?: readonly JetstreamTrace[] | 'default' | 'all' | 'none';
+    /**
+     * Header names to capture as span attributes (`messaging.header.<name>`).
+     * Match is case-insensitive. Glob wildcards (`*`) and negation (`!prefix-*`)
+     * are supported in the per-pattern form.
+     *
+     * SECURITY / GDPR: headers may contain authentication tokens, session
+     * identifiers, or other sensitive data. Captured values are exported to
+     * the configured OTel backend. Use an explicit allowlist in production.
+     * Setting this to `true` captures every header and is intended for
+     * development environments only.
+     *
+     * Transport-internal headers (`x-correlation-id`, `x-reply-to`, `x-error`,
+     * `x-subject`, `x-caller-name`) and propagator-owned headers
+     * (`traceparent`, `tracestate`, `baggage`, `sentry-trace`, `b3`, …) are
+     * always suppressed regardless of the allowlist.
+     *
+     * @default ['x-request-id']
+     */
+    readonly captureHeaders?: readonly string[] | boolean;
+    /**
+     * Capture the message payload as the `messaging.nats.message.body` span
+     * attribute. Defaults to `false` for privacy and cost reasons.
+     *
+     * Passing `true` captures up to 4 KiB per message. Use the object form
+     * for finer control over size and subject scope.
+     *
+     * SECURITY / GDPR: payloads commonly contain PII, credentials, financial
+     * data, or content regulated by HIPAA / PCI-DSS. Enabling body capture
+     * in production is almost always a policy violation. Prefer enabling
+     * only in development, or pair with a custom `SpanProcessor` that
+     * scrubs or drops the attribute before export.
+     *
+     * @default false
+     */
+    readonly captureBody?: boolean | CaptureBodyOptions;
+    /**
+     * Invoked after a publish span has been started and before the actual
+     * publish call executes. Use to enrich the span with custom attributes.
+     * Must be synchronous — thrown errors are caught and logged at debug
+     * level without affecting the publish path.
+     */
+    publishHook?(span: Span, ctx: JetstreamPublishContext): void;
+    /**
+     * Invoked after a consume span has been started and before the handler
+     * is dispatched. Use to enrich the span with custom attributes derived
+     * from the incoming message or handler metadata.
+     */
+    consumeHook?(span: Span, ctx: JetstreamConsumeContext): void;
+    /**
+     * Invoked once an operation's outcome is known (success, error, or
+     * timeout) and the span status has been set, just before the span ends.
+     * Fires for publish, consume, and RPC client spans.
+     */
+    responseHook?(span: Span, ctx: JetstreamResponseContext): void;
+    /**
+     * Predicate evaluated at the top of every outgoing publish. Returning
+     * `false` skips span creation for that publish; propagation of trace
+     * context through headers still occurs, so downstream consumers are
+     * unaffected. Useful for suppressing noise from health-check or
+     * internal-only subjects.
+     */
+    shouldTracePublish?(subject: string, record: JetstreamRecord): boolean;
+    /**
+     * Predicate evaluated at the top of every incoming message delivery.
+     * Returning `false` skips span creation for that delivery; the handler
+     * still executes normally and trace context is still extracted from
+     * headers for downstream calls.
+     */
+    shouldTraceConsume?(subject: string, msg: ConsumeSourceMsg): boolean;
+    /**
+     * Classify a thrown error as `'expected'` (business error, part of the
+     * RPC contract) or `'unexpected'` (infrastructure failure or bug). Drives
+     * OpenTelemetry span status and attributes only.
+     *
+     * - `'expected'` → span status `OK` with `jetstream.rpc.reply.has_error`
+     *   and `jetstream.rpc.reply.error.code` attributes
+     * - `'unexpected'` → span status `ERROR` with `span.recordException(err)`
+     *
+     * Reply envelopes delivered to RPC clients are identical in both cases.
+     * This classification affects only the observability artifact.
+     *
+     * The default recognizes NestJS-idiomatic primitives for business errors:
+     * `RpcException` and `HttpException`. Teams with custom error hierarchies
+     * override to recognize their own types.
+     *
+     * @example
+     *   errorClassifier: (err) => {
+     *     if (err instanceof MyDomainError) return 'expected';
+     *     if (err?.code?.startsWith('BIZ_')) return 'expected';
+     *     return 'unexpected';
+     *   }
+     */
+    errorClassifier?(err: unknown): ErrorClassification;
 }
 
 /**
- * Manages JetStream stream lifecycle: creation, updates, and idempotent ensures.
+ * Stream config overrides exposed to users.
  *
- * Creates up to three stream types depending on configuration:
- * - **Event stream** — workqueue events (always, when consumer enabled)
- * - **Command stream** — RPC commands (only in jetstream RPC mode)
- * - **Broadcast stream** — fan-out events (only if broadcast handlers exist)
+ * `retention` is excluded because it is controlled by the transport layer
+ * (Workqueue for events/commands, Limits for broadcast/ordered).
+ * Any `retention` value provided at runtime is silently stripped.
+ */
+type StreamConfigOverrides = Partial<Omit<StreamConfig, 'retention'>>;
+/**
+ * RPC transport configuration.
  *
- * All operations are idempotent: safe to call on every startup and reconnection.
+ * Discriminated union on `mode`:
+ * - `'core'`      — NATS native request/reply. Lowest latency.
+ * - `'jetstream'`  — Commands persisted in JetStream. Responses via Core NATS inbox.
+ *
+ * When `mode` is `'core'`, only `timeout` is available.
+ * When `mode` is `'jetstream'`, additional stream/consumer overrides are exposed.
  */
-declare class StreamProvider {
-    private readonly options;
-    private readonly connection;
-    private readonly logger;
-    private readonly migration;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
+type RpcConfig = {
+    mode: 'core';
+    /** Request timeout in ms. Default: 30_000. */
+    timeout?: number;
+} | {
+    mode: 'jetstream';
+    /** Handler timeout in ms. Default: 180_000 (3 min). */
+    timeout?: number;
+    /** Raw NATS StreamConfig overrides for the command stream. */
+    stream?: StreamConfigOverrides;
+    /** Raw NATS ConsumerConfig overrides for the command consumer. */
+    consumer?: Partial<ConsumerConfig>;
+    /** Options passed to the nats.js `consumer.consume()` call for the command consumer. */
+    consume?: Partial<ConsumeOptions>;
+    /** Maximum number of concurrent RPC handler executions. */
+    concurrency?: number;
     /**
-     * Ensure all required streams exist with correct configuration.
+     * Auto-extend ack deadline via `msg.working()` during RPC handler execution.
+     * The RPC handler timeout (`setTimeout` + `msg.term()`) still acts as the hard cap.
+     */
+    ackExtension?: boolean | number;
+};
+/** Overrides for JetStream stream and consumer configuration. */
+interface StreamConsumerOverrides {
+    stream?: StreamConfigOverrides;
+    consumer?: Partial<ConsumerConfig>;
+    /**
+     * Options passed to the nats.js `consumer.consume()` call.
+     * Controls prefetch buffer size, idle heartbeat interval, and auto-refill thresholds.
      *
-     * @param kinds Which stream kinds to create. Determined by the module based
-     *              on RPC mode and registered handler patterns.
-     * If the dlq option is enabled, also ensures the DLQ stream exists.
+     * nats.js supports two consumption modes (message-based and byte-based).
+     * Do not mix `max_bytes`/`threshold_bytes` with `threshold_messages` —
+     * use one mode or the other.
+     *
+     * @see https://github.com/nats-io/nats.js — ConsumeOptions
      */
-    ensureStreams(kinds: StreamKind[]): Promise<void>;
-    /** Get the stream name for a given kind. */
-    getStreamName(kind: StreamKind): string;
-    /** Get the subjects pattern for a given kind. */
-    getSubjects(kind: StreamKind): string[];
-    /** Ensure a single stream exists, creating or updating as needed. */
-    private ensureStream;
-    /** Ensure a dead-letter queue stream exists, creating or updating as needed. */
-    private ensureDlqStream;
-    private handleExistingStream;
-    private buildMutableOnlyConfig;
-    private logChanges;
-    /** Build the full stream config by merging defaults with user overrides. */
-    private buildConfig;
+    consume?: Partial<ConsumeOptions>;
     /**
-     * Build the stream configuration for the Dead-Letter Queue (DLQ).
+     * Maximum number of concurrent handler executions (RxJS `mergeMap` limit).
      *
-     * Merges the library default DLQ config with user-provided overrides.
-     * Ensures transport-controlled settings like retention are safely decoupled.
+     * Default: `undefined` (unlimited — naturally bounded by `max_ack_pending`).
+     * Set this to protect downstream systems from overload.
+     *
+     * **Important:** if `concurrency < max_ack_pending`, messages buffer in RxJS
+     * while their NATS ack timer ticks. Increase `ack_wait` proportionally to
+     * prevent unnecessary redeliveries.
      */
-    private buildDlqConfig;
-    /** Get default config for a stream kind. */
-    private getDefaults;
-    /** Check if scheduling is enabled for a stream kind via `allow_msg_schedules` override. */
-    private isSchedulingEnabled;
-    /** Get user-provided overrides for a stream kind, stripping transport-controlled properties. */
-    private getOverrides;
+    concurrency?: number;
     /**
-     * Remove transport-controlled properties from user overrides.
-     * `retention` is managed by the transport (Workqueue/Limits per stream kind)
-     * and silently stripped to protect users from misconfiguration.
+     * Auto-extend the NATS ack deadline via `msg.working()` during handler execution.
+     *
+     * - `false` (default): disabled — NATS redelivers after `ack_wait` if not acked.
+     * - `true`: auto-extend at `ack_wait / 2` interval (calculated from consumer config).
+     * - `number`: explicit extension interval in milliseconds.
      */
-    private stripTransportControlled;
+    ackExtension?: boolean | number;
 }
-
 /**
- * Routes incoming event messages (workqueue, broadcast, and ordered) to NestJS handlers.
- *
- * **Workqueue & Broadcast** — at-least-once delivery:
- * - Success -> ack | Error -> nak (retry) | Dead letter -> term
+ * Configuration for ordered event consumers.
  *
- * **Ordered** — strict sequential delivery:
- * - No ack/nak/DLQ — nats.js auto-acknowledges ordered consumer messages.
- * - Handler errors are logged but do not affect delivery.
+ * Ordered consumers use Limits retention and deliver messages in strict
+ * sequential order with at-most-once delivery. No ack/nak/DLQ.
  *
- * **Dead-Letter Queue (DLQ) - for handling failed message deliveries**
- * - If `options.dlq` is configured, messages that exhaust their max delivery attempts are published to a DLQ stream.
- * - The DLQ stream name is derived from the service name (e.g., `orders__microservice_dlq-stream`).
- * - Original message data and metadata are preserved in the DLQ message, with additional headers indicating the reason for failure.
+ * Only a subset of consumer options applies — ordered consumers are
+ * ephemeral and auto-managed by nats.js.
  */
-declare class EventRouter {
-    private readonly messageProvider;
-    private readonly patternRegistry;
-    private readonly codec;
-    private readonly eventBus;
-    private readonly deadLetterConfig?;
-    private readonly processingConfig?;
-    private readonly ackWaitMap?;
-    private readonly connection?;
-    private readonly options?;
-    private readonly logger;
-    private readonly subscriptions;
-    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined, processingConfig?: EventProcessingConfig | undefined, ackWaitMap?: Map<StreamKind, number> | undefined, connection?: ConnectionProvider | undefined, options?: JetstreamModuleOptions | undefined);
+interface OrderedEventOverrides {
+    /** Stream overrides (e.g. `max_age`, `max_bytes`). */
+    stream?: StreamConfigOverrides;
     /**
-     * Update the max_deliver thresholds from actual NATS consumer configs.
-     * Called after consumers are ensured so the DLQ map reflects reality.
+     * Where to start reading when the consumer is (re)created.
+     * @default DeliverPolicy.All
      */
-    updateMaxDeliverMap(consumerMaxDelivers: Map<string, number>): void;
-    /** Start routing event, broadcast, and ordered messages to handlers. */
-    start(): void;
-    /** Stop routing and unsubscribe from all streams. */
-    destroy(): void;
-    /** Subscribe to a message stream and route each message to its handler. */
-    private subscribeToStream;
-    private getConcurrency;
-    private getAckExtensionConfig;
-    /** Handle a dead letter: invoke callback, then term or nak based on result. */
+    deliverPolicy?: DeliverPolicy;
     /**
-     * Fallback execution for a dead letter when DLQ is disabled, or when
-     * publishing to the DLQ stream fails (due to network or NATS errors).
-     *
-     * Triggers the user-provided `onDeadLetter` hook for logging/alerting.
-     * On success, terminates the message. On error, leaves it unacknowledged (nak)
-     * so NATS can retry the delivery on the next cycle.
+     * Start sequence number. Only used when `deliverPolicy` is `StartSequence`.
      */
-    private fallbackToOnDeadLetterCallback;
+    optStartSeq?: number;
     /**
-     * Publish a dead letter to the configured Dead-Letter Queue (DLQ) stream.
-     *
-     * Appends diagnostic metadata headers to the original message and preserves
-     * the primary payload. If publishing succeeds, it notifies the standard
-     * `onDeadLetter` callback and terminates the message. If it fails, it falls
-     * back to the callback entirely to prevent silent data loss.
+     * Start time (ISO string). Only used when `deliverPolicy` is `StartTime`.
      */
-    private publishToDlq;
+    optStartTime?: string;
     /**
-     * Orchestrates the handling of a message that has exhausted delivery limits.
-     *
-     * Emits a system event and delegates either to the robust DLQ stream publisher
-     * or directly to the fallback callback based on the active module configuration.
+     * Replay policy for historical messages.
+     * @default ReplayPolicy.Instant
      */
-    private handleDeadLetter;
+    replayPolicy?: ReplayPolicy;
 }
-
 /**
- * Routes RPC command messages in JetStream mode.
+ * Configuration for the handler metadata KV registry.
  *
- * Delivery semantics:
- * - Handler must complete within timeout (default: 3 min)
- * - Success -> ack -> publish response to ReplyTo (publish failure does not affect ack)
- * - Handler error -> publish error to ReplyTo -> term (no redelivery)
- * - Timeout -> no response -> term
- * - No handler / decode error -> term immediately
+ * When any handler has `meta` in its extras, the transport writes metadata
+ * entries to a NATS KV bucket at startup. External services (API gateways,
+ * dashboards) can watch the bucket for service discovery.
  *
- * Nak is never used for RPC — prevents duplicate side effects.
+ * All fields are optional — sensible defaults are applied.
  */
-declare class RpcRouter {
-    private readonly messageProvider;
-    private readonly patternRegistry;
-    private readonly connection;
-    private readonly codec;
-    private readonly eventBus;
-    private readonly rpcOptions?;
-    private readonly ackWaitMap?;
-    private readonly logger;
-    private readonly timeout;
-    private readonly concurrency;
-    private resolvedAckExtensionInterval;
-    private subscription;
-    private cachedNc;
-    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, rpcOptions?: RpcRouterOptions | undefined, ackWaitMap?: Map<StreamKind, number> | undefined);
-    /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
-    private get ackExtensionInterval();
-    /** Start routing command messages to handlers. */
-    start(): Promise<void>;
-    /** Stop routing and unsubscribe. */
-    destroy(): void;
+interface MetadataRegistryOptions {
+    /**
+     * KV bucket name.
+     * @default 'handler_registry'
+     */
+    bucket?: string;
+    /**
+     * Number of KV bucket replicas. Must be an odd number (1, 3, 5, 7, ...).
+     * Requires a NATS cluster with at least this many nodes.
+     * @default 1
+     */
+    replicas?: number;
+    /**
+     * KV bucket TTL in milliseconds.
+     *
+     * Entries expire automatically unless refreshed by a heartbeat.
+     * The transport refreshes entries every `ttl / 2` while the pod is alive.
+     * When the pod stops (graceful or crash), entries expire after this duration.
+     *
+     * @default 30_000 (30 seconds)
+     */
+    ttl?: number;
 }
-
 /**
- * Manages JetStream consumer lifecycle: creation and idempotent ensures.
+ * Root module configuration for `JetstreamModule.forRoot()`.
  *
- * Creates durable pull-based consumers that survive restarts.
- * Consumer configuration is merged from defaults and user overrides.
+ * Minimal usage requires only `name` and `servers`.
+ * All other fields have production-ready defaults.
  */
-declare class ConsumerProvider {
-    private readonly options;
-    private readonly connection;
-    private readonly streamProvider;
-    private readonly patternRegistry;
-    private readonly logger;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, streamProvider: StreamProvider, patternRegistry: PatternRegistry);
+interface JetstreamModuleOptions {
+    /** Service name. Used for stream/consumer/subject naming. */
+    name: string;
+    /** NATS server URLs. */
+    servers: string[];
     /**
-     * Ensure consumers exist for the specified kinds.
+     * Global message codec.
+     * @default JsonCodec
+     */
+    codec?: Codec;
+    /**
+     * RPC transport mode and configuration.
+     * @default { mode: 'core' }
+     */
+    rpc?: RpcConfig;
+    /**
+     * Enable consumer infrastructure (streams, consumers, message routing).
+     * Set to `false` for publisher-only services (e.g., API gateways).
+     * @default true
+     */
+    consumer?: boolean;
+    /** Workqueue event stream/consumer overrides. */
+    events?: StreamConsumerOverrides;
+    /** Broadcast event stream/consumer overrides. */
+    broadcast?: StreamConsumerOverrides;
+    /**
+     * Ordered event consumer configuration.
      *
-     * @returns Map of kind -> ConsumerInfo for downstream use.
+     * Ordered events use a separate stream with Limits retention and deliver
+     * messages in strict sequential order. Use `ordered:` prefix when publishing.
+     *
+     * @see OrderedEventOverrides
      */
-    ensureConsumers(kinds: StreamKind[]): Promise<Map<StreamKind, ConsumerInfo>>;
-    /** Get the consumer name for a given kind. */
-    getConsumerName(kind: StreamKind): string;
+    ordered?: OrderedEventOverrides;
     /**
-     * Ensure a single consumer exists with the desired config.
-     * Used at **startup** — creates or updates the consumer to match
-     * the current pod's configuration.
+     * Transport lifecycle hook handlers.
+     * Unset hooks are silently ignored — no default logging.
      */
-    ensureConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
+    hooks?: Partial<TransportHooks>;
     /**
-     * Recover a consumer that disappeared during runtime.
-     * Used by **self-healing** — creates if missing, but NEVER updates config.
+     * Async callback invoked when an event message exhausts all delivery attempts.
+     * Called before msg.term(). If it throws, the message is nak'd for retry.
      *
-     * If a migration backup stream exists, another pod is mid-migration — we
-     * throw so the self-healing retry loop waits with backoff until migration
-     * completes and the backup is cleaned up.
+     * Use this to persist dead letters to an external store (DB, S3, another queue).
+     * The NATS connection is available via `JETSTREAM_CONNECTION` token in forRootAsync.
      *
-     * This prevents old pods from:
-     * - Overwriting a newer pod's consumer config during rolling updates
-     * - Creating consumers during migration (which would consume and delete
-     *   workqueue messages while they're being restored)
+     * @example
+     * ```typescript
+     * JetstreamModule.forRootAsync({
+     *   name: 'my-service',
+     *   imports: [DlqModule],
+     *   inject: [DlqService, JETSTREAM_CONNECTION],
+     *   useFactory: (dlqService, connection) => ({
+     *     servers: ['nats://localhost:4222'],
+     *     onDeadLetter: async (info) => {
+     *       await dlqService.persist(info);
+     *     },
+     *   }),
+     * })
+     * ```
+     */
+    onDeadLetter?(info: DeadLetterInfo): Promise<void>;
+    /**
+     * Dead-letter queue (DLQ) configuration.
+     * DLQ is a separate stream used to store messages that have exhausted all delivery attempts.
+     * @example
+     * ```typescript
+     * JetstreamModule.forRootAsync({
+     *   name: 'my-service',
+     *   servers: ['nats://localhost:4222'],
+     *   dlq: {
+     *     stream: {
+     *       max_age: toNanos(30, 'days'),
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    dlq?: {
+        stream?: StreamConfigOverrides;
+    };
+    /**
+     * Graceful shutdown timeout in ms.
+     * Handlers exceeding this are abandoned.
+     * @default 10_000
+     */
+    shutdownTimeout?: number;
+    /**
+     * Allow destructive stream migration when immutable config changes are detected.
+     *
+     * When `true`, the transport will recreate streams (via blue-green sourcing)
+     * if immutable properties like `storage` differ from the running stream.
+     * Messages are preserved during migration.
+     *
+     * `retention` is NOT migratable — it is controlled by the transport
+     * (Workqueue for events, Limits for broadcast/ordered) and a mismatch
+     * is always treated as an error regardless of this flag.
+     *
+     * When `false` (default), immutable conflicts are logged as warnings and
+     * the stream continues with its existing configuration.
+     *
+     * @default false
+     */
+    allowDestructiveMigration?: boolean;
+    /**
+     * Handler metadata KV registry configuration.
+     *
+     * When any handler has `meta` in its `@EventPattern` / `@MessagePattern` extras,
+     * the transport writes metadata to a NATS KV bucket at startup.
+     * External services (API gateways, dashboards, CLI tools) can read or watch
+     * the bucket for dynamic service discovery.
+     *
+     * Auto-enabled when any handler has `meta`. Set to customize bucket name,
+     * replicas, or TTL.
+     *
+     * @see MetadataRegistryOptions
+     */
+    metadata?: MetadataRegistryOptions;
+    /**
+     * Raw NATS ConnectionOptions pass-through for advanced connection config.
+     * Allows setting tls, auth, reconnect behavior, maxReconnectAttempts, etc.
+     * Merged with `name` and `servers` — those take precedence.
+     */
+    connectionOptions?: Partial<ConnectionOptions>;
+    /**
+     * Built-in Prometheus metrics.
+     *
+     * Pass `true` to enable with defaults, or a {@link MetricsConfig} object for
+     * full control (custom registry, prefix, labels, polling, buckets).
+     * When omitted or `false`, the metrics module is not registered and
+     * `prom-client` is not imported — zero overhead.
+     *
+     * Requires `prom-client` peer dependency to be installed when enabled.
+     * The service writes to `prom-client`'s global `register` by default,
+     * making integration with `@willsoto/nestjs-prometheus` (or any
+     * `prom-client`-based `/metrics` exporter) work without coordination.
+     *
+     * @see MetricsConfig
+     * @example
+     * ```typescript
+     * JetstreamModule.forRoot({
+     *   name: 'orders',
+     *   servers: ['nats://localhost:4222'],
+     *   metrics: true,
+     * })
+     * ```
      */
-    recoverConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
+    metrics?: MetricsOption;
     /**
-     * Throw if a migration backup stream exists for this stream.
-     * The self-healing retry loop catches the error and retries with backoff,
-     * naturally waiting until the migrating pod finishes and cleans up the backup.
+     * OpenTelemetry integration. When omitted, sensible defaults are applied:
+     * tracing is enabled, default trace kinds are emitted, only standard
+     * correlation headers are captured. If no OTel SDK is registered in the
+     * consuming application, all tracer calls are no-ops — there is no
+     * runtime cost.
+     *
+     * @see OtelOptions
      */
-    private assertNoMigrationInProgress;
+    otel?: OtelOptions;
+}
+/** Options for `JetstreamModule.forFeature()`. */
+interface JetstreamFeatureOptions {
+    /** Target service name for subject construction. */
+    name: string;
     /**
-     * Create a consumer, handling the race where another pod creates it first.
+     * Override the global codec for this client.
+     * Falls back to the root codec from `forRoot()` when omitted.
      */
-    private createConsumer;
-    /** Build consumer config by merging defaults with user overrides. */
-    private buildConfig;
-    /** Get default config for a consumer kind. */
-    private getDefaults;
-    /** Get user-provided overrides for a consumer kind. */
-    private getOverrides;
+    codec?: Codec;
 }
-
-/** Callback to recreate a consumer when it disappears. */
-type ConsumerRecoveryFn = (kind: StreamKind) => Promise<ConsumerInfo>;
 /**
- * Manages pull-based message consumption from JetStream consumers.
- *
- * Uses `defer()` + `repeat()` pattern for self-healing: when the async
- * iterator completes (e.g., NATS restart), the consumer automatically
- * re-establishes after a short delay.
+ * Async configuration for `JetstreamModule.forRootAsync()`.
  *
- * Emits messages to kind-specific RxJS subjects for downstream routing.
+ * Supports three patterns: `useFactory`, `useExisting`, `useClass`.
  */
-declare class MessageProvider {
-    private readonly connection;
-    private readonly eventBus;
-    private readonly consumeOptionsMap;
-    private readonly consumerRecoveryFn?;
-    private readonly logger;
-    private readonly activeIterators;
-    private orderedReadyResolve;
-    private orderedReadyReject;
-    private destroy$;
-    private eventMessages$;
-    private commandMessages$;
-    private broadcastMessages$;
-    private orderedMessages$;
-    constructor(connection: ConnectionProvider, eventBus: EventBus, consumeOptionsMap?: Map<StreamKind, Partial<ConsumeOptions>>, consumerRecoveryFn?: ConsumerRecoveryFn | undefined);
-    /** Observable stream of workqueue event messages. */
-    get events$(): Observable<JsMsg>;
-    /** Observable stream of RPC command messages (jetstream mode). */
-    get commands$(): Observable<JsMsg>;
-    /** Observable stream of broadcast event messages. */
-    get broadcasts$(): Observable<JsMsg>;
-    /** Observable stream of ordered event messages (strict sequential delivery). */
-    get ordered$(): Observable<JsMsg>;
-    /**
-     * Start consuming messages from the given consumer infos.
-     *
-     * Each consumer gets an independent self-healing flow.
-     * Call `destroy()` to stop all consumers.
-     */
-    start(consumers: Map<StreamKind, ConsumerInfo>): void;
+type JetstreamModuleAsyncOptions = {
+    /** Service name — required upfront for DI token generation. */
+    name: string;
+    /** Additional module imports (e.g., ConfigModule). */
+    imports?: ModuleMetadata['imports'];
     /**
-     * Start an ordered consumer for strict sequential delivery.
-     *
-     * Unlike durable consumers, ordered consumers are ephemeral — created at
-     * consumption time, no durable state. nats.js handles auto-recreation.
+     * Built-in Prometheus metrics. Specified at the async-options level (parallel
+     * to {@link name}) because module composition is decided synchronously before
+     * the async factory runs. Use `true` for defaults, a {@link MetricsConfig}
+     * object for full control, or omit/`false` to disable entirely.
      *
-     * @param streamName - JetStream stream to consume from.
-     * @param filterSubjects - NATS subjects to filter on.
-     * @param orderedConfig - Optional overrides for ordered consumer options.
+     * @see JetstreamModuleOptions.metrics
      */
-    startOrdered(streamName: string, filterSubjects: string[], orderedConfig?: OrderedEventOverrides): Promise<void>;
-    /** Stop all consumer flows and reinitialize subjects for potential restart. */
-    destroy(): void;
-    /** Create a self-healing consumer flow for a specific kind. */
-    private createFlow;
-    /** Single iteration: get consumer -> pull messages -> emit to subject. */
-    private consumeOnce;
+    metrics?: MetricsOption;
+} & ({
+    useFactory(...args: unknown[]): Promise<Omit<JetstreamModuleOptions, 'name'>> | Omit<JetstreamModuleOptions, 'name'>;
+    inject?: FactoryProvider['inject'];
+    useExisting?: never;
+    useClass?: never;
+} | {
+    useExisting: Type<Omit<JetstreamModuleOptions, 'name'>>;
+    useFactory?: never;
+    inject?: never;
+    useClass?: never;
+} | {
+    useClass: Type<Omit<JetstreamModuleOptions, 'name'>>;
+    useFactory?: never;
+    inject?: never;
+    useExisting?: never;
+});
+
+/** Options for one-shot delayed delivery via NATS 2.12 message scheduling. */
+interface ScheduleRecordOptions {
+    /** When to deliver the message. Must be in the future. */
+    at: Date;
+}
+
+/** @internal Grouped pattern lists by stream kind, used for stream/consumer setup. */
+interface PatternsByKind {
+    /** Workqueue event patterns. */
+    events: string[];
+    /** RPC command patterns. */
+    commands: string[];
+    /** Broadcast event patterns. */
+    broadcasts: string[];
+    /** Ordered event patterns (strict sequential delivery). */
+    ordered: string[];
+}
+/** Options for configuring event/broadcast processing behavior. */
+interface EventProcessingConfig {
+    events?: {
+        concurrency?: number;
+        ackExtension?: boolean | number;
+    };
+    broadcast?: {
+        concurrency?: number;
+        ackExtension?: boolean | number;
+    };
+}
+/** Options for dead letter queue handling. */
+interface DeadLetterConfig {
     /**
-     * Detect "consumer not found" errors from `js.consumers.get()`.
-     *
-     * Unlike JetStream Manager calls (which throw `JetStreamApiError`),
-     * the JetStream client's `consumers.get()` throws a plain `Error`
-     * with the error code embedded in the message text.
+     * Map of stream name -> max_deliver value.
+     * Used to detect when a message from a given stream has exhausted all delivery attempts.
      */
-    private isConsumerNotFound;
-    /** Get the target subject for a consumer kind. */
-    private getTargetSubject;
-    /** Monitor heartbeats and restart the consumer iterator on prolonged silence. */
-    private monitorConsumerHealth;
-    /** Create a self-healing ordered consumer flow. */
-    private createOrderedFlow;
-    /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
-    private createSelfHealingFlow;
-    /** Single iteration: create ordered consumer -> push messages into the subject. */
-    private consumeOrderedOnce;
+    maxDeliverByStream: Map<string, number>;
+    /** Async callback invoked when a message exhausts all deliveries. */
+    onDeadLetter(info: DeadLetterInfo): Promise<void>;
+}
+/** Options for configuring RPC processing behavior. */
+interface RpcRouterOptions {
+    timeout?: number;
+    concurrency?: number;
+    ackExtension?: boolean | number;
 }
 
 /**
- * Publishes handler metadata to a NATS KV bucket for external service discovery.
- *
- * Uses TTL + heartbeat to manage entry lifecycle:
- * - Entries are written on startup and refreshed every `ttl / 2`
- * - When the pod stops (graceful or crash), heartbeat stops → entries expire via TTL
- * - No explicit delete needed — NATS handles expiry automatically
+ * Registry mapping NATS subjects to NestJS message handlers.
  *
- * This provider is fully decoupled from stream/consumer infrastructure —
- * it only depends on the NATS connection and module options.
+ * Handles subject normalization and categorization:
+ * - Detects broadcast handlers via `extras.broadcast` metadata
+ * - Normalizes full NATS subjects back to user-facing patterns
+ * - Provides lists of patterns by category for stream/consumer setup
  */
-declare class MetadataProvider {
-    private readonly connection;
+declare class PatternRegistry {
+    private readonly options;
     private readonly logger;
-    private readonly bucketName;
-    private readonly replicas;
-    private readonly ttl;
-    private currentEntries?;
-    private heartbeatTimer?;
-    private cachedKv?;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
+    private readonly registry;
+    private cachedPatterns;
+    private _hasEvents;
+    private _hasCommands;
+    private _hasBroadcasts;
+    private _hasOrdered;
+    private _hasMetadata;
+    constructor(options: JetstreamModuleOptions);
     /**
-     * Write handler metadata entries to the KV bucket and start heartbeat.
-     *
-     * Creates the bucket if it doesn't exist (idempotent).
-     * Skips silently when entries map is empty.
-     * Starts a heartbeat interval that refreshes entries every `ttl / 2`
-     * to prevent TTL expiry while the pod is alive.
+     * Register all handlers from the NestJS strategy.
      *
-     * Non-critical — errors are logged but do not prevent transport startup.
+     * @param handlers Map of pattern -> MessageHandler from `Server.getHandlers()`.
+     */
+    registerHandlers(handlers: Map<string, MessageHandler>): void;
+    /** Find handler for a full NATS subject. */
+    getHandler(subject: string): MessageHandler | null;
+    /**
+     * Resolve the declared pattern and {@link StreamKind} for a full NATS subject.
      *
-     * @param entries Map of KV key → metadata object.
+     * Returns `null` when the subject is not registered. The declared pattern is
+     * the value the user passed to `@EventPattern`/`@MessagePattern` — stable and
+     * bounded, suitable for use as a Prometheus label without cardinality risk.
      */
-    publish(entries: Map<string, Record<string, unknown>>): Promise<void>;
+    resolveDeclared(subject: string): {
+        pattern: string;
+        kind: StreamKind;
+    } | null;
+    /** Get all registered broadcast patterns (for consumer filter_subject setup). */
+    getBroadcastPatterns(): string[];
+    hasBroadcastHandlers(): boolean;
+    hasRpcHandlers(): boolean;
+    hasEventHandlers(): boolean;
+    hasOrderedHandlers(): boolean;
+    /** Get fully-qualified NATS subjects for ordered handlers. */
+    getOrderedSubjects(): string[];
+    /** Check if any registered handler has metadata. */
+    hasMetadata(): boolean;
     /**
-     * Stop the heartbeat timer.
+     * Get handler metadata entries for KV publishing.
      *
-     * After this call, entries will expire via TTL once the heartbeat window passes.
-     * Called during transport shutdown (strategy.close()).
+     * Returns a map of KV key -> metadata object for all handlers that have `meta`.
+     * Key format: `{serviceName}.{kind}.{pattern}`.
      */
-    destroy(): void;
-    /** Write entries to KV with per-entry error handling. */
-    private writeEntries;
-    /** Start heartbeat interval that refreshes entries every ttl/2. */
-    private startHeartbeat;
-    /** Refresh all current entries in KV (heartbeat tick). */
-    private refreshEntries;
-    /** Create or open the KV bucket (cached after first call). */
-    private openBucket;
+    getMetadataEntries(): Map<string, Record<string, unknown>>;
+    /** Get patterns grouped by kind (cached after registration). */
+    getPatternsByKind(): PatternsByKind;
+    /** Normalize a full NATS subject back to the user-facing pattern. */
+    normalizeSubject(subject: string): string;
+    private buildPatternsByKind;
+    private resolveStreamKind;
+    private logSummary;
 }
 
 /**
- * NATS JetStream API error codes used by the transport.
+ * Handles RPC via NATS Core request/reply pattern.
  *
- * Ref: https://github.com/nats-io/nats-server (server error definitions)
- * Verified on NATS 2.12.6 via integration tests (2026-04-02).
+ * Subscribes to `{service}.cmd.>` with a queue group for load balancing.
+ * Each request is processed and replied to directly via `msg.respond()`.
+ *
+ * This is the default RPC mode — lowest latency, no persistence overhead.
  */
-declare enum NatsErrorCode {
-    /** Consumer does not exist on the specified stream. */
-    ConsumerNotFound = 10014,
-    /** Consumer name already in use with different configuration (race condition on create). */
-    ConsumerAlreadyExists = 10148,
-    /** Stream does not exist. */
-    StreamNotFound = 10059
+declare class CoreRpcServer {
+    private readonly connection;
+    private readonly patternRegistry;
+    private readonly codec;
+    private readonly eventBus;
+    private readonly logger;
+    private subscription;
+    private readonly otel;
+    private readonly serviceName;
+    private readonly serverEndpoint;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus);
+    /** Start listening for RPC requests on the command subject. */
+    start(): Promise<void>;
+    /** Stop listening and clean up the subscription. */
+    stop(): void;
+    /** Handle an incoming Core NATS request. */
+    private handleRequest;
+    private reportHandlerCompleted;
+    /** Send an error response back to the caller with x-error header. */
+    private respondWithError;
 }
 
 /**
- * NestJS custom transport strategy for NATS JetStream.
+ * Manages JetStream stream lifecycle: creation, updates, and idempotent ensures.
  *
- * Coordinates all server-side providers:
- * 1. Registers handlers from NestJS into PatternRegistry
- * 2. Creates required streams and consumers
- * 3. Starts message consumption and routing
- * 4. Handles Core or JetStream RPC based on configuration
+ * Creates up to three stream types depending on configuration:
+ * - **Event stream** — workqueue events (always, when consumer enabled)
+ * - **Command stream** — RPC commands (only in jetstream RPC mode)
+ * - **Broadcast stream** — fan-out events (only if broadcast handlers exist)
  *
- * All dependencies are injected via the NestJS DI container.
+ * All operations are idempotent: safe to call on every startup and reconnection.
  */
-declare class JetstreamStrategy extends Server implements CustomTransportStrategy {
+declare class StreamProvider {
     private readonly options;
     private readonly connection;
-    private readonly patternRegistry;
-    private readonly streamProvider;
-    private readonly consumerProvider;
-    private readonly messageProvider;
-    private readonly eventRouter;
-    private readonly rpcRouter;
-    private readonly coreRpcServer;
-    private readonly ackWaitMap;
-    private readonly metadataProvider?;
-    readonly transportId: symbol;
-    private readonly listeners;
-    private started;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, streamProvider: StreamProvider, consumerProvider: ConsumerProvider, messageProvider: MessageProvider, eventRouter: EventRouter, rpcRouter: RpcRouter, coreRpcServer: CoreRpcServer, ackWaitMap?: Map<StreamKind, number>, metadataProvider?: MetadataProvider | undefined);
+    private readonly logger;
+    private readonly migration;
+    private readonly otel;
+    private readonly otelServiceName;
+    private readonly otelEndpoint;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
     /**
-     * Start the transport: register handlers, create infrastructure, begin consumption.
+     * Ensure all required streams exist with correct configuration.
      *
-     * Called by NestJS when `connectMicroservice()` is used, or internally by the module.
+     * @param kinds Which stream kinds to create. Determined by the module based
+     *              on RPC mode and registered handler patterns.
+     * If the dlq option is enabled, also ensures the DLQ stream exists.
      */
-    listen(callback: () => void): Promise<void>;
-    /** Stop all consumers, routers, subscriptions, and metadata heartbeat. Called during shutdown. */
-    close(): void;
+    ensureStreams(kinds: StreamKind[]): Promise<void>;
+    /** Get the stream name for a given kind. */
+    getStreamName(kind: StreamKind): string;
+    /** Get the subjects pattern for a given kind. */
+    getSubjects(kind: StreamKind): string[];
+    /** Ensure a single stream exists, creating or updating as needed. */
+    private ensureStream;
+    /** Ensure a dead-letter queue stream exists, creating or updating as needed. */
+    private ensureDlqStream;
+    private handleExistingStream;
+    private buildMutableOnlyConfig;
+    private logChanges;
+    /** Build the full stream config by merging defaults with user overrides. */
+    private buildConfig;
     /**
-     * Register event listener (required by Server base class).
+     * Build the stream configuration for the Dead-Letter Queue (DLQ).
      *
-     * Stores callbacks for client use. Primary lifecycle events
-     * are routed through EventBus.
+     * Merges the library default DLQ config with user-provided overrides.
+     * Ensures transport-controlled settings like retention are safely decoupled.
      */
-    on(event: string, callback: Function): void;
+    private buildDlqConfig;
+    /** Get default config for a stream kind. */
+    private getDefaults;
+    /** Check if scheduling is enabled for a stream kind via `allow_msg_schedules` override. */
+    private isSchedulingEnabled;
+    /** Get user-provided overrides for a stream kind, stripping transport-controlled properties. */
+    private getOverrides;
     /**
-     * Unwrap the underlying NATS connection.
-     *
-     * @throws Error if the transport has not started.
+     * Remove transport-controlled properties from user overrides.
+     * `retention` is managed by the transport (Workqueue/Limits per stream kind)
+     * and silently stripped to protect users from misconfiguration.
      */
-    unwrap<T>(): T;
-    /** Access the pattern registry (for module-level introspection). */
-    getPatternRegistry(): PatternRegistry;
-    /** Determine which streams and durable consumers are needed. */
-    private resolveRequiredKinds;
-    /** Populate the shared ack_wait map from actual NATS consumer configs. */
-    private populateAckWaitMap;
-    /** Build max_deliver map from actual NATS consumer configs (not options). */
-    private buildMaxDeliverMap;
+    private stripTransportControlled;
 }
 
-/** Minimal interface for anything that can be stopped during shutdown. */
-interface Stoppable {
-    close(): void;
-}
-/**
- * Orchestrates graceful transport shutdown.
- *
- * Shutdown sequence:
- * 1. Emit onShutdownStart hook
- * 2. Stop accepting new messages (close subscriptions, stop consumers)
- * 3. Drain and close NATS connection (with timeout safety net)
- * 4. Emit onShutdownComplete hook
- *
- * Idempotent — concurrent or repeated calls return the same promise.
- * This is critical because NestJS may call `onApplicationShutdown` on
- * multiple module instances (forRoot + forFeature) that share this
- * singleton, and the call order is not guaranteed.
- */
-declare class ShutdownManager {
-    private readonly connection;
+declare class EventRouter {
+    private readonly messageProvider;
+    private readonly patternRegistry;
+    private readonly codec;
     private readonly eventBus;
-    private readonly timeout;
+    private readonly deadLetterConfig?;
+    private readonly processingConfig?;
+    private readonly ackWaitMap?;
+    private readonly connection?;
+    private readonly options?;
     private readonly logger;
-    private shutdownPromise?;
-    constructor(connection: ConnectionProvider, eventBus: EventBus, timeout: number);
+    private readonly subscriptions;
+    private readonly otel;
+    private readonly serviceName;
+    private readonly serverEndpoint;
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined, processingConfig?: EventProcessingConfig | undefined, ackWaitMap?: Map<StreamKind, number> | undefined, connection?: ConnectionProvider | undefined, options?: JetstreamModuleOptions | undefined);
     /**
-     * Execute the full shutdown sequence.
+     * Update the max_deliver thresholds from actual NATS consumer configs.
+     * Called after consumers are ensured so the DLQ map reflects reality.
+     */
+    updateMaxDeliverMap(consumerMaxDelivers: Map<string, number>): void;
+    /** Start routing event, broadcast, and ordered messages to handlers. */
+    start(): void;
+    /** Stop routing and unsubscribe from all streams. */
+    destroy(): void;
+    /** Subscribe to a message stream and route each message to its handler. */
+    private subscribeToStream;
+    private getConcurrency;
+    private getAckExtensionConfig;
+    /**
+     * Last-resort path for a dead letter: invoke `onDeadLetter`, then `term` on
+     * success or `nak` on hook failure so NATS retries on the next delivery
+     * cycle. Used when DLQ stream isn't configured, or when publishing to it
+     * failed and we still have to surface the message somewhere observable.
+     */
+    private fallbackToOnDeadLetterCallback;
+    /**
+     * Publish a dead letter to the configured Dead-Letter Queue (DLQ) stream.
      *
-     * Idempotent — concurrent or repeated calls return the same promise.
+     * Appends diagnostic metadata headers to the original message and preserves
+     * the primary payload. If publishing succeeds, it notifies the standard
+     * `onDeadLetter` callback and terminates the message. If it fails, it falls
+     * back to the callback entirely to prevent silent data loss.
+     */
+    private publishToDlq;
+    /**
+     * Orchestrates the handling of a message that has exhausted delivery limits.
      *
-     * @param strategy Optional stoppable to close (stops consumers and subscriptions).
+     * Emits a system event and delegates either to the robust DLQ stream publisher
+     * or directly to the fallback callback based on the active module configuration.
      */
-    shutdown(strategy?: Stoppable): Promise<void>;
-    private doShutdown;
+    private handleDeadLetter;
 }
 
 /**
- * Root module for the NestJS JetStream transport.
- *
- * - `forRoot()` / `forRootAsync()` — registers once in AppModule.
- *   Creates shared NATS connection, codec, event bus, and optionally
- *   the consumer infrastructure.
+ * Routes RPC command messages in JetStream mode.
  *
- * - `forFeature()` — registers in feature modules.
- *   Creates a lightweight client proxy targeting a specific service.
+ * Delivery semantics:
+ * - Handler must complete within timeout (default: 3 min)
+ * - Success -> ack -> publish response to ReplyTo (publish failure does not affect ack)
+ * - Handler error -> publish error to ReplyTo -> term (no redelivery)
+ * - Timeout -> no response -> term
+ * - No handler / decode error -> term immediately
  *
- * @example
- * ```typescript
- * // AppModule — global setup
- * @Module({
- *   imports: [
- *     JetstreamModule.forRoot({
- *       name: 'orders',
- *       servers: ['nats://localhost:4222'],
- *     }),
- *   ],
- * })
- * export class AppModule {}
+ * Nak is never used for RPC — prevents duplicate side effects.
+ */
+declare class RpcRouter {
+    private readonly messageProvider;
+    private readonly patternRegistry;
+    private readonly connection;
+    private readonly codec;
+    private readonly eventBus;
+    private readonly rpcOptions?;
+    private readonly ackWaitMap?;
+    private readonly logger;
+    private readonly timeout;
+    private readonly concurrency;
+    private resolvedAckExtensionInterval;
+    private subscription;
+    private cachedNc;
+    private readonly otel;
+    private readonly serviceName;
+    private readonly serverEndpoint;
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, rpcOptions?: RpcRouterOptions | undefined, ackWaitMap?: Map<StreamKind, number> | undefined, options?: JetstreamModuleOptions);
+    /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
+    private get ackExtensionInterval();
+    /** Start routing command messages to handlers. */
+    start(): Promise<void>;
+    /** Stop routing and unsubscribe. */
+    destroy(): void;
+}
+
+/**
+ * Manages JetStream consumer lifecycle: creation and idempotent ensures.
  *
- * // Feature module — per-service clients
- * @Module({
- *   imports: [
- *     JetstreamModule.forFeature({ name: 'users' }),
- *     JetstreamModule.forFeature({ name: 'payments' }),
- *   ],
- * })
- * export class OrdersModule {}
- * ```
+ * Creates durable pull-based consumers that survive restarts.
+ * Consumer configuration is merged from defaults and user overrides.
  */
-declare class JetstreamModule implements OnApplicationShutdown {
-    private readonly shutdownManager?;
-    private readonly strategy?;
-    constructor(shutdownManager?: ShutdownManager | undefined, strategy?: (JetstreamStrategy | null) | undefined);
+declare class ConsumerProvider {
+    private readonly options;
+    private readonly connection;
+    private readonly streamProvider;
+    private readonly patternRegistry;
+    private readonly logger;
+    private readonly otel;
+    private readonly otelServiceName;
+    private readonly otelEndpoint;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, streamProvider: StreamProvider, patternRegistry: PatternRegistry);
     /**
-     * Register the JetStream transport globally.
-     *
-     * Creates a shared NATS connection, codec, event bus, and optionally
-     * the full consumer infrastructure (streams, consumers, routers).
+     * Ensure consumers exist for the specified kinds.
      *
-     * @param options Module configuration.
-     * @returns Dynamic module ready to be imported.
+     * @returns Map of kind -> ConsumerInfo for downstream use.
      */
-    static forRoot(options: JetstreamModuleOptions): DynamicModule;
+    ensureConsumers(kinds: StreamKind[]): Promise<Map<StreamKind, ConsumerInfo>>;
+    /** Get the consumer name for a given kind. */
+    getConsumerName(kind: StreamKind): string;
     /**
-     * Register the JetStream transport globally with async configuration.
-     *
-     * Supports `useFactory`, `useExisting`, and `useClass` patterns
-     * for loading configuration from ConfigService, environment, etc.
-     *
-     * @param asyncOptions Async configuration.
-     * @returns Dynamic module ready to be imported.
+     * Ensure a single consumer exists with the desired config.
+     * Used at **startup** — creates or updates the consumer to match
+     * the current pod's configuration.
      */
-    static forRootAsync(asyncOptions: JetstreamModuleAsyncOptions): DynamicModule;
+    ensureConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
     /**
-     * Register a lightweight client proxy for a target service.
+     * Recover a consumer that disappeared during runtime.
+     * Used by **self-healing** — creates if missing, but NEVER updates config.
      *
-     * Reuses the shared NATS connection from `forRoot()`.
-     * Import in each feature module that needs to communicate with a specific service.
+     * If a migration backup stream exists, another pod is mid-migration — we
+     * throw so the self-healing retry loop waits with backoff until migration
+     * completes and the backup is cleaned up.
      *
-     * @param options Feature options with target service name.
-     * @returns Dynamic module with the client provider.
+     * This prevents old pods from:
+     * - Overwriting a newer pod's consumer config during rolling updates
+     * - Creating consumers during migration (which would consume and delete
+     *   workqueue messages while they're being restored)
      */
-    static forFeature(options: JetstreamFeatureOptions): DynamicModule;
-    private static createCoreProviders;
-    /** Create providers that depend on JETSTREAM_OPTIONS (shared by sync and async). */
-    private static createCoreDependentProviders;
-    /** Create async options provider from useFactory/useExisting/useClass. */
-    private static createAsyncOptionsProvider;
+    recoverConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
     /**
-     * Gracefully shut down the transport on application termination.
+     * Throw if a migration backup stream exists for this stream.
+     * The self-healing retry loop catches the error and retries with backoff,
+     * naturally waiting until the migrating pod finishes and cleans up the backup.
      */
-    onApplicationShutdown(): Promise<void>;
+    private assertNoMigrationInProgress;
+    /**
+     * Create a consumer, handling the race where another pod creates it first.
+     */
+    private createConsumer;
+    /** Build consumer config by merging defaults with user overrides. */
+    private buildConfig;
+    /** Get default config for a consumer kind. */
+    private getDefaults;
+    /** Get user-provided overrides for a consumer kind. */
+    private getOverrides;
 }
 
+/** Callback to recreate a consumer when it disappears. */
+type ConsumerRecoveryFn = (kind: StreamKind) => Promise<ConsumerInfo>;
 /**
- * NestJS ClientProxy implementation for the JetStream transport.
- *
- * Supports two operational modes:
- * - **Core mode** (default): Uses `nc.request()` for RPC, `nc.publish()` for events.
- * - **JetStream mode**: Uses `js.publish()` for RPC commands + inbox for responses.
+ * Manages pull-based message consumption from JetStream consumers.
  *
- * Events always go through JetStream publish for guaranteed delivery.
- * The mode only affects RPC (request/reply) behavior.
+ * Uses `defer()` + `repeat()` pattern for self-healing: when the async
+ * iterator completes (e.g., NATS restart), the consumer automatically
+ * re-establishes after a short delay.
  *
- * Clients are lightweight — they share the NATS connection from `forRoot()`.
+ * Emits messages to kind-specific RxJS subjects for downstream routing.
  */
-declare class JetstreamClient extends ClientProxy {
-    private readonly rootOptions;
+declare class MessageProvider {
     private readonly connection;
-    private readonly codec;
     private readonly eventBus;
+    private readonly consumeOptionsMap;
+    private readonly consumerRecoveryFn?;
     private readonly logger;
-    /** Target service name this client sends messages to. */
-    private readonly targetName;
-    /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
-    private readonly callerName;
-    /**
-     * Subject prefixes of the form `{serviceName}__microservice.{kind}.` — one
-     * per stream kind this client may publish to. Built once in the constructor
-     * so producing a full subject is a single string concat with the user pattern.
-     */
-    private readonly eventSubjectPrefix;
-    private readonly commandSubjectPrefix;
-    private readonly orderedSubjectPrefix;
-    /**
-     * RPC configuration snapshots. The values are derived from rootOptions at
-     * construction time so the publish hot path never has to re-run
-     * isCoreRpcMode / getRpcTimeout on every call.
-     */
-    private readonly isCoreMode;
-    private readonly defaultRpcTimeout;
-    /** Shared inbox for JetStream-mode RPC responses. */
-    private inbox;
-    private inboxSubscription;
-    /** Pending JetStream-mode RPC callbacks, keyed by correlation ID. */
-    private readonly pendingMessages;
-    /** Pending JetStream-mode RPC timeouts, keyed by correlation ID. */
-    private readonly pendingTimeouts;
-    /** Subscription to connection status events for disconnect handling. */
-    private statusSubscription;
+    private readonly activeIterators;
+    private orderedReadyResolve;
+    private orderedReadyReject;
+    private destroy$;
+    private eventMessages$;
+    private commandMessages$;
+    private broadcastMessages$;
+    private orderedMessages$;
+    constructor(connection: ConnectionProvider, eventBus: EventBus, consumeOptionsMap?: Map<StreamKind, Partial<ConsumeOptions>>, consumerRecoveryFn?: ConsumerRecoveryFn | undefined);
+    /** Observable stream of workqueue event messages. */
+    get events$(): Observable<JsMsg>;
+    /** Observable stream of RPC command messages (jetstream mode). */
+    get commands$(): Observable<JsMsg>;
+    /** Observable stream of broadcast event messages. */
+    get broadcasts$(): Observable<JsMsg>;
+    /** Observable stream of ordered event messages (strict sequential delivery). */
+    get ordered$(): Observable<JsMsg>;
     /**
-     * Cached readiness flag. Once `connect()` has wired the inbox and status
-     * subscription, subsequent publishes skip the `await connect()` microtask
-     * and reach for the underlying connection synchronously instead.
+     * Start consuming messages from the given consumer infos.
+     *
+     * Each consumer gets an independent self-healing flow.
+     * Call `destroy()` to stop all consumers.
      */
-    private readyForPublish;
-    constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
+    start(consumers: Map<StreamKind, ConsumerInfo>): void;
     /**
-     * Establish connection. Called automatically by NestJS on first use.
+     * Start an ordered consumer for strict sequential delivery.
      *
-     * Sets up the JetStream RPC inbox (if in JetStream mode) and subscribes
-     * to connection status events for fail-fast disconnect handling.
+     * Unlike durable consumers, ordered consumers are ephemeral — created at
+     * consumption time, no durable state. nats.js handles auto-recreation.
      *
-     * @returns The underlying NATS connection.
+     * @param streamName - JetStream stream to consume from.
+     * @param filterSubjects - NATS subjects to filter on.
+     * @param orderedConfig - Optional overrides for ordered consumer options.
      */
-    connect(): Promise<NatsConnection>;
-    /** Clean up resources: reject pending RPCs, unsubscribe from status events. */
-    close(): Promise<void>;
+    startOrdered(streamName: string, filterSubjects: string[], orderedConfig?: OrderedEventOverrides): Promise<void>;
+    /** Stop all consumer flows and reinitialize subjects for potential restart. */
+    destroy(): void;
+    /** Create a self-healing consumer flow for a specific kind. */
+    private createFlow;
+    /** Single iteration: get consumer -> pull messages -> emit to subject. */
+    private consumeOnce;
     /**
-     * Direct access to the raw NATS connection.
+     * Detect "consumer not found" errors from `js.consumers.get()`.
      *
-     * @throws Error if not connected.
+     * Unlike JetStream Manager calls (which throw `JetStreamApiError`),
+     * the JetStream client's `consumers.get()` throws a plain `Error`
+     * with the error code embedded in the message text.
      */
-    unwrap<T = NatsConnection>(): T;
+    private isConsumerNotFound;
+    /** Get the target subject for a consumer kind. */
+    private getTargetSubject;
+    /** Monitor heartbeats and restart the consumer iterator on prolonged silence. */
+    private monitorConsumerHealth;
+    /** Create a self-healing ordered consumer flow. */
+    private createOrderedFlow;
+    /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
+    private createSelfHealingFlow;
+    /** Single iteration: create ordered consumer -> push messages into the subject. */
+    private consumeOrderedOnce;
+}
+
+/**
+ * Publishes handler metadata to a NATS KV bucket for external service discovery.
+ *
+ * Uses TTL + heartbeat to manage entry lifecycle:
+ * - Entries are written on startup and refreshed every `ttl / 2`
+ * - When the pod stops (graceful or crash), heartbeat stops → entries expire via TTL
+ * - No explicit delete needed — NATS handles expiry automatically
+ *
+ * This provider is fully decoupled from stream/consumer infrastructure —
+ * it only depends on the NATS connection and module options.
+ */
+declare class MetadataProvider {
+    private readonly connection;
+    private readonly logger;
+    private readonly bucketName;
+    private readonly replicas;
+    private readonly ttl;
+    private currentEntries?;
+    private heartbeatTimer?;
+    private cachedKv?;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
     /**
-     * Publish a fire-and-forget event to JetStream.
+     * Write handler metadata entries to the KV bucket and start heartbeat.
      *
-     * Events are published to either the workqueue stream or broadcast stream
-     * depending on the subject prefix. When a schedule is present the message
-     * is published to a `_sch` subject within the same stream, with the target
-     * set to the original event subject.
-     */
-    protected dispatchEvent<T = unknown>(packet: ReadPacket): Promise<T>;
-    /**
-     * Publish an RPC command and register callback for response.
+     * Creates the bucket if it doesn't exist (idempotent).
+     * Skips silently when entries map is empty.
+     * Starts a heartbeat interval that refreshes entries every `ttl / 2`
+     * to prevent TTL expiry while the pod is alive.
      *
-     * Core mode: uses nc.request() with timeout.
-     * JetStream mode: publishes to stream + waits for inbox response.
-     */
-    protected publish(packet: ReadPacket, callback: (p: WritePacket) => void): () => void;
-    /** Core mode: nc.request() with timeout. */
-    private publishCoreRpc;
-    /** JetStream mode: publish to stream + wait for inbox response. */
-    private publishJetStreamRpc;
-    /** Fail-fast all pending JetStream RPC callbacks on connection loss. */
-    private handleDisconnect;
-    /** Reject all pending RPC callbacks, clear timeouts, and tear down inbox. */
-    private rejectPendingRpcs;
-    /** Setup shared inbox subscription for JetStream RPC responses. */
-    private setupInbox;
-    /** Route an inbox reply to the matching pending callback. */
-    private routeInboxReply;
-    /**
-     * Resolve a user pattern to a fully-qualified NATS subject, dispatching
-     * between the event, broadcast, and ordered prefixes.
+     * Non-critical — errors are logged but do not prevent transport startup.
      *
-     * The leading-char check short-circuits the `startsWith` comparisons for
-     * patterns that cannot possibly carry a broadcast/ordered marker, which is
-     * the overwhelmingly common case.
+     * @param entries Map of KV key → metadata object.
      */
-    private buildEventSubject;
-    /** Build NATS headers merging custom headers with transport headers. */
-    private buildHeaders;
-    /** Extract data, headers, timeout, and schedule from raw packet data or JetstreamRecord. */
-    private extractRecordData;
+    publish(entries: Map<string, Record<string, unknown>>): Promise<void>;
     /**
-     * Build a schedule-holder subject for NATS message scheduling.
-     *
-     * The schedule-holder subject resides in the same stream as the target but
-     * uses a separate `_sch` namespace that is NOT matched by any consumer filter.
-     * NATS holds the message and publishes it to the target subject after the delay.
+     * Stop the heartbeat timer.
      *
-     * Examples:
-     * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder`
-     * - `broadcast.config.updated` → `broadcast._sch.config.updated`
+     * After this call, entries will expire via TTL once the heartbeat window passes.
+     * Called during transport shutdown (strategy.close()).
      */
-    private buildScheduleSubject;
+    destroy(): void;
+    /** Write entries to KV with per-entry error handling. */
+    private writeEntries;
+    /** Start heartbeat interval that refreshes entries every ttl/2. */
+    private startHeartbeat;
+    /** Refresh all current entries in KV (heartbeat tick). */
+    private refreshEntries;
+    /** Create or open the KV bucket (cached after first call). */
+    private openBucket;
 }
 
-/**
- * Immutable message record for JetStream transport.
- *
- * Compatible with NestJS record builder pattern (like RmqRecord, NatsRecord).
- * Pass as the second argument to `client.send()` or `client.emit()`.
- *
- * @example
- * ```typescript
- * const record = new JetstreamRecordBuilder({ id: 1 })
- *   .setHeader('x-tenant', 'acme')
- *   .setTimeout(5000)
- *   .build();
+/**
+ * NATS JetStream API error codes used by the transport.
  *
- * client.send('get.user', record);
- * ```
+ * Ref: https://github.com/nats-io/nats-server (server error definitions)
+ * Verified on NATS 2.12.6 via integration tests (2026-04-02).
  */
-declare class JetstreamRecord<TData = unknown> {
-    /** Message payload. */
-    readonly data: TData;
-    /** Custom headers set via {@link JetstreamRecordBuilder.setHeader}. */
-    readonly headers: ReadonlyMap<string, string>;
-    /** Per-request RPC timeout override in ms. */
-    readonly timeout?: number | undefined;
-    /** Custom message ID for JetStream deduplication. */
-    readonly messageId?: string | undefined;
-    /** Schedule options for delayed delivery. */
-    readonly schedule?: ScheduleRecordOptions | undefined;
-    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
-    readonly ttl?: string | undefined;
-    constructor(
-    /** Message payload. */
-    data: TData, 
-    /** Custom headers set via {@link JetstreamRecordBuilder.setHeader}. */
-    headers: ReadonlyMap<string, string>, 
-    /** Per-request RPC timeout override in ms. */
-    timeout?: number | undefined, 
-    /** Custom message ID for JetStream deduplication. */
-    messageId?: string | undefined, 
-    /** Schedule options for delayed delivery. */
-    schedule?: ScheduleRecordOptions | undefined, 
-    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
-    ttl?: string | undefined);
+declare enum NatsErrorCode {
+    /** Consumer does not exist on the specified stream. */
+    ConsumerNotFound = 10014,
+    /** Consumer name already in use with different configuration (race condition on create). */
+    ConsumerAlreadyExists = 10148,
+    /** Stream does not exist. */
+    StreamNotFound = 10059
 }
+
 /**
- * Fluent builder for constructing JetstreamRecord instances.
+ * NestJS custom transport strategy for NATS JetStream.
  *
- * Protected headers (`correlation-id`, `reply-to`, `error`) cannot be
- * set by the user — attempting to do so throws an error at build time.
+ * Coordinates all server-side providers:
+ * 1. Registers handlers from NestJS into PatternRegistry
+ * 2. Creates required streams and consumers
+ * 3. Starts message consumption and routing
+ * 4. Handles Core or JetStream RPC based on configuration
+ *
+ * All dependencies are injected via the NestJS DI container.
  */
-declare class JetstreamRecordBuilder<TData = unknown> {
-    private data;
-    private readonly headers;
-    private timeout;
-    private messageId;
-    private scheduleOptions;
-    private ttlDuration;
-    constructor(data?: TData);
+declare class JetstreamStrategy extends Server implements CustomTransportStrategy {
+    private readonly options;
+    private readonly connection;
+    private readonly patternRegistry;
+    private readonly streamProvider;
+    private readonly consumerProvider;
+    private readonly messageProvider;
+    private readonly eventRouter;
+    private readonly rpcRouter;
+    private readonly coreRpcServer;
+    private readonly ackWaitMap;
+    private readonly metadataProvider?;
+    readonly transportId: symbol;
+    private readonly listeners;
+    private started;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, streamProvider: StreamProvider, consumerProvider: ConsumerProvider, messageProvider: MessageProvider, eventRouter: EventRouter, rpcRouter: RpcRouter, coreRpcServer: CoreRpcServer, ackWaitMap?: Map<StreamKind, number>, metadataProvider?: MetadataProvider | undefined);
     /**
-     * Set the message payload.
+     * Start the transport: register handlers, create infrastructure, begin consumption.
      *
-     * @param data - Payload to serialize via the configured {@link Codec}.
+     * Called by NestJS when `connectMicroservice()` is used, or internally by the module.
      */
-    setData(data: TData): this;
+    listen(callback: () => void): Promise<void>;
+    /** Stop all consumers, routers, subscriptions, and metadata heartbeat. Called during shutdown. */
+    close(): void;
     /**
-     * Set a single custom header.
+     * Override NestJS `Server.addHandler` to fail-fast on duplicate pattern registration.
      *
-     * @param key - Header name (e.g. `'x-tenant'`).
-     * @param value - Header value.
-     * @throws Error if the header name is reserved by the transport.
+     * The base class silently overwrites duplicate RPC handlers (last wins) and appends
+     * duplicate event handlers to a linked list. Both behaviors are hazardous in a
+     * JetStream context: silent overwrite drops a handler the user wrote, and double
+     * event dispatch double-acks/double-processes the same JetStream message.
+     *
+     * We treat any pattern collision as a fatal misconfiguration so it surfaces at
+     * bootstrap instead of in production traffic.
      */
-    setHeader(key: string, value: string): this;
+    addHandler(pattern: unknown, callback: MessageHandler, isEventHandler?: boolean, extras?: Record<string, unknown>): void;
     /**
-     * Set multiple custom headers at once.
+     * Register event listener (required by Server base class).
      *
-     * @param headers - Key-value pairs to set as headers.
-     * @throws Error if any header name is reserved by the transport.
+     * Stores callbacks for client use. Primary lifecycle events
+     * are routed through EventBus.
      */
-    setHeaders(headers: Record<string, string>): this;
+    on(event: string, callback: Function): void;
     /**
-     * Set a custom message ID for JetStream deduplication.
-     *
-     * NATS JetStream uses this ID to detect duplicate publishes within the
-     * stream's `duplicate_window`. If two messages with the same ID arrive
-     * within the window, the second is silently dropped.
-     *
-     * When not set, a random UUID is generated automatically.
-     *
-     * @param id - Unique message identifier (e.g. order ID, idempotency key).
+     * Unwrap the underlying NATS connection.
      *
-     * @example
-     * ```typescript
-     * new JetstreamRecordBuilder(data)
-     *   .setMessageId(`order-${order.id}`)
-     *   .build();
-     * ```
+     * @throws Error if the transport has not started.
      */
-    setMessageId(id: string): this;
+    unwrap<T>(): T;
+    /** Access the pattern registry (for module-level introspection). */
+    getPatternRegistry(): PatternRegistry;
+    /** Determine which streams and durable consumers are needed. */
+    private resolveRequiredKinds;
+    /** Populate the shared ack_wait map from actual NATS consumer configs. */
+    private populateAckWaitMap;
+    /** Build max_deliver map from actual NATS consumer configs (not options). */
+    private buildMaxDeliverMap;
+}
+
+/** Minimal interface for anything that can be stopped during shutdown. */
+interface Stoppable {
+    close(): void;
+}
+/**
+ * Orchestrates graceful transport shutdown.
+ *
+ * Shutdown sequence:
+ * 1. Emit onShutdownStart hook
+ * 2. Stop accepting new messages (close subscriptions, stop consumers)
+ * 3. Drain and close NATS connection (with timeout safety net)
+ * 4. Emit onShutdownComplete hook
+ *
+ * Idempotent — concurrent or repeated calls return the same promise.
+ * This is critical because NestJS may call `onApplicationShutdown` on
+ * multiple module instances (forRoot + forFeature) that share this
+ * singleton, and the call order is not guaranteed.
+ */
+declare class ShutdownManager {
+    private readonly connection;
+    private readonly eventBus;
+    private readonly timeout;
+    private readonly logger;
+    private shutdownPromise?;
+    constructor(connection: ConnectionProvider, eventBus: EventBus, timeout: number);
     /**
-     * Set per-request RPC timeout.
+     * Execute the full shutdown sequence.
      *
-     * @param ms - Timeout in milliseconds. Overrides the global RPC timeout for this request only.
+     * Idempotent — concurrent or repeated calls return the same promise.
+     *
+     * @param strategy Optional stoppable to close (stops consumers and subscriptions).
      */
-    setTimeout(ms: number): this;
+    shutdown(strategy?: Stoppable): Promise<void>;
+    private doShutdown;
+}
+
+/**
+ * Root module for the NestJS JetStream transport.
+ *
+ * - `forRoot()` / `forRootAsync()` — registers once in AppModule.
+ *   Creates shared NATS connection, codec, event bus, and optionally
+ *   the consumer infrastructure.
+ *
+ * - `forFeature()` — registers in feature modules.
+ *   Creates a lightweight client proxy targeting a specific service.
+ *
+ * @example
+ * ```typescript
+ * // AppModule — global setup
+ * @Module({
+ *   imports: [
+ *     JetstreamModule.forRoot({
+ *       name: 'orders',
+ *       servers: ['nats://localhost:4222'],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Feature module — per-service clients
+ * @Module({
+ *   imports: [
+ *     JetstreamModule.forFeature({ name: 'users' }),
+ *     JetstreamModule.forFeature({ name: 'payments' }),
+ *   ],
+ * })
+ * export class OrdersModule {}
+ * ```
+ */
+declare class JetstreamModule implements OnApplicationShutdown {
+    private readonly shutdownManager?;
+    private readonly strategy?;
+    constructor(shutdownManager?: ShutdownManager | undefined, strategy?: (JetstreamStrategy | null) | undefined);
     /**
-     * Schedule one-shot delayed delivery.
-     *
-     * The message is held by NATS and delivered to the event consumer
-     * at the specified time. Requires NATS >= 2.12 and `allow_msg_schedules: true`
-     * on the event stream (via `events: { stream: { allow_msg_schedules: true } }`).
+     * Register the JetStream transport globally.
      *
-     * Only meaningful for events (`client.emit()`). If used with RPC
-     * (`client.send()`), a warning is logged and the schedule is ignored.
+     * Creates a shared NATS connection, codec, event bus, and optionally
+     * the full consumer infrastructure (streams, consumers, routers).
      *
-     * @param date - Delivery time. Must be in the future.
-     * @throws Error if the date is not in the future.
+     * @param options Module configuration.
+     * @returns Dynamic module ready to be imported.
      */
-    scheduleAt(date: Date): this;
+    static forRoot(options: JetstreamModuleOptions): DynamicModule;
     /**
-     * Set per-message TTL (time-to-live).
-     *
-     * The message expires individually after the specified duration,
-     * independent of the stream's `max_age`. Requires NATS >= 2.11 and
-     * `allow_msg_ttl: true` on the stream.
+     * Register the JetStream transport globally with async configuration.
      *
-     * Only meaningful for events (`client.emit()`). If used with RPC
-     * (`client.send()`), a warning is logged and the TTL is ignored.
+     * Supports `useFactory`, `useExisting`, and `useClass` patterns
+     * for loading configuration from ConfigService, environment, etc.
      *
-     * @param nanos - TTL in nanoseconds. Use {@link toNanos} for human-readable values.
+     * @param asyncOptions Async configuration.
+     * @returns Dynamic module ready to be imported.
+     */
+    static forRootAsync(asyncOptions: JetstreamModuleAsyncOptions): DynamicModule;
+    /**
+     * Register a lightweight client proxy for a target service.
      *
-     * @example
-     * ```typescript
-     * import { toNanos } from '@horizon-republic/nestjs-jetstream';
+     * Reuses the shared NATS connection from `forRoot()`.
+     * Import in each feature module that needs to communicate with a specific service.
      *
-     * new JetstreamRecordBuilder(payload).ttl(toNanos(30, 'minutes')).build();
-     * new JetstreamRecordBuilder(payload).ttl(toNanos(24, 'hours')).build();
-     * ```
+     * @param options Feature options with target service name.
+     * @returns Dynamic module with the client provider.
      */
-    ttl(nanos: number): this;
+    static forFeature(options: JetstreamFeatureOptions): DynamicModule;
+    private static createCoreProviders;
+    /** Create providers that depend on JETSTREAM_OPTIONS (shared by sync and async). */
+    private static createCoreDependentProviders;
+    /** Create async options provider from useFactory/useExisting/useClass. */
+    private static createAsyncOptionsProvider;
     /**
-     * Build the immutable {@link JetstreamRecord}.
-     *
-     * @returns A frozen record ready to pass to `client.send()` or `client.emit()`.
+     * Gracefully shut down the transport on application termination.
      */
-    build(): JetstreamRecord<TData>;
-    /** Validate that a header key is not reserved. */
-    private validateHeaderKey;
+    onApplicationShutdown(): Promise<void>;
 }
 
 /**
@@ -1873,4 +2353,4 @@ declare const isJetStreamRpcMode: (rpc: RpcConfig | undefined) => boolean;
 /** Check if the RPC config specifies Core mode (default). */
 declare const isCoreRpcMode: (rpc: RpcConfig | undefined) => boolean;
 
-export { type Codec, DEFAULT_BROADCAST_CONSUMER_CONFIG, DEFAULT_BROADCAST_STREAM_CONFIG, DEFAULT_COMMAND_CONSUMER_CONFIG, DEFAULT_COMMAND_STREAM_CONFIG, DEFAULT_DLQ_STREAM_CONFIG, DEFAULT_EVENT_CONSUMER_CONFIG, DEFAULT_EVENT_STREAM_CONFIG, DEFAULT_JETSTREAM_RPC_TIMEOUT, DEFAULT_METADATA_BUCKET, DEFAULT_METADATA_HISTORY, DEFAULT_METADATA_REPLICAS, DEFAULT_METADATA_TTL, DEFAULT_ORDERED_STREAM_CONFIG, DEFAULT_RPC_TIMEOUT, DEFAULT_SHUTDOWN_TIMEOUT, type DeadLetterInfo, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_OPTIONS, JetstreamClient, JetstreamDlqHeader, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, MsgpackCodec, NatsErrorCode, type OrderedEventOverrides, PatternPrefix, RESERVED_HEADERS, type RpcConfig, RpcContext, type ScheduleRecordOptions, type StreamConfigOverrides, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildBroadcastSubject, buildSubject, consumerName, dlqStreamName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, metadataKey, streamName, toNanos };
+export { type CaptureBodyOptions, type Codec, ConsumeKind, type ConsumeSourceMsg, DEFAULT_BROADCAST_CONSUMER_CONFIG, DEFAULT_BROADCAST_STREAM_CONFIG, DEFAULT_COMMAND_CONSUMER_CONFIG, DEFAULT_COMMAND_STREAM_CONFIG, DEFAULT_DLQ_STREAM_CONFIG, DEFAULT_EVENT_CONSUMER_CONFIG, DEFAULT_EVENT_STREAM_CONFIG, DEFAULT_JETSTREAM_RPC_TIMEOUT, DEFAULT_METADATA_BUCKET, DEFAULT_METADATA_HISTORY, DEFAULT_METADATA_REPLICAS, DEFAULT_METADATA_TTL, DEFAULT_ORDERED_STREAM_CONFIG, DEFAULT_RPC_TIMEOUT, DEFAULT_SHUTDOWN_TIMEOUT, DEFAULT_TRACES, type DeadLetterInfo, type ErrorClassification, type HandlerMetadata, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_OPTIONS, JetstreamClient, type JetstreamConsumeContext, JetstreamDlqHeader, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, type JetstreamPublishContext, JetstreamRecord, JetstreamRecordBuilder, type JetstreamResponseContext, JetstreamStrategy, JetstreamTrace, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, MsgpackCodec, NatsErrorCode, type OrderedEventOverrides, type OtelOptions, PatternPrefix, PublishKind, RESERVED_HEADERS, type RpcConfig, RpcContext, type ScheduleRecordOptions, type ServerEndpoint, type StreamConfigOverrides, type StreamConsumerOverrides, StreamKind, TRACER_NAME, TransportEvent, type TransportHooks, buildBroadcastSubject, buildSubject, consumerName, dlqStreamName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, metadataKey, streamName, toNanos };