@staix/agent-hub 0.29.0 → 0.31.0

package/src/rooms/link.ts

@@ -3,7 +3,7 @@ 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 { decodeRoomMessage, encodeRoomMessage, type RoomMessage } from "./application.ts";
 
 export type RoomLinkState = "offline" | "connecting" | "online";
@@ -28,6 +28,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 +41,31 @@ 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 {
+  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;
@@ -165,6 +185,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; }
@@ -233,6 +254,8 @@ export class RoomLink {
     this.republish = undefined;
     if (session) {
       clearTimeout(session.handshake);
+      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 */ }
     }
@@ -259,10 +282,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;
@@ -276,6 +300,59 @@ 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 {
+    this.current(session);
+    // Only an unsent observation may be replaced. Never reorder an attempted frame.
+    if (presence) {
+      const at = session.outbound.findIndex((frame, index) => 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);
+    const frame = session.outbound[0]!;
+    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;
+    session.frameSent = false; session.retryAttempt = 0;
+    if (session.frameRetry) clearTimeout(session.frameRetry);
+    session.frameRetry = undefined;
+    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.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; }
@@ -327,13 +404,19 @@ 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;
@@ -341,6 +424,7 @@ export class RoomLink {
       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 +449,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 +472,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 +547,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 +570,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 +587,32 @@ 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 {
+    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));
   }
@@ -511,29 +635,86 @@ export class RoomLink {
   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 (!session || session.phase !== "ready") { if (metadata) throw new RoomNotSentError(); fail("unavailable"); }
     const digest = this.current(session).current.digest;
     const allowed = () => this.publicationCurrent(session, digest) && current();
-    return this.serialSend(async () => {
+    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 (!allowed()) 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 });
+      let 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 frameDigest: string;
+      if (metadata) {
+        queueStarted = true;
+        let record: Awaited<ReturnType<RoomStore["queueApplication"]>>;
+        try { record = await this.options.store.queueApplication(this.options.name, wire, metadata, allowed); }
+        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 }, allowed);
+        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.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 && !forceRequest;
     if (response) this.replyPresence = false;
     this.forcePresenceRequest = false;
     let sent = false;
@@ -549,17 +730,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/remote-peer.ts

@@ -1,16 +1,27 @@
 /** A host-owned room transport, never a task owner, reviewer, tool caller or native runtime. */
 import { BasePeer, type DeliveryReceipt } from "../hub/peers.ts";
 import type { Envelope, PeerState } from "../hub/envelope.ts";
-import { parseRemotePeerId, type RoomChatEnvelope } from "./application.ts";
+import { encodeRoomMessage, parseRemotePeerId, type RoomChatEnvelope } from "./application.ts";
 import { readRoomOutbound, roomBoundary, type RoomBoundaryContext } from "./boundary.ts";
