@horizon-republic/nestjs-jetstream 2.12.1 → 2.13.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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 { JetStreamManager, JetStreamClient, StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, StreamInfo, 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';
@@ -11,7 +11,7 @@ import { Observable } from 'rxjs';
  *
  * Implementations handle serialization between application objects and
  * binary data transmitted over NATS. The transport uses a single global
- * codec — all messages (RPC and events) share the same format.
+ * codec: all messages (RPC and events) share the same format.
  *
  * @example
  * ```typescript
@@ -37,10 +37,10 @@ interface Codec {
 /**
  * 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).
+ * - `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",
@@ -65,7 +65,7 @@ declare enum MessageKind {
 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
+ * operations either acknowledge cleanly or surface a transport error; there
  * is no retried/terminated dimension at the publish boundary.
  */
 type PublishStatus = 'success' | 'error';
@@ -152,7 +152,7 @@ interface TransportHooks {
      * 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
+     * @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).
@@ -161,7 +161,7 @@ interface TransportHooks {
      */
     [TransportEvent.Published](subject: string, kind: StreamKind, durationMs: number, status: PublishStatus): void;
     /**
-     * Fired after an RPC round-trip completes from the caller's perspective —
+     * 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.
@@ -175,7 +175,7 @@ interface TransportHooks {
 }
 /**
  * Internal subscriber for a transport event. Multiple subscribers may be
- * registered per event via `EventBus.subscribe()` — used by built-in
+ * 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;
@@ -241,7 +241,7 @@ interface MetricsConfig {
     /**
      * 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
+     * Set to `0` to disable polling; counter/histogram metrics still update
      * via the event bus.
      */
     pollInterval?: number;
@@ -256,7 +256,7 @@ type MetricsOption = boolean | MetricsConfig;
 
 /**
  * Instrumentation scope name reported on every span the library emits.
- * Matches the npm package name — the convention used by
+ * Matches the npm package name, the convention used by
  * `@opentelemetry/instrumentation-*` and most third-party instrumentations.
  */
 declare const TRACER_NAME = "@horizon-republic/nestjs-jetstream";
@@ -287,7 +287,7 @@ declare enum JetstreamTrace {
     Consume = "consume",
     /**
      * `CLIENT` span covering a full RPC round-trip on the caller side
-     * (`client.send()` → reply received). Wraps the inner publish.
+     * (`client.send()` -> reply received). Wraps the inner publish.
      * Default: ON.
      */
     RpcClientSend = "rpc.client.send",
@@ -325,8 +325,8 @@ declare const DEFAULT_TRACES: readonly JetstreamTrace[];
  * Central event bus for transport lifecycle notifications.
  *
  * Two emission paths:
- *  - User hooks registered via `forRoot({ hooks })` — at most one per event.
- *  - Internal subscribers added via `subscribe()` — many per event, used by
+ *  - 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.
  *
  * Both fire on every `emit()` call. Subscriber failures are isolated and
@@ -366,9 +366,9 @@ declare class EventBus {
  * 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
+ * - `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()`.
  */
@@ -391,7 +391,7 @@ declare class ConnectionProvider {
     private lifecycleSpan;
     constructor(options: JetstreamModuleOptions, eventBus: EventBus);
     /**
-     * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
+     * Establish NATS connection. Idempotent: returns cached connection on subsequent calls.
      *
      * @throws Error if connection is refused (fail fast).
      */
@@ -417,7 +417,7 @@ declare class ConnectionProvider {
     /**
      * Gracefully shut down the connection.
      *
-     * Sequence: drain → wait for close. Falls back to force-close on error.
+     * Sequence: drain -> wait for close. Falls back to force-close on error.
      */
     shutdown(): Promise<void>;
     private initJetStreamManager;
@@ -429,6 +429,31 @@ declare class ConnectionProvider {
     private monitorStatus;
 }
 
+/** Single source of truth for all stream, consumer, and subject names. */
+declare class NameResolver {
+    private readonly options;
+    private readonly kinds;
+    private readonly dlq;
+    constructor(options: JetstreamModuleOptions);
+    streamName(kind: StreamKind): string;
+    consumerName(kind: StreamKind): string;
+    dlqStreamName(): string;
+    subject(kind: StreamKind, pattern: string): string;
+    filterSubject(kind: StreamKind): string;
+    schedulePrefix(kind: StreamKind): string;
+    hasCustomPrefix(kind: StreamKind): boolean;
+    /**
+     * Map a resolved event subject back to its schedule-holder base subject
+     * (the `_sch` namespace twin, without the per-message unique suffix).
+     */
+    scheduleSubjectBase(eventSubject: string): string;
+    private get;
+    private buildKindMap;
+    private normalizePrefix;
+    private conventionPrefix;
+    private conventionSchedulePrefix;
+}
+
 /**
  * NestJS ClientProxy implementation for the JetStream transport.
  *
@@ -439,7 +464,7 @@ declare class ConnectionProvider {
  * 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()`.
+ * Clients are lightweight: they share the NATS connection from `forRoot()`.
  */
 declare class JetstreamClient extends ClientProxy {
     private readonly rootOptions;
@@ -451,14 +476,14 @@ declare class JetstreamClient extends ClientProxy {
     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.
-     */
+    /** Convention subject prefixes for foreign targets; one per stream kind. */
     private readonly eventSubjectPrefix;
     private readonly commandSubjectPrefix;
     private readonly orderedSubjectPrefix;
+    /** Broadcast subject prefix derived from the own resolver; never null. */
+    private readonly broadcastPrefix;
+    /** Resolver for self-target subjects; null when targeting a foreign service. */
+    private readonly selfNames;
     /**
      * RPC configuration snapshots. The values are derived from rootOptions at
      * construction time so the publish hot path never has to re-run
@@ -470,13 +495,8 @@ declare class JetstreamClient extends ClientProxy {
     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;
+    /** Reply inbox and pending-request registry for JetStream-mode RPC. */
+    private readonly rpcInbox;
     /** Subscription to connection status events for disconnect handling. */
     private statusSubscription;
     /**
@@ -485,7 +505,7 @@ declare class JetstreamClient extends ClientProxy {
      * and reach for the underlying connection synchronously instead.
      */
     private readyForPublish;
-    constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
+    constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, names?: NameResolver);
     /**
      * Establish connection. Called automatically by NestJS on first use.
      *
@@ -523,23 +543,14 @@ declare class JetstreamClient extends ClientProxy {
     private publishCoreRpc;
     /** JetStream mode: publish to stream + wait for inbox response. */
     private publishJetStreamRpc;
+    private warnIfDuplicate;
     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;
     /**
-     * Resolve a user pattern to a fully-qualified NATS subject, dispatching
-     * between the event, broadcast, and ordered prefixes.
-     *
-     * 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.
+     * Resolve a user pattern to a fully-qualified NATS subject. Self-targets go
+     * through the resolver so custom subjectPrefix options are honoured.
      */
     private buildEventSubject;
     /** Build NATS headers merging custom headers with transport headers. */
@@ -549,17 +560,12 @@ declare class JetstreamClient extends ClientProxy {
     /**
      * 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.
-     *
-     * A unique per-message suffix is appended because the server stores schedules
-     * as rollup messages — one active schedule per subject (ADR-51). Without it,
-     * concurrent schedules of the same pattern would silently replace each other.
-     *
-     * Examples:
-     * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder.<nuid>`
-     * - `broadcast.config.updated` → `broadcast._sch.config.updated.<nuid>`
+     * The holder lives in the same stream as the target but under the `_sch`
+     * namespace no consumer filter matches; the server publishes it to the
+     * target subject when the schedule fires. The unique per-message suffix
+     * exists because the server stores schedules as rollup messages, one
+     * active schedule per subject (ADR-51): without it, concurrent schedules
+     * of the same pattern would silently replace each other.
      */
     private buildScheduleSubject;
 }
@@ -611,7 +617,7 @@ declare class JetstreamRecord<TData = unknown> {
  * Fluent builder for constructing JetstreamRecord instances.
  *
  * Protected headers (`correlation-id`, `reply-to`, `error`) cannot be
- * set by the user — attempting to do so throws an error at build time.
+ * set by the user; attempting to do so throws an error at build time.
  */
 declare class JetstreamRecordBuilder<TData = unknown> {
     private data;
@@ -742,9 +748,8 @@ interface HandlerMetadata {
 }
 /**
  * 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.
+ * attributes. `port` is optional: OTel semconv makes it conditional, so we
+ * omit it rather than invent a number the user never configured.
  */
 interface ServerEndpoint {
     readonly host: string;
@@ -799,7 +804,7 @@ interface JetstreamResponseContext {
 }
 /**
  * Classification outcome for a thrown error. Affects span status and
- * attributes only — reply envelopes and internal logging are unchanged.
+ * attributes only; reply envelopes and internal logging are unchanged.
  */
 type ErrorClassification = 'expected' | 'unexpected';
 /** Object form of {@link OtelOptions.captureBody}. */
@@ -820,7 +825,7 @@ interface CaptureBodyOptions {
     readonly subjectAllowlist?: readonly string[];
 }
 /**
- * OpenTelemetry configuration for `JetstreamModule.forRoot({ otel: … })`.
+ * 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.
  */
@@ -835,11 +840,11 @@ interface OtelOptions {
     /**
      * 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
+     * - `'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
+     * - `JetstreamTrace[]`: explicit selection
      *
      * @default 'default'
      */
@@ -857,7 +862,7 @@ interface OtelOptions {
      *
      * 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
+     * (`traceparent`, `tracestate`, `baggage`, `sentry-trace`, `b3`, ...) are
      * always suppressed regardless of the allowlist.
      *
      * @default ['x-request-id']
@@ -882,7 +887,7 @@ interface OtelOptions {
     /**
      * 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
+     * Must be synchronous; thrown errors are caught and logged at debug
      * level without affecting the publish path.
      */
     publishHook?(span: Span, ctx: JetstreamPublishContext): void;
@@ -918,9 +923,9 @@ interface OtelOptions {
      * 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`
+     * - `'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)`
+     * - `'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.
@@ -941,6 +946,18 @@ interface OtelOptions {
 
 type ProvisioningEntity = 'stream' | 'consumer';
 
+/** How the library provisions a JetStream entity. */
+declare enum ManagementMode {
+    /** Library creates/updates the entity (current behavior). Default. */
+    Auto = "auto",
+    /** Bind to an externally-provisioned entity; never create or update. */
+    Manual = "manual"
+}
+/** Per-entity provisioning control for one stream kind. */
+interface EntityManagement {
+    stream?: ManagementMode;
+    consumer?: ManagementMode;
+}
 /**
  * Stream config overrides exposed to users.
  *
@@ -949,12 +966,19 @@ type ProvisioningEntity = 'stream' | 'consumer';
  * Any `retention` value provided at runtime is silently stripped.
  */
 type StreamConfigOverrides = Partial<Omit<StreamConfig, 'retention'>>;
+/**
+ * Ack-deadline auto-extension setting.
+ *
+ * `false` disables extension, `true` extends at half of `ack_wait`,
+ * and a number sets an explicit extension interval in milliseconds.
+ */
+type AckExtensionConfig = boolean | number;
 /**
  * RPC transport configuration.
  *
  * Discriminated union on `mode`:
- * - `'core'`      — NATS native request/reply. Lowest latency.
- * - `'jetstream'`  — Commands persisted in JetStream. Responses via Core NATS inbox.
+ * - `'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.
@@ -979,8 +1003,16 @@ type RpcConfig = {
      * 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;
+    ackExtension?: AckExtensionConfig;
+    /** Provisioning control for RPC stream/consumer. Falls back to provisioning.management. */
+    management?: EntityManagement;
+    /** Custom subject prefix (trailing dot normalized), e.g. 'company.orders.'. */
+    subjectPrefix?: string;
 };
+/** The JetStream variant of {@link RpcConfig}. */
+type JetStreamRpcConfig = Extract<RpcConfig, {
+    mode: 'jetstream';
+}>;
 /** Overrides for JetStream stream and consumer configuration. */
 interface StreamConsumerOverrides {
     stream?: StreamConfigOverrides;
@@ -990,16 +1022,16 @@ interface StreamConsumerOverrides {
      * 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` —
+     * 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
+     * @see https://github.com/nats-io/nats.js ConsumeOptions
      */
     consume?: Partial<ConsumeOptions>;
     /**
      * Maximum number of concurrent handler executions (RxJS `mergeMap` limit).
      *
-     * Default: `undefined` (unlimited — naturally bounded by `max_ack_pending`).
+     * 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
@@ -1010,11 +1042,15 @@ interface StreamConsumerOverrides {
     /**
      * Auto-extend the NATS ack deadline via `msg.working()` during handler execution.
      *
-     * - `false` (default): disabled — NATS redelivers after `ack_wait` if not acked.
+     * - `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.
      */
-    ackExtension?: boolean | number;
+    ackExtension?: AckExtensionConfig;
+    /** Provisioning control for this kind's stream/consumer. Falls back to provisioning.management. */
+    management?: EntityManagement;
+    /** Custom subject prefix (trailing dot normalized), e.g. 'company.orders.'. */
+    subjectPrefix?: string;
 }
 /**
  * Configuration for ordered event consumers.
@@ -1022,7 +1058,7 @@ interface StreamConsumerOverrides {
  * Ordered consumers use Limits retention and deliver messages in strict
  * sequential order with at-most-once delivery. No ack/nak/DLQ.
  *
- * Only a subset of consumer options applies — ordered consumers are
+ * Only a subset of consumer options applies; ordered consumers are
  * ephemeral and auto-managed by nats.js.
  */
 interface OrderedEventOverrides {
@@ -1046,6 +1082,10 @@ interface OrderedEventOverrides {
      * @default ReplayPolicy.Instant
      */
     replayPolicy?: ReplayPolicy;
+    /** Provisioning control for this kind's stream/consumer. Falls back to provisioning.management. */
+    management?: EntityManagement;
+    /** Custom subject prefix (trailing dot normalized), e.g. 'company.orders.'. */
+    subjectPrefix?: string;
 }
 /**
  * Configuration for the handler metadata KV registry.
@@ -1054,7 +1094,7 @@ interface OrderedEventOverrides {
  * entries to a NATS KV bucket at startup. External services (API gateways,
  * dashboards) can watch the bucket for service discovery.
  *
- * All fields are optional — sensible defaults are applied.
+ * All fields are optional; sensible defaults are applied.
  */
 interface MetadataRegistryOptions {
     /**
@@ -1086,6 +1126,8 @@ interface ProvisioningOptions {
      * Warn-only; never blocks boot. Off by default.
      */
     preflightStorageCheck?: boolean;
+    /** Default management mode for every stream and consumer. @default ManagementMode.Auto */
+    management?: ManagementMode;
 }
 /**
  * Root module configuration for `JetstreamModule.forRoot()`.
@@ -1129,7 +1171,7 @@ interface JetstreamModuleOptions {
     ordered?: OrderedEventOverrides;
     /**
      * Transport lifecycle hook handlers.
-     * Unset hooks are silently ignored — no default logging.
+     * Unset hooks are silently ignored; no default logging.
      */
     hooks?: Partial<TransportHooks>;
     /**
@@ -1173,6 +1215,8 @@ interface JetstreamModuleOptions {
      */
     dlq?: {
         stream?: StreamConfigOverrides;
+        /** Provisioning control for the DLQ stream. Falls back to provisioning.management. */
+        management?: EntityManagement;
     };
     /**
      * Graceful shutdown timeout in ms.
@@ -1187,7 +1231,7 @@ interface JetstreamModuleOptions {
      * 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
+     * `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.
      *
@@ -1214,7 +1258,7 @@ interface JetstreamModuleOptions {
     /**
      * 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.
+     * Merged with `name` and `servers`; those take precedence.
      */
     connectionOptions?: Partial<ConnectionOptions>;
     /**
@@ -1223,7 +1267,7 @@ interface JetstreamModuleOptions {
      * 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.
+     * `prom-client` is not imported, so there is zero overhead.
      *
      * Requires `prom-client` peer dependency to be installed when enabled.
      * The service writes to `prom-client`'s global `register` by default,
@@ -1245,7 +1289,7 @@ interface JetstreamModuleOptions {
      * 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
+     * consuming application, all tracer calls are no-ops with no
      * runtime cost.
      *
      * Accepts a full {@link OtelOptions} object, or the boolean shorthand
@@ -1273,7 +1317,7 @@ interface JetstreamFeatureOptions {
  * Supports three patterns: `useFactory`, `useExisting`, `useClass`.
  */
 type JetstreamModuleAsyncOptions = {
-    /** Service name — required upfront for DI token generation. */
+    /** Service name, required upfront for DI token generation. */
     name: string;
     /** Additional module imports (e.g., ConfigModule). */
     imports?: ModuleMetadata['imports'];
@@ -1352,6 +1396,7 @@ interface RpcRouterOptions {
  */
 declare class PatternRegistry {
     private readonly options;
+    private readonly names;
     private readonly logger;
     private readonly registry;
     private cachedPatterns;
@@ -1360,7 +1405,7 @@ declare class PatternRegistry {
     private _hasBroadcasts;
     private _hasOrdered;
     private _hasMetadata;
-    constructor(options: JetstreamModuleOptions);
+    constructor(options: JetstreamModuleOptions, names: NameResolver);
     /**
      * Register all handlers from the NestJS strategy.
      *
@@ -1373,7 +1418,7 @@ declare class PatternRegistry {
      * Resolve the declared pattern and {@link StreamKind} for a full NATS subject.
      *
      * Returns `null` when the subject is not registered. The declared pattern is
-     * the value the user passed to `@EventPattern`/`@MessagePattern` — stable and
+     * the value the user passed to `@EventPattern`/`@MessagePattern`: stable and
      * bounded, suitable for use as a Prometheus label without cardinality risk.
      */
     resolveDeclared(subject: string): {
@@ -1382,6 +1427,10 @@ declare class PatternRegistry {
     } | null;
     /** Get all registered broadcast patterns (for consumer filter_subject setup). */
     getBroadcastPatterns(): string[];
+    /** Get registered event patterns as raw user-declared patterns. */
+    getEventPatterns(): string[];
+    /** Get registered command patterns as raw user-declared patterns. */
+    getCommandPatterns(): string[];
     hasBroadcastHandlers(): boolean;
     hasRpcHandlers(): boolean;
     hasEventHandlers(): boolean;
@@ -1399,8 +1448,6 @@ declare class PatternRegistry {
     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;
@@ -1412,19 +1459,20 @@ declare class PatternRegistry {
  * 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.
+ * This is the default RPC mode: lowest latency, no persistence overhead.
  */
 declare class CoreRpcServer {
     private readonly connection;
     private readonly patternRegistry;
     private readonly codec;
     private readonly eventBus;
+    private readonly names?;
     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);
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, names?: NameResolver | undefined);
     /** Start listening for RPC requests on the command subject. */
     start(): Promise<void>;
     /** Stop listening and clean up the subscription. */
@@ -1437,71 +1485,12 @@ declare class CoreRpcServer {
 }
 
 /**
- * Manages JetStream stream lifecycle: creation, updates, and idempotent ensures.
- *
- * 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)
+ * Routes event, broadcast, and ordered messages to their handlers.
  *
- * All operations are idempotent: safe to call on every startup and reconnection.
+ * Per stream kind it assembles a routing pipeline (resolve, handle, settle)
+ * and a concurrency gate, then feeds the message stream through them. The
+ * dead-letter flow lives in {@link DeadLetterCapture}.
  */
-declare class StreamProvider {
-    private readonly options;
-    private readonly connection;
-    private readonly logger;
-    private readonly migration;
-    private readonly otel;
-    private readonly otelServiceName;
-    private readonly otelEndpoint;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
-    /**
-     * Ensure all required streams exist with correct configuration.
-     *
-     * @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.
-     */
-    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;
-    private buildReservation;
-    private errorContext;
-    private runStreamOp;
-    /** The broadcast stream is global — every service in the cluster shares it. */
-    private isSharedStream;
-    /** Build the full stream config by merging defaults with user overrides. */
-    private buildConfig;
-    /**
-     * Build the stream configuration for the Dead-Letter Queue (DLQ).
-     *
-     * Merges the library default DLQ config with user-provided overrides.
-     * Ensures transport-controlled settings like retention are safely decoupled.
-     */
-    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;
-    /**
-     * 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.
-     */
-    private stripTransportControlled;
-}
-
 declare class EventRouter {
     private readonly messageProvider;
     private readonly patternRegistry;
@@ -1510,14 +1499,13 @@ declare class EventRouter {
     private readonly deadLetterConfig?;
     private readonly processingConfig?;
     private readonly ackWaitMap?;
-    private readonly connection?;
-    private readonly options?;
     private readonly logger;
     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);
+    private readonly capture;
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined, processingConfig?: EventProcessingConfig | undefined, ackWaitMap?: Map<StreamKind, number> | undefined, connection?: ConnectionProvider, options?: JetstreamModuleOptions, names?: NameResolver);
     /**
      * Update the max_deliver thresholds from actual NATS consumer configs.
      * Called after consumers are ensured so the DLQ map reflects reality.
@@ -1527,42 +1515,10 @@ declare class EventRouter {
     start(): void;
     /** Stop routing and unsubscribe from all streams. */
     destroy(): void;
-    /** Subscribe to a message stream and route each message to its handler. */
+    /** Assemble the pipeline and concurrency gate for one stream and subscribe. */
     private subscribeToStream;
     private getConcurrency;
     private getAckExtensionConfig;
-    /**
-     * Last resort: invoke onDeadLetter, then term on success. On failure the
-     * message is nak'd — never redelivered past max_deliver, but preserved.
-     */
-    private fallbackToOnDeadLetterCallback;
-    /**
-     * Copy headers for the DLQ republish, dropping NATS control headers — a
-     * copied Nats-TTL would expire the DLQ entry, Nats-Msg-Id trips dedup.
-     */
-    private buildDlqHeaders;
-    /**
-     * Past max_deliver the server never redelivers, so these in-process attempts
-     * are the only second chance a dead letter gets. No artificial delay — an
-     * unreachable broker already spaces attempts via its own request timeout.
-     */
-    private publishToDlqWithRetry;
-    /**
-     * 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.
-     */
-    private publishToDlq;
-    /**
-     * 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.
-     */
-    private handleDeadLetter;
 }
 
 /**
@@ -1575,7 +1531,7 @@ declare class EventRouter {
  * - Timeout -> no response -> term
  * - No handler / decode error -> term immediately
  *
- * Nak is never used for RPC — prevents duplicate side effects.
+ * Nak is never used for RPC; it would risk duplicate side effects.
  */
 declare class RpcRouter {
     private readonly messageProvider;
@@ -1603,6 +1559,108 @@ declare class RpcRouter {
     destroy(): void;
 }
 
+/** Minimal JetStreamManager surface used by the binder. */
+interface BinderJsm {
+    streams: {
+        info(name: string): Promise<StreamInfo>;
+    };
+    consumers: {
+        info(stream: string, consumer: string): Promise<ConsumerInfo>;
+    };
+}
+/** Bind-only provisioning path: info()-only lookups and validation. */
+declare class InfrastructureBinder {
+    private readonly options;
+    private readonly names;
+    private readonly registry;
+    private readonly logger;
+    constructor(options: JetstreamModuleOptions, names: NameResolver, registry: PatternRegistry);
+    bindStream(jsm: BinderJsm, kind: StreamKind): Promise<StreamInfo>;
+    bindDlqStream(jsm: BinderJsm): Promise<StreamInfo>;
+    bindConsumer(jsm: BinderJsm, kind: StreamKind): Promise<ConsumerInfo>;
+    private fetchStream;
+    private fetchConsumer;
+    private assertHandlersCovered;
+    private assertDlqSubjectCoverage;
+    private assertScheduleCoverage;
+    private assertScheduleHoldersNotConsumed;
+    private warnOnOrphanedMigrationBackup;
+    private warnOnSchedulesDisabled;
+    private warnOnRetention;
+    private warnOnUnlimitedDelivery;
+    private warnOnShortAckWait;
+    private resolveHandlerSubjects;
+}
+
+/**
+ * Manages JetStream stream lifecycle: creation, updates, and idempotent ensures.
+ *
+ * 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 operations are idempotent: safe to call on every startup and reconnection.
+ */
+declare class StreamProvider {
+    private readonly options;
+    private readonly connection;
+    private readonly names;
+    private readonly binder;
+    private readonly logger;
+    private readonly migration;
+    private readonly otel;
+    private readonly otelServiceName;
+    private readonly otelEndpoint;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, names: NameResolver, binder: InfrastructureBinder);
+    /**
+     * Ensure all required streams exist with correct configuration.
+     *
+     * @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.
+     */
+    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;
+    private buildReservation;
+    private errorContext;
+    private runStreamOp;
+    private partitionByManagement;
+    private bindStream;
+    private bindDlqStream;
+    /** The broadcast stream is global; every service in the cluster shares it. */
+    private isSharedStream;
+    /** Build the full stream config by merging defaults with user overrides. */
+    private buildConfig;
+    /**
+     * Build the DLQ stream config: library defaults merged with user overrides,
+     * with transport-controlled settings like retention stripped.
+     */
+    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;
+    /**
+     * 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.
+     */
+    private stripTransportControlled;
+}
+
 /**
  * Manages JetStream consumer lifecycle: creation and idempotent ensures.
  *
@@ -1614,11 +1672,13 @@ declare class ConsumerProvider {
     private readonly connection;
     private readonly streamProvider;
     private readonly patternRegistry;
+    private readonly names;
+    private readonly binder;
     private readonly logger;
     private readonly otel;
     private readonly otelServiceName;
     private readonly otelEndpoint;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, streamProvider: StreamProvider, patternRegistry: PatternRegistry);
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, streamProvider: StreamProvider, patternRegistry: PatternRegistry, names: NameResolver, binder: InfrastructureBinder);
     /**
      * Ensure consumers exist for the specified kinds.
      *
@@ -1629,22 +1689,16 @@ declare class ConsumerProvider {
     getConsumerName(kind: StreamKind): string;
     /**
      * Ensure a single consumer exists with the desired config.
-     * Used at **startup** — creates or updates the consumer to match
-     * the current pod's configuration.
+     * Startup path: creates or updates the consumer to match the current pod's configuration.
      */
     ensureConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
     /**
      * Recover a consumer that disappeared during runtime.
-     * Used by **self-healing** — creates if missing, but NEVER updates config.
-     *
-     * 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.
      *
-     * 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)
+     * Self-healing path: creates if missing but never updates config, so an old pod
+     * cannot overwrite a newer pod's config during rolling updates. If a migration
+     * backup stream exists, throws so the retry loop backs off until migration completes;
+     * creating a consumer mid-migration would eat workqueue messages being restored.
      */
     recoverConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
     /**
@@ -1653,13 +1707,12 @@ declare class ConsumerProvider {
      * naturally waiting until the migrating pod finishes and cleans up the backup.
      */
     private assertNoMigrationInProgress;
-    /**
-     * Create a consumer, handling the race where another pod creates it first.
-     */
+    /** Create a consumer, handling the race where another pod creates it first. */
     private createConsumer;
     private runConsumerOp;
     /** Build consumer config by merging defaults with user overrides. */
     private buildConfig;
+    private buildCustomPrefixConfig;
     /** Get default config for a consumer kind. */
     private getDefaults;
     /** Get user-provided overrides for a consumer kind. */
@@ -1710,7 +1763,7 @@ declare class MessageProvider {
     /**
      * Start an ordered consumer for strict sequential delivery.
      *
-     * Unlike durable consumers, ordered consumers are ephemeral — created at
+     * Unlike durable consumers, ordered consumers are ephemeral: created at
      * consumption time, no durable state. nats.js handles auto-recreation.
      *
      * @param streamName - JetStream stream to consume from.
@@ -1747,13 +1800,9 @@ declare class MessageProvider {
 /**
  * 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.
+ * Entries are written on startup and refreshed every `ttl / 2`. When the pod stops
+ * (graceful or crash), the heartbeat stops and entries expire via TTL, so no
+ * explicit delete is needed.
  */
 declare class MetadataProvider {
     private readonly connection;
@@ -1766,16 +1815,12 @@ declare class MetadataProvider {
     private cachedKv?;
     constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
     /**
-     * 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.
+     * Write handler metadata entries to the KV bucket and start the heartbeat.
      *
-     * Non-critical — errors are logged but do not prevent transport startup.
+     * Creates the bucket if missing; skips silently when the map is empty.
+     * Non-critical: errors are logged but do not prevent transport startup.
      *
-     * @param entries Map of KV key → metadata object.
+     * @param entries Map of KV key to metadata object.
      */
     publish(entries: Map<string, Record<string, unknown>>): Promise<void>;
     /**
@@ -1799,7 +1844,7 @@ declare class MetadataProvider {
  * NATS JetStream API error codes used by the transport.
  *
  * Ref: https://github.com/nats-io/nats-server (server error definitions)
- * Codes verified across NATS 2.12.6–2.14.1 via integration tests (original codes: 2026-04-02).
+ * Codes verified across NATS 2.12.6-2.14.1 via integration tests (original codes: 2026-04-02).
  */
 declare enum NatsErrorCode {
     /** Consumer does not exist on the specified stream. */
@@ -1808,7 +1853,7 @@ declare enum NatsErrorCode {
     ConsumerAlreadyExists = 10148,
     /** Stream does not exist. */
     StreamNotFound = 10059,
-    /** Storage resources exceeded — reservation exceeds server `max_file_store`. */
+    /** Storage resources exceeded: reservation exceeds server `max_file_store`. */
     StorageResourcesExceeded = 10047,
     /**
      * No suitable peers for placement (fewer healthy peers than `num_replicas`,
@@ -1820,13 +1865,8 @@ declare enum NatsErrorCode {
 /**
  * NestJS custom transport strategy for NATS JetStream.
  *
- * 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.
+ * Registers handlers, provisions streams and consumers, then starts message
+ * consumption and routing (Core or JetStream RPC based on configuration).
  */
 declare class JetstreamStrategy extends Server implements CustomTransportStrategy {
     private readonly options;
@@ -1853,23 +1893,14 @@ declare class JetstreamStrategy extends Server implements CustomTransportStrateg
     /** Stop all consumers, routers, subscriptions, and metadata heartbeat. Called during shutdown. */
     close(): void;
     /**
-     * Override NestJS `Server.addHandler` to fail-fast on duplicate pattern registration.
+     * Override NestJS `Server.addHandler` to fail fast on duplicate pattern registration.
      *
-     * 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.
+     * The base class silently overwrites duplicate RPC handlers and chains duplicate event
+     * handlers, which would double-ack the same JetStream message. Any collision is treated
+     * as a fatal misconfiguration so it surfaces at bootstrap, not in production traffic.
      */
     addHandler(pattern: unknown, callback: MessageHandler, isEventHandler?: boolean, extras?: Record<string, unknown>): void;
-    /**
-     * Register event listener (required by Server base class).
-     *
-     * Stores callbacks for client use. Primary lifecycle events
-     * are routed through EventBus.
-     */
+    /** Register event listener (required by Server base class); lifecycle events use EventBus. */
     on(event: string, callback: Function): void;
     /**
      * Unwrap the underlying NATS connection.
@@ -1904,7 +1935,7 @@ interface Stoppable {
  * 3. Drain and close NATS connection (with timeout safety net)
  * 4. Emit onShutdownComplete hook
  *
- * Idempotent — concurrent or repeated calls return the same promise.
+ * 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.
@@ -1919,7 +1950,7 @@ declare class ShutdownManager {
     /**
      * Execute the full shutdown sequence.
      *
-     * Idempotent — concurrent or repeated calls return the same promise.
+     * Idempotent: concurrent or repeated calls return the same promise.
      *
      * @param strategy Optional stoppable to close (stops consumers and subscriptions).
      */
@@ -1930,16 +1961,16 @@ declare class ShutdownManager {
 /**
  * Root module for the NestJS JetStream transport.
  *
- * - `forRoot()` / `forRootAsync()` — registers once in AppModule.
+ * - `forRoot()` / `forRootAsync()`: registers once in AppModule.
  *   Creates shared NATS connection, codec, event bus, and optionally
  *   the consumer infrastructure.
  *
- * - `forFeature()` — registers in feature modules.
+ * - `forFeature()`: registers in feature modules.
  *   Creates a lightweight client proxy targeting a specific service.
  *
  * @example
  * ```typescript
- * // AppModule — global setup
+ * // AppModule: global setup
  * @Module({
  *   imports: [
  *     JetstreamModule.forRoot({
@@ -1950,7 +1981,7 @@ declare class ShutdownManager {
  * })
  * export class AppModule {}
  *
- * // Feature module — per-service clients
+ * // Feature module: per-service clients
  * @Module({
  *   imports: [
  *     JetstreamModule.forFeature({ name: 'users' }),
@@ -2037,7 +2068,7 @@ interface PackrLike {
  * MessagePack codec backed by a caller-provided `msgpackr` `Packr` instance.
  *
  * Use this codec when publishing structured payloads larger than roughly
- * 1–2 KB — below that size the default {@link JsonCodec} wins on per-call
+ * 1-2 KB; below that size the default {@link JsonCodec} wins on per-call
  * constant overhead. Above it, MessagePack encodes and decodes several times
  * faster and produces smaller wire frames. The format is cross-language, so
  * Node producers and non-Node consumers (Python, Go, Java, Rust, ...) stay
@@ -2161,7 +2192,7 @@ declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
     terminate(reason?: string): void;
     /** Narrow to JsMsg or return null for Core messages. Used by metadata getters. */
     private asJetStream;
-    /** Ensure the message is JetStream — settlement actions are not available for Core NATS. */
+    /** Ensure the message is JetStream; settlement actions are not available for Core NATS. */
     private assertJetStream;
     /** @internal */
     get shouldRetry(): boolean;
@@ -2177,7 +2208,7 @@ declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
  * Health indicator result compatible with @nestjs/terminus.
  *
  * Follows the Terminus convention: returns status object on success,
- * throws on failure. Works with Terminus out of the box — no wrapper needed:
+ * throws on failure. Works with Terminus out of the box, no wrapper needed:
  *
  * @example
  * ```typescript
@@ -2207,7 +2238,7 @@ declare class JetstreamHealthIndicator {
      * Returns `{ [key]: { status: 'up', ... } }` on success.
      * Throws an error with `{ [key]: { status: 'down', ... } }` on failure.
      *
-     * The thrown error sets `isHealthCheckError: true` and `causes` — the
+     * The thrown error sets `isHealthCheckError: true` and `causes`, the
      * duck-type contract that Terminus `HealthCheckExecutor` uses to distinguish
      * health failures from unexpected exceptions. Works with both Terminus v10
      * (`instanceof HealthCheckError`) and v11+ (`error?.isHealthCheckError`).
@@ -2318,7 +2349,7 @@ declare enum JetstreamHeader {
     Error = "x-error"
 }
 declare enum JetstreamDlqHeader {
-    /** Reason for the message being sent to the DLQ — the last handler error message. */
+    /** Reason the message was sent to the DLQ: the last handler error message. */
     DeadLetterReason = "x-dead-letter-reason",
     /** Original NATS subject the message was originally published to */
     OriginalSubject = "x-original-subject",
@@ -2338,14 +2369,6 @@ declare const RESERVED_HEADERS: Set<string>;
  * @returns `{name}__microservice`
  */
 declare const internalName: (name: string) => string;
-/**
- * Build a fully-qualified NATS subject for workqueue events, RPC commands, or ordered events.
- *
- * @param serviceName - Target service name.
- * @param kind - Subject kind ({@link StreamKind.Event}, {@link StreamKind.Command}, or {@link StreamKind.Ordered}).
- * @param pattern - The message pattern (e.g. `'user.created'`).
- * @returns `{serviceName}__microservice.{kind}.{pattern}`
- */
 declare const buildSubject: (serviceName: string, kind: SubjectKind, pattern: string) => string;
 /**
  * Build a broadcast subject.
@@ -2388,7 +2411,7 @@ declare enum PatternPrefix {
     Ordered = "ordered:"
 }
 /** Check if the RPC config specifies JetStream mode. */
-declare const isJetStreamRpcMode: (rpc: RpcConfig | undefined) => boolean;
+declare const isJetStreamRpcMode: (rpc: RpcConfig | undefined) => rpc is JetStreamRpcConfig;
 /** Check if the RPC config specifies Core mode (default). */
 declare const isCoreRpcMode: (rpc: RpcConfig | undefined) => boolean;
 
@@ -2418,4 +2441,4 @@ declare class JetstreamProvisioningError extends Error {
     constructor(fields: ProvisioningErrorFields);
 }
 
-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, JetstreamProvisioningError, type JetstreamPublishContext, JetstreamRecord, JetstreamRecordBuilder, type JetstreamResponseContext, JetstreamStrategy, JetstreamTrace, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, MsgpackCodec, NatsErrorCode, type OrderedEventOverrides, type OtelOptions, PatternPrefix, type ProvisioningOptions, 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 };
+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 EntityManagement, 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, JetstreamProvisioningError, type JetstreamPublishContext, JetstreamRecord, JetstreamRecordBuilder, type JetstreamResponseContext, JetstreamStrategy, JetstreamTrace, JsonCodec, MIN_METADATA_TTL, ManagementMode, MessageKind, type MetadataRegistryOptions, MsgpackCodec, NatsErrorCode, type OrderedEventOverrides, type OtelOptions, PatternPrefix, type ProvisioningOptions, 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 };