@cotal-ai/core 0.56.1 → 0.58.0

package/dist/endpoint.js

@@ -4,6 +4,7 @@ import { createConnection } from "node:net";
 import { connect, credsAuthenticator, headers, tokenAuthenticator, nanos, AuthorizationError, PermissionViolationError, UserAuthenticationExpiredError, NoRespondersError, RequestError, } from "@nats-io/transport-node";
 import { wsconnect } from "@nats-io/nats-core";
 import { credsClaims, credsFingerprint, credsRenewalDelayMs, idFromCreds } from "./identity.js";
+import { requireBrokerFloor } from "./broker-floor.js";
 import { inspectCredHealth } from "./provision.js";
 import { parseSecretStoreIdentity, } from "./secret-store.js";
 import { resolveService, invokeCommand, submitAndFollowGoal } from "./endpoint-invoke.js";
@@ -19,7 +20,7 @@ import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCode
 import {} from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
 import { Bucket, KvWatchInclude } from "@nats-io/kv/internal";
-import { openMembersRegistry, commitMember, tombstoneMember, activateMember, readMember, listMembers, durableEligible, StaleMembershipWrite, } from "./members.js";
+import { openMembersRegistry, commitMember, tombstoneMember, activateMember, readMember, listMembers, listLifecycleMemberChannels, durableEligible, StaleMembershipWrite, } from "./members.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";
@@ -143,6 +144,8 @@ export class CotalEndpoint extends EventEmitter {
     authExpiryReconnectTimer;
     sentinelCreds;
     tls;
+    transportPingIntervalMs;
+    transportMaxPingOut;
     heartbeatMs;
     ttlMs;
     doRegister;
@@ -483,6 +486,14 @@ export class CotalEndpoint extends EventEmitter {
         this.user = opts.user;
         this.pass = opts.pass;
         this.tls = opts.tls ?? false;
+        for (const [label, value] of [["transportPingIntervalMs", opts.transportPingIntervalMs], ["transportMaxPingOut", opts.transportMaxPingOut]]) {
+            if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0))
+                throw new Error(`EndpointOptions.${label} must be a positive safe integer`);
+        }
+        if ((opts.transportPingIntervalMs === undefined) !== (opts.transportMaxPingOut === undefined))
+            throw new Error("EndpointOptions transportPingIntervalMs and transportMaxPingOut must be configured together");
+        this.transportPingIntervalMs = opts.transportPingIntervalMs;
+        this.transportMaxPingOut = opts.transportMaxPingOut;
         // No implicit channel: an endpoint reads exactly what its caller lists. Omitted means none.
         this.channels = opts.channels ?? [];
         this.heartbeatMs = opts.heartbeatMs ?? 2000;
