@cotal-ai/core 0.50.1 → 0.52.0

package/dist/endpoint.js

@@ -141,6 +141,10 @@ export class CotalEndpoint extends EventEmitter {
      *  `DrainingConnectionError` out of `reset()` on a timer nothing awaits. */
     presenceWatchIter;
     channelWatchIter;
+    /** The daemon's lease-loss watch (#1596): the INTENT that survives a connection rebuild, plus the
+     *  live iterator. See {@link watchDeliveryLease}. */
+    leaseWatchIntent;
+    leaseWatchIter;
     /** Plane-3 durable-membership registry KV — lazily opened by the privileged delivery daemon (or a
      *  short-lived provisioner). */
     membersKv;
@@ -221,6 +225,14 @@ export class CotalEndpoint extends EventEmitter {
     presenceWriteFailingSince;
     /** #1356: the broker's last refusal message, kept alongside the start time for diagnosis. */
     lastPresenceWriteError;
+    /** #1461: monotonic per-put generation on the presence path, so a settle can tell whether it is
+     *  the latest evidence on its epoch. {@link publishPresence} snapshots it at put start and every
+     * settle records its generation here: a settle is the latest evidence only while no put that
+     * started after it has already settled. */
+    presencePutGeneration = 0;
+    /** #1461: the generation of the newest presence put that has SETTLED (succeeded or rejected),
+     * or `undefined` when none ever has. A put that is merely in flight is not evidence yet. */
+    presencePutSettled;
     roster = new Map();
     /** Resolves when the current presence watch has consumed its complete initial KV snapshot. */
     presenceSnapshot = Promise.resolve();
@@ -249,6 +261,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 +317,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 +329,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 +442,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;
@@ -971,6 +995,12 @@ export class CotalEndpoint extends EventEmitter {
             if (watchChannels)
                 await this.startChannelWatch();
         }
+        // Rebind the daemon's lease-loss watch onto the fresh connection (#1596). The intent survived
+        // clearConnectionScoped; a bind that completes after a stop or another rebuild found no intent
+        // and released itself. The replay re-delivers the row's current state, so a change that landed
+        // in the null window still reaches the trigger.
+        if (this.leaseWatchIntent)
+            await this.bindDeliveryLeaseWatch();
         // FAIL BEFORE PRESENCE (SPEC 13.1): an AUTHED endpoint that will register on the roster or
         // bind lifecycle-keyed consumers must hold its launcher-supplied lifecycle uid BEFORE anything
         // makes it visible - a missing uid must never leave a roster ghost that could not bind (false
@@ -1095,6 +1125,7 @@ export class CotalEndpoint extends EventEmitter {
             /* already closed with the connection */
         }
         this.channelWatchIter = undefined;
+        this.stopDeliveryLeaseWatch();
         for (const sub of this.chatSubs.values()) {
             try {
                 sub.unsubscribe();
@@ -1189,6 +1220,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.
@@ -1467,6 +1502,7 @@ export class CotalEndpoint extends EventEmitter {
             /* already closed */
         }
         this.channelWatchIter = undefined;
+        this.stopDeliveryLeaseWatch();
         try {
             if (this.doRegister) {
                 this.status = "offline";
@@ -1671,6 +1707,7 @@ export class CotalEndpoint extends EventEmitter {
         if (!Array.isArray(opts.parts) || opts.parts.length === 0)
             throw new Error("multicastExpecting requires at least one part");
         const message = this.casEnvelope(opts);
+        assertPartsSerializable(message.parts);
         // Publish DIRECTLY rather than through publishMsg: this path must set the expectation and read
         // the ack, and publishMsg deliberately does neither.
         const ack = await this.js.publish(chatSubject(this.space, this.owner, this.actor, opts.channel), JSON.stringify(message), { msgID: opts.id, expect: { lastSubjectSequence: expected } });
@@ -2057,6 +2094,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) {
@@ -2507,7 +2550,10 @@ export class CotalEndpoint extends EventEmitter {
         }));
     }
     /** Fetch recent messages from a channel's JetStream backlog. `signal` cancels the active pull and
-     *  reclaims its ephemeral consumer before the promise rejects. */
+     *  reclaims its ephemeral consumer before the promise rejects. Returns `HistoryMessage[]`
+     *  (#1413): every field present on a row was checked by the drain before the row was
+     *  returned — a stored row missing `ts` / `space` / `parts` / `from.name` is dropped, never
+     *  returned with that member silently `undefined`. */
     async channelHistory(channel, opts) {
         // 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);
@@ -2654,7 +2700,10 @@ export class CotalEndpoint extends EventEmitter {
     /** Fetch recent DMs (any sender→any recipient) from the space's DM backlog. `signal` cancels the
      *  active pull and reclaims its ephemeral consumer. 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. */
+     *  skips for them — only an `admin`-profile cred can read it. Returns `HistoryMessage[]`
+     *  (#1413): every field present on a row was checked by the drain before the row was
+     *  returned — a stored row missing `ts` / `space` / `parts` / `from.name` is dropped, never
+     *  returned with that member silently `undefined`. */
     async dmHistory(opts) {
         // every inst.<recipOwner>.<recipActor>.<sndOwner>.<sndActor> DM — the whole DM subtree (god-view)
         return (await this.streamHistory(dmStream(this.space), [`${spacePrefix(this.space)}.inst.>`], opts?.limit ?? 100, undefined, opts?.signal)).map((r) => r.msg);
@@ -3032,6 +3081,7 @@ export class CotalEndpoint extends EventEmitter {
     async publishMsg(subject, msg) {
         if (!this.js)
             throw new Error(this.notLiveMsg());
+        assertPartsSerializable(msg.parts);
         // msgID = message id → free server-side dedup across JetStream redelivery.
         await this.js.publish(subject, JSON.stringify(msg), { msgID: msg.id });
     }
@@ -3283,6 +3333,68 @@ export class CotalEndpoint extends EventEmitter {
     async readDeliveryLease(shardIndex) {
         return (await this.readDeliveryLeaseEntry(shardIndex))?.info;
     }
+    /** Watch THIS shard's lease key and nothing else, for the daemon's loss trigger (#1596).
+     *
+     *  A KV watch is the native JetStream push for "the row changed hands NOW": a filtered ordered
+     *  consumer on the lease bucket delivers the row's own writes the moment the broker applies them,
+     *  instead of the daemon waiting for its next renew tick to notice. The watch is a TRIGGER, never a
+     *  decision: every event is handed to `onEvent` with the row as the broker now states it (PUT) or
+     *  the fact it is gone (DEL/PURGE, `info` undefined), and the caller re-runs the SAME decision tree
+     *  its renew tick would (`leaseAction`, `mayServeOn`, `readOwnLease`-style ownership tests). An
+     *  event the daemon itself caused (its acquire, its renew, its ready flip) is an ordinary input to
+     *  that tree — the row still reads `held` by this endpoint — so it never quiesces on its own write;
+     *  no event filtering happens here.
+     *
+     *  Like the presence watch, this survives a connection rebuild as INTENT: the iterator dies with
+     *  its connection and {@link connectAndBind} rebinds it onto the fresh one, so a reconnect can
+     *  never leave the daemon blind to the row for the rest of its life. The rebind replays the
+     *  bucket's current last-per-subject state, so a change that landed during the null window is
+     *  delivered on the fresh watch. Resolves a stop handle. */
+    async watchDeliveryLease(shardIndex, onEvent) {
+        this.leaseWatchIntent = { shardIndex, onEvent };
+        await this.bindDeliveryLeaseWatch();
+        return () => {
+            if (this.leaseWatchIntent?.onEvent !== onEvent)
+                return; // a later watch owns the slot
+            this.leaseWatchIntent = undefined;
+            this.stopDeliveryLeaseWatch();
+        };
+    }
+    stopDeliveryLeaseWatch() {
+        try {
+            this.leaseWatchIter?.stop();
+        }
+        catch { /* already closed with its connection */ }
+        this.leaseWatchIter = undefined;
+    }
+    async bindDeliveryLeaseWatch() {
+        const intent = this.leaseWatchIntent;
+        const iter = await (await this.deliveryRegistry()).watch({ key: leaseKey(intent.shardIndex) });
+        if (this.leaseWatchIntent !== intent) {
+            try {
+                iter.stop();
+            }
+            catch { /* already closed */ }
+            return;
+        }
+        this.leaseWatchIter = iter;
+        void (async () => {
+            for await (const e of iter) {
+                if (this.leaseWatchIter !== iter)
+                    break;
+                if (e.operation === "DEL" || e.operation === "PURGE") {
+                    intent.onEvent(undefined);
+                    continue;
+                }
+                try {
+                    intent.onEvent(e.json());
+                }
+                catch {
+                    intent.onEvent(undefined);
+                }
+            }
+        })().catch((e) => this.emit("error", e));
+    }
     /** The lease row AND the KV revision it is at. The revision is the CAS token every renew and the
      *  CAS release are argued against, so a caller re-establishing ownership after a failed renew
      *  needs the BROKER's sequence, not the one it last cached: a renew can fail with its write
@@ -5148,6 +5260,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 +5278,12 @@ 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;
+        // #1461: snapshot the put's generation BEFORE the put. A settle (success or rejection) is the
+        // latest evidence on its epoch only while no put that started after it has ALREADY settled —
+        // a newer put merely in flight is not evidence yet. Same-epoch puts overlap routinely
+        // (heartbeat 2s against a ~5s JetStream put timeout), so "succeeded" alone is not "newest".
+        const generation = ++this.presencePutGeneration;
         try {
             await this.kv.put(this.card.id, JSON.stringify(record));
         }
@@ -5173,21 +5293,39 @@ export class CotalEndpoint extends EventEmitter {
             // nothing else here notices. Record WHEN the refusals started, at the one site that knows the
             // failing write was a presence write; a caller cannot infer that from the generic `warning`
             // stream, which carries any recoverable error.
-            if (epoch === this.presenceEpoch && !this.stopped) {
+            //
+            // #1461: a rejection speaks when it is the newest SETTLED evidence — a newer put that has
+            // merely started does not silence it, but a newer put that already settled (either way)
+            // does.
+            const superseded = (this.presencePutSettled ?? 0) > generation;
+            this.presencePutSettled = Math.max(this.presencePutSettled ?? 0, generation);
+            if (epoch === this.presenceEpoch && !this.stopped && !superseded) {
                 this.presenceWriteFailingSince ??= Date.now();
                 this.lastPresenceWriteError = e?.message ?? String(e);
             }
             throw e;
         }
-        // A late SUCCESS is the same hazard mirrored, and this fence answers only the cross-epoch half
-        // of it: a success belonging to a retired epoch cannot erase a refusal the current one
-        // established from its own evidence. It does NOT order puts within a single epoch, because it
-        // compares epoch identity rather than which put is the latest evidence, so an earlier put that
-        // succeeds late still clears a later put's refusal. Heartbeats run at 2s against a ~5s put
-        // timeout, so that overlap is routine rather than a corner, and the next failing put re-plants
-        // the record with a fresh `since`. Tracked in #1461, not repaired here.
-        if (epoch !== this.presenceEpoch || this.stopped)
+        // A late SUCCESS cannot erase a refusal from newer evidence. Two fences, each answering half:
+        // the epoch fence (#1356) keeps a put that outlives its connection from writing or erasing a
+        // record that belongs to a later connection; the generation fence (#1461) orders puts WITHIN
+        // one epoch by SETTLE order, not start order: a settle is the latest evidence only while no
+        // put that started after it has already settled, whichever way that newer put settled. So an
+        // earlier put settling AFTER a later put settled no longer speaks — success cannot clear a
+        // newer refusal (#1461's original case), and a newer settle is not blocked by being merely
+        // started (panel round 1). Without the fence, an earlier put succeeding late cleared a later
+        // put's refusal while the bucket still refused writes (heartbeat 2s against a ~5s put timeout,
+        // so the overlap is routine rather than a corner).
+        const superseded = (this.presencePutSettled ?? 0) > generation;
+        this.presencePutSettled = Math.max(this.presencePutSettled ?? 0, generation);
+        if (epoch !== this.presenceEpoch || this.stopped || superseded)
             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
@@ -5204,8 +5342,9 @@ export class CotalEndpoint extends EventEmitter {
         this.lastPresenceWriteError = undefined;
     }
     /** #1356: the presence bucket has been refusing writes since this time, or `undefined` when the
-     *  last publish succeeded. Cleared by the first successful write, so a survived blip reads as
-     *  healthy and only a SUSTAINED failure carries a duration.
+     *  last publish succeeded. Cleared by a successful write that is the latest evidence on its
+     *  epoch (#1461), so a survived blip reads as healthy and only a SUSTAINED failure carries a
+     *  duration.
      *
      *  Presence writes are the CANARY, not the scope: the broker can disable JetStream account-wide
      *  while the NATS connection stays up, so a caller must not read this as "only presence is
@@ -5440,8 +5579,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 +5623,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);
@@ -5592,7 +5736,8 @@ function kindFromParsed(kind) {
  *  unparseable subject, or `from.id !== parsed.sender` (SPEC §5). This derives the remaining
  *  routing tokens from the subject for rows that survived — it does not rewrite a mismatched
  *  `from.id`. Live tails, channel backfill, and channel recall skip the mismatch; history
- *  does the same (#388). */
+ *  does the same (#388). The row's other fields pass through UNTOUCHED, so what the caller's
+ *  row type already verified stays verified (#1413). */
 function authenticatedMessage(msg, parsed) {
     if (parsed.kind === "chat")
         return authenticatedChannelMessage(msg, parsed.rest);
@@ -5627,6 +5772,8 @@ function historyMessageFromDelivery(m) {
     }
     if (!isHistoryDrainEnvelope(raw))
         return undefined;
+    if (!isVerifiedHistoryRow(raw))
+        return undefined;
     const parsed = parseSubject(m.subject);
     if (!parsed || !isPrincipalOwnerToken(parsed.owner))
         return undefined;
@@ -5634,17 +5781,59 @@ function historyMessageFromDelivery(m) {
         return undefined;
     return authenticatedMessage(raw, parsed);
 }
+/** The members `HistoryMessage` promises beyond the drain envelope (#1413): a full
+ *  `EndpointRef` (`from.name`, and `from.role` only when a string), a finite `ts`, a string
+ *  `space`, `parts` the drain could read, and the optional members in their promised shape
+ *  when present. Every field the PUBLIC row type promises is checked here, before the row is
+ *  returned. A row missing one is dropped, never returned with that member silently
+ *  `undefined` under the full type — a consumer reading `msg.ts`, `msg.space`, `msg.parts`
+ *  or `msg.from.name` must not be able to reach one that was never there. Nothing is invented
+ *  for an absent field.
+ *
+ *  `parts` is held to READABLE, not to `isMessagePart`: every member must be an object with a
+ *  string `kind` (so `partsToText` can read `part.kind` without throwing), but a keyless
+ *  `{kind:"data"}` row from a pre-#1404 producer is not dropped — history must surface it.
+ *  `mentions`, `replyTo`, and `contextId` keep exactly their `CotalMessage` shapes when
+ *  present: an array of strings, a string, a string. */
+function isVerifiedHistoryRow(row) {
+    if (typeof row.from.name !== "string")
+        return false;
+    if (row.from.role !== undefined && typeof row.from.role !== "string")
+        return false;
+    if (typeof row.ts !== "number" || !Number.isFinite(row.ts))
+        return false;
+    if (typeof row.space !== "string")
+        return false;
+    if (!Array.isArray(row.parts) || !row.parts.every(isReadableMessagePart))
+        return false;
+    if (row.mentions !== undefined &&
+        (!Array.isArray(row.mentions) || !row.mentions.every((name) => typeof name === "string")))
+        return false;
+    if (row.replyTo !== undefined && typeof row.replyTo !== "string")
+        return false;
+    if (row.contextId !== undefined && typeof row.contextId !== "string")
+        return false;
+    return true;
+}
+/** A part `partsToText` can read without throwing: an object with a string `kind` (#1413).
+ *  Deliberately weaker than `isMessagePart` — a keyless `{kind:"data"}` part passes here —
+ *  because history must surface rows a pre-#1404 producer wrote, not drop them. */
+function isReadableMessagePart(value) {
+    return isRecord(value) && typeof value.kind === "string";
+}
 /**
  * Narrow enough for the type checker and for fail-closed history: object envelope, usable `id`,
  * object `from`. That is what lets `from.id !== parsed.sender` run without throwing, and what
  * lets `authenticatedMessage` take the row without a cast.
  *
  * Does NOT verify SPEC §5 message shape. It does not require a string `from.id` (the SPEC §5
- * comparison still rejects a mismatch), exactly one route key, a finite `ts`, a string
- * `space`, a full EndpointRef `from` (`name`/`role`), or well-formed `parts`. Those belong
- * to `isCotalMessage` (Plane-3). History must not use that guard: a public
- * `unicast(..., { parts: [{ kind: "data", data: undefined }] })` serializes to `{kind:"data"}`
- * and must still surface.
+ * comparison still rejects a mismatch) or exactly one route key. The members the PUBLIC
+ * history row promises beyond this envelope — a full EndpointRef `from` (`name`/`role`), a
+ * finite `ts`, a string `space` — are checked by {@link isVerifiedHistoryRow} before the row
+ * is returned (#1413). Well-formed `parts` still belong to `isCotalMessage` (Plane-3), and
+ * history must not use that guard: a publisher now REFUSES a `data` part carrying a non-JSON
+ * value, but a keyless `{kind:"data"}` row from a pre-fix producer can still sit in a stream,
+ * and history must surface it rather than drop it.
  */
 function isHistoryDrainEnvelope(value) {
     return isRecord(value) && isUsableMessageId(value.id) && isRecord(value.from);
@@ -5702,6 +5891,85 @@ function isMessagePart(value) {
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
+/** A `data` part value the wire can carry faithfully: a JSON value at EVERY depth (SPEC §5's
+ *  `<any JSON value>`). `JSON.stringify` does not reject what it cannot represent — it silently
+ *  rewrites: `undefined` (and a function-valued member) drops the key, `NaN`/`Infinity` store as
+ *  `null`, a `Date` stores as a string, a sparse array's holes store as `null`, a `Map` stores as
+ *  `{}`, a `Buffer` stores as `{"type":"Buffer",...}`. A reader then cannot tell a stored `null`
+ *  from a real one (#1404 fix round). So the producer checks structurally, matching the exported
+ *  `JsonValue`: null, boolean, finite number, string, an array whose every slot (holes included)
+ *  passes, or a plain object (prototype `null` or `Object.prototype`) whose every defined member
+ *  passes. A cycle is refused here too, never left for stringify's TypeError.
+ *
+ *  THE OBJECT/ARRAY ASYMMETRY ON `undefined`: an `undefined`-valued MEMBER of a plain object is
+ *  allowed — stringify drops just that key, which is faithful (and the exported type says so) —
+ *  while `undefined` at the top level or in an ARRAY SLOT is refused, because there stringify
+ *  cannot drop a position: it stores `null`, which is a rewrite a reader cannot distinguish from
+ *  a real `null`.
+ *
+ *  `seen` is the set of ANCESTORS on the current path, not every object visited: it is deleted
+ *  from on the way out, so a SHARED subtree (`{a: x, b: x}`) passes — stringify carries it twice,
+ *  which is faithful — while an object that contains itself at any depth still reports its path. */
+function jsonPathProblem(path, value, seen) {
+    if (value === null)
+        return undefined;
+    const t = typeof value;
+    if (t === "boolean" || t === "string")
+        return undefined;
+    if (t === "number")
+        return Number.isFinite(value) ? undefined : `${path} is not a finite number`;
+    if (t === "undefined" || t === "function" || t === "symbol" || t === "bigint")
+        return `${path} is not a JSON value`;
+    if (typeof value === "object") {
+        if (seen.has(value))
+            return `${path} is cyclic`;
+        seen.add(value);
+        let problem;
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                problem = jsonPathProblem(`${path}[${i}]`, value[i], seen);
+                if (problem)
+                    return problem;
+            }
+        }
+        else {
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== null && proto !== Object.prototype) {
+                seen.delete(value);
+                return `${path} is not a plain object`;
+            }
+            for (const key of Object.keys(value)) {
+                // A member whose value is undefined is the allowed key-drop, not a defect: stringify omits
+                // the key, the object stays a JSON object, so skip it rather than walk it.
+                if (value[key] === undefined)
+                    continue;
+                problem = jsonPathProblem(`${path}.${key}`, value[key], seen);
+                if (problem)
+                    return problem;
+            }
+        }
+        seen.delete(value);
+        return undefined;
+    }
+    return `${path} is not a JSON value`;
+}
+/** Refuse, at publish, a `data` part `JSON.stringify` would silently rewrite. The guard is the
+ *  runtime half of `Part`'s `data: JsonValue` arm: with it, a non-JSON value at any depth never
+ *  reaches the wire, so every reader (live core-sub, Plane-3 durable, history) gives one answer —
+ *  the message was never sent — instead of the old split where history returned a rewritten row
+ *  while Plane-3 terminated a keyless one as malformed. The error names the path to the offending
+ *  value (e.g. `data[2].at`), so a caller learns which member to fix rather than that stringify
+ *  would have mangled something. Throws rather than coercing: no fallback. */
+function assertPartsSerializable(parts) {
+    for (const p of parts) {
+        if (p.kind !== "data")
+            continue;
+        const problem = jsonPathProblem("data", p.data, new Set());
+        if (problem !== undefined) {
+            throw new Error(`cannot publish a data part carrying a non-JSON value (SPEC §5) - ${problem}`);
+        }
+    }
+}
 /** Shallow-equal two per-channel-mode maps (presence dedup): a change must re-emit, so an attention
  *  toggle isn't swallowed as a quiet heartbeat. Absent and empty compare equal. */
 function sameChannelModes(a, b) {
@@ -5711,6 +5979,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