@cotal-ai/core 0.50.1 → 0.51.0

package/dist/endpoint.js

@@ -249,6 +249,11 @@ export class CotalEndpoint extends EventEmitter {
     presenceRebindAt = 0;
     status = "idle";
     activity;
+    condition;
+    /** Advances on every condition change so an older in-flight put cannot be the final KV state. */
+    conditionRevision = 0;
+    /** Read once at construction. Core publishes this opaque provider reference and never parses it. */
+    environment;
     /** Mirror of the connector's authoritative attention state, published in presence (advisory). The
      *  endpoint never reads these back into delivery — they exist only to broadcast. */
     attentionMode;
@@ -300,6 +305,8 @@ export class CotalEndpoint extends EventEmitter {
      *  only evidence the split rate exists. Always on, never behind a flag — a counter you have to
      *  enable is not there when the thing you needed it for happened. */
     splitsRecovered = 0;
+    /** Presence rows rejected because their embedded id did not match the ACL-scoped KV key. */
+    presenceBindingDrops = 0;
     /** 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() {
@@ -310,6 +317,10 @@ export class CotalEndpoint extends EventEmitter {
     get splitRecoveryCount() {
         return this.splitsRecovered;
     }
+    /** Mis-keyed presence rows this reader rejected. The warning event may be missed; the count cannot. */
+    get presenceBindingDropCount() {
+        return this.presenceBindingDrops;
+    }
     /** 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) {
@@ -419,6 +430,7 @@ export class CotalEndpoint extends EventEmitter {
         // principalKey validates both tokens.
         const principal = principalKey(this.owner, this.actor);
         this.card = { ...opts.card, id: principal.key, owner: this.owner, actor: this.actor };
+        this.environment = process.env.COTAL_ENVIRONMENT?.trim() || undefined;
         this.servers = opts.servers ?? DEFAULT_SERVER;
         this.token = opts.token;
         this.user = opts.user;
@@ -1189,6 +1201,10 @@ export class CotalEndpoint extends EventEmitter {
         this.subs.length = 0;
         if (!failedNc)
             return;
+        // The old status iterator is stale after nc is cleared, so its close cannot report this edge.
+        // As in doRebuild, teardown itself must announce the no-nc window before closing the socket.
+        this.emit("transport", { connected: false });
+        this.emit("connection", { connected: false });
         // Layered teardown, comments kept OUT of the code span below on purpose: the mutation fixture
         // bin/smoke/mutations/failed-bind-cleanup.json anchors on that span verbatim and the fixture
         // census (bin/smoke/mutation-fixtures.smoke.ts) reddens an anchor that crosses a comment line.
@@ -2057,6 +2073,12 @@ export class CotalEndpoint extends EventEmitter {
         this.status = status;
         await this.publishPresence();
     }
+    /** Publish a harness-reported condition, or clear it. Core stores the relay without interpretation. */
+    async setCondition(condition) {
+        this.condition = condition ?? undefined;
+        this.conditionRevision++;
+        await this.publishPresence();
+    }
     /** Publish the agent's global attention mode into presence (advisory observability). Mirror only —
      *  delivery decisions stay in the connector's authoritative state. */
     async setAttention(attention) {
@@ -5148,6 +5170,8 @@ export class CotalEndpoint extends EventEmitter {
             // omitted only where the endpoint has none (a pure operator/daemon connection never registers).
             ...(this.ownLifecycleUid !== undefined ? { lifecycleUid: this.ownLifecycleUid } : {}),
             status: this.status,
+            condition: this.condition,
+            environment: this.environment,
             activity: this.activity,
             attention: this.attentionMode,
             channelModes: this.channelModes,
@@ -5164,6 +5188,7 @@ export class CotalEndpoint extends EventEmitter {
         // it, a heartbeat put (default 2s) whose ~5s JetStream timeout elapses after a rebuild plants a
         // refusal on the connection that just published successfully.
         const epoch = this.presenceEpoch;
+        const conditionRevision = this.conditionRevision;
         try {
             await this.kv.put(this.card.id, JSON.stringify(record));
         }
@@ -5188,6 +5213,13 @@ export class CotalEndpoint extends EventEmitter {
         // the record with a fresh `since`. Tracked in #1461, not repaired here.
         if (epoch !== this.presenceEpoch || this.stopped)
             return;
+        // Presence writes may overlap. If this put carried an older condition, repair the KV with the
+        // latest local state before returning so a late failure publish cannot resurrect after a new
+        // turn cleared it. The revision is condition-specific; unrelated heartbeat overlap is unchanged.
+        if (conditionRevision !== this.conditionRevision) {
+            await this.publishPresence();
+            return;
+        }
         this.clearPresenceWriteFailure();
     }
     /** #1356: drop the presence-refusal record when the connection that OBSERVED those refusals goes
@@ -5440,8 +5472,11 @@ export class CotalEndpoint extends EventEmitter {
         // with its bucket key is forged or corrupt. Drop it rather than surface a spoofed roster identity.
         // The write-side scoping ($KV.<presenceBucket>.<own-id>) is the primary guard; this rejects a
         // mis-keyed record even if a broad writer slips one in under another agent's key.
-        if (raw.card?.id !== id)
+        if (raw.card?.id !== id) {
+            this.presenceBindingDrops++;
+            this.emitRecoverable(new Error(`dropped presence entry for key ${JSON.stringify(id)}: card.id ${JSON.stringify(raw.card?.id)} does not match its KV key`));
             return;
+        }
         const prev = this.roster.get(id);
         const stale = Date.now() - raw.ts > this.ttlMs;
         // A watch recovering from a stall replays the bucket. Those PUTs still carry the publisher's
@@ -5481,6 +5516,8 @@ export class CotalEndpoint extends EventEmitter {
             prev.lifecycleUid === p.lifecycleUid &&
             prev.status === p.status &&
             prev.activity === p.activity &&
+            sameCondition(prev.condition, p.condition) &&
+            prev.environment === p.environment &&
             prev.attention === p.attention &&
             sameChannelModes(prev.channelModes, p.channelModes)) {
             this.roster.set(id, p);
@@ -5711,6 +5748,12 @@ function sameChannelModes(a, b) {
         return false;
     return ak.every((k) => a[k] === b?.[k]);
 }
+function sameCondition(a, b) {
+    return a?.code === b?.code
+        && a?.source === b?.source
+        && a?.message === b?.message
+        && a?.since === b?.since;
+}
 function authOpts(a) {
     const tls = a.tls ? {} : undefined;
     // USER MODE: present the shared auth-account sentinel creds AND the user bearer as `auth_token` (an