@@ -849,6 +860,7 @@ export class CotalEndpoint extends EventEmitter {
         CotalEndpoint.assertRenewableGeneration(candidate, this.currentCreds, delay);
         this.currentCreds = candidate;
         this.armCredsRefresh(delay);
+        this.emit("creds-adopted", credsClaims(candidate));
         return credsClaims(candidate);
     }
     /** The 75%-of-lifetime renewal timer tick: prove + adopt + swap the LIVE connection. Preflights (it
@@ -979,6 +991,8 @@ export class CotalEndpoint extends EventEmitter {
             // sub.allow=[_INBOX_<connId>.>] it stops a peer from subscribing the wildcard inbox to sniff
             // others' DM deliveries. Set unconditionally so the prefix can never drift from the ACL.
             inboxPrefix: `_INBOX_${this.connId}`,
+            ...(this.transportPingIntervalMs === undefined ? {} : { pingInterval: this.transportPingIntervalMs }),
+            ...(this.transportMaxPingOut === undefined ? {} : { maxPingOut: this.transportMaxPingOut }),
             // The bearer rides a GETTER: nats.js re-evaluates the token authenticator per (re)connect
             // attempt, so internal reconnects present whatever refreshBearer last fetched.
             // Creds ALWAYS ride the CHECKED getter, renewed or static, so every attempt — including the
@@ -992,6 +1006,9 @@ export class CotalEndpoint extends EventEmitter {
             // instead. Anonymous access stays reachable the only way it should be: by passing no creds.
             ...authOpts({ token: this.token, user: this.user, pass: this.pass, creds: this.currentCreds !== undefined || this.credsSource ? () => this.credsForWire() : undefined, bearer: this.userMode ? () => this.currentBearer : undefined, sentinelCreds: this.sentinelCreds, tls: this.tls }),
         });
+        // SPEC §13.12: the control surface requires nats-server >= 2.12; this runs on every
+        // fresh connection, including the reconnects the library performs on its own here.
+        requireBrokerFloor(this.nc);
         this.armAuthExpiryReconnectFence(this.nc);
         this.watchStatus();
         this.js = jetstream(this.nc);
@@ -1759,6 +1776,14 @@ export class CotalEndpoint extends EventEmitter {
     }
     /** Unicast: direct message to one specific instance. */
     async unicast(instanceId, text, opts) {
+        const { msg } = await this.unicastAttributed(instanceId, text, opts);
+        return msg;
+    }
+    /** Unicast, returning the JetStream publish ack alongside the message: the only truthful proof
+     *  a sender has is that the broker stored the message at a sequence, never that anyone read it. */
+    async unicastAttributed(instanceId, text, opts) {
+        if (!this.js)
+            throw new Error(this.notLiveMsg());
         const msg = {
             id: randomUUID(),
             ts: Date.now(),
@@ -1774,8 +1799,11 @@ export class CotalEndpoint extends EventEmitter {
         const recip = parsePrincipalKey(instanceId);
         if (!recip)
             throw new Error(`unicast: "${instanceId}" is not a valid recipient principal <owner>.<actor>`);
-        await this.publishMsg(unicastSubject(this.space, recip.owner, recip.actor, this.owner, this.actor), msg);
-        return msg;
+        assertPartsSerializable(msg.parts);
+        // Publish DIRECTLY rather than through publishMsg, the way multicastExpecting does: this path
+        // must read the ack, and publishMsg deliberately discards it.
+        const ack = await this.js.publish(unicastSubject(this.space, recip.owner, recip.actor, this.owner, this.actor), JSON.stringify(msg), { msgID: msg.id });
+        return { msg, ack: { seq: ack.seq, duplicate: ack.duplicate === true } };
     }
     /** Anycast: deliver to ANY one instance of a service (role) — queue-group load balancing. */
     async anycast(service, text, opts) {
@@ -2233,17 +2261,23 @@ export class CotalEndpoint extends EventEmitter {
     /** Overlay the host's live model and optional variant onto the card's display-only metadata, then
      *  republish presence. For connectors that learn their actual selection only after launch (e.g.
      *  Claude Code's `SessionStart` hook). The mutated card is read live by every later publish, so even
-     *  a pre-connect call surfaces on the first presence write. */
-    async setCardModel(model, variant) {
+     *  a pre-connect call surfaces on the first presence write. `provider` is the effective provider
+     *  the connector reported serving the model; when omitted an existing `meta.provider` is left
+     *  untouched (unlike `variant`, it is never deleted, since a caller that does not know the
+     *  provider says nothing about whether one still applies). */
+    async setCardModel(model, variant, provider) {
         const m = model.trim();
         const v = variant?.trim();
-        if (!m || (this.card.meta?.model === m && this.card.meta.variant === v))
+        const p = provider?.trim();
+        if (!m || (this.card.meta?.model === m && this.card.meta.variant === v && (p === undefined || this.card.meta?.provider === p)))
             return;
         const meta = { ...(this.card.meta ?? {}), model: m };
         if (v)
             meta.variant = v;
         else
             delete meta.variant;
+        if (p)
+            meta.provider = p;
         this.card.meta = meta;
         await this.publishPresence();
     }
@@ -3988,7 +4022,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, principalLiveness: opts.principalLiveness, reloadStoreIdentity: opts.reloadStoreIdentity };
+        this.plane3 = { aclFor, reloadMembershipCreds: opts.reloadMembershipCreds, evictPrincipal: opts.evictPrincipal, planeConnLiveness: opts.planeConnLiveness, principalLiveness: opts.principalLiveness, reloadStoreIdentity: opts.reloadStoreIdentity, onDeliveryCredsAdopted: opts.onDeliveryCredsAdopted };
         await this.armPlane3();
     }
     /** Serve one runtime durable-membership control request (the server-side delivery daemon). The caller
@@ -4388,8 +4422,10 @@ export class CotalEndpoint extends EventEmitter {
             // Arm the resident wire swap ONLY now — after BOTH proofs settled, right before the reply is
             // returned+responded — so a slow membership proof can never let the delivery reconnect strand
             // this reply. Only when delivery actually adopted a new candidate (currentCreds was updated).
-            if (delivery.ok)
+            if (delivery.ok) {
+                this.plane3?.onDeliveryCredsAdopted?.();
                 this.scheduleResidentSwap();
+            }
             return failures.length
                 ? { ok: false, error: failures.join("; "), data: { delivery, membership } }
                 : { ok: true, data: { delivery, membership } };
@@ -4425,6 +4461,29 @@ export class CotalEndpoint extends EventEmitter {
                 return { ok: false, error: e.message };
             }
         }
+        if (req.op === "lifecycleMemberships") {
+            // The terminal teardown's membership INVENTORY: a complete, read-only, lifecycle-exact listing
+            // of one principal's durable membership rows (tombstones included) from the trusted daemon that
+            // owns the members bucket. The caller deletes only the exact keys it gets back, through its
+            // target-pinned deprovisioner grant; this verb deletes nothing and returns no other lifecycle.
+            const principal = typeof req.args?.principal === "string" ? req.args.principal.trim() : "";
+            const uid = typeof req.args?.lifecycleUid === "string" ? req.args.lifecycleUid : "";
+            if (!parsePrincipalKey(principal))
+                return { ok: false, error: "lifecycleMemberships: a principal (owner.actor dot-form) is required" };
+            try {
+                assertLifecycleToken(uid);
+            }
+            catch (e) {
+                return { ok: false, error: `lifecycleMemberships: ${e.message}` };
+            }
+            try {
+                const channels = await listLifecycleMemberChannels(await this.membersRegistry(), principal, uid);
+                return { ok: true, data: { complete: true, channels } };
+            }
+            catch (e) {
+                return { ok: false, error: `lifecycleMemberships: the inventory read did not complete (${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