@staix/agent-hub 0.32.0 → 0.34.0

package/src/rooms/link.ts

@@ -1,11 +1,12 @@
 /** Outbound room transport. The local bus and application delivery boundary belong to X4. */
-import { createBrokerAuth, decodeBrokerChallenge, encodeBrokerControl } from "../broker/protocol.ts";
+import { BROKER_CODEC_FEATURES_OPT_IN, createBrokerAuth, decodeBrokerChallenge, encodeBrokerControl } from "../broker/protocol.ts";
 import { assertRoomCryptoReady, encodeBase64url, sha256, RoomCryptoError } from "./crypto.ts";
 import { brokerUrl, canonicalBytes, decodeFrame, decodeRoster, openFrame, roomMembers, sealFrame, verifyPublicRoster, RoomWireError, type FrameWire, type FrameOpenResult, type VerifiedPublicRoster } from "./wire.ts";
 import type { RoomRefusalReason, RoomState, RoomStore } from "./store.ts";
 import { RoomUnmatchedReceiptError, RoomFreshChatCapacityError, RoomStoreError, type RoomOutgoingInput } from "./store.ts";
 import { ROOM_STOP_TIMEOUT_MS, roomRefreshPeriod } from "./liveness.ts";
-import { decodeRoomMessage, encodeRoomMessage, type RoomMessage } from "./application.ts";
+import { roomHealthCause, roomHealthNextStep, type RoomHealthCause } from "./health.ts";
+import { ROOM_CODEC_FEATURES, roomCodecFeatures, roomRequiredCodecFeature, decodeRoomMessage, encodeRoomMessage, type RoomCodecFeature, type RoomMessage } from "./application.ts";
 
 export type RoomLinkState = "offline" | "connecting" | "online";
 export type RoomPresenceState = "idle" | "busy" | "paused" | "offline";
