@cotal-ai/core 0.16.0 → 0.18.0

package/dist/endpoint.js

@@ -4,16 +4,19 @@ import { createConnection } from "node:net";
 import { connect, credsAuthenticator, headers, tokenAuthenticator, nanos, AuthorizationError, PermissionViolationError, UserAuthenticationExpiredError, NoRespondersError, RequestError, } from "@nats-io/transport-node";
 import { credsClaims, credsFingerprint, credsRenewalDelayMs, idFromCreds } from "./identity.js";
 import { inspectCredHealth } from "./provision.js";
+import { resolveService, invokeCommand, submitAndFollowGoal } from "./endpoint-invoke.js";
+import { EpEnvelopeError } from "./endpoint-envelope.js";
 import { liveKvEntries } from "./kv-scan.js";
+import { ARTIFACT_PART_KIND, isArtifactPart } from "./artifact.js";
 import { assertValidName } from "./resolve.js";
 import { createSpaceStreams, dmDurableConfig, dlvDurableConfig, taskDurableConfig, fanoutDurableConfig, inboxReaderConfig, MAX_MSGS_PER_SUBJECT, MANAGER_LEASE_TTL_MS } from "./streams.js";
 import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, } from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
 import { openMembersRegistry, commitMember, tombstoneMember, activateMember, readMember, listMembers, durableEligible, StaleMembershipWrite, } from "./members.js";
-import { openAclRegistry, readAcl, readAclForAlias, AmbiguousAclAlias, commitAcl as writeAclRecord } from "./acls.js";
+import { openAclRegistry, readAcl, readAclForAlias, AmbiguousAclAlias, commitAcl as writeAclRecord, reissueAcl as writeAclReissue } from "./acls.js";
 import { openDeliveryRegistry } from "./lease.js";
 import { openChannelRegistry, effectiveReplay, effectiveReplayWindowMs, effectiveDeliveryClass, readChannelConfig, readChannelDefaults, } from "./channels.js";