+import { RoomNotSentError } from "./link.ts";
 
 export interface RemotePeerPorts {
   member: string;
   context: (env: Envelope) => RoomBoundaryContext;
   send: (env: RoomChatEnvelope, deliveryId: string, expiresAt: number, current: () => boolean, withheld: boolean) => Promise<void>;
   now?: () => number;
+  /** Current Bus admission, separate from immutable room trust/exposure proof. */
+  ready?: () => boolean;
   /** Record post-publication trust loss locally before any late signed outcome can settle it. */
-  quarantine?: (deliveryId: string) => void;
+  quarantine?: (deliveryId: string, reason?: "not_exposed" | "boundary_refused" | "invalid_message") => void;
+  /** Requeue a send that the room link proves never reached its durable outbox. */
+  notSent?: (deliveryId: string) => boolean;
+  /** True for any durable RoomStore row with this Bus delivery ID; false only proves absence. */
+  queued?: (deliveryId: string) => boolean | undefined;
+  /** Persist a conservative Bus hold when neither requeue nor durable Store retry is available. */
+  holdMissing?: (deliveryId: string) => boolean;
+  /** Wake host retry scheduling after an active intent meets an external Bus fence. */
+  waiting?: () => void;
 }
 
 export class RemotePeer extends BasePeer {
@@ -20,8 +31,11 @@ export class RemotePeer extends BasePeer {
   private generation = 0;
   private running = false;
   private online = false;
+  private blockedNotSent = false;
   private observed: PeerState = "offline";
   private readonly pending = new Set<string>();
+  private readonly waitingForReady = new Set<string>();
+  private readonly sending = new Set<string>();
   private readonly deadlines = new Map<string, number>();
   constructor(id: string, readonly remoteRoom: string, readonly remoteQueueTtlMs: number, private readonly ports: RemotePeerPorts) {
     super(id);
@@ -31,50 +45,203 @@ export class RemotePeer extends BasePeer {
   }
   // Room ack/TTL deadlines, not the native inactivity watchdog, own transport settlement.
   protected override touch(): void { this.clearWatchdog(); }
-  private update(): void { this.setState(this.pending.size ? "busy" : this.running && this.online ? this.observed : "offline"); }
+  private update(): void { this.setState(this.pending.size ? "busy" : this.running && this.online && !this.blockedNotSent ? this.observed : "offline"); }
+  private head(): string | undefined { return this.pending.values().next().value as string | undefined; }
+  /** Reserve recovered Store intents synchronously before any proof decrypt/screen await. */
+  reservePending(deliveryId: string): void {
+    this.pending.add(deliveryId);
+    this.waitingForReady.add(deliveryId);
+    this.blockedNotSent = false;
+    this.update();
+  }
   async start(): Promise<void> { this.running = true; this.generation++; this.update(); }
   async stop(): Promise<void> {
     this.running = false; this.generation++;
-    for (const id of [...this.pending]) { this.quarantine(id); this.receipt({ id, state: "needs_review", reason: "room transport stopped" }); }
+    // Active journal rows and their sealed room frames survive a sender restart.
+    // Stop only fences in-flight callbacks; it is not evidence of an uncertain send.
+    this.pending.clear();
+    this.waitingForReady.clear();
     this.deadlines.clear(); this.update();
   }
-  private quarantine(id: string): void { try { this.ports.quarantine?.(id); } catch { /* the Bus still retains uncertainty if room storage is unavailable */ } }
-  presence(state: PeerState, online: boolean): void { this.observed = state; this.online = online; this.update(); }
+  private quarantine(id: string, reason?: "not_exposed" | "boundary_refused" | "invalid_message"): void { try { this.ports.quarantine?.(id, reason); } catch { /* The durable application remains for TTL review if local storage is unavailable. */ } }
+  private ready(): boolean { try { return this.ports.ready?.() !== false; } catch { return false; } }
+  waitForReady(deliveryId: string): void {
+    this.waitingForReady.add(deliveryId);
+    this.pending.add(deliveryId);
+    this.blockedNotSent = false;
+    this.update();
+    try { this.ports.waiting?.(); } catch { /* A future real Bus callback will retry. */ }
+  }
+  /** Consume an immediate resume token while retaining the active FIFO head. */
+  deferResume(deliveryId: string): void { this.waitingForReady.delete(deliveryId); }
+  readyToResume(deliveryId: string): boolean {
+    return this.waitingForReady.has(deliveryId) && this.head() === deliveryId && this.running && this.online && !this.blockedNotSent && this.ready();
+  }
+  isPendingHead(deliveryId: string): boolean { return this.head() === deliveryId; }
+  private holdMissing(id: string): boolean { try { return this.ports.holdMissing?.(id) === true; } catch { return false; } }
+  private notSent(id: string, blockUntilWake = true): void {
+    let retained: boolean | undefined;
+    try { retained = this.ports.queued?.(id); } catch { retained = undefined; }
+    if (retained === true) {
+      // A prior attempt is already durable. Never create a second Bus delivery ID.
+      if (!blockUntilWake || !this.ready()) this.waitForReady(id);
+      else { this.blockedNotSent = true; this.update(); }
+      return;
+    }
+    if (retained === undefined) {
+      // Store read failure cannot prove not-sent, so preserve the active RAM fence.
+      this.blockedNotSent = true; this.update(); return;
+    }
+    let requeued = false;
+    try { requeued = this.ports.notSent?.(id) === true; } catch { /* Keep uncertainty handling on the state transition below. */ }
+    // An expired requeue may have completed the Bus row synchronously. In that
+    // case its receipt already removed this ID and drained the following FIFO item.
+    if (!this.pending.has(id)) { this.update(); return; }
+    if (requeued) {
+      this.waitingForReady.delete(id);
+      this.blockedNotSent = blockUntilWake;
+      this.pending.delete(id);
+      this.update();
+      return;
+    }
+    const held = retained === false && this.holdMissing(id);
+    if (held) {
+      this.waitingForReady.delete(id);
+      this.blockedNotSent = false;
+      this.pending.delete(id);
+    } else this.blockedNotSent = true; // Keep the ID busy if the journal write failed or the actor went stale.
+    this.update();
+  }
+  presence(state: PeerState, online: boolean): void {
+    if (online && (!this.online || state !== this.observed)) this.blockedNotSent = false;
+    this.observed = state; this.online = online; this.update();
+  }
+  /** Rehydrate a journal-owned delivery without creating a new bus delivery or application id. */
+  async resume(env: Envelope, deliveryId: string, expiresAt: number, immutable: RoomChatEnvelope): Promise<void> {
+    if (!this.running || !this.online || !this.ready() || this.blockedNotSent || !deliveryId || this.head() !== deliveryId || !Number.isSafeInteger(expiresAt) || expiresAt <= (this.ports.now?.() ?? Date.now())) return;
+    this.waitingForReady.delete(deliveryId);
+    this.pending.add(deliveryId); this.update();
+    await this.publish(env, deliveryId, expiresAt, this.generation, immutable);
+  }
+  /** A link becoming ready is an actual wake-up after a typed not-sent refusal. */
+  wake(): void { this.blockedNotSent = false; this.update(); }
   setRemoteDeadline(envelopeId: string, expiresAt: number): void {
     if (Number.isSafeInteger(expiresAt) && expiresAt > 0 && this.deadlines.size < 200) this.deadlines.set(envelopeId, expiresAt);
   }
   receipt(receipt: DeliveryReceipt): boolean {
     if (!this.pending.has(receipt.id)) return false;
-    if (receipt.state !== "accepted") this.pending.delete(receipt.id);
+    if (receipt.state !== "accepted") { this.pending.delete(receipt.id); this.waitingForReady.delete(receipt.id); }
     this.delivery(receipt); // Journal settlement precedes a state transition that may drain the next item.
     this.update();
     return true;
   }
+  /** Clear transport wait after the Bus records a signed outcome or durable hold. */
+  settled(deliveryId: string): void { this.pending.delete(deliveryId); this.waitingForReady.delete(deliveryId); this.update(); }
+  /** Reserve a restart-era active Store delivery before asynchronous proof validation. */
+  retainPending(deliveryId: string): void {
+    if (this.pending.has(deliveryId)) return;
+    this.pending.add(deliveryId);
+    this.waitingForReady.add(deliveryId);
+    this.update();
+  }
   async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
-    if (!this.running || !this.online || !deliveryId || envs.length !== 1) throw new Error("room: unavailable");
+    if (!deliveryId || envs.length !== 1) throw new Error("room: unavailable");
+    if (!this.running || !this.online) { this.notSent(deliveryId); return; }
+    if (!this.ready()) { this.notSent(deliveryId, false); return; }
     const env = envs[0]!, generation = this.generation;
     const expiresAt = this.deadlines.get(env.id);
     this.deadlines.delete(env.id);
-    const context = this.ports.context(env);
-    const current = () => this.running && this.online && this.generation === generation && context.current();
+    if (expiresAt === undefined) throw new Error("room: queued deadline unavailable");
+    this.pending.add(deliveryId); this.update();
+    await this.publish(env, deliveryId, expiresAt, generation);
+  }
+  private async publish(env: Envelope, deliveryId: string, expiresAt: number, generation: number, immutable?: RoomChatEnvelope): Promise<void> {
+    if (this.sending.has(deliveryId)) return;
+    this.sending.add(deliveryId);
+    try { await this.publishOnce(env, deliveryId, expiresAt, generation, immutable); }
+    finally { this.sending.delete(deliveryId); }
+  }
+  private async publishOnce(env: Envelope, deliveryId: string, expiresAt: number, generation: number, immutable?: RoomChatEnvelope): Promise<void> {
+    let context: RoomBoundaryContext;
+    try { context = this.ports.context(env); }
+    catch { this.notSent(deliveryId); return; }
+    const trusted = () => { try { return context.current() === true; } catch { return false; } };
+    let readinessLost = false;
+    const current = () => {
+      const ready = this.ready();
+      if (!ready) readinessLost = true;
+      return this.pending.has(deliveryId) && this.running && this.online && this.generation === generation && ready && trusted();
+    };
     const result = await roomBoundary(env, { ...context, current });
-    if (!current()) throw new Error("room: state_changed");
+    if (!this.pending.has(deliveryId)) return;
+    if (!current()) {
+      if (!trusted()) { this.quarantine(deliveryId, "boundary_refused"); this.receipt({ id: deliveryId, state: "needs_review", reason: "room trust changed before publication" }); }
+      else if (!this.running || !this.online || generation !== this.generation) this.notSent(deliveryId);
+      else if (!this.ready()) this.notSent(deliveryId, false);
+      return;
+    }
+    if (readinessLost && result.status === "refused" && trusted()) { this.notSent(deliveryId, false); return; }
     if (result.status === "refused") {
-      this.delivery({ id: deliveryId, state: "failed_safe", reason: `room: ${result.code}` });
+      const reason = result.code === "not_exposed" || result.code === "invalid_message" ? result.code : "boundary_refused";
+      if (immutable) {
+        this.quarantine(deliveryId, reason);
+        this.receipt({ id: deliveryId, state: "needs_review", reason: `room retry refused: ${result.code}` });
+      } else this.receipt({ id: deliveryId, state: "failed_safe", reason: `room: ${result.code}` });
       return;
     }
     const view = readRoomOutbound(result.proof);
-    if (!view || expiresAt === undefined || expiresAt <= (this.ports.now?.() ?? Date.now())) {
-      this.delivery({ id: deliveryId, state: "needs_review", reason: "room queued deadline unavailable or expired" });
+    if (!view || expiresAt <= (this.ports.now?.() ?? Date.now())) {
+      if (immutable) this.quarantine(deliveryId, "boundary_refused");
+      this.receipt({ id: deliveryId, state: "needs_review", reason: "room queued deadline unavailable or expired" });
+      return;
+    }
+    if (immutable && Buffer.compare(Buffer.from(encodeRoomMessage({ v: 1, type: "chat", envelope: view })), Buffer.from(encodeRoomMessage({ v: 1, type: "chat", envelope: immutable }))) !== 0) {
+      this.quarantine(deliveryId, "boundary_refused");
+      this.receipt({ id: deliveryId, state: "needs_review", reason: "room retry privacy proof changed from immutable application" });
       return;
     }
-    this.pending.add(deliveryId); this.update();
     try {
       await this.ports.send(view, deliveryId, expiresAt, () => current() && readRoomOutbound(result.proof) !== undefined, result.withheld);
-      if (!current()) { this.quarantine(deliveryId); this.receipt({ id: deliveryId, state: "needs_review", reason: "room trust changed during publication" }); }
-    } catch {
-      this.quarantine(deliveryId);
-      this.receipt({ id: deliveryId, state: "needs_review", reason: "room publication outcome is uncertain" });
+      if (!this.pending.has(deliveryId)) return;
+      if (!trusted() && this.running && this.online && generation === this.generation) {
+        this.quarantine(deliveryId, "boundary_refused"); this.receipt({ id: deliveryId, state: "needs_review", reason: "room trust changed during publication" });
+        return;
+      }
+      if (!this.ready()) {
+        let retained: boolean | undefined;
+        try { retained = this.ports.queued?.(deliveryId); } catch { retained = undefined; }
+        if (immutable || retained === true) this.waitForReady(deliveryId);
+        else this.notSent(deliveryId, false);
+        return;
+      }
+    } catch (error) {
+      if (!this.pending.has(deliveryId)) return;
+      if (error instanceof RoomNotSentError) {
+        let retained: boolean | undefined;
+        try { retained = this.ports.queued?.(deliveryId); } catch { retained = undefined; }
+        if (immutable || retained === true) {
+          if (!this.ready()) this.waitForReady(deliveryId);
+        } else this.notSent(deliveryId);
+        return;
+      }
+      if (!trusted()) {
+        this.quarantine(deliveryId, "boundary_refused");
+        this.receipt({ id: deliveryId, state: "needs_review", reason: "room trust changed during publication" });
+        return;
+      }
+      if (!this.running || !this.online || generation !== this.generation) return;
+      let retained: boolean | undefined;
+      try { retained = this.ports.queued?.(deliveryId); } catch { retained = undefined; }
+      if (!this.ready()) {
+        if (immutable || retained === true) this.waitForReady(deliveryId);
+        else this.notSent(deliveryId, false);
+        return;
+      }
+      if (retained !== true) {
+        if (retained === false && this.holdMissing(deliveryId)) {
+          this.pending.delete(deliveryId); this.blockedNotSent = false; this.update();
+        } else { this.blockedNotSent = true; this.update(); }
+      } // A durable intent stays active and retries on its next ACK deadline.
     }
   }
 }