@@ -14,7 +15,7 @@ export interface RoomLinkOptions {
   store: RoomStore;
   name: string;
   presence?: () => readonly { id: string; state: string }[];
-  onPresence?: (value: { member: string; peers: readonly RoomPresencePeer[]; restored?: true }) => void;
+  onPresence?: (value: { member: string; peers: readonly RoomPresencePeer[]; restored?: true; observedAt?: number | null }) => void;
   onState?: (state: RoomLinkState) => void;
   application?: RoomLinkApplication;
   refreshMs?: number;
@@ -33,7 +34,7 @@ export interface RoomLinkApplication {
   transportAck?(context: RoomLinkContext, input: { digest: string }): void;
   receiptTtlMs?(context: RoomLinkContext): number;
   capacityChanged?(context: RoomLinkContext): void;
-  gap?(context: RoomLinkContext, input: { sender: string; count: string }): void;
+  codecsChanged?(context: RoomLinkContext, input: { member: string; features?: readonly RoomCodecFeature[] }): void;
 }
 /** Host port signal: no application claim/effect occurred; the durable plaintext remains pending. */
 export class RoomApplicationDeferredError extends Error {
@@ -45,17 +46,32 @@ export class RoomLinkError extends Error {
   }
 }
 /** Only before durable application enqueue: the Bus may retain its original queue item. */
+export class RoomCodecUnsupportedError extends Error {
+  readonly code = "codec_unsupported";
+  constructor(readonly feature: RoomCodecFeature) {
+    super(`Room send refused: recipient codec support for ${feature} is unavailable; upgrade both hubs and the broker, reconnect the room, then retry.`);
+    this.name = "RoomCodecUnsupportedError";
+  }
+}
 export class RoomNotSentError extends Error {
   readonly code = "not_sent";
   constructor() { super("room application was not queued; retry when the link is ready"); this.name = "RoomNotSentError"; }
 }
+/** No compatibility observation exists yet; retain work under its original queue deadline. */
+export class RoomCodecPendingError extends RoomNotSentError {
+  constructor(readonly changed: () => boolean) {
+    super(); this.name = "RoomCodecPendingError";
+    this.message = "Room codec observation is pending; wait for a signed codec advertisement, then retry.";
+  }
+}
+export type RoomCodecState = "pending" | "supported" | "unsupported";
 const RECEIPT_TTL_MS = 24 * 3_600_000;
 const LIMITS = Object.freeze({ packets: 8, queuedBytes: 2_097_152, packetBytes: 1_048_576, backpressure: 1_048_576, handshakeMs: 30_000, reconnectMaxMs: 300_000 });
 const decoder = new TextDecoder("utf-8", { fatal: true });
 const PEER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 const DIGEST = /^[A-Za-z0-9_-]{43}$/;
 const STATES: readonly string[] = ["idle", "busy", "paused", "offline"];
-interface PendingFrame { wire: Uint8Array; digest: string; presence: boolean; requestReply: boolean; current: () => boolean; retained?: () => boolean; onSent?: () => void; afterInboundAck?: string }
+interface PendingFrame { wire: Uint8Array; digest: string; presence: boolean; requestReply: boolean; current: () => boolean; retained?: () => boolean; onSent?: () => void; afterInboundAck?: string; codecFeatures?: boolean; supported?: () => boolean; codecPending?: () => boolean; codecTarget?: { member: string; feature: RoomCodecFeature } }
 interface Session {
   closingHead?: PendingFrame;
   refresh?: ReturnType<typeof setTimeout>;
@@ -72,6 +88,13 @@ interface Session {
   frameRetry?: ReturnType<typeof setTimeout>;
   lastPresence?: string;
   ephemeral?: boolean;
+  codecFeatures?: boolean;
+  codecSession?: string;
+  codecPublishing?: Promise<void>;
+  codecDirty?: boolean;
+  pendingPresence?: Map<string, { session: string | null; epoch: string; peers: RoomPresencePeer[]; observedAt: number | null }>;
+  codecPeers?: Map<string, { session: string | null; supported: boolean }>;
+  features?: Map<string, { session: string; features: readonly string[] }>;
   ws: WebSocket;
   generation: number;
   room: string;
@@ -106,7 +129,8 @@ function packet(bytes: Uint8Array): Record<string, unknown> {
   return row;
 }
 function presence(bytes: Uint8Array, exposed: readonly string[]): RoomPresencePeer[] {
-  const decoded = packet(bytes), row = exact(decoded, Object.hasOwn(decoded, "requestReply") ? ["v", "type", "peers", "requestReply"] : ["v", "type", "peers"]);
+  const decoded = packet(bytes), row = exact(decoded, ["v", "type", "peers", ...(Object.hasOwn(decoded, "requestReply") ? ["requestReply"] : []), ...(Object.hasOwn(decoded, "features") ? ["features", "codecSession"] : [])]);
+  if (Object.hasOwn(row, "features")) { roomCodecFeatures(row.features); if (typeof row.codecSession !== "string" || !DIGEST.test(row.codecSession)) fail(); }
   if (row.requestReply !== undefined && typeof row.requestReply !== "boolean") fail();
   if (row.type !== "presence" || !Array.isArray(row.peers) || row.peers.length > 64) fail();
   const peers = row.peers.map(value => {
@@ -131,6 +155,9 @@ export class RoomLink {
   private reconnect?: ReturnType<typeof setTimeout>;
   private attempts = 0;
   private state: RoomLinkState = "offline";
+  private cause?: RoomHealthCause;
+  private blockedCodec?: { member: string; feature: RoomCodecFeature };
+  private clockHighWater?: number;
   private publishing = false;
   private publishDirty = false;
   private replyPresence = false;
@@ -144,13 +171,33 @@ export class RoomLink {
 
   /** Advisory transport state without copying or decoding a room epoch for a status poll. */
   get connectionState(): RoomLinkState { return this.state; }
+  get connectionCause(): RoomHealthCause | undefined { return this.cause; }
   /** Negotiated transport evidence only; unknown until this session is ready. */
+  codecState(recipient: string, feature: RoomCodecFeature): RoomCodecState {
+    const session = this.session;
+    if (!session || session.phase !== "ready") return "pending";
+    if (session.codecFeatures !== true) return "unsupported";
+    const peer = session.codecPeers?.get(recipient);
+    if (!peer || peer.session === null) return "pending";
+    if (!peer.supported) return "unsupported";
+    const advertised = session.features?.get(recipient);
+    if (!advertised || advertised.session !== peer.session) return "pending";
+    return advertised.features.includes(feature) ? "supported" : "unsupported";
+  }
+  codecSupported(recipient: string, feature: RoomCodecFeature): boolean { return this.codecState(recipient, feature) === "supported"; }
+  private codecRefusal(recipient: string, feature: RoomCodecFeature): RoomNotSentError | RoomCodecUnsupportedError {
+    if (this.codecState(recipient, feature) === "unsupported") return new RoomCodecUnsupportedError(feature);
+    const session = this.session, peer = session?.codecPeers?.get(recipient), advertisement = session?.features?.get(recipient);
+    return new RoomCodecPendingError(() => this.session !== session || session?.codecPeers?.get(recipient) !== peer
+      || session?.features?.get(recipient) !== advertisement || this.codecState(recipient, feature) !== "pending");
+  }
   get livenessTracked(): boolean | undefined { return this.session?.phase === "ready" ? this.session.ephemeral : undefined; }
-  status(): { state: RoomLinkState; members: number } {
+  status(): { state: RoomLinkState; members: number; cause?: RoomHealthCause; nextStep?: string } {
     try {
       const row = this.options.store.get(this.options.name);
-      return { state: this.state, members: row && !row.left ? roomMembers(row.current).length : 0 };
-    } catch { return { state: "offline", members: 0 }; }
+      return { state: this.state, members: row && !row.left ? roomMembers(row.current).length : 0,
+        ...(this.cause ? { cause: this.cause, nextStep: roomHealthNextStep(this.cause) } : {}) };
+    } catch (error) { const cause = roomHealthCause(error); return { state: "offline", members: 0, cause, nextStep: roomHealthNextStep(cause) }; }
   }
   async start(): Promise<void> {
     if (this.running || this.stopping) return;
@@ -224,12 +271,12 @@ export class RoomLink {
     if (session.refresh) clearTimeout(session.refresh);
     // Legacy brokers retain state-change/dedupe publication without periodic traffic.
     if (!session.ephemeral || !this.running || this.stopping) return;
-    session.refreshedAt = (this.options.now ?? Date.now)();
+    session.refreshedAt = this.observationTime();
     session.refresh = setTimeout(() => {
       session.refresh = undefined;
       if (this.session !== session || !this.running || this.stopping || session.phase !== "ready") return;
-      const now = (this.options.now ?? Date.now)();
-      if (now - session.refreshedAt! >= this.refreshMs) {
+      const now = this.observationTime();
+      if (now !== undefined && session.refreshedAt !== undefined && now - session.refreshedAt >= this.refreshMs) {
         session.pendingPresenceReplies.clear(); session.presenceAsked = false;
         session.requestPresenceReply = true; this.forcePresenceRequest = true;
         void this.publishPresence().catch(() => this.retry(session));
@@ -238,15 +285,35 @@ export class RoomLink {
     }, this.refreshMs);
     session.refresh.unref?.();
   }
-  private setState(state: RoomLinkState): void {
-    if (this.state === state) return;
-    this.state = state;
+  private observationTime(): number | undefined {
+    let now: number;
+    try { now = (this.options.now ?? Date.now)(); } catch { this.setState(this.state, "unavailable"); return undefined; }
+    if (!Number.isSafeInteger(now) || now < 0) { this.setState(this.state, "unavailable"); return undefined; }
+    if (this.clockHighWater !== undefined && now < this.clockHighWater) { this.setState(this.state, "clock_rollback"); return undefined; }
+    this.clockHighWater = now;
+    return now;
+  }
+  /** Called only after the Store-backed sequence port committed a reservation. */
+  private clockRecoveredAfterWrite(): void {
+    if (this.cause === "clock_rollback" && this.observationTime() !== undefined) this.setState(this.state);
+  }
+  private refreshCodecCause(member: string): void {
+    const blocked = this.blockedCodec;
+    if (!blocked || blocked.member !== member) return;
+    const compatibility = this.codecState(member, blocked.feature);
+    if (compatibility === "supported") this.setState(this.state);
+    else this.setState(this.state, compatibility === "pending" ? "codec_pending" : "codec_unsupported");
+  }
+  private setState(state: RoomLinkState, cause?: RoomHealthCause): void {
+    if (cause !== "codec_pending" && cause !== "codec_unsupported") this.blockedCodec = undefined;
+    if (this.state === state && this.cause === cause) return;
+    this.state = state; this.cause = cause;
     try { this.options.onState?.(state); } catch { /* observation never changes transport authority */ }
   }
   private current(session: Session, digest?: string, final = false): RoomState {
     if ((!this.running && !(final && this.stopping)) || this.session !== session || session.generation !== this.generation || session.ws.readyState !== WebSocket.OPEN) fail("state_changed");
     let row: RoomState | undefined;
-    try { row = this.options.store.get(this.options.name); } catch { fail("unavailable"); }
+    try { row = this.options.store.get(this.options.name); } catch (error) { this.setState(this.state, roomHealthCause(error)); fail("unavailable"); }
     if (!row || row.left || row.current.room !== session.room || row.broker !== session.broker || (digest !== undefined && row.current.digest !== digest)) fail("state_changed");
     return row;
   }
@@ -324,7 +391,7 @@ export class RoomLink {
     }).catch(() => undefined);
     return work;
   }
-  private disconnect(session = this.session): void {
+  private disconnect(session = this.session, cause?: RoomHealthCause): void {
     if (session && session !== this.session) return;
     this.generation++;
     this.session = undefined;
@@ -340,12 +407,20 @@ export class RoomLink {
       session.queue.length = 0; session.queuedBytes = 0; session.deferredFrame = undefined;
       try { session.ws.close(1000, "disconnected"); } catch { /* already closed */ }
     }
-    this.setState("offline");
+    this.setState("offline", cause);
   }
-  private retry(session?: Session): void {
+  private retry(session?: Session, error?: unknown): void {
     if (this.stopping) return;
     if (session && this.session !== session) return;
-    this.disconnect(session);
+    let cause: RoomHealthCause = "transport_closed";
+    if (error instanceof RoomStoreError) cause = roomHealthCause(error);
+    else if (this.cause === "broker_refused" || this.cause === "clock_rollback") cause = this.cause;
+    else if (error instanceof RoomLinkError) {
+      if (error.code === "limit") cause = "backpressure";
+      else if (error.code === "invalid_wire") cause = "untrusted";
+      else cause = error.code;
+    } else if (this.cause === "backpressure") cause = this.cause;
+    this.disconnect(session, cause);
     if (!this.running || this.reconnect) return;
     const ceiling = Math.min(LIMITS.reconnectMaxMs, 1000 * 2 ** Math.min(this.attempts++, 9));
     const delay = Math.floor(ceiling / 2 + Math.random() * ceiling / 2);
@@ -355,24 +430,24 @@ export class RoomLink {
   private connect(): void {
     if (!this.running || this.session) return;
     let row: RoomState | undefined;
-    try { row = this.options.store.get(this.options.name); } catch { this.setState("offline"); return; }
+    try { row = this.options.store.get(this.options.name); } catch (error) { this.retry(undefined, error); return; }
     if (!row || row.left) { this.setState("offline"); return; }
     let url: URL;
     try {
       url = new URL(brokerUrl(row.broker));
       if (url.pathname !== "/" || url.search) fail("untrusted");
-    } catch { this.setState("offline"); return; }
+    } catch { this.setState("offline", "untrusted"); return; }
     url.pathname = `/v1/rooms/${row.current.room}`;
     let ws: WebSocket;
-    // ponytail: negotiate only ephemeral here; replace this opt-in with #1204 T4 codec capabilities.
-    try { ws = new WebSocket(url.href, { headers: { "x-agent-hub-ephemeral": "1" } }); } catch { this.retry(); return; }
+    // Preserve the released ephemeral header exactly; old brokers ignore the additional codec token.
+    try { ws = new WebSocket(url.href, { headers: { "x-agent-hub-ephemeral": "1", "x-agent-hub-codecs": BROKER_CODEC_FEATURES_OPT_IN } }); } catch { this.retry(); return; }
     ws.binaryType = "arraybuffer";
     const generation = ++this.generation;
     const session: Session = { ws, generation, room: row.current.room, broker: row.broker, phase: "challenge", pendingPresenceReplies: new Set(), presenceAsked: false, outbound: [], outboundBytes: 0, frameSent: false, retryAttempt: 0, queue: [], queuedBytes: 0, processing: false, initialRoster: true, requestPresenceReply: true,
       handshake: setTimeout(() => this.retry(session), LIMITS.handshakeMs) };
     session.handshake.unref?.();
     this.session = session;
-    this.setState("connecting");
+    this.setState("connecting", "connecting");
     ws.addEventListener("message", event => this.receive(session, event.data));
     ws.addEventListener("close", () => this.retry(session));
     ws.addEventListener("error", () => this.retry(session));
@@ -382,15 +457,15 @@ export class RoomLink {
     if (bytes.length > LIMITS.packetBytes || session.ws.bufferedAmount > LIMITS.backpressure) fail("limit");
     session.ws.send(bytes);
   }
-  private queueFrame(session: Session, wire: Uint8Array, digest: string, requestReply = false, current: () => boolean = () => true, presence = false, retained?: () => boolean, onSent?: () => void, afterInboundAck?: string): void {
+  private queueFrame(session: Session, wire: Uint8Array, digest: string, requestReply = false, current: () => boolean = () => true, presence = false, retained?: () => boolean, onSent?: () => void, afterInboundAck?: string, codecFeatures = false, supported?: () => boolean, codecPending?: () => boolean, codecTarget?: { member: string; feature: RoomCodecFeature }): void {
     this.current(session, undefined, this.stopping);
     // Only an unsent observation may be replaced. Never reorder an attempted frame.
     if (presence) {
-      const at = session.outbound.findIndex((frame, index) => frame !== session.closingHead && frame.presence && (!frame.requestReply || requestReply) && (index > 0 || !session.frameSent && !session.frameRetry));
+      const at = session.outbound.findIndex((frame, index) => frame !== session.closingHead && frame.presence && !!frame.codecFeatures === codecFeatures && (!frame.requestReply || requestReply) && (index > 0 || !session.frameSent && !session.frameRetry));
       if (at >= 0) session.outboundBytes -= session.outbound.splice(at, 1)[0]!.wire.byteLength;
     }
     if (session.outbound.length >= LIMITS.packets || session.outboundBytes + wire.byteLength > LIMITS.queuedBytes) fail("limit");
-    session.outbound.push({ wire, digest, presence, requestReply, current, retained, onSent, afterInboundAck }); session.outboundBytes += wire.byteLength;
+    session.outbound.push({ wire, digest, presence, requestReply, current, retained, onSent, afterInboundAck, codecFeatures, supported, codecPending, codecTarget }); session.outboundBytes += wire.byteLength;
     this.pumpFrames(session);
   }
   private pumpFrames(session: Session): void {
@@ -411,10 +486,22 @@ export class RoomLink {
       void this.publishPresence().catch(() => this.retry(session));
       return;
     }
+    if (frame.supported && !frame.supported()) {
+      this.blockedCodec = frame.codecTarget;
+      this.setState(this.state, frame.codecPending?.() ? "codec_pending" : "codec_unsupported");
+      if (frame.retained) {
+        // The durable intent owns retry. Withdraw only this unsent ciphertext so
+        // later receipts can progress; a fresh codec observation reseals its retry.
+        session.outbound.shift(); session.outboundBytes -= frame.wire.byteLength; session.retryAttempt = 0;
+        this.pumpFrames(session);
+      }
+      return;
+    }
     // A foreground receipt follows the chat ACK on the socket. Otherwise broker
     // verification/storage of the receipt can pin the chat's one-packet slot.
     if (frame.afterInboundAck && session.processingFrame === frame.afterInboundAck && session.acknowledgedFrame !== frame.afterInboundAck) return;
     this.send(session, frame.wire); session.frameSent = true;
+    if (frame.codecTarget) this.refreshCodecCause(frame.codecTarget.member);
     const onSent = frame.onSent; frame.onSent = undefined; onSent?.();
   }
   private storedFrame(session: Session, digest: string): void {
@@ -424,12 +511,14 @@ export class RoomLink {
     session.frameSent = false; session.retryAttempt = 0;
     if (session.frameRetry) clearTimeout(session.frameRetry);
     session.frameRetry = undefined;
+    if (this.cause === "backpressure") this.setState(this.state);
     if (this.stoppedFrame?.digest === digest) this.stoppedFrame.resolve();
     this.pumpFrames(session);
   }
   private backoffFrame(session: Session, digest: string): void {
     if (session.outbound[0]?.digest !== digest || session.frameRetry) return;
     session.frameSent = false;
+    this.setState(this.state, "backpressure");
     const delay = Math.min(30_000, 250 * 2 ** Math.min(session.retryAttempt++, 7));
     session.frameRetry = setTimeout(() => {
       session.frameRetry = undefined;
@@ -466,7 +555,7 @@ export class RoomLink {
     if (session.processing || this.session !== session || !session.queue.length) return;
     const bytes = session.queue.shift()!; session.queuedBytes -= bytes.length;
     session.processing = true;
-    void this.handle(session, bytes).catch(() => this.retry(session)).finally(() => {
+    void this.handle(session, bytes).catch(error => this.retry(session, error)).finally(() => {
       session.processing = false;
       this.drain(session);
     });
@@ -506,8 +595,8 @@ export class RoomLink {
       return;
     }
     if (message.type === "ready") {
-      const ready = exact(message, ["v", "type", "room", "member", "epoch", "digest", ...(Object.hasOwn(message, "ephemeral") ? ["ephemeral"] : [])]), roster = session.roster;
-      if (ready.ephemeral !== undefined && ready.ephemeral !== true) fail();
+      const ready = exact(message, ["v", "type", "room", "member", "epoch", "digest", ...(Object.hasOwn(message, "ephemeral") ? ["ephemeral"] : []), ...(Object.hasOwn(message, "codecFeatures") ? ["codecFeatures", "codecSession"] : [])]), roster = session.roster;
+      if (ready.ephemeral !== undefined && ready.ephemeral !== true || ready.codecFeatures !== undefined && (ready.codecFeatures !== true || ready.ephemeral !== true || typeof ready.codecSession !== "string" || !DIGEST.test(ready.codecSession))) fail();
       if (!roster || ready.room !== local.current.room || ready.member !== this.options.store.identity.public.fingerprint || ready.epoch !== roster.epoch || ready.digest !== roster.digest) fail("untrusted");
       if (roster.digest !== local.current.digest) {
         if (roster.owner !== this.options.store.identity.public.fingerprint || BigInt(roster.epoch) >= BigInt(local.current.epoch)) fail("untrusted");
@@ -515,17 +604,20 @@ export class RoomLink {
         this.send(session, local.wire); return;
       }
       if (session.presenceRoster !== roster.digest) {
-        session.presenceRoster = roster.digest; session.pendingPresenceReplies.clear(); session.presenceAsked = false;
+        if (this.blockedCodec) this.setState(this.state);
+        session.presenceRoster = roster.digest; session.features = new Map(); session.codecPeers = new Map(); session.pendingPresence = new Map(); session.pendingPresenceReplies.clear(); session.presenceAsked = false;
         session.requestPresenceReply = true; session.lastPresence = undefined;
       }
       session.ephemeral = ready.ephemeral === true;
+      session.codecFeatures = ready.codecFeatures === true;
+      session.codecSession = typeof ready.codecSession === "string" ? ready.codecSession : undefined;
       session.phase = "ready"; session.ownerUpgrading = false; clearTimeout(session.handshake); this.attempts = 0;
       if (session.deferredFrame) {
         session.queue.unshift(session.deferredFrame); session.queuedBytes += session.deferredFrame.byteLength; session.deferredFrame = undefined;
       }
       if (!this.running || this.stopping) return;
-      this.armPresenceRefresh(session);
       this.setState("online");
+      this.armPresenceRefresh(session);
       const context = this.context(session, local.current.digest);
       this.options.application?.members(context);
       this.restoreReceipts(session);
@@ -536,6 +628,33 @@ export class RoomLink {
       void this.publishPresence().catch(() => this.retry(session));
       return;
     }
+    if (message.type === "codec_peers") {
+      const inventory = exact(message, ["v", "type", "peers", "digest"]);
+      if (!Array.isArray(inventory.peers) || inventory.peers.length > 64 || typeof inventory.digest !== "string" || !DIGEST.test(inventory.digest)) fail("untrusted");
+      if (inventory.digest !== local.current.digest) return; // A previous-roster observation cannot revoke or grant current support.
+      if (!session.codecFeatures || session.phase !== "ready") fail("untrusted");
+      const members = roomMembers(local.current), seen = new Set<string>();
+      const peers = inventory.peers.map(value => {
+        const peer = exact(value, ["member", "session", "supported"]);
+        if (typeof peer.member !== "string" || !members.some(member => member.fingerprint === peer.member) || seen.has(peer.member)
+          || peer.member === this.options.store.identity.public.fingerprint || typeof peer.supported !== "boolean"
+          || peer.session !== null && (typeof peer.session !== "string" || !DIGEST.test(peer.session)) || peer.session === null && peer.supported) fail("untrusted");
+        seen.add(peer.member);
+        return { member: peer.member, session: peer.session as string | null, supported: peer.supported };
+      });
+      let advertise = false;
+      for (const peer of peers) {
+        const previous = session.codecPeers?.get(peer.member);
+        if (previous?.session === peer.session && previous.supported === peer.supported) continue;
+        (session.codecPeers ??= new Map()).set(peer.member, { session: peer.session, supported: peer.supported });
+        session.features?.delete(peer.member); session.pendingPresence?.delete(peer.member);
+        if (peer.supported && peer.session !== null) advertise = true;
+        this.refreshCodecCause(peer.member);
+        try { this.options.application?.codecsChanged?.(this.context(session, local.current.digest), { member: peer.member }); } catch { /* Compatibility evidence grants no authority. */ }
+      }
+      if (advertise) void this.publishCodecPresence(session).catch(error => this.retry(session, error));
+      return;
+    }
     if (message.type === "frame") {
       if (session.phase !== "ready") {
         // X2 may already have one ciphertext in flight while this verified owner
@@ -587,6 +706,7 @@ export class RoomLink {
       // X2 declares these refusal controls nonterminal. Their unsigned control
       // cannot settle any application; its local ACK deadline records uncertainty.
       if (error.code === "replay_refused" || error.code === "unexpected_ack") return;
+      this.setState(this.state, "broker_refused");
       fail("unavailable");
     }
     fail();
@@ -615,9 +735,15 @@ export class RoomLink {
         if (!sender) return { status: "trust_changed" };
         let validPresence = false;
         try {
-          if (packet(input.plaintext).type === "presence") { presence(input.plaintext, sender.exposedPeers); validPresence = true; }
+          if (packet(input.plaintext).type === "presence") {
+            presence(input.plaintext, sender.exposedPeers);
+            const features = packet(input.plaintext).features;
+            if (frame.codecFeatures === true ? !session.codecFeatures || features === undefined : features !== undefined) fail();
+            validPresence = true;
+          }
           else {
             invalidApplication = true;
+            if (frame.codecFeatures) fail("untrusted");
             if (!this.options.application) fail("untrusted");
             application = decodeRoomMessage(input.plaintext);
             if (application.type === "chat" && application.envelope.from !== "user" && !sender.exposedPeers.includes(application.envelope.from)) fail("untrusted");
@@ -666,7 +792,6 @@ export class RoomLink {
       this.options.store.settleInbox(this.options.name, acceptedDigest);
       if (result?.status === "accepted") this.capacityChanged(session, digest);
     } else if (result?.status === "accepted") {
-      if (result.gap !== "0") try { this.options.application?.gap?.(this.context(session, digest), { sender: frame.sender, count: result.gap }); } catch { /* metadata observation cannot affect admission */ }
       const sender = roomMembers(latest.current).find(member => member.fingerprint === frame.sender);
       if (!sender) fail("untrusted");
       if (application && this.options.application) {
@@ -674,9 +799,35 @@ export class RoomLink {
       } else {
         const peers = presence(result.plaintext, sender.exposedPeers);
         this.current(session, digest);
-        session.pendingPresenceReplies.delete(frame.sender);
-        if (session.presenceAsked && session.pendingPresenceReplies.size === 0) session.requestPresenceReply = false;
-        try { this.options.onPresence?.({ member: frame.sender, peers }); } catch { /* validated observation only */ }
+        if (frame.codecFeatures === true) {
+          const payload = packet(result.plaintext), peer = session.codecPeers?.get(frame.sender);
+          if (frame.epoch === latest.current.epoch && peer?.supported && peer.session !== null && payload.codecSession === peer.session) {
+            const features = roomCodecFeatures(payload.features), previous = session.features?.get(frame.sender);
+            const changed = ROOM_CODEC_FEATURES.filter(feature => previous === undefined || previous.session !== peer.session || previous.features.includes(feature) !== features.includes(feature));
+            if (!previous || previous.session !== peer.session || previous.features.length !== features.length || previous.features.some((feature, index) => feature !== features[index])) {
+              (session.features ??= new Map()).set(frame.sender, { session: peer.session, features });
+            }
+            this.refreshCodecCause(frame.sender);
+            const pending = session.pendingPresence?.get(frame.sender);
+            session.pendingPresence?.delete(frame.sender);
+            if (pending?.session === peer.session && pending.epoch === latest.current.epoch) {
+              try { this.options.onPresence?.({ member: frame.sender, peers: pending.peers, observedAt: pending.observedAt }); } catch { /* Observation only, with the original local receive time. */ }
+            }
+            this.pumpFrames(session);
+            if (changed.length) try { this.options.application?.codecsChanged?.(this.context(session, digest), { member: frame.sender, features: changed }); } catch { /* Compatibility observations cannot change admission. */ }
+          }
+        } else {
+          session.pendingPresenceReplies.delete(frame.sender);
+          if (session.presenceAsked && session.pendingPresenceReplies.size === 0) session.requestPresenceReply = false;
+          const peer = session.codecPeers?.get(frame.sender), advertisement = session.features?.get(frame.sender);
+          const knownLegacy = peer !== undefined && peer.session !== null && peer.supported === false;
+          if (session.codecFeatures && peers.some(peer => peer.state !== "offline") && !knownLegacy && (!peer?.session || advertisement?.session !== peer.session)) {
+            (session.pendingPresence ??= new Map()).set(frame.sender, { session: peer?.session ?? null, epoch: frame.epoch, peers, observedAt: this.observationTime() ?? null });
+          } else {
+            session.pendingPresence?.delete(frame.sender); // A newer negative or admitted observation supersedes any deferred live state.
+            try { this.options.onPresence?.({ member: frame.sender, peers }); } catch { /* validated observation only */ }
+          }
+        }
         this.current(session, digest);
         this.options.store.settleInbox(this.options.name, acceptedDigest);
         this.capacityChanged(session, digest);
@@ -749,9 +900,21 @@ export class RoomLink {
     const session = this.session;
     if (this.stopping || !this.running || !session || session.phase !== "ready") { if (metadata) throw new RoomNotSentError(); fail("unavailable"); }
     if (this.applicationPauses.size) { if (metadata) throw new RoomNotSentError(); fail("state_changed"); }
+    const required = roomRequiredCodecFeature(message);
+    if (required && !this.codecSupported(recipient, required)) throw this.codecRefusal(recipient, required);
     const digest = this.current(session).current.digest;
     const allowed = () => this.publicationCurrent(session, digest) && current();
-    const admitted = () => this.applicationPauses.size === 0 && allowed();
+    const supported = () => required === undefined || this.codecSupported(recipient, required);
+    let codecLost = false;
+    const admitted = () => {
+      if (!supported()) { codecLost = true; return false; }
+      return this.applicationPauses.size === 0 && allowed();
+    };
+    const assertAdmitted = () => {
+      if (admitted()) return;
+      if (codecLost && required) throw this.codecRefusal(recipient, required);
+      fail("state_changed");
+    };
     let queueStarted = false;
     try {
       let presenceWork: Promise<void> | undefined;
@@ -767,7 +930,7 @@ export class RoomLink {
       // Reserve this chat's FIFO slot before yielding to the earlier observation.
       return await this.serialSend(async () => {
       if (presenceWork) await presenceWork;
-      if (!admitted()) fail("state_changed");
+      assertAdmitted();
       if (metadata && (session.outbound.length >= LIMITS.packets || session.outboundBytes + plaintext.byteLength > LIMITS.queuedBytes
         || session.ws.bufferedAmount > LIMITS.backpressure)) throw new RoomNotSentError();
       if (message.type === "receipt") {
@@ -781,13 +944,21 @@ export class RoomLink {
       const row = this.current(session, digest);
       if (!roomMembers(row.current).some(member => member.fingerprint === recipient) || recipient === this.options.store.identity.public.fingerprint) fail("untrusted");
       let wire = await sealFrame({ epoch: row.current, identity: this.options.store.identity, recipients: [recipient], plaintext, sequence: this.options.store.sequence });
-      if (!admitted()) fail("state_changed");
+      this.clockRecoveredAfterWrite();
+      assertAdmitted();
       let frameDigest: string;
       if (metadata) {
         queueStarted = true;
         let record: Awaited<ReturnType<RoomStore["queueApplication"]>>;
         try { record = await this.options.store.queueApplication(this.options.name, wire, metadata, admitted); }
         catch (error) {
+          if (codecLost && required && error instanceof RoomStoreError && error.code === "state_changed") {
+            // The atomic fence refused this attempt. Positively distinguish a
+            // never-admitted application from an earlier durable retry intent.
+            if (!this.options.store.applicationOutbox(this.options.name).some(row => row.deliveryId === metadata.deliveryId || row.application === metadata.application)) throw this.codecRefusal(recipient, required);
+            if (this.codecState(recipient, required) !== "unsupported") throw this.codecRefusal(recipient, required);
+            throw new RoomNotSentError();
+          }
           // An explicit atomic refusal plus absent durable intent is positive not-sent evidence.
           if (error instanceof RoomStoreError && ["limit", "invalid", "untrusted", "state_changed"].includes(error.code)
             && !this.options.store.applicationOutbox(this.options.name).some(row => row.deliveryId === metadata.deliveryId || row.application === metadata.application)) throw new RoomNotSentError();
@@ -806,7 +977,7 @@ export class RoomLink {
         this.queueFrame(session, wire, frameDigest, false, allowed, false,
           metadata ? () => this.options.store.applicationSendable(this.options.name, frameDigest)
             : message.type === "receipt" ? () => this.options.store.receiptSendable(this.options.name, frameDigest) : undefined,
-          undefined, message.type === "receipt" && message.frame === session.processingFrame ? message.frame : undefined);
+          undefined, message.type === "receipt" && message.frame === session.processingFrame ? message.frame : undefined, false, required ? supported : undefined, required ? () => this.codecState(recipient, required) === "pending" : undefined, required ? { member: recipient, feature: required } : undefined);
       } catch (error) {
         // The durable outbox owns retry after local backpressure; this is no uncertainty.
         if (!allowed() || !(error instanceof RoomLinkError) || error.code !== "limit" || !metadata && message.type !== "receipt") throw error;
@@ -814,10 +985,50 @@ export class RoomLink {
       }
       return frameDigest;
     }); } catch (error) {
+      if (error instanceof RoomCodecUnsupportedError || error instanceof RoomCodecPendingError) throw error;
       if (metadata && !queueStarted) throw new RoomNotSentError();
       throw error;
     }
   }
+  /** A newly ready member may have missed our first advertisement. Repair it
+   * independently of legacy request/reply and snapshot dedupe, without a timer. */
+  private publishCodecPresence(session: Session): Promise<void> {
+    if (session.codecPublishing) { session.codecDirty = true; return session.codecPublishing; }
+    const work = (async () => {
+      do {
+        session.codecDirty = false;
+        await this.serialSend(async () => {
+          if (!this.running || this.stopping || this.session !== session || !session.codecFeatures || !session.codecSession || session.phase !== "ready") return;
+          const row = this.current(session), identity = this.options.store.identity;
+          if (!this.publicationCurrent(session, row.current.digest)) return;
+          const own = roomMembers(row.current).find(member => member.fingerprint === identity.public.fingerprint);
+          if (!own) fail("untrusted");
+          const peers = this.currentPresence(own.exposedPeers), recipients = roomMembers(row.current).map(member => member.fingerprint).filter(member => member !== identity.public.fingerprint).sort();
+          if (!recipients.length) return;
+          const wire = await sealFrame({ epoch: row.current, identity, recipients,
+            plaintext: canonicalBytes({ v: 1, type: "presence", peers, features: ROOM_CODEC_FEATURES, codecSession: session.codecSession }),
+            ephemeral: true, codecFeatures: true, sequence: this.options.store.sequence });
+          if (!this.publicationCurrent(session, row.current.digest)) return;
+          const digest = await this.frameDigest(wire);
+          this.queueFrame(session, wire, digest, false,
+            () => this.publicationCurrent(session, row.current.digest) && peers.every(({ id }) => this.currentPresence(own.exposedPeers).some(value => value.id === id)),
+            true, undefined, undefined, undefined, true);
+        });
+      } while (session.codecDirty && this.session === session && this.running && !this.stopping);
+    })();
+    session.codecPublishing = work;
+    void work.finally(() => {
+      if (session.codecPublishing !== work) return;
+      session.codecPublishing = undefined;
+      const again = session.codecDirty; session.codecDirty = false;
+      // A peer event can arrive after the loop resolved but before this cleanup.
+      // Consume that real event once, after releasing the old publication slot.
+      if (again && this.session === session && this.running && !this.stopping && session.phase === "ready") {
+        void this.publishCodecPresence(session).catch(error => this.retry(session, error));
+      }
+    }).catch(() => undefined);
+    return work;
+  }
   async publishPresence(): Promise<void> {
     const session = this.session;
     if (!this.running || this.stopping || !session || session.phase !== "ready") return;
@@ -846,7 +1057,20 @@ export class RoomLink {
         const requestReply = !response && session.requestPresenceReply;
         const presenceKey = JSON.stringify([row.current.digest, recipients, peers, requestReply]);
         if (!response && !forceRequest && session.lastPresence === presenceKey) return;
+        // Positive codec evidence precedes the peer-state observation on this
+        // FIFO lane. Observed idle never races its own pending advertisement.
+        if (session.codecFeatures && session.codecSession) {
+          const featureWire = await sealFrame({ epoch: row.current, identity, recipients,
+            plaintext: canonicalBytes({ v: 1, type: "presence", peers, features: ROOM_CODEC_FEATURES, codecSession: session.codecSession }),
+            ephemeral: true, codecFeatures: true, sequence: this.options.store.sequence });
+          if (!this.publicationCurrent(session, row.current.digest)) return;
+          const featureDigest = await this.frameDigest(featureWire);
+          this.queueFrame(session, featureWire, featureDigest, false,
+            () => this.publicationCurrent(session, row.current.digest) && peers.every(({ id }) => this.currentPresence(own.exposedPeers).some(value => value.id === id)),
+            true, undefined, undefined, undefined, true);
+        }
         const wire = await sealFrame({ epoch: row.current, identity, recipients, plaintext: canonicalBytes({ v: 1, type: "presence", peers, ...(requestReply ? { requestReply: true } : {}) }), ...(session.ephemeral ? { ephemeral: true as const } : {}), sequence: this.options.store.sequence });
+        this.clockRecoveredAfterWrite();
         if (!this.publicationCurrent(session, row.current.digest)) return;
         // Machine-local exposure can change during reserve/encryption/signing even
         // when the signed roster is unchanged. Never emit an id it now withholds.
@@ -864,7 +1088,7 @@ export class RoomLink {
         session.lastPresence = presenceKey; sent = true;
       });
     } catch (error) {
-      this.retry(session); // Existing bounded reconnect, never a self-polling refresh retry.
+      this.retry(session, error); // Existing bounded reconnect, never a self-polling refresh retry.
       throw error;
     } finally {
       this.publishing = false;