-import { anycastSubject, CHANNEL_DEFAULTS_KEY, chatStream, chatHistDurable, chatSubject, controlServiceSubject, CONTROL_SELF_SERVICE, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, dlvStream, dlvDurable, dlvSubject, dinboxSubject, inboxStream, parseDinboxPrincipal, FANOUT_DURABLE, INBOX_READER_DURABLE, leaseKey, managerBucket, MANAGER_LEASE_KEY, chatWildcard, assertValidChannel, channelInAllow, isConcreteChannel, normalizeMentions, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, membershipBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
+import { anycastSubject, CHANNEL_DEFAULTS_KEY, chatStream, chatHistDurable, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, dlvStream, dlvDurable, dlvSubject, dinboxSubject, inboxStream, parseDinboxPrincipal, FANOUT_DURABLE, INBOX_READER_DURABLE, leaseKey, managerBucket, MANAGER_LEASE_KEY, managerLeaseKey, chatWildcard, assertValidChannel, channelInAllow, isConcreteChannel, normalizeMentions, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, membershipBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
 export const DEFAULT_SERVER = "nats://127.0.0.1:4222";
 const PLANE3_FRAME_HEADER = "Cotal-Delivery-Frame";
 /** Space joined when none is given on the CLI (the `cotal-<space>` cmux tab, etc.). */
@@ -34,6 +37,33 @@ export const DEFAULT_SPACE = "main";
  *  (unknown owner) or DELIVER transfer is `term()`d + surfaced after this many redeliveries, so one
  *  stuck/poison entry can't head-of-line the single shared reader forever. */
 const READER_MAX_REDELIVERIES = 10;
+/** Page size for the mediated history read when the caller names none — matches `channelHistory`'s
+ *  own default, since the mediated read exists to be a drop-in for it. */
+const READ_HISTORY_DEFAULT_LIMIT = 100;
+/** Hard server-side ceiling on one mediated page. The caller PROPOSES a limit and the mediator
+ *  decides: the reader is pooled and privileged, so an unbounded caller-chosen limit would let one
+ *  request pull a channel's whole retained set through it. Clamped, not refused — a UI asking for
+ *  more than a page should get a page, and `complete: false` already tells it more remains. */
+const READ_HISTORY_MAX_LIMIT = 200;
+/** The NEWEST prefix-from-the-end of `items` whose serialized size fits `budget` bytes, order
+ *  preserved. Returns `[]` when not even the newest single message fits — the caller must refuse
+ *  loudly there rather than serve an empty page, which would read as "no history".
+ *
+ *  Measured in ENCODED bytes, not `string.length`: a page of multi-byte text would otherwise be
+ *  undercounted and still overflow the broker. Same discipline as `assertFactFits`. */
+export function fitHistoryPage(items, budget) {
+    const enc = new TextEncoder();
+    let used = 2; // the enclosing `[]`
+    let first = items.length; // index of the oldest kept item
+    for (let i = items.length - 1; i >= 0; i--) {
+        const size = enc.encode(JSON.stringify(items[i])).length + 1; // + the `,` separator
+        if (used + size > budget)
+            break;
+        used += size;
+        first = i;
+    }
+    return first === items.length ? [] : items.slice(first);
+}
 export class CotalEndpoint extends EventEmitter {
     card;
     space;
@@ -171,6 +201,14 @@ export class CotalEndpoint extends EventEmitter {
     actor;
     /** This incarnation's lifecycle UID (opts.lifecycleUid) — see {@link EndpointOptions.lifecycleUid}. */
     ownLifecycleUid;
+    /** Per-endpoint-name {@link resolveService} cache for {@link invokeService} — dropped on a
+     *  `failed-precondition` currency refusal (the described incarnation was superseded). */
+    resolvedServices = new Map();
+    /** This endpoint's wire principal (owner + actor tokens, §13.2) — what its minted grant rows
+     *  pin. Public so a caller can build owner-mode target blocks for {@link invokeService}. */
+    get principal() {
+        return { owner: this.owner, actor: this.actor };
+    }
     /** The endpoint's own lifecycle UID, REQUIRED for every lifecycle-keyed messaging resource; absent
      *  ⇒ loud refusal naming the operation (the hard cut of SPEC §13.1 — no alias-keyed fallback). */
     requireLifecycleUid(what) {
@@ -1022,6 +1060,55 @@ export class CotalEndpoint extends EventEmitter {
         const m = await this.nc.request(reqSubject, JSON.stringify(body), { timeout: timeoutMs, noMux: true, reply });
         return m.json();
     }
+    /** This endpoint's v0.4 caller triple (§13.2) — the identity its minted ep-rail rows pin. The
+     *  owner/actor principal is mode-correct by construction (static: DEV_OWNER + the connection
+     *  identity; user mode: the bearer's callout-derived pair — 1c.2c), and the lifecycle UID is the
+     *  launcher-supplied incarnation the rows are keyed on (ledger-consistent: the §13.1 presence
+     *  lifecycle-proof refuses a divergent uid before any publish). */
+    serviceCaller() {
+        return { owner: this.owner, actor: this.actor, uid: this.requireLifecycleUid("invokeService") };
+    }
+    /** GENERIC v0.4 service invoke over this endpoint's own connection (P2 item 1, 1c.2b): resolve
+     *  the named endpoint's registered surface — describe, §13.7 store fetch, digest-verified
+     *  recompile ({@link resolveService}; cached per endpoint name) — and invoke one command. The
+     *  resolve is describe-bound currency: when a DIFFERENT instance answers a later invoke
+     *  (`failed-precondition`, a restart/supersede), the cache is dropped and resolved ONCE more
+     *  against the current incarnation. Errors from the responder come back structurally on the
+     *  attributed reply (`reply.ok === false`); transport/validation refusals throw
+     *  {@link EpEnvelopeError}. */
+    async invokeService(endpoint, command, args, opts = {}) {
+        if (!this.nc)
+            throw new Error(this.notLiveMsg());
+        const nc = this.nc;
+        const caller = this.serviceCaller();
+        const resolve = async () => {
+            const cached = this.resolvedServices.get(endpoint);
+            if (cached)
+                return cached;
+            const svc = await resolveService(nc, this.space, endpoint, caller, { deadlineMs: opts.deadlineMs ?? 10_000 });
+            this.resolvedServices.set(endpoint, svc);
+            return svc;
+        };
+        const invokeOpts = { ...(opts.target ? { target: opts.target } : {}), ...(opts.deadlineMs !== undefined ? { deadlineMs: opts.deadlineMs } : {}) };
+        const doInvoke = async () => {
+            try {
+                return await invokeCommand(nc, this.space, await resolve(), command, args, invokeOpts);
+            }
+            catch (e) {
+                if (!(e instanceof EpEnvelopeError) || e.code !== "failed-precondition")
+                    throw e;
+                // The describe-bound incarnation is gone (restart/supersede) — re-resolve once, then invoke
+                // against the CURRENT one; a second failure is the real state and throws.
+                this.resolvedServices.delete(endpoint);
+                return await invokeCommand(nc, this.space, await resolve(), command, args, invokeOpts);
+            }
+        };
+        // P2 item 2 (2b): a goal-bearing command (spawn/launch) follows its acceptance to the terminal so
+        // the caller still returns on the real outcome (UX unchanged); every other command replies directly.
+        if (!opts.follow)
+            return doInvoke();
+        return submitAndFollowGoal(nc, this.space, endpoint, caller, opts.deadlineMs ?? 10_000, doInvoke);
+    }
     /** Send a durable-membership request to the SERVER-SIDE delivery daemon (`ctl.delivery`) and await its
      *  reply. Unlike {@link requestControl}, the reply rides a subject UNDER `ctl.delivery.<id>.>` (not the
      *  per-id `_INBOX`), so the scoped delivery cred can answer without broad inbox-publish — see
@@ -1368,6 +1455,45 @@ export class CotalEndpoint extends EventEmitter {
         // history from any sender
         return this.streamHistory(chatStream(this.space), chatSubject(this.space, "*", "*", channel), opts?.limit ?? 100);
     }
+    /** 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}
+     *  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
+     *  older history remains behind it.
+     *
+     *  **Why this exists when `channelHistory` already works:** authorization. A consumer pins its
+     *  authorization at CREATE time, so a caller whose read ACL is revoked mid-scroll keeps being served
+     *  by the consumer it already holds. The mediator re-reads authorization on EVERY call (live
+     *  registry row ∩ mint-time ceiling — SPEC §9.6), so a revocation stops the very next read and a
+     *  registry-only widen cannot exceed the effective credential. That is the whole point of the verb;
+     *  a mediator that cached the ACL would be a rename of the path it replaces.
+     *
+     *  **The caller never names itself.** The daemon takes the principal from the broker-authenticated
+     *  request subject ({@link serveControl} fail-closes when the payload `from` disagrees), so there is
+     *  no caller-supplied identity to forge.
+     *
+     *  A channel outside the caller's read ACL THROWS. It must never come back as an empty page: "you
+     *  may not read this" and "there is nothing here" are different answers and only one is safe to
+     *  render as an empty conversation.
+     *
+     *  Chat channels only — DM history is deliberately not served here (it is god-view-only today, a
+     *  different authorization model, and one handler with two authz paths is the wrong shape on the
+     *  surface where a mistake exposes private messages). */
+    async readHistory(channel, opts) {
+        const reply = await this.requestDelivery("readHistory", { channel, limit: opts?.limit });
+        if (!reply.ok)
+            throw new Error(reply.error ?? "readHistory failed");
+        const data = reply.data;
+        // Validate rather than coerce. A malformed reply must not be massaged into a plausible page:
+        // defaulting `complete` would invent the very signal a caller uses to decide whether it is
+        // looking at the start of a conversation.
+        if (!Array.isArray(data?.items) || typeof data?.complete !== "boolean")
+            throw new Error("readHistory: the delivery daemon returned a malformed page (expected { items, complete })");
+        return { items: data.items, complete: data.complete };
+    }
     /** Fetch recent DMs (any sender→any recipient) from the space's DM backlog. God-view only:
      *  a normal agent/observer's ACL denies CONSUMER.CREATE on DM_<space>, so this throws-and-
      *  skips for them — only an `admin`-profile cred can read it. */
@@ -1700,6 +1826,14 @@ export class CotalEndpoint extends EventEmitter {
     async commitAcl(targetId, lifecycleUid, allowSubscribe) {
         await writeAclRecord(await this.aclRegistry(), targetId, lifecycleUid, allowSubscribe);
     }
+    /**
+     * Raise the mint-time ACL ceiling. Provision/remint only — see {@link reissueAcl}.
+     * Process discipline: call only in the same act that bakes `allowSubscribe` into the JWT; the
+     * write is not crypto-bound to credential bytes.
+     */
+    async reissueAcl(targetId, lifecycleUid, allowSubscribe) {
+        await writeAclReissue(await this.aclRegistry(), targetId, lifecycleUid, allowSubscribe);
+    }
     /** The server-side delivery daemon's fresh-per-entry ACL read: one LIFECYCLE's current read ACL
      *  (`allowSubscribe`) from the durable registry (exact key `<owner>.<actor>.<uid>`), or `undefined`
      *  if no record (an unknown lifecycle — the reader DEFERS, never drops). A present `[]` (known
@@ -1713,7 +1847,13 @@ export class CotalEndpoint extends EventEmitter {
      *  authorize the successor (SPEC 13.1: at most one live lifecycle per alias). */
     async aclForAlias(principal) {
         const row = await readAclForAlias(await this.aclRegistry(), principal);
-        return row === undefined ? undefined : { allowSubscribe: row.record.allowSubscribe, lifecycleUid: row.lifecycleUid };
+        if (row === undefined)
+            return undefined;
+        const allow = row.record.allowSubscribe;
+        // Legacy rows predate the ceiling field: treat missing as equal to allowSubscribe so behaviour
+        // matches what that row already exposed. New rows always carry an explicit ceiling.
+        const issued = row.record.issuedAllowSubscribe ?? allow;
+        return { allowSubscribe: allow, issuedAllowSubscribe: issued, lifecycleUid: row.lifecycleUid };
     }
     /** Lazily open the delivery lease/readiness KV (pre-created at `cotal up`; bind, never create). */
     async deliveryRegistry() {
@@ -1798,44 +1938,97 @@ export class CotalEndpoint extends EventEmitter {
     encodeManagerLease(info) {
         return new TextEncoder().encode(JSON.stringify(info));
     }
-    /** Acquire the singleton manager lease via ATOMIC CAS create. THROWS if a live lease exists (a loud
-     *  refusal-to-start, never a retry) so two managers never split control. A crashed holder's lease
-     *  auto-expires (bucket TTL). Returns the lease revision (for renew). */
+    /** Acquire THIS logical instance's liveness lease via ATOMIC CAS create on its own per-instance key
+     *  ({@link managerLeaseKey}). THROWS only if that SAME instance id already holds a live key (a same-root
+     *  concurrent double-start, or a restart racing the crashed predecessor's not-yet-expired key) — a loud
+     *  refusal, never a retry. A DIFFERENT instance (second workspace root ⇒ different id) creates its OWN
+     *  key and coexists (P2 item 3 demotion). A crashed holder's key auto-expires (bucket TTL). Returns the
+     *  lease revision (for renew). */
     async acquireManagerLease(info) {
-        return (await this.managerLeaseRegistry()).create(MANAGER_LEASE_KEY, this.encodeManagerLease({ ...info, since: Date.now() }));
+        return (await this.managerLeaseRegistry()).create(managerLeaseKey(info.instanceId), this.encodeManagerLease({ ...info, since: Date.now() }));
     }
-    /** Renew the held lease (CAS update against `revision`) before the bucket TTL expires it. Throws if the
-     *  revision moved (lost the lease). Returns the new revision. */
+    /** Renew THIS instance's held key (CAS update against `revision`) before the bucket TTL expires it.
+     *  Throws if the revision moved (lost the lease). Returns the new revision. */
     async renewManagerLease(info, revision) {
-        return (await this.managerLeaseRegistry()).update(MANAGER_LEASE_KEY, this.encodeManagerLease({ ...info, since: Date.now() }), revision);
+        return (await this.managerLeaseRegistry()).update(managerLeaseKey(info.instanceId), this.encodeManagerLease({ ...info, since: Date.now() }), revision);
     }
-    /** Release the held lease on clean shutdown so a replacement manager acquires immediately. CAS-guarded
-     *  by `revision`: if we already LOST the lease (renew gap / another manager took over) the stored
-     *  revision has moved, the conditional delete no-ops, and we never delete the replacement's live lease. */
-    async releaseManagerLease(revision) {
+    /** Release THIS instance's key on clean shutdown so a same-id restart re-acquires immediately. CAS-guarded
+     *  by `revision`: if we already LOST it (renew gap) the stored revision has moved, the conditional delete
+     *  no-ops. Keyed per instance, so a release NEVER touches a sibling manager's key (security pin 6). */
+    async releaseManagerLease(instanceId, revision) {
         try {
             const kv = await this.managerLeaseRegistry();
             if (revision === undefined)
-                await kv.delete(MANAGER_LEASE_KEY);
+                await kv.delete(managerLeaseKey(instanceId));
             else
-                await kv.delete(MANAGER_LEASE_KEY, { previousSeq: revision });
+                await kv.delete(managerLeaseKey(instanceId), { previousSeq: revision });
         }
         catch { /* not ours / already gone */ }
     }
-    /** Read the live manager lease, or undefined if none (bucket absent / key deleted/expired). Open-only —
-     *  never creates the bucket, so a probe that finds no manager leaves none behind. */
+    /** Read a live manager liveness lease, or undefined if NONE (no manager instance holds the space). A
+     *  presence/existence check for the CLI's `spawn -f` reuse and `waitLeaseGone`, which only need "is any
+     *  manager here". Open-only — never creates the bucket, so a probe that finds no manager leaves none
+     *  behind. (Instance-precise enumeration for the class scatter comes from the registration records KV
+     *  in 3b-4, not this liveness bucket.)
+     *
+     *  MULTI-INSTANCE EXACT, and it has to be read that way rather than as a point get. Several managers
+     *  may hold one space, each renewing its own `lease.<instanceId>`. A single `last_by_subj` over
+     *  `lease.*` returns the newest message under the wildcard REGARDLESS OF KEY — so a stopping peer's
+     *  DEL tombstone, being newest, answered "no manager here" while a sibling was alive and renewing.
+     *  Only an explicit `kv.delete` writes that tombstone: a manager whose lease TTL-expires is removed by
+     *  limits and leaves nothing behind, so the poisoning case was the ORDINARY one (stop a manager
+     *  cleanly, then `spawn -f`), not the crash. Enumerating live entries collapses to the greatest
+     *  revision PER KEY and drops keys whose final state is a marker, so a peer's DEL can only retire that
+     *  peer's own key and can never mask a live one. */
     async readManagerLease() {
         if (!this.nc)
             return undefined;
         try {
-            const kv = await new Kvm(this.nc).open(managerBucket(this.space));
-            const e = await kv.get(MANAGER_LEASE_KEY);
-            if (!e || e.operation === "DEL" || e.operation === "PURGE")
+            const jsm = this.jsm ?? (this.jsm = await jetstreamManager(this.nc));
+            const stream = `KV_${managerBucket(this.space)}`;
+            const prefix = `$KV.${managerBucket(this.space)}.${MANAGER_LEASE_KEY}.`;
+            // STREAM.INFO to learn WHICH instance keys exist, then one point-get per key. NOT a bucket
+            // scan: `liveKvEntries` binds a push consumer, and this principal's grant on this bucket is
+            // STREAM.INFO + STREAM.MSG.GET + the `lease.*` publish only (`provision.ts`, supervisor). A
+            // consumer here is a permissions violation for the very callers this probe serves, and no
+            // open-mesh test can see that, because an open mesh has no permissions to violate.
+            const info = await jsm.streams.info(stream, { subjects_filter: `${prefix}*` });
+            let newest;
+            for (const subject of Object.keys(info.state.subjects ?? {})) {
+                // `last_by_subj` is CORRECT PER KEY and wrong across keys. Scoped to one instance's subject
+                // it returns that instance's latest state, so a DEL here retires only its own key. The
+                // defect was asking one wildcard for the newest message in the whole subtree, where a
+                // stopping peer's tombstone outranks a live sibling's older PUT.
+                const m = await jsm.streams.getMessage(stream, { last_by_subj: subject }).catch(() => null);
+                if (m === null)
+                    continue; // key vanished between INFO and GET: it is not a live holder
+                const op = m.header?.get("KV-Operation");
+                if (op === "DEL" || op === "PURGE" || m.data.length === 0)
+                    continue;
+                if (newest === undefined || m.seq > newest.seq)
+                    newest = { data: m.data, seq: m.seq };
+            }
+            if (newest === undefined)
                 return undefined;
-            return e.json();
+            return JSON.parse(new TextDecoder().decode(newest.data));
         }
-        catch {
-            return undefined;
+        catch (e) {
+            // ABSENCE MUST BE PROVEN, NOT INFERRED FROM A FAILED READ. Exactly two outcomes mean "genuinely
+            // no manager": 10037, no message on the subtree, and a missing bucket — this probe is open-only
+            // and on an authed mesh nothing creates it until a manager first takes a lease, so a space that
+            // has never run one has no stream to read. Every OTHER failure (a JetStream hiccup, a request
+            // timeout, a permissions refusal, or `liveKvEntries` refusing a pass that died mid-delivery) used
+            // to return undefined here as well, and every caller reads undefined as "the space is empty": the
+            // CLI's `spawn -f` reuse stands a SECOND manager up against a live one and `waitLeaseGone` reports
+            // the space free. A read that failed is not evidence of absence, so refuse loudly rather than
+            // degrade (AGENTS.md: no fallbacks). This is the wider of the two doors the point-get fix closes:
+            // it needs only a transient error, where the tombstone path needed a peer to stop.
+            const code = e.code;
+            if (code === 10037)
+                return undefined;
+            if (code === 404 || /stream not found/i.test(e?.message ?? ""))
+                return undefined;
+            throw e;
         }
     }
     /** Privileged: one owner's NON-TOMBSTONED durable memberships as `{channel, generation, activated}` —
@@ -2047,7 +2240,7 @@ export class CotalEndpoint extends EventEmitter {
     async startPlane3(aclFor, opts = {}) {
         if (!this.js)
             throw new Error("endpoint not started");
-        this.plane3 = { aclFor, reloadMembershipCreds: opts.reloadMembershipCreds, evictPrincipal: opts.evictPrincipal, planeConnLiveness: opts.planeConnLiveness };
+        this.plane3 = { aclFor, reloadMembershipCreds: opts.reloadMembershipCreds, evictPrincipal: opts.evictPrincipal, planeConnLiveness: opts.planeConnLiveness, principalLiveness: opts.principalLiveness };
         await this.armPlane3();
     }
     /** Serve one runtime durable-membership control request (the server-side delivery daemon). The caller
@@ -2061,6 +2254,8 @@ export class CotalEndpoint extends EventEmitter {
             return this.deliveryJoin(caller, args);
         if (req.op === "durableLeave")
             return this.deliveryLeave(caller, args);
+        if (req.op === "readHistory")
+            return this.deliveryReadHistory(caller, args);
         if (req.op === "listMemberships") {
             if (typeof args.lifecycleUid !== "string")
                 return { ok: false, error: "listMemberships: the caller's lifecycleUid is required (membership rows are lifecycle-keyed, SPEC 13.1)" };
@@ -2157,6 +2352,107 @@ export class CotalEndpoint extends EventEmitter {
         }
         return { ok: true, data: { channel } };
     }
+    /** Serve one MEDIATED HISTORY READ (`readHistory`, the client side is {@link readHistory}). The daemon
+     *  holds the consumer so the caller does not have to: this is a privilege reduction, not a new
+     *  capability, and it is the shape SPEC's "Mediated reads (normative)" rule asks for.
+     *
+     *  THE ONE INVARIANT THIS METHOD EXISTS FOR: authorization is read FRESH on every call and never
+     *  cached across calls. A consumer pins its authorization when it is created, so a revoked caller
+     *  keeps being served by a consumer it already holds; re-reading here is what makes a revocation
+     *  stop the very NEXT read. Cache this and the verb loses its only advantage over the raw consumer
+     *  path.
+     *
+     *  AUTHORITY (SPEC §9.6): "current read ACL" is the effective broker-accepted credential. The
+     *  durable registry is a live mirror of that credential, not a second grant source. History
+     *  authorizes against `allowSubscribe ∩ issuedAllowSubscribe` — the live row (so revocation via
+     *  plain commitAcl still stops the next read) intersected with the mint-time ceiling (so a
+     *  registry widen without a remint cannot grant what the JWT does not). Raising the ceiling is
+     *  {@link reissueAcl}, which is what provision does when it bakes the list into the JWT.
+     *
+     *  The caller arrives as an alias (the control subject carries owner+actor, never a uid) and is the
+     *  AUTHENTICATED subject sender — `serveControl` has already fail-closed on any payload that names a
+     *  different principal, so `caller` cannot be self-asserted. */
+    async deliveryReadHistory(caller, args) {
+        const channel = this.checkDurableChannelArg(args, "readHistory");
+        if (typeof channel !== "string")
+            return channel; // a ControlReply error
+        // The caller PROPOSES a limit; the mediator decides. Reject a nonsense limit loudly rather than
+        // silently substituting a default — a caller asking for -1 has a bug and should hear about it.
+        const asked = args.limit === undefined ? READ_HISTORY_DEFAULT_LIMIT : args.limit;
+        if (typeof asked !== "number" || !Number.isInteger(asked) || asked < 1)
+            return { ok: false, error: `readHistory: limit must be a positive integer (got ${JSON.stringify(args.limit)})` };
+        const limit = Math.min(asked, READ_HISTORY_MAX_LIMIT);
+        // FRESH per call — see the method doc. Same registry, same alias resolution, and the same loud
+        // refusal on two live rows that `durableJoin` uses: a stale lifecycle must never authorize its
+        // successor's read.
+        //
+        // SPEC §9.6: "current read ACL" is the effective broker-accepted credential. The registry row is
+        // a live mirror and can be rewritten by plain commitAcl without a remint. Authorizing history
+        // from the row ALONE let a widen grant reads channelHistory still broker-denies — a new
+        // capability wearing a privilege-reduction label (panel BLOCKING at 914fd7b0). History therefore
+        // requires the channel in BOTH the live row AND the mint-time ceiling (`issuedAllowSubscribe`).
+        // Revocation still works: narrowing allowSubscribe stops the next read. Raising the ceiling
+        // requires reissueAcl (provision/remint), which is the same act that bakes the list into the JWT.
+        let acl;
+        try {
+            acl = await this.aclForAlias(caller);
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+        if (acl === undefined)
+            return { ok: false, error: `readHistory: no read ACL on record for ${caller} - not permitted` };
+        const inLive = channelInAllow(acl.allowSubscribe, channel);
+        const inIssued = channelInAllow(acl.issuedAllowSubscribe, channel);
+        if (!inLive || !inIssued) {
+            // Name the live list in the error — that is what operators edit and what revocation clears.
+            // A ceiling miss (registry widened past the credential) is the same refusal shape as a live
+            // miss so a caller cannot probe which half failed.
+            return {
+                ok: false,
+                error: `readHistory: channel "${channel}" is not within your read ACL [${acl.allowSubscribe.join(", ")}] - refused`,
+            };
+        }
+        // One message MORE than the page is the completeness probe: if the backlog hands back limit+1,
+        // something older exists behind the page and `complete` is false. Cheaper and more honest than a
+        // separate count, which could race the page it describes.
+        let page;
+        try {
+            page = await this.channelHistory(channel, { limit: limit + 1 });
+        }
+        catch (e) {
+            // Surface the read failure. `streamHistory` deliberately raises rather than returning empty on a
+            // denial or a cut-short window, and that distinction must survive the rail: an error here would
+            // otherwise reach the caller as an empty page and render as "no history".
+            return { ok: false, error: `readHistory: ${e.message}` };
+        }
+        const reachedStart = page.length <= limit;
+        const wanted = reachedStart ? page : page.slice(-limit);
+        // A page that cannot be SENT is not a page. The reply rides one NATS message, so `limit` alone is
+        // the wrong bound: 200 large messages serialize past `max_payload`, `m.respond` throws inside
+        // `serveControl`'s swallow, and the caller sees a bare request timeout it cannot tell apart from a
+        // dead daemon. Measured, not predicted: 200 x ~6 KB timed out at 5s with the message "timeout".
+        //
+        // So bound by BYTES too, keeping the NEWEST that fit — which needs no new vocabulary, because
+        // `complete: false` already means "older history remains behind this page". Trimming here is the
+        // documented truncation signal doing its job, not a silent degradation.
+        const fitted = fitHistoryPage(wanted, this.payloadBudget());
+        // `wanted.length > 0` is load-bearing, not defensive: an EMPTY channel also fits nothing, and
+        // without this guard a channel nobody has posted to was refused with "the newest message exceeds
+        // the payload budget" — a confident, entirely wrong explanation for a legitimately empty result.
+        // Genuine emptiness is `{ items: [], complete: true }`; only a message too large to ever send is
+        // the error.
+        if (wanted.length > 0 && fitted.length === 0)
+            return { ok: false, error: `readHistory: the newest message on "${channel}" alone exceeds the broker payload budget (${this.payloadBudget()} bytes) - refused loudly rather than served as an empty page` };
+        return { ok: true, data: { items: fitted, complete: reachedStart && fitted.length === wanted.length } };
+    }
+    /** Bytes a control reply may occupy: the broker's `max_payload` less headroom for the `ControlReply`
+     *  envelope wrapped around the items. Read from the live server info rather than assumed, since an
+     *  operator can raise or lower it. */
+    payloadBudget() {
+        const max = this.nc?.info?.max_payload ?? 1_048_576;
+        return Math.max(1, Math.floor(max * 0.9));
+    }
     /** (Re)bind the Plane-3 fan-out writer + trusted reader. Idempotent — the durables resume from their
      *  cursor. Called by {@link startPlane3} once AND by {@link connectAndBind} on every (re)connect, so
      *  the delivery daemon's reconnect RE-ARMS the backstop + the ctl.delivery responder. Without this, a broker blip would silently kill
@@ -2266,6 +2562,24 @@ export class CotalEndpoint extends EventEmitter {
                 return { ok: false, error: e.message };
             }
         }
+        if (req.op === "principalLiveness") {
+            // The freeze-holder liveness probe (#391): the READ-ONLY half of `evictPrincipal`. A repair
+            // that must REFUSE while the holder is alive cannot use eviction as its own precheck — that
+            // kills the holder before anything can refuse on its behalf. Same executor-hook shape as the
+            // verbs above (the $SYS observer cred lives outside this trust boundary); absent hook =
+            // refused loudly, and the caller maps a refusal to UNKNOWN and never repairs over it.
+            if (!this.plane3?.principalLiveness)
+                return { ok: false, error: "principalLiveness: no liveness oracle wired on this daemon" };
+            const principal = typeof req.args?.principal === "string" ? req.args.principal.trim() : "";
+            if (!principal)
+                return { ok: false, error: "principalLiveness: a principal (owner.actor dot-form) is required" };
+            try {
+                return { ok: true, data: await this.plane3.principalLiveness(principal) };
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+        }
         return { ok: false, error: `op "${req.op}" not supported on the delivery admin service` };
     }
     /** Fan-out loop: bind the privileged `fanout` durable on CHAT and route each message (routing only —
@@ -3390,6 +3704,13 @@ function isEndpointRef(value) {
     return isRecord(value) && typeof value.id === "string" && typeof value.name === "string" &&
         (value.role === undefined || typeof value.role === "string");
 }
+/** A conformant message part: the three CORE kinds, or a reverse-DNS extension kind (SPEC §5).
+ *
+ *  Reached from {@link isCotalMessage}, which gates the Plane-3 delivery frame — so a core kind
+ *  missing an arm here is not a schema nicety: the durable backstop DROPS every message carrying
+ *  it, silently, and the drop surfaces nowhere near the feature that added the part. `artifact`
+ *  was exactly that case before it was added (a bare kind has no dot, so it fell through to the
+ *  extension regex and failed). */
 function isMessagePart(value) {
     if (!isRecord(value) || typeof value.kind !== "string")
         return false;
@@ -3397,6 +3718,8 @@ function isMessagePart(value) {
         return typeof value.text === "string";
     if (value.kind === "data")
         return Object.prototype.hasOwnProperty.call(value, "data");
+    if (value.kind === ARTIFACT_PART_KIND)
+        return isArtifactPart(value);
     return /^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(value.kind);
 }
 function isRecord(value) {
@@ -3501,6 +3824,33 @@ export function isPermissionDenied(e) {
         return true;
     return /permissions?\s+violation/i.test(String(e?.message ?? ""));
 }
+/** True ONLY for a denial on a **publish** — the single case that proves the message was never
+ *  ACCEPTED or stored. (Not "never reached the server": the server necessarily received enough of
+ *  it to reject it. The distinction matters precisely here, because this helper exists to separate
+ *  provably-not-stored from possibly-stored, and the looser phrasing overstates the very thing
+ *  being measured.) {@link isPermissionDenied} deliberately does not look at the operation: it exists to
+ *  separate "denied" from "service down", and that answer is the same either way. The operation
+ *  matters enormously to a caller that reports *delivery*, because a JetStream publish is
+ *  request/PubAck and the subscription half is the reply inbox — a denial THERE rejects
+ *  `js.publish()` while the stream may already hold the message. Verified against a live broker: a
+ *  user allowed to publish but denied its `_INBOX` subscription got
+ *  `Permissions Violation for Subscription to "_INBOX.….*"` back from `js.publish()`, and an
+ *  unrestricted observer then read `messages: 1` off the stream.
+ *
+ *  Note what is deliberately NOT accepted: the untyped text fallback above. A permission-shaped
+ *  message string carries no operation, so it cannot prove non-delivery, and guessing "publish"
+ *  from wording would reintroduce exactly the false certainty this exists to prevent. Anything not
+ *  provably a publish denial is unknown, and a caller reporting delivery must fail toward
+ *  "I could not confirm" rather than toward "it did not happen" — the costly mistake is telling
+ *  someone to re-send a message that was in fact stored. */
+export function isPublishPermissionDenied(e) {
+    const typed = e instanceof PermissionViolationError
+        ? e
+        : e?.cause instanceof PermissionViolationError
+            ? (e.cause)
+            : undefined;
+    return typed?.operation === "publish";
+}
 /** Parse a NATS server URL (`nats://host:port`, `host:port`, a bare host, or a comma list — the
  *  first entry wins) into a host+port for {@link tcpInfoProbe}. Defaults the port to 4222. */
 function hostPort(server) {
@@ -3568,6 +3918,51 @@ function tcpInfoProbe(server, timeoutMs) {
         socket.on("close", () => finish(false)); // closed before a full INFO line arrived
     });
 }
+/** Bounded TCP reachability on a socket we OWN: does a handshake to `server` complete within
+ *  `timeoutMs`? Deliberately narrower than {@link tcpInfoProbe} — it asks only whether the
+ *  transport can be reached, never whether NATS is speaking there, so the TLS-first listener that
+ *  `tcpInfoProbe` reports false for still passes this gate and goes on to a real connect.
+ *
+ *  It exists because `connect()` cannot be trusted to release a connection it never established.
+ *  `@nats-io/transport-node`'s `NodeTransport.dial()` keeps its socket in a local until the
+ *  handshake resolves (`this.socket = await this.dial(hp)`), so `this.socket` is STILL UNDEFINED
+ *  when the client's own connect timeout wins the race in `protocol.ts`'s `dial` and the catch
+ *  calls `transport.close()` — whose teardown is `this.socket?.destroy()`, i.e. a destroy of
+ *  nothing. Against an address that BLACKHOLES (SYN unanswered) rather than REFUSES (RST), the
+ *  socket is orphaned in libuv until the OS SYN timeout, and the process cannot exit for minutes
+ *  after the probe already returned its answer. That is issue #389, and it is upstream: nothing a
+ *  caller passes (`reconnect: false`, `timeout`) reaches the orphan. Our socket, our `destroy()`,
+ *  on every exit path — never an `unref`/force-exit, which would hide the symptom and a future
+ *  real hang with it. */
+function tcpDialable(server, timeoutMs) {
+    return new Promise((resolve) => {
+        let socket;
+        let done = false;
+        const finish = (dialable) => {
+            if (done)
+                return;
+            done = true;
+            try {
+                socket?.destroy();
+            }
+            catch { /* already gone */ }
+            resolve(dialable);
+        };
+        let host, port;
+        try {
+            ({ host, port } = hostPort(server));
+        }
+        catch {
+            return resolve(false);
+        }
+        socket = createConnection({ host, port });
+        socket.setTimeout(timeoutMs);
+        socket.on("connect", () => finish(true));
+        socket.on("timeout", () => finish(false)); // blackhole: SYN unanswered inside our deadline
+        socket.on("error", () => finish(false)); // refused / reset / DNS failure
+        socket.on("close", () => finish(false));
+    });
+}
 /** 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
@@ -3577,12 +3972,22 @@ function tcpInfoProbe(server, timeoutMs) {
  *  refuses these creds is still up — so the caller surfaces the real auth failure, and `up` won't
  *  start a duplicate on the bound port). Only a genuine connection failure (refused/timeout) is false. */
 export async function isReachable(servers = DEFAULT_SERVER, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 1000;
     if (!opts.creds && !opts.token && !opts.user && !opts.pass && !opts.tls)
-        return tcpInfoProbe(servers, opts.timeoutMs ?? 1000);
+        return tcpInfoProbe(servers, timeoutMs);
+    // The credless branch above already owns its socket. This one reaches `connect()`, so it carries
+    // the same orphaned-socket defect probeConnect did (#389) and takes the same gate: reach the
+    // address on a socket we own first, and give `connect()` the remainder of the budget its own
+    // timeout always covered. A gate failure is a genuine connection failure, which is exactly the
+    // `false` the catch below already returns for one — an auth rejection cannot reach us from an
+    // address that never completed a handshake.
+    const started = Date.now();
+    if (!(await tcpDialable(servers, timeoutMs)))
+        return false;
     try {
         const nc = await connect({
             servers,
-            timeout: opts.timeoutMs ?? 1000,
+            timeout: Math.max(1, timeoutMs - (Date.now() - started)),
             reconnect: false,
             maxReconnectAttempts: 0,
             ...authOpts(opts),
@@ -3600,10 +4005,22 @@ export async function isReachable(servers = DEFAULT_SERVER, opts = {}) {
  *  specific identity is accepted (`ok`); omit them to probe mere liveness (an auth broker answers
  *  `auth-required`, which still proves it's up). */
 export async function probeConnect(server = DEFAULT_SERVER, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 1000;
+    const started = Date.now();
+    // Reach the address on a socket we own BEFORE handing it to `connect()`, which orphans the
+    // connection it never established (see {@link tcpDialable} for the upstream mechanism, #389).
+    // This cannot change any verdict: every address that gets past here had to complete a TCP
+    // handshake for `connect()` to have gotten anywhere either, and a gate failure is routed through
+    // the SAME classification the catch uses — so a locally-dead cred is still `stale-auth` and not
+    // silently downgraded to `unreachable` by the address being dark. The cost is one extra
+    // handshake on the reachable path; the deadline below is the REMAINDER of the budget, because
+    // `connect()`'s own `timeout` always covered its handshake too.
+    if (!(await tcpDialable(server, timeoutMs)))
+        return classifyProbeFailure(undefined, opts);
     try {
         const nc = await connect({
             servers: server,
-            timeout: opts.timeoutMs ?? 1000,
+            timeout: Math.max(1, timeoutMs - (Date.now() - started)),
             reconnect: false,
             maxReconnectAttempts: 0,
             ...authOpts(opts),
@@ -3612,26 +4029,33 @@ export async function probeConnect(server = DEFAULT_SERVER, opts = {}) {
         return { ok: true };
     }
     catch (e) {
-        // A presented cred that is PROVABLY expired by its own JWT is stale-auth (credential death) —
-        // and that is knowable LOCALLY, without the network, so it is decided FIRST, before the error
-        // type. On the wire the broker's rejection and the socket close race: a slow CI/Windows handshake
-        // can surface a bare transport failure (→ "unreachable") instead of a clean AuthorizationError,
-        // which used to misclassify a dead cred. Reading the cred removes that timing dependency entirely,
-        // so the classification is deterministic. Unreadable content falls through to the wire truth (no
-        // false stale diagnosis from garbage).
-        if (typeof opts.creds === "string") {
-            try {
-                if (inspectCredHealth(opts.creds).state === "expired")
-                    return { ok: false, reason: "stale-auth" };
-            }
-            catch { /* not introspectable — keep the wire truth */ }
+        return classifyProbeFailure(e, opts);
+    }
+}
+/** Why a {@link probeConnect} attempt did not end in `ok`. Shared by the pre-connect reachability
+ *  gate and the connect catch so both classify identically — the gate must never turn a diagnosable
+ *  credential death into a bare `unreachable` just because the address went dark.
+ *
+ *  A presented cred that is PROVABLY expired by its own JWT is stale-auth (credential death) — and
+ *  that is knowable LOCALLY, without the network, so it is decided FIRST, before the error type. On
+ *  the wire the broker's rejection and the socket close race: a slow CI/Windows handshake can
+ *  surface a bare transport failure (→ "unreachable") instead of a clean AuthorizationError, which
+ *  used to misclassify a dead cred. Reading the cred removes that timing dependency entirely, so the
+ *  classification is deterministic. Unreadable content falls through to the wire truth (no false
+ *  stale diagnosis from garbage). `e` is undefined when the gate refused before any connect. */
+function classifyProbeFailure(e, opts) {
+    if (typeof opts.creds === "string") {
+        try {
+            if (inspectCredHealth(opts.creds).state === "expired")
+                return { ok: false, reason: "stale-auth" };
         }
-        if (e instanceof UserAuthenticationExpiredError)
-            return { ok: false, reason: "stale-auth" };
-        // The broker answered but rejected these creds (so it IS up) — auth-required, not stale-auth.
-        if (e instanceof AuthorizationError)
-            return { ok: false, reason: "auth-required" };
-        return { ok: false, reason: "unreachable" };
+        catch { /* not introspectable — keep the wire truth */ }
     }
+    if (e instanceof UserAuthenticationExpiredError)
+        return { ok: false, reason: "stale-auth" };
+    // The broker answered but rejected these creds (so it IS up) — auth-required, not stale-auth.
+    if (e instanceof AuthorizationError)
+        return { ok: false, reason: "auth-required" };
+    return { ok: false, reason: "unreachable" };
 }
 //# sourceMappingURL=endpoint.js.map