@cotal-ai/core 0.90.1 → 0.92.0

package/dist/endpoint.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from "node:events";
 import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
 import { createConnection } from "node:net";
 import { connect, credsAuthenticator, headers, tokenAuthenticator, nanos, millis, AuthorizationError, PermissionViolationError, UserAuthenticationExpiredError, NoRespondersError, RequestError, TimeoutError, ClosedConnectionError, } from "@nats-io/transport-node";
 import { wsconnect } from "@nats-io/nats-core";
@@ -17,11 +18,12 @@ import { assertIdToken, assertGeneration } from "./endpoint-subjects.js";
 import { readAcceptedRow } from "./issued-authority.js";
 import { lastKvEntries, liveKvEntries } from "./kv-scan.js";
 import { isConsumerAlreadyExists, isConsumerNotFound, isJetStreamMissing } from "./jetstream-missing.js";
+import { isRestoredConsumer } from "./backup.js";
 import { ARTIFACT_PART_KIND, isArtifactPart } from "./artifact.js";
 import { assertValidName } from "./resolve.js";
 import { EVICT_PRINCIPALS_MAX } from "./evict.js";
 import { createSpaceStreams, dmDurableConfig, dlvDurableConfig, taskDurableConfig, fanoutDurableConfig, inboxReaderConfig, MAX_MSGS_PER_SUBJECT, MANAGER_LEASE_TTL_MS, MANAGER_LEASE_ATTEMPT_MS, TTL_RECONCILE_CANARY_KEY, PRESENCE_STORAGE } from "./streams.js";
-import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, } from "@nats-io/jetstream";
+import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, JetStreamApiError, } from "@nats-io/jetstream";
 import {} from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
 import { Bucket, KvWatchInclude } from "@nats-io/kv/internal";
@@ -61,6 +63,31 @@ export const MULTI_FILTER_READ_CONCURRENCY = 4;
  *  minutes is what the nats.js ordered consumers it replaces carried, and it keeps a reader alive
  *  across the gap between pulls on a slow link. */
 const HISTORY_READER_INACTIVE_MS = 5 * 60_000;
+/** A DM-only endpoint's own `dm_` durable does not exist. The endpoint never creates it. */
+export class DmDurableMissingError extends Error {
+    stream;
+    durable;
+    code = "dm-durable-missing";
+    constructor(stream, durable) {
+        super(`dm-durable-missing: durable "${durable}" on stream "${stream}" does not exist; a DM-only endpoint binds an existing durable and never creates one`);
+        this.stream = stream;
+        this.durable = durable;
+        this.name = "DmDurableMissingError";
+    }
+}
+/** The broker refused a DM-only endpoint's bind of its own `dm_` durable. No other credential or
+ *  read path is tried. */
+export class DmBindRefusedError extends Error {
+    stream;
+    durable;
+    code = "dm-bind-refused";
+    constructor(stream, durable, cause) {
+        super(`dm-bind-refused: binding durable "${durable}" on stream "${stream}" was refused (${cause instanceof Error ? cause.message : String(cause)})`, { cause });
+        this.stream = stream;
+        this.durable = durable;
+        this.name = "DmBindRefusedError";
+    }
+}
 /** A presence bucket that has refused consecutive writes for at least one full presence TTL.
  * The condition is non-transient: ordinary heartbeat retry has already failed for the whole
  * liveness window, so callers should report the roster as last-known until a write succeeds. */
