@staix/agent-hub 0.30.0 → 0.32.0

package/src/rooms/link.ts

@@ -3,7 +3,8 @@ import { createBrokerAuth, decodeBrokerChallenge, encodeBrokerControl } from "..
 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, type RoomOutgoingInput } 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";
 
 export type RoomLinkState = "offline" | "connecting" | "online";
@@ -13,9 +14,11 @@ export interface RoomLinkOptions {
   store: RoomStore;
   name: string;
   presence?: () => readonly { id: string; state: string }[];
-  onPresence?: (value: { member: string; peers: readonly RoomPresencePeer[] }) => void;
+  onPresence?: (value: { member: string; peers: readonly RoomPresencePeer[]; restored?: true }) => void;
   onState?: (state: RoomLinkState) => void;
   application?: RoomLinkApplication;
+  refreshMs?: number;
+  now?: () => number;
 }
 /** Host-bound application ports; broker/config data never selects callbacks. */
 export interface RoomLinkContext {
@@ -28,6 +31,7 @@ export interface RoomLinkApplication {
   stored(context: RoomLinkContext, input: { digest: string; seq: string }): void;
   /** Fixed transport metadata only; never application completion or authority. */
   transportAck?(context: RoomLinkContext, input: { digest: string }): void;
+  receiptTtlMs?(context: RoomLinkContext): number;
   capacityChanged?(context: RoomLinkContext): void;
   gap?(context: RoomLinkContext, input: { sender: string; count: string }): void;
 }
@@ -40,12 +44,34 @@ export class RoomLinkError extends Error {
     super(`Room link: ${code}`); this.name = "RoomLinkError";
   }
 }
+/** Only before durable application enqueue: the Bus may retain its original queue item. */
+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"; }
+}
+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 Session {
+  closingHead?: PendingFrame;
+  refresh?: ReturnType<typeof setTimeout>;
+  refreshedAt?: number;
+  processingFrame?: string;
+  acknowledgedFrame?: string;
+  pendingPresenceReplies: Set<string>;
+  presenceAsked: boolean;
+  presenceRoster?: string;
+  outbound: PendingFrame[];
+  outboundBytes: number;
+  frameSent: boolean;
+  retryAttempt: number;
+  frameRetry?: ReturnType<typeof setTimeout>;
+  lastPresence?: string;
+  ephemeral?: boolean;
   ws: WebSocket;
   generation: number;
   room: string;
@@ -95,6 +121,11 @@ function presence(bytes: Uint8Array, exposed: readonly string[]): RoomPresencePe
 /** One bounded, generation-fenced outbound connection. No callback receives body text or task data. */
 export class RoomLink {
   private running = false;
+  private stopping = false;
+  private stopWork?: Promise<void>;
+  private stoppedFrame?: { digest: string; resolve: () => void };
+  private readonly refreshMs: number;
+  private readonly applicationPauses = new Set<symbol>();
   private generation = 0;
   private session?: Session;
   private reconnect?: ReturnType<typeof setTimeout>;
@@ -109,10 +140,12 @@ export class RoomLink {
   private forcePresenceRequest = false;
   private republish?: ReturnType<typeof setTimeout>;
   private sendTail: Promise<void> = Promise.resolve();
-  constructor(private readonly options: RoomLinkOptions) {}
+  constructor(private readonly options: RoomLinkOptions) { this.refreshMs = roomRefreshPeriod(options.refreshMs); }
 
   /** Advisory transport state without copying or decoding a room epoch for a status poll. */
   get connectionState(): RoomLinkState { return this.state; }
+  /** Negotiated transport evidence only; unknown until this session is ready. */
+  get livenessTracked(): boolean | undefined { return this.session?.phase === "ready" ? this.session.ephemeral : undefined; }
   status(): { state: RoomLinkState; members: number } {
     try {
       const row = this.options.store.get(this.options.name);
@@ -120,39 +153,105 @@ export class RoomLink {
     } catch { return { state: "offline", members: 0 }; }
   }
   async start(): Promise<void> {
-    if (this.running) return;
+    if (this.running || this.stopping) return;
+    this.stopWork = undefined;
     this.running = true;
     const generation = ++this.generation;
     try { await assertRoomCryptoReady(); } catch { this.running = false; throw new RoomLinkError("unavailable"); }
     if (!this.running || generation !== this.generation) return;
     this.connect();
   }
-  stop(): void {
-    this.running = false;
+  stop(): Promise<void> {
+    if (this.stopWork) return this.stopWork;
+    this.running = false; this.stopping = true;
+    const session = this.session;
+    if (session && (session.frameSent || session.frameRetry)) session.closingHead = session.outbound[0];
     if (this.reconnect) clearTimeout(this.reconnect);
     this.reconnect = undefined;
-    this.disconnect();
+    if (this.republish) clearTimeout(this.republish);
+    this.republish = undefined;
+    if (session?.refresh) clearTimeout(session.refresh);
+    if (session) {
+      // A storage control may already be waiting behind a slow application turn.
+      // Consume only those controls before sealing the final FIFO observation.
+      const queued = session.queue.splice(0); session.queuedBytes = 0;
+      for (const bytes of queued) this.receive(session, Uint8Array.from(bytes).buffer);
+    }
+    this.setState("offline");
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<void>(resolve => { timer = setTimeout(resolve, ROOM_STOP_TIMEOUT_MS); });
+    // Storage controls are consumed directly during shutdown, outside the serial
+    // receive lane which may still be awaiting application work being fenced.
+    const final = session?.phase === "ready" ? this.finalPresence(session).catch(() => undefined) : Promise.resolve();
+    this.stopWork = Promise.race([final, deadline]).finally(() => {
+      if (timer) clearTimeout(timer);
+      this.disconnect(session); this.stoppedFrame?.resolve(); this.stoppedFrame = undefined; this.stopping = false;
+    });
+    return this.stopWork;
+  }
+  private async finalPresence(session: Session): Promise<void> {
+    await this.serialSend(async () => {
+      const row = this.current(session, undefined, true), identity = this.options.store.identity;
+      if (session.phase !== "ready" || session.roster?.digest !== row.current.digest) return;
+      const own = roomMembers(row.current).find(member => member.fingerprint === identity.public.fingerprint);
+      if (!own) fail("untrusted");
+      const recipients = roomMembers(row.current).map(member => member.fingerprint).filter(member => member !== identity.public.fingerprint).sort();
+      if (!recipients.length) return;
+      const peers = this.currentPresence(own.exposedPeers).map(peer => ({ ...peer, state: "offline" as const }));
+      const wire = await sealFrame({ epoch: row.current, identity, recipients, plaintext: canonicalBytes({ v: 1, type: "presence", peers }), ...(session.ephemeral ? { ephemeral: true as const } : {}), sequence: this.options.store.sequence });
+      this.current(session, row.current.digest, true);
+      const digest = await this.frameDigest(wire);
+      this.current(session, row.current.digest, true);
+      // Unattempted RAM work can be withdrawn; durable application/receipt rows
+      // remain owned by the Store. An attempted head keeps its exact FIFO place.
+      const attempted = session.closingHead;
+      session.outbound = attempted ? [attempted] : [];
+      session.outboundBytes = attempted?.wire.byteLength ?? 0;
+      const stored = new Promise<void>(resolve => { this.stoppedFrame = { digest, resolve }; });
+      this.queueFrame(session, wire, digest, false,
+        () => { try { this.current(session, row.current.digest, true); return peers.every(peer => this.currentPresence(own.exposedPeers).some(value => value.id === peer.id)); } catch { return false; } }, true);
+      return stored;
+    });
   }
   refresh(): void {
+    if (this.stopping) return;
     if (this.reconnect) clearTimeout(this.reconnect);
     this.reconnect = undefined;
     this.disconnect();
     if (this.running) this.connect();
   }
+  private armPresenceRefresh(session: Session): void {
+    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.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) {
+        session.pendingPresenceReplies.clear(); session.presenceAsked = false;
+        session.requestPresenceReply = true; this.forcePresenceRequest = true;
+        void this.publishPresence().catch(() => this.retry(session));
+      }
+      this.armPresenceRefresh(session);
+    }, this.refreshMs);
+    session.refresh.unref?.();
+  }
   private setState(state: RoomLinkState): void {
     if (this.state === state) return;
     this.state = state;
     try { this.options.onState?.(state); } catch { /* observation never changes transport authority */ }
   }
-  private current(session: Session, digest?: string): RoomState {
-    if (!this.running || this.session !== session || session.generation !== this.generation || session.ws.readyState !== WebSocket.OPEN) fail("state_changed");
+  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"); }
     if (!row || row.left || row.current.room !== session.room || row.broker !== session.broker || (digest !== undefined && row.current.digest !== digest)) fail("state_changed");
     return row;
   }
   private isCurrent(session: Session, digest: string): boolean {
-    try { this.current(session, digest); return true; } catch { return false; }
+    try { if (this.stopping) return false; this.current(session, digest); return true; } catch { return false; }
   }
   private publicationCurrent(session: Session, digest: string): boolean {
     return session.phase === "ready" && session.roster?.digest === digest && this.isCurrent(session, digest);
@@ -165,6 +264,7 @@ export class RoomLink {
     if (!this.publicationCurrent(session, row.current.digest) || !this.options.store.ordinaryInboxAvailable(this.options.name, bytes)) return;
     // Intent survives coalescing, ordinary responses and publication failure.
     // Only an actually sent request with current capacity may clear the numeric flag.
+    if (!this.forcePresenceRequest) { session.pendingPresenceReplies.clear(); session.presenceAsked = false; }
     session.requestPresenceReply = true; this.forcePresenceRequest = true;
     try { await this.publishPresence(); }
     catch (error) { this.retry(session); throw error; }
@@ -194,7 +294,7 @@ export class RoomLink {
         }
         let peers: RoomPresencePeer[] | undefined;
         try { peers = presence(entry.plaintext, member.exposedPeers); } catch { /* a rotation may have removed an exposed id since the durable receive */ }
-        if (peers) { try { this.options.onPresence?.({ member: entry.sender, peers }); } catch { /* observation only */ } }
+        if (peers) { try { this.options.onPresence?.({ member: entry.sender, peers, restored: true }); } catch { /* observation only */ } }
       }
       // Presence is ephemeral: stale exposure/member metadata is discarded, never
       // replayed after a rotation or left at the head of recovery forever.
@@ -204,6 +304,7 @@ export class RoomLink {
     }
   }
   private async deliverApplication(session: Session, digest: string, input: Parameters<RoomLinkApplication["receive"]>[1]): Promise<void> {
+    if (!this.running || this.stopping) fail("state_changed");
     try { await this.options.application?.receive(this.context(session, digest), input); }
     catch (error) { if (!(error instanceof RoomApplicationDeferredError)) throw error; }
     this.current(session, digest);
@@ -233,12 +334,16 @@ export class RoomLink {
     this.republish = undefined;
     if (session) {
       clearTimeout(session.handshake);
+      if (session.refresh) clearTimeout(session.refresh);
+      if (session.frameRetry) clearTimeout(session.frameRetry);
+      session.outbound.length = 0; session.outboundBytes = 0; session.pendingPresenceReplies.clear();
       session.queue.length = 0; session.queuedBytes = 0; session.deferredFrame = undefined;
       try { session.ws.close(1000, "disconnected"); } catch { /* already closed */ }
     }
     this.setState("offline");
   }
   private retry(session?: Session): void {
+    if (this.stopping) return;
     if (session && this.session !== session) return;
     this.disconnect(session);
     if (!this.running || this.reconnect) return;
@@ -259,10 +364,11 @@ export class RoomLink {
     } catch { this.setState("offline"); return; }
     url.pathname = `/v1/rooms/${row.current.room}`;
     let ws: WebSocket;
-    try { ws = new WebSocket(url.href); } catch { this.retry(); return; }
+    // 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; }
     ws.binaryType = "arraybuffer";
     const generation = ++this.generation;
-    const session: Session = { ws, generation, room: row.current.room, broker: row.broker, phase: "challenge", queue: [], queuedBytes: 0, processing: false, initialRoster: true, requestPresenceReply: true,
+    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;
@@ -272,11 +378,84 @@ export class RoomLink {
     ws.addEventListener("error", () => this.retry(session));
   }
   private send(session: Session, bytes: Uint8Array): void {
-    this.current(session);
+    this.current(session, undefined, this.stopping);
     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 {
+    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));
+      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;
+    this.pumpFrames(session);
+  }
+  private pumpFrames(session: Session): void {
+    if (session.frameSent || session.frameRetry || !session.outbound.length) return;
+    this.current(session, undefined, this.stopping);
+    const frame = session.outbound[0]!;
+    // An expired backoff timer is not proof that a pre-stop attempt was stored.
+    if (this.stopping && frame === session.closingHead) return;
+    if (frame.retained && !frame.retained()) {
+      // Disposed/expired intent cannot survive in the transport's RAM queue.
+      session.outbound.shift(); session.outboundBytes -= frame.wire.byteLength; session.retryAttempt = 0;
+      this.pumpFrames(session); return;
+    }
+    if (!frame.current()) {
+      if (!frame.presence) fail("state_changed");
+      session.outbound.shift(); session.outboundBytes -= frame.wire.byteLength; session.lastPresence = undefined;
+      this.pumpFrames(session);
+      void this.publishPresence().catch(() => this.retry(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;
+    const onSent = frame.onSent; frame.onSent = undefined; onSent?.();
+  }
+  private storedFrame(session: Session, digest: string): void {
+    if (session.outbound[0]?.digest !== digest) return;
+    const frame = session.outbound.shift()!; session.outboundBytes -= frame.wire.byteLength;
+    if (session.closingHead === frame) session.closingHead = undefined;
+    session.frameSent = false; session.retryAttempt = 0;
+    if (session.frameRetry) clearTimeout(session.frameRetry);
+    session.frameRetry = undefined;
+    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;
+    const delay = Math.min(30_000, 250 * 2 ** Math.min(session.retryAttempt++, 7));
+    session.frameRetry = setTimeout(() => {
+      session.frameRetry = undefined;
+      if (this.session !== session || !this.running || session.phase !== "ready") return;
+      try { this.pumpFrames(session); } catch { this.retry(session); }
+    }, delay);
+    session.frameRetry.unref?.();
+    this.pumpFrames(session);
+  }
   private receive(session: Session, data: unknown): void {
+    if (this.stopping && this.session === session) {
+      if (!(data instanceof ArrayBuffer) || data.byteLength > LIMITS.packetBytes) return;
+      try {
+        const row = exact(packet(new Uint8Array(data)), ["v", "type", "digest", "seq", "duplicate"]);
+        if (row.type === "stored" && typeof row.digest === "string" && DIGEST.test(row.digest)
+          && typeof row.seq === "string" && /^[1-9][0-9]{0,19}$/.test(row.seq) && typeof row.duplicate === "boolean") {
+          this.current(session, undefined, true);
+          if (this.options.store.receiptSendable(this.options.name, row.digest)) {
+            this.options.store.markStored(this.options.name, row.digest, row.seq);
+            this.options.store.retireStoredReceipt(this.options.name, row.digest);
+          }
+          this.storedFrame(session, row.digest);
+        }
+      } catch { /* Invalid controls cannot complete graceful shutdown. */ }
+      return;
+    }
     if (this.session !== session || !this.running) return;
     if (!(data instanceof ArrayBuffer) || data.byteLength === 0 || data.byteLength > LIMITS.packetBytes || session.queue.length + (session.deferredFrame ? 1 : 0) >= LIMITS.packets || session.queuedBytes + (session.deferredFrame?.byteLength ?? 0) + data.byteLength > LIMITS.queuedBytes) { this.retry(session); return; }
     const bytes = new Uint8Array(data).slice();
@@ -327,20 +506,29 @@ export class RoomLink {
       return;
     }
     if (message.type === "ready") {
-      const ready = exact(message, ["v", "type", "room", "member", "epoch", "digest"]), roster = session.roster;
+      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();
       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");
         session.ownerUpgrading = true;
         this.send(session, local.wire); return;
       }
+      if (session.presenceRoster !== roster.digest) {
+        session.presenceRoster = roster.digest; session.pendingPresenceReplies.clear(); session.presenceAsked = false;
+        session.requestPresenceReply = true; session.lastPresence = undefined;
+      }
+      session.ephemeral = ready.ephemeral === true;
       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");
       const context = this.context(session, local.current.digest);
       this.options.application?.members(context);
+      this.restoreReceipts(session);
       await this.retryPendingApplications();
       this.current(session, local.current.digest);
       await this.options.application?.online(context);
@@ -365,7 +553,14 @@ export class RoomLink {
     if (message.type === "stored") {
       const row = exact(message, ["v", "type", "digest", "seq", "duplicate"]);
       if (typeof row.digest !== "string" || !DIGEST.test(row.digest) || typeof row.seq !== "string" || !/^[1-9][0-9]{0,19}$/.test(row.seq) || typeof row.duplicate !== "boolean") fail();
+      const receipt = this.options.store.receiptSendable(this.options.name, row.digest);
+      if (receipt) {
+        this.options.store.markStored(this.options.name, row.digest, row.seq);
+        this.options.store.retireStoredReceipt(this.options.name, row.digest);
+      }
+      this.storedFrame(session, row.digest);
       this.options.application?.stored(this.context(session, local.current.digest), { digest: row.digest, seq: row.seq });
+      this.restoreReceipts(session);
       return; // Broker storage is not a signed recipient application-completion receipt.
     }
     if (message.type === "queue_ack") {
@@ -381,10 +576,17 @@ export class RoomLink {
       return;
     }
     if (message.type === "error") {
-      const error = exact(message, ["v", "type", "code"]);
+      const error = exact(message, Object.hasOwn(message, "digest") ? ["v", "type", "code", "digest"] : ["v", "type", "code"]);
+      if (error.digest !== undefined && (error.code !== "queue_full" || typeof error.digest !== "string" || !DIGEST.test(error.digest))) fail();
+      if (error.code === "queue_full") {
+        // Older brokers omit correlation; one frame in flight makes its head unambiguous.
+        const digest = typeof error.digest === "string" ? error.digest : session.outbound[0]?.digest;
+        if (digest) this.backoffFrame(session, digest);
+        return;
+      }
       // X2 declares these refusal controls nonterminal. Their unsigned control
       // cannot settle any application; its local ACK deadline records uncertainty.
-      if (error.code === "queue_full" || error.code === "replay_refused" || error.code === "unexpected_ack") return;
+      if (error.code === "replay_refused" || error.code === "unexpected_ack") return;
       fail("unavailable");
     }
     fail();
@@ -449,6 +651,7 @@ export class RoomLink {
       else throw error;
     }
     const acceptedDigest = await this.frameDigest(bytes);
+    session.processingFrame = acceptedDigest;
     const latest = this.frameCurrent(session, frame);
     if (latest.current.digest !== digest) refused = "trust_changed";
     if (result?.status === "stale") {
@@ -471,6 +674,8 @@ 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 */ }
         this.current(session, digest);
         this.options.store.settleInbox(this.options.name, acceptedDigest);
@@ -486,9 +691,33 @@ export class RoomLink {
     this.frameCurrent(session, frame);
     // This ACK only retires ciphertext from the broker queue. A durable refusal
     // or stale drop is never a signed recipient application-completion receipt.
-    this.send(session, encodeBrokerControl({ v: 1, type: "received", digest: acceptedDigest }));
+    this.retireFrame(session, frame, acceptedDigest);
+    session.processingFrame = undefined; session.acknowledgedFrame = undefined;
     await this.refreshPresenceIfCapacityFree().catch(() => undefined);
   }
+  private retireFrame(session: Session, frame: FrameWire, digest: string): void {
+    this.frameCurrent(session, frame);
+    // Final admission commits its receipt; deferred admission retains the durable inbox.
+    // Waiting for broker storage or deferred admission would pin capacity one indefinitely.
+    if (this.options.store.applicationReceipt(this.options.name, digest)
+      && !this.options.store.receiptStored(this.options.name, digest)) fail("unavailable");
+    this.send(session, encodeBrokerControl({ v: 1, type: "received", digest }));
+    session.acknowledgedFrame = digest;
+    this.pumpFrames(session);
+  }
+  private restoreReceipts(session: Session): void {
+    if (!this.running || this.stopping) return;
+    this.current(session);
+    this.options.store.expireReceipts(this.options.name);
+    for (const entry of this.options.store.outbox(this.options.name)) {
+      if (entry.kind !== "receipt" || session.outbound.some(frame => frame.digest === entry.digest)) continue;
+      if (session.outbound.length >= LIMITS.packets || session.outboundBytes + entry.wire.byteLength > LIMITS.queuedBytes) break;
+      const roster = this.current(session).current.digest;
+      this.queueFrame(session, entry.wire, entry.digest, false, () => this.publicationCurrent(session, roster), false,
+        () => this.options.store.receiptSendable(this.options.name, entry.digest), undefined,
+        entry.receiptFor === session.processingFrame ? entry.receiptFor : undefined);
+    }
+  }
   private async frameDigest(bytes: Uint8Array): Promise<string> {
     return encodeBase64url(await sha256(bytes));
   }
@@ -508,34 +737,100 @@ export class RoomLink {
     this.sendTail = next.then(() => undefined, () => undefined);
     return next;
   }
+  /** Host-only admission pause; trust/current predicates remain independent. */
+  async quiesceApplications(): Promise<() => void> {
+    const token = Symbol(); this.applicationPauses.add(token);
+    await this.sendTail;
+    let released = false;
+    return () => { if (!released) { released = true; this.applicationPauses.delete(token); } };
+  }
   async publishApplication(message: RoomMessage, recipient: string, outgoing?: RoomOutgoingInput, current: () => boolean = () => true): Promise<string> {
     const plaintext = encodeRoomMessage(message), metadata = outgoing ? { ...outgoing } : undefined;
     const session = this.session;
-    if (!session || session.phase !== "ready") fail("unavailable");
+    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 digest = this.current(session).current.digest;
     const allowed = () => this.publicationCurrent(session, digest) && current();
-    return this.serialSend(async () => {
-      if (!allowed()) fail("state_changed");
+    const admitted = () => this.applicationPauses.size === 0 && allowed();
+    let queueStarted = false;
+    try {
+      let presenceWork: Promise<void> | undefined;
+      // A chat is the transport barrier for earlier observations. Receipts keep
+      // their durable-commit/ACK path and do not wait behind a new observation.
+      if (message.type === "chat" && this.republish) {
+        clearTimeout(this.republish); this.republish = undefined;
+        presenceWork = this.publishPresence();
+        // It may fail before reaching the serial lane. Observe rejection now;
+        // the reserved chat slot still awaits the original error below.
+        void presenceWork.catch(() => undefined);
+      }
+      // 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");
+      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") {
+        const pending = this.options.store.receiptStored(this.options.name, message.frame);
+        if (pending?.state === "dispatching") {
+          if (!decodeFrame(pending.wire).recipients.includes(recipient)) fail("untrusted");
+          this.restoreReceipts(session);
+          return pending.digest;
+        }
+      }
       const row = this.current(session, digest);
       if (!roomMembers(row.current).some(member => member.fingerprint === recipient) || recipient === this.options.store.identity.public.fingerprint) fail("untrusted");
-      const wire = await sealFrame({ epoch: row.current, identity: this.options.store.identity, recipients: [recipient], plaintext, sequence: this.options.store.sequence });
-      if (!allowed()) fail("state_changed");
-      const record = metadata ? await this.options.store.queueApplication(this.options.name, wire, metadata, allowed) : undefined;
-      const frameDigest = record?.digest ?? await this.frameDigest(wire);
+      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");
+      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) {
+          // 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();
+          throw error;
+        }
+        frameDigest = record.frameDigest ?? record.digest;
+      } else if (message.type === "receipt") {
+        const ttlMs = this.options.application?.receiptTtlMs?.(this.context(session, digest)) ?? RECEIPT_TTL_MS;
+        const receipt = await this.options.store.queueReceipt(this.options.name, message.frame, wire, { ttlMs, replaceExisting: true }, admitted);
+        if (!allowed()) fail("state_changed");
+        if (receipt.state === "accepted") return receipt.digest; // Existing broker-stored proof needs no pending wire slot.
+        frameDigest = receipt.digest; wire = receipt.wire;
+      } else frameDigest = await this.frameDigest(wire);
       if (!allowed()) fail("state_changed");
-      this.send(session, wire);
+      try {
+        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);
+      } 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;
+        if (session.outbound[0]?.digest === frameDigest) this.backoffFrame(session, frameDigest);
+      }
       return frameDigest;
-    });
+    }); } catch (error) {
+      if (metadata && !queueStarted) throw new RoomNotSentError();
+      throw error;
+    }
   }
   async publishPresence(): Promise<void> {
     const session = this.session;
-    if (!session || session.phase !== "ready") return;
+    if (!this.running || this.stopping || !session || session.phase !== "ready") return;
     if (this.publishing) { this.publishDirty = true; return; }
+    // Keep the already scheduled coalesced snapshot. Cancelling it on every
+    // state flip turns an awaited burst back into one durable seal per call.
+    if (this.republish && !this.replyPresence && !this.forcePresenceRequest) { this.publishDirty = true; return; }
     if (this.republish) clearTimeout(this.republish);
     this.republish = undefined; this.publishDirty = false;
-    const response = this.replyPresence && !this.forcePresenceRequest;
+    const forceRequest = this.forcePresenceRequest;
+    const response = this.replyPresence;
     if (response) this.replyPresence = false;
-    this.forcePresenceRequest = false;
+    this.forcePresenceRequest = response && forceRequest;
     let sent = false;
     this.publishing = true;
     try {
@@ -549,17 +844,24 @@ export class RoomLink {
       await this.serialSend(async () => {
         if (!this.publicationCurrent(session, row.current.digest)) return;
         const requestReply = !response && session.requestPresenceReply;
-        const wire = await sealFrame({ epoch: row.current, identity, recipients, plaintext: canonicalBytes({ v: 1, type: "presence", peers, ...(requestReply ? { requestReply: true } : {}) }), sequence: this.options.store.sequence });
+        const presenceKey = JSON.stringify([row.current.digest, recipients, peers, requestReply]);
+        if (!response && !forceRequest && session.lastPresence === presenceKey) return;
+        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 });
         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.
+        const frameDigest = await this.frameDigest(wire);
+        if (!this.publicationCurrent(session, row.current.digest)) return;
         const allowed = new Set(this.currentPresence(own.exposedPeers).map(peer => peer.id));
         if (peers.some(peer => !allowed.has(peer.id))) return;
-        this.send(session, wire); sent = true;
-        if (requestReply) {
-          session.requestPresenceReply = false;
-          if (this.retiredPresenceBytes && this.options.store.ordinaryInboxAvailable(this.options.name, this.retiredPresenceBytes)) this.retiredPresenceBytes = 0;
-        }
+        this.queueFrame(session, wire, frameDigest, requestReply,
+          () => this.publicationCurrent(session, row.current.digest) && peers.every(peer => this.currentPresence(own.exposedPeers).some(value => value.id === peer.id)), true, undefined,
+          requestReply ? () => {
+            if (!session.presenceAsked) { session.pendingPresenceReplies = new Set(recipients); session.presenceAsked = true; }
+            session.requestPresenceReply = session.pendingPresenceReplies.size > 0;
+            if (this.retiredPresenceBytes && this.options.store.ordinaryInboxAvailable(this.options.name, this.retiredPresenceBytes)) this.retiredPresenceBytes = 0;
+          } : undefined);
+        session.lastPresence = presenceKey; sent = true;
       });
     } catch (error) {
       this.retry(session); // Existing bounded reconnect, never a self-polling refresh retry.

package/src/rooms/liveness.ts

@@ -0,0 +1,11 @@
+/** Host timing only; signed presence remains the existing v1 ids/state payload. */
+export const ROOM_REFRESH_MS = 30_000;
+export const ROOM_PRESENCE_MISSES = 3;
+export const ROOM_STOP_TIMEOUT_MS = 2_000;
+
+export function roomRefreshPeriod(value = ROOM_REFRESH_MS): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > Math.floor(2_147_483_647 / ROOM_PRESENCE_MISSES)) {
+    throw new Error("room refresh period is invalid; use a positive whole duration within the timer bound");
+  }
+  return value;
+}