@@ -169,6 +196,9 @@ export class CotalEndpoint extends EventEmitter {
     doWatchChannels;
     readOnce;
     doConsume;
+    dmOnly;
+    /** The DM-only handler now running, if any; stop awaits it. */
+    dmOnlyInFlight;
     ackWaitMs;
     inactiveThresholdMs;
     nc;
@@ -560,6 +590,21 @@ export class CotalEndpoint extends EventEmitter {
         this.readOnce = opts.readOnce ?? false;
         if (this.readOnce && (this.doConsume || this.doRegister))
             throw new Error("EndpointOptions.readOnce requires consume and registerPresence false: a one-time read cannot keep a consumer's channel cache or its own presence current");
+        if (opts.dmOnly !== undefined) {
+            if (typeof opts.dmOnly.handler !== "function")
+                throw new Error("EndpointOptions.dmOnly.handler must be a function");
+            const settle = opts.dmOnly.settleTimeoutMs;
+            if (settle !== undefined && (!Number.isSafeInteger(settle) || settle <= 0))
+                throw new Error("EndpointOptions.dmOnly.settleTimeoutMs must be a positive safe integer");
+            if (!this.authed)
+                throw new Error("EndpointOptions.dmOnly requires creds or a bearer: it binds a provisioned durable and never creates one");
+            if (!this.doConsume || this.doRegister || this.doWatch || this.doWatchChannels || this.readOnce)
+                throw new Error("EndpointOptions.dmOnly requires consume true and registerPresence, watchPresence, watchChannels and readOnce false");
+            if (this.channels.length || opts.card.role || opts.acceptedToken !== undefined)
+                throw new Error("EndpointOptions.dmOnly takes no channels, role or acceptedToken: the endpoint reads only its own DM durable");
+            this.requireLifecycleUid("EndpointOptions.dmOnly");
+            this.dmOnly = opts.dmOnly;
+        }
         // Seed the presence mirror so file-default channel modes are visible from the first publish
         // (not only after the first runtime toggle). Mirror only — delivery reads the connector's state.
         this.channelModes = opts.channelModes && Object.keys(opts.channelModes).length ? opts.channelModes : undefined;
@@ -1075,6 +1120,16 @@ export class CotalEndpoint extends EventEmitter {
         this.armAuthExpiryReconnectFence(this.nc);
         this.watchStatus();
         this.js = jetstream(this.nc);
+        // DM-only (EndpointOptions.dmOnly): the own DM durable is the whole binding. Nothing below runs:
+        // no accepted-row read, presence, channel registry, JetStream manager, lease, membership,
+        // Plane-3 or liveness responder, so the credential needs no row for any of them.
+        if (this.dmOnly) {
+            await this.bindDmOnly(this.dmOnly);
+            if (this.stopped)
+                return;
+            this.emit("connection", { connected: true });
+            return;
+        }
         // Discovery of the issued generation (SPEC 13.15): the ISSUER wrote the accepted reference
         // under the token this launch was handed; the broker admits the read only under this
         // connection's own per-key grant. What comes back must name this incarnation, and a fresh
@@ -1656,6 +1711,14 @@ export class CotalEndpoint extends EventEmitter {
             /* best-effort graceful leave */
         }
         await this.settleDeliveryLeaseWatches();
+        // DM-only: the pull above is stopped, so no new copy reaches the handler. Let a running handler
+        // settle while the connection is still open, so its ack can reach the broker; close either way.
+        let dmOnlyUnsettled = false;
+        if (this.dmOnly && this.dmOnlyInFlight) {
+            const settleMs = this.dmOnly.settleTimeoutMs ?? 30_000;
+            dmOnlyUnsettled = await withDeadline(this.dmOnlyInFlight.then(() => false), settleMs, () => new Error("unsettled"))
+                .catch(() => true);
+        }
         await this.closeWithoutLibraryReconnect(this.nc);
         // #1356: stop() does its own teardown and never runs clearConnectionScoped, so clear here too —
         // AFTER the best-effort offline publish above, which would otherwise re-record a refusal on its
@@ -1669,6 +1732,8 @@ export class CotalEndpoint extends EventEmitter {
         await this.startPromise;
         if ([...this.ownedConnections].some((nc) => !nc.isClosed()))
             throw new Error("endpoint stop could not prove its connection closed; local consumer custody must be retained");
+        if (dmOnlyUnsettled)
+            throw new Error(`endpoint stop closed the connection but the DM-only handler did not settle within ${this.dmOnly?.settleTimeoutMs ?? 30_000}ms; its copy stays unacked and handler custody must be retained`);
     }
     // ---- messaging -----------------------------------------------------------
     /** Multicast: broadcast to everyone on a channel. */
@@ -2451,6 +2516,28 @@ export class CotalEndpoint extends EventEmitter {
     channelReplayWindow(channel) {
         return this.channelConfigs.get(channel)?.replayWindow ?? this.channelDefaults.replayWindow;
     }
+    /** A channel's effective replay policy read straight from the registry bucket, for a caller that
+     *  reads it right after start, before any watch cache has caught up, or that watches nothing. A
+     *  wildcard reads the space defaults only. A space with no registry bucket has the built-in policy. */
+    async channelReplayPolicy(channel) {
+        if (!this.nc)
+            throw new Error(this.notLiveMsg());
+        const kv = this.channelKv ?? (await openChannelRegistry(this.nc, this.space, { create: false }));
+        let cfg;
+        let defaults;
+        try {
+            [cfg, defaults] = await Promise.all([
+                isConcreteChannel(channel) ? readChannelConfig(kv, channel) : Promise.resolve(undefined),
+                readChannelDefaults(kv),
+            ]);
+        }
+        catch (e) {
+            // `open` binds lazily, so a space with no registry bucket surfaces on the first read.
+            if (!isJetStreamMissing(e, JetStreamApiCodes.StreamNotFound))
+                throw e;
+        }
+        return { replay: effectiveReplay(cfg, defaults), window: cfg?.replayWindow ?? defaults?.replayWindow ?? null };
+    }
     /** Effective delivery class for a channel (per-channel override ?? space default ?? "durable"),
      *  from the live watch cache — drives the non-gating delivery-health surface (only durable-class
      *  channels have a Plane-3 backstop to report on). */
@@ -2563,6 +2650,42 @@ export class CotalEndpoint extends EventEmitter {
         this.joinSeq.delete(channel);
         return { left: true };
     }
+    /**
+     * What the chat stream still holds and what removes the rest. `perSender` is the stream's
+     * per-subject cap: a subject is one sender on one channel, and past the cap that sender's oldest
+     * message on the channel is discarded. `maxAgeMs` is the stream's age limit. Each is `null` when
+     * the stream sets none. `senders` counts each sender's retained messages per channel, so a sender
+     * at the cap marks a channel whose retained history has lost that sender's older messages while
+     * other senders' messages from the same time remain.
+     */
+    async chatRetention() {
+        if (!this.nc)
+            throw new Error(this.notLiveMsg());
+        const mgr = await jetstreamManager(this.nc);
+        let info;
+        try {
+            info = await mgr.streams.info(chatStream(this.space), { subjects_filter: ">" });
+        }
+        catch (e) {
+            // As in listChannels: an absent CHAT stream holds nothing yet; any other failure stays loud.
+            if (!isJetStreamMissing(e, JetStreamApiCodes.StreamNotFound))
+                throw e;
+            return { perSender: null, maxAgeMs: null, senders: [] };
+        }
+        const senders = [];
+        for (const [subject, messages] of Object.entries(info.state.subjects ?? {})) {
+            const p = parseSubject(subject);
+            if (p?.kind === "chat" && isPrincipalOwnerToken(p.owner))
+                senders.push({ channel: p.rest, sender: p.sender, messages });
+        }
+        const cap = info.config.max_msgs_per_subject;
+        const age = info.config.max_age;
+        return {
+            perSender: typeof cap === "number" && cap > 0 ? cap : null,
+            maxAgeMs: typeof age === "number" && age > 0 ? Math.round(age / 1_000_000) : null,
+            senders: senders.sort((a, b) => a.channel.localeCompare(b.channel) || a.sender.localeCompare(b.sender)),
+        };
+    }
     /** One coherent channel model for dashboards: every channel that has messages OR a registry
      *  entry (configured-but-empty), each tagged with its {@link ChannelConfig}. Works even on
      *  observer endpoints (no consumers needed). */
@@ -2905,6 +3028,94 @@ export class CotalEndpoint extends EventEmitter {
         // history from any sender
         return (await this.streamHistory(chatStream(this.space), [chatSubject(this.space, "*", "*", channel)], opts?.limit ?? 100, undefined, opts?.signal)).map((r) => r.msg);
     }
+    /** Read one concrete channel using this lifecycle's single-filter CHAT grant (SPEC §8/§9).
+     *  No observer authority, presence or delivery ACL mirror is required. Returns the newest page,
+     *  oldest-first, including this caller's own sends. `complete` says no older valid row remains.
+     *  Reads have a ten-second budget, shortened by `signal`. Concurrent connections sharing this
+     *  lifecycle wait for native consumer inactivity cleanup; they never delete another reader. */
+    async channelHistoryPage(channel, opts) {
+        assertValidChannel(channel);
+        if (!isConcreteChannel(channel))
+            throw new Error("channelHistoryPage requires one concrete channel");
+        const limit = opts?.limit ?? 50;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error("channelHistoryPage limit must be a whole number from 1 to 1000");
+        if (!this.nc || !this.js)
+            throw new Error("endpoint not started");
+        const jsm = this.jsm ??= await jetstreamManager(this.nc);
+        const signal = AbortSignal.any([AbortSignal.timeout(10_000), ...(opts?.signal ? [opts.signal] : [])]);
+        signal.throwIfAborted();
+        const stream = chatStream(this.space);
+        const name = chatHistDurable(this.owner, this.actor, this.requireLifecycleUid("channelHistoryPage"));
+        const subject = chatSubject(this.space, "*", "*", channel);
+        const marker = randomUUID();
+        let created;
+        for (;;) {
+            signal.throwIfAborted();
+            try {
+                // The pinned client's add is CREATE-only. A unique description makes even an otherwise
+                // identical occupied config conflict. Never bind/update it or pre-delete by shared name.
+                created = await jsm.consumers.add(stream, {
+                    name, description: marker, filter_subject: subject,
+                    ack_policy: AckPolicy.None, deliver_policy: DeliverPolicy.All,
+                    mem_storage: true, inactive_threshold: nanos(250),
+                });
+                break;
+            }
+            catch (e) {
+                if (!(e instanceof JetStreamApiError) || e.code !== 10148)
+                    throw e; // consumer already exists
+                await delay(50, undefined, { signal });
+            }
+        }
+        signal.throwIfAborted();
+        const owns = (info) => info.created === created.created &&
+            info.config.description === marker && info.config.filter_subject === subject;
+        if (!owns(created))
+            throw new Error("channelHistoryPage: consumer ownership was not established");
+        const consumer = await this.js.consumers.get(stream, name);
+        const pending = created.num_pending;
+        const out = [];
+        let delivered = 0;
+        if (pending > 0) {
+            const iter = await consumer.consume({ max_messages: Math.min(pending, 32) });
+            const stop = () => iter.stop(abortReason(signal));
+            signal.addEventListener("abort", stop, { once: true });
+            try {
+                signal.throwIfAborted();
+                for await (const m of iter) {
+                    signal.throwIfAborted();
+                    if (!subjectMatches(subject, m.subject))
+                        throw new Error("channelHistoryPage: consumer delivered another channel; ownership was lost");
+                    delivered++;
+                    const msg = historyMessageFromDelivery(m);
+                    if (msg) {
+                        out.push(msg);
+                        if (out.length > limit + 1)
+                            out.shift();
+                    }
+                    if (delivered >= pending)
+                        break;
+                }
+            }
+            finally {
+                signal.removeEventListener("abort", stop);
+                iter.stop();
+            }
+            signal.throwIfAborted();
+            if (delivered !== pending)
+                throw new Error(`channelHistoryPage: read ${delivered} of ${pending} messages before the window was cut short`);
+        }
+        signal.throwIfAborted();
+        // A legacy join/recall reader can delete/recreate this fixed name. A final ownership check
+        // makes that interference loud. It is detection, not a fence against those legacy readers.
+        if (!owns(await consumer.info()))
+            throw new Error("channelHistoryPage: consumer ownership was lost");
+        signal.throwIfAborted();
+        // No DELETE, even after abort: a delayed owner could otherwise delete its successor between
+        // INFO and DELETE. Native inactivity reaps this transient reader without that TOCTOU race.
+        return { items: out.slice(-limit), complete: out.length <= limit };
+    }
     /**
      * The newest `limit` chat messages across MANY channels at once, oldest-first within the page,
      * each tagged with the channel the BROKER delivered it on.
@@ -2996,19 +3207,19 @@ export class CotalEndpoint extends EventEmitter {
         // payload's `ts` here instead would change which messages the page holds, which is the
         // selection question this pull request already had to answer once.
         const rows = pages.flat().sort((a, b) => a.seq - b.seq).slice(-limit);
-        return rows.map(({ subject, msg }) => {
+        return rows.map(({ seq, subject, msg }) => {
             const p = parseSubject(subject);
             // The filter set is built from chat subjects, so this cannot fire against a healthy broker.
             // It is here because the alternative to raising is tagging a message with a guess.
             if (p?.kind !== "chat")
                 throw new Error(`multiChannelHistory: the broker delivered ${subject}, which is not a chat subject on this space`);
-            return { channel: p.rest, msg };
+            return { channel: p.rest, seq, msg };
         });
     }
-    /** Read a channel's recent history THROUGH THE DELIVERY DAEMON instead of through a consumer this
-     *  connection creates itself — the mediated read of SPEC's "Mediated reads (normative)" rule (no raw
-     *  consumer / `DIRECT.GET` / `STREAM.MSG.GET` for an untrusted holder; the trusted reader serves it
-     *  onto the caller's own confined rail). `items` is shape-identical to what {@link channelHistory}
+    /** Read a channel's recent history through the delivery daemon, using a provisioned ACL mirror.
+     *  SPEC's ban on raw control-surface stream reads does not remove the single-channel CHAT grant.
+     *  Human callers without an ACL mirror use {@link channelHistoryPage}; this method adds fresh
+     *  mirror checks for provisioned readers. `items` is shape-identical to what {@link channelHistory}
      *  returns — the same `CotalMessage[]`, the same newest-N selection, the same oldest-first order
      *  within the page — so a caller migrates by reading `.items` and nothing else changes. The return
      *  is WRAPPED rather than bare precisely because of `complete`: a bare array cannot say whether
@@ -5179,14 +5390,25 @@ export class CotalEndpoint extends EventEmitter {
         }
         return { ok: false, error: `op "${req.op}" not supported on the delivery admin service` };
     }
+    /** Create one of the daemon's Plane-3 durables. A named create is idempotent for the same config,
+     *  and a denial is never taken for existence. The one conflict accepted is this durable as a full
+     *  restore recreated it, starting after its recorded ACK floor ({@link isRestoredConsumer}); every
+     *  other failure propagates. */
+    async addPlane3Durable(stream, config) {
+        try {
+            await this.jsm.consumers.add(stream, config);
+        }
+        catch (e) {
+            if (!isConsumerAlreadyExists(e) || !isRestoredConsumer(this.space, stream, await this.jsm.consumers.info(stream, config.durable_name), config))
+                throw e;
+        }
+    }
     /** Fan-out loop: bind the privileged `fanout` durable on CHAT and route each message (routing only —
      *  the trusted reader is the auth gate). */
     async runFanout() {
         if (!this.js || !this.jsm)
             return;
-        // Named consumer creation is idempotent for the same config. A denial must not be mistaken for
-        // "already exists"; let the broker response decide and propagate every failure.
-        await this.jsm.consumers.add(chatStream(this.space), fanoutDurableConfig(this.space, { ackWaitMs: this.ackWaitMs }));
+        await this.addPlane3Durable(chatStream(this.space), fanoutDurableConfig(this.space, { ackWaitMs: this.ackWaitMs }));
         const consumer = await this.js.consumers.get(chatStream(this.space), FANOUT_DURABLE);
         const msgs = await consumer.consume();
         this.streamMsgs.push(msgs);
@@ -5298,8 +5520,7 @@ export class CotalEndpoint extends EventEmitter {
     async runReader() {
         if (!this.js || !this.jsm)
             return;
-        // Same fail-loud rule as fan-out: idempotent success is success, denial is not existence.
-        await this.jsm.consumers.add(inboxStream(this.space), inboxReaderConfig(this.space, { ackWaitMs: this.ackWaitMs }));
+        await this.addPlane3Durable(inboxStream(this.space), inboxReaderConfig(this.space, { ackWaitMs: this.ackWaitMs }));
         const consumer = await this.js.consumers.get(inboxStream(this.space), INBOX_READER_DURABLE);
         const msgs = await consumer.consume();
         this.streamMsgs.push(msgs);
@@ -5753,31 +5974,10 @@ export class CotalEndpoint extends EventEmitter {
         this.streamMsgs.push(msgs);
         void (async () => {
             for await (const m of msgs) {
-                let msg;
-                try {
-                    msg = m.json();
-                }
-                catch (e) {
-                    m.term(); // undecodable — never redeliver
-                    this.emit("error", e);
-                    continue;
-                }
-                // Authenticity guard (fail closed): the sender is encoded in the subject, which the
-                // server policed who could publish. The payload `from` is advisory — it must match,
-                // and a missing `from` or an unparseable subject on a delivery is itself an anomaly.
-                // Reject (term — a spoof is permanently invalid, never redeliver) BEFORE any handler.
-                if (!isRecord(msg) || !isUsableMessageId(msg.id)) {
-                    m.term(); // malformed envelope (SPEC sec 5): absent/non-string id — permanently invalid
-                    this.emit("error", new Error(`dropped message on ${m.subject}: absent or non-string id`));
+                const authed = this.authenticateStreamMsg(m);
+                if (!authed)
                     continue;
-                }
-                const parsed = parseSubject(m.subject);
-                if (!parsed || !msg.from || msg.from.id !== parsed.sender || !isPrincipalOwnerToken(parsed.owner)) {
-                    m.term();
-                    this.emit("error", new Error(`dropped message on ${m.subject}: payload from ${msg.from?.id ?? "(none)"} ` +
-                        `does not match subject sender ${parsed?.sender ?? "(unparseable)"}`));
-                    continue;
-                }
+                const { msg, parsed } = authed;
                 // No-replay + dedup (chat only): drop a message at/below this channel's join watermark
                 // — pre-join history the New tail still carries for a *lagging* joiner (cursor behind the
                 // frontier), and the overlap a replay backfill already delivered. Must ack, or JetStream
@@ -5805,6 +6005,101 @@ export class CotalEndpoint extends EventEmitter {
                 this.emit("error", e);
         });
     }
+    /** Decode one stream copy and apply the authenticity guard (fail closed): the sender is encoded in
+     *  the subject, which the server policed who could publish. The payload `from` is advisory — it
+     *  must match, and a missing `from` or an unparseable subject on a delivery is itself an anomaly.
+     *  A rejected copy is `term()`ed (permanently invalid, never redelivered) and reported, and
+     *  `undefined` returns, so no handler ever sees it. */
+    authenticateStreamMsg(m) {
+        let msg;
+        try {
+            msg = m.json();
+        }
+        catch (e) {
+            m.term(); // undecodable — never redeliver
+            this.emit("error", e);
+            return undefined;
+        }
+        if (!isRecord(msg) || !isUsableMessageId(msg.id)) {
+            m.term(); // malformed envelope (SPEC sec 5): absent/non-string id — permanently invalid
+            this.emit("error", new Error(`dropped message on ${m.subject}: absent or non-string id`));
+            return undefined;
+        }
+        const parsed = parseSubject(m.subject);
+        if (!parsed || !msg.from || msg.from.id !== parsed.sender || !isPrincipalOwnerToken(parsed.owner)) {
+            m.term();
+            this.emit("error", new Error(`dropped message on ${m.subject}: payload from ${msg.from?.id ?? "(none)"} ` +
+                `does not match subject sender ${parsed?.sender ?? "(unparseable)"}`));
+            return undefined;
+        }
+        return { msg, parsed };
+    }
+    /** Bind this endpoint's own existing DM durable and drive it serially (EndpointOptions.dmOnly).
+     *  The bind is one CONSUMER.INFO on `dm_<owner>-<actor>-<uid>`; reading is MSG.NEXT with a batch
+     *  of one, and the next copy reaches the handler only after the previous handler settles. */
+    async bindDmOnly(mode) {
+        if (!this.js)
+            throw new Error("endpoint not started");
+        const stream = dmStream(this.space);
+        const durable = dmDurable(this.owner, this.actor, this.requireLifecycleUid("consuming the DM inbox"));
+        let consumer;
+        try {
+            consumer = await this.js.consumers.get(stream, durable);
+        }
+        catch (e) {
+            if (isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
+                throw new DmDurableMissingError(stream, durable);
+            throw new DmBindRefusedError(stream, durable, e);
+        }
+        const ackWaitMs = await ackWaitOf(consumer); // cached by the bind's own CONSUMER.INFO, no request
+        // A rebind after reconnect must not overlap the previous epoch's running handler. A handler that
+        // does not settle within the stop bound fails this bind; the retry loop tries again.
+        if (this.dmOnlyInFlight) {
+            const settleMs = mode.settleTimeoutMs ?? 30_000;
+            await withDeadline(this.dmOnlyInFlight, settleMs, () => new Error(`DM-only rebind waited ${settleMs}ms for the previous handler to settle; not reading the next DM yet`));
+        }
+        const msgs = await consumer.consume({ max_messages: 1 });
+        this.streamMsgs.push(msgs);
+        // The epoch this loop belongs to. nats.js can yield copies it already received after stop() began
+        // or after a rebuild replaced the connection (a stacked pull after a missed-heartbeat reset hands
+        // over several at once). Such a copy never reaches the handler and is neither acked nor nak'd:
+        // the connection is closing or closed, so any reply could be lost, and the broker redelivers an
+        // unacked copy after the durable's ack_wait to whichever epoch binds next.
+        const boundNc = this.nc;
+        const retired = () => this.stopped || this.nc !== boundNc || !boundNc || boundNc.isClosed();
+        void (async () => {
+            for await (const m of msgs) {
+                if (retired())
+                    break;
+                const authed = this.authenticateStreamMsg(m);
+                if (!authed)
+                    continue;
+                if (authed.parsed.kind !== "inst") {
+                    m.term(); // the DM stream filter admits only inst.* subjects; anything else is not a DM
+                    continue;
+                }
+                const run = Promise.resolve().then(() => mode.handler(authenticatedMessage(authed.msg, authed.parsed), dmOnlyDelivery(m, ackWaitMs, boundNc), {
+                    historical: false,
+                    kind: "dm",
+                }));
+                const flight = run.then(() => { }, () => { });
+                this.dmOnlyInFlight = flight;
+                try {
+                    await run;
+                }
+                catch (e) {
+                    this.emit("error", e instanceof Error ? e : new Error(String(e)));
+                }
+                finally {
+                    if (this.dmOnlyInFlight === flight)
+                        this.dmOnlyInFlight = undefined;
+                }
+            }
+        })().catch((e) => {
+            if (!this.stopped)
+                this.emit("error", e);
+        });
+    }
     /** Open a native core subscription to a channel's live feed (the manager-free live read path,
      *  broker-enforced by `sub.allow`). At-most-once — no replay, no ack; it is the live delivery for
      *  every channel (boot + runtime). For a `durable` channel it is also the low-latency wake-hint
@@ -6777,6 +7072,20 @@ function durableDelivery(m, ackWaitMs) {
         redelivery: { deliveryCount: m.info.deliveryCount, ackWaitMs, working: () => m.working() },
     };
 }
+/** A DM-only copy's delivery. An ack, nak or in-progress signal on a closed connection is refused
+ *  with a throw instead of being dropped silently: the copy stays unacked and the broker redelivers it. */
+function dmOnlyDelivery(m, ackWaitMs, nc) {
+    const open = (what) => {
+        if (!nc || nc.isClosed())
+            throw new Error(`DM-only ${what} refused: the connection that delivered this copy is closed; the broker will redeliver it`);
+    };
+    return {
+        ack: () => { open("ack"); m.ack(); },
+        nak: () => { open("nak"); m.nak(); },
+        durable: true,
+        redelivery: { deliveryCount: m.info.deliveryCount, ackWaitMs, working: () => { open("in-progress signal"); m.working(); } },
+    };
+}
 /** History drain keeps `m.json()` and used to throw the subject away. SPEC §5: on receive, verify
  *  `from.id` equals the subject sender; on mismatch, a missing `from`, or an unparseable delivery
  *  subject, reject and never surface. Fail closed on shape too: a stored JSON `null` or a truthy
@@ -7304,6 +7613,11 @@ function tcpDialable(server, timeoutMs) {
         socket.on("close", () => finish(false));
     });
 }
+/** Whether a failed connect was the server refusing these credentials: a server answered, so it is
+ *  up. The same errors {@link isReachable} reads as up after its own authenticated connect. */
+export function isAuthRejection(e) {
+    return e instanceof AuthorizationError || e instanceof UserAuthenticationExpiredError;
+}
 /** Whether a NATS server is *running* at `servers`. With NO creds this is a SILENT plaintext
  *  liveness check ({@link tcpInfoProbe}): it reads the server's pre-auth `INFO` greeting and closes
  *  WITHOUT authenticating, so a live broker (open OR auth — INFO precedes auth) returns true while