@bastani/atomic 0.9.39-alpha.2 → 0.9.40-alpha.1

package/dist/builtin/intercom/broker/send-handler.ts

@@ -8,8 +8,13 @@ import {
 } from "../workflow-stage-target.js";
 import { normalizeGroup } from "../group.js";
 import { isMessage } from "./client-message-validation.js";
-import { resolveSessionTarget, sessionTargetFailureReason } from "../session-target.js";
+import {
+	resolveSessionTarget,
+	resolveSessionTargetByHostSessionId,
+	sessionTargetFailureReason,
+} from "../session-target.js";
 import { DeliveredMessageCache } from "./delivered-message-cache.js";
+import { type ReceiptSender, type RecipientReceipts, UNCERTAIN_RECEIPT_REASON } from "./recipient-receipts.js";
 import { buildMessageSendSignature } from "./send-signature.js";
 import { SupervisorChannelCache } from "./supervisor-channel.js";
 import { isVerticalBypass, sameGroup } from "./group-isolation.js";
@@ -34,6 +39,8 @@ export interface BrokerConnectedSession {
   supervisorId?: string;
   /** Private issuer identity used to restore child capabilities after reconnects. */
   supervisorOwnerToken?: string;
+  /** #3761: the recipient confirms each message once it has saved it; `delivered` waits for that confirmation. */
+  readonly acknowledgesReceipt?: true;
 }
 
 /** Immutable registration authority plus normalized memberships used when an accepted ask is rebound. */
@@ -80,12 +87,56 @@ export type LegacyWorkflowStageTargetResolver = (runId: string, stageKey: string
 export const PENDING_STAGE_ASK_REFUSAL =
   "Cannot ask a workflow stage whose session has not initialized. Use send; Atomic will queue the message until the stage session initializes.";
 
+/**
+ * #3760: offered every send or ask that found no live recipient, before it fails with `Session not found`.
+ * Returns true when it answered or held the send (a subagent that its owner is restoring).
+ */
+export type RestoringRecipientHold = (send: {
+  readonly socket: net.Socket;
+  readonly from: BrokerConnectedSession;
+  readonly clientMessage: SendClientMessage & { readonly to: string };
+  readonly target: string;
+  readonly messageId: string;
+  readonly attemptId?: string;
+}) => boolean;
 
-
-
-interface SendClientMessage extends Record<string, unknown> {
+export interface SendClientMessage extends Record<string, unknown> {
   type: string;
 }
+
+/**
+ * Multi-node S5: a validated send whose target no local session, local hold or workflow route resolved. The
+ * router answers it through the shared state (another broker's recipient, a shared hold or an offline session),
+ * or calls `notFound`, which answers exactly as a single-node broker would.
+ */
+export interface RemoteSendRequest {
+  readonly socket: net.Socket;
+  readonly from: BrokerConnectedSession;
+  readonly clientMessage: SendClientMessage & { readonly to: string };
+  readonly message: Message;
+  /** The trimmed `to`. */
+  readonly target: string;
+  /** The canonical send whose unkeyed SHA-256 is the cross-node digest. */
+  readonly signature: string;
+  readonly attemptId?: string;
+  readonly supervisorSend: boolean;
+  readonly requirePendingReply: boolean;
+  readonly expectedRecipientId?: string;
+  readonly resolveReplyTarget: boolean;
+  readonly awaitRestoringRecipient: boolean;
+  /**
+   * Set when the target resolved to a session on this broker: the router answers a same-id retry of a send that
+   * already went through the shared outbox from that row, and calls `notFound` to deliver anything else locally.
+   */
+  readonly localTarget?: BrokerConnectedSession;
+  /** Without `localTarget`, nothing on any node: answer exactly as a single-node broker does. */
+  readonly notFound: () => void;
+}
+
+/** Local sends the multi-node router has already checked against the shared outbox. */
+const checkedAgainstSharedOutbox = new WeakSet<SendClientMessage>();
+
+export type RemoteSendRouter = (request: RemoteSendRequest) => void;
 function wireMessageId(value: unknown): string {
   if (typeof value !== "object" || value === null) return "unknown";
   const id = (value as Record<string, unknown>).id;
@@ -115,6 +166,9 @@ export function handleBrokerSend(
 	resolveLegacyWorkflowStageTarget?: LegacyWorkflowStageTargetResolver,
 	writeConfirmed?: ConfirmedMessageWriter,
 	isNonAgentWorkflowTarget?: (target: string) => boolean,
+	holdForRestoringRecipient?: RestoringRecipientHold,
+	receipts?: RecipientReceipts<BrokerConnectedSession>,
+	routeRemote?: RemoteSendRouter,
 ): void {
   const message = clientMessage.message;
   const messageId = wireMessageId(message);
@@ -286,9 +340,76 @@ export function handleBrokerSend(
       return;
     }
   }
-  const resolution = exactIdTarget
+  const nameOrIdResolution = exactIdTarget
     ? ({ kind: "resolved", session: exactIdTarget.info } as const)
     : resolveSessionTarget(candidates, trimmedTo);
+  // #3760: a host session id (a resumed session's or a restored subagent's own session id) reaches the one
+  // visible session it registered, under the same group visibility as names.
+  const resolution = nameOrIdResolution.kind === "not_found"
+    ? resolveSessionTargetByHostSessionId(
+        candidates,
+        trimmedTo,
+        (info) => sessions.get(info.id)?.registrationReturnAddress,
+      )
+    : nameOrIdResolution;
+  if (
+    routeRemote !== undefined &&
+    resolution.kind === "not_found" &&
+    workflowTarget === undefined &&
+    !visibleCandidates.some((info) => !isAgentRecipient(info) && info.name?.toLowerCase() === trimmedTo.toLowerCase())
+  ) {
+    const send = clientMessage as SendClientMessage & { readonly to: string };
+    if (
+      !supervisorSend &&
+      !requirePendingReply &&
+      expectedRecipientId === undefined &&
+      holdForRestoringRecipient?.({
+        socket,
+        from: fromSession,
+        clientMessage: send,
+        target: trimmedTo,
+        messageId: message.id,
+        ...(attemptId ? { attemptId } : {}),
+      })
+    ) {
+      return;
+    }
+    routeRemote({
+      socket,
+      from: fromSession,
+      clientMessage: send,
+      message,
+      target: trimmedTo,
+      signature,
+      ...(attemptId === undefined ? {} : { attemptId }),
+      supervisorSend,
+      requirePendingReply,
+      ...(expectedRecipientId === undefined ? {} : { expectedRecipientId }),
+      resolveReplyTarget: clientMessage.resolveReplyTarget === true,
+      awaitRestoringRecipient: clientMessage.awaitRestoringRecipient === true,
+      // Nothing on any node: answer exactly as a single-node broker does.
+      notFound: () =>
+        handleBrokerSend(
+          socket,
+          clientMessage,
+          currentId,
+          sessions,
+          deliveredMessages,
+          write,
+          supervisorCache,
+          pendingQuestions,
+          routePendingStage,
+          resolveLiveWorkflowStage,
+          canControlLiveWorkflowStage,
+          resolveLegacyWorkflowStageTarget,
+          writeConfirmed,
+          isNonAgentWorkflowTarget,
+          holdForRestoringRecipient,
+          receipts,
+        ),
+    });
+    return;
+  }
   if (expectedRecipientId !== undefined && (resolution.kind !== "resolved" || resolution.session.id !== expectedRecipientId)) {
     write(socket, { type: "delivery_failed", messageId, attemptId,
       reason: resolution.kind === "resolved" ? "Reply target does not match the expected recipient" : sessionTargetFailureReason(clientMessage.to, resolution),
@@ -315,8 +436,52 @@ export function handleBrokerSend(
       write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Cannot message the current session" });
       return;
     }
+	if (routeRemote !== undefined && !checkedAgainstSharedOutbox.delete(clientMessage)) {
+		// Multi-node: a retry whose first attempt reached this recipient through another broker is answered from the
+		// shared outbox row; `DeliveredMessageCache` never saw that delivery.
+		routeRemote({
+			socket,
+			from: fromSession,
+			clientMessage: clientMessage as SendClientMessage & { readonly to: string },
+			message,
+			target: trimmedTo,
+			signature,
+			...(attemptId === undefined ? {} : { attemptId }),
+			supervisorSend,
+			requirePendingReply,
+			...(expectedRecipientId === undefined ? {} : { expectedRecipientId }),
+			resolveReplyTarget: clientMessage.resolveReplyTarget === true,
+			awaitRestoringRecipient: clientMessage.awaitRestoringRecipient === true,
+			localTarget: target,
+			notFound: () => {
+				checkedAgainstSharedOutbox.add(clientMessage);
+				handleBrokerSend(
+					socket,
+					clientMessage,
+					currentId,
+					sessions,
+					deliveredMessages,
+					write,
+					supervisorCache,
+					pendingQuestions,
+					routePendingStage,
+					resolveLiveWorkflowStage,
+					canControlLiveWorkflowStage,
+					resolveLegacyWorkflowStageTarget,
+					writeConfirmed,
+					isNonAgentWorkflowTarget,
+					holdForRestoringRecipient,
+					receipts,
+					routeRemote,
+				);
+			},
+		});
+		return;
+	}
 	const targetIdentity = deliveryTargetIdentity(target);
 	const deliveredMatch = deliveredMessages.lookupForTarget(message.id, signature, targetIdentity);
+	// #3761: a recipient that confirms saves ignores a copy it already saved, so a reserved message is sent again.
+	const confirmsSaves = target.acknowledgesReceipt === true && receipts !== undefined;
 	if (requirePendingReply && deliveredMatch === "match") {
 		write(socket, { type: "delivered", messageId: message.id, attemptId });
 		return;
@@ -340,7 +505,7 @@ export function handleBrokerSend(
 		});
 		return;
 	}
-	if (requirePendingReply && deliveredMatch === "uncertain") {
+	if (requirePendingReply && deliveredMatch === "uncertain" && !confirmsSaves) {
 		write(socket, {
 			type: "delivery_failed",
 			messageId: message.id,
@@ -427,7 +592,7 @@ export function handleBrokerSend(
 		});
 		return;
 	}
-	if (deliveredMatch === "uncertain") {
+	if (deliveredMatch === "uncertain" && !confirmsSaves) {
 		write(socket, {
 			type: "delivery_failed",
 			messageId: message.id,
@@ -501,7 +666,7 @@ export function handleBrokerSend(
 		write(socket, { type: "delivered", messageId: message.id, attemptId });
 		return;
 	}
-	if (reservation !== "recorded") {
+	if (reservation !== "recorded" && !(reservation === "uncertain" && confirmsSaves)) {
 		write(socket, {
 			type: "delivery_failed",
 			messageId: message.id,
@@ -517,24 +682,28 @@ export function handleBrokerSend(
 	}
 	if (message.expectsReply === true && clientMessage.resolveReplyTarget === true && attemptId !== undefined)
 		write(socket, { type: "question_target", messageId: message.id, attemptId, sessionId: target.info.id });
-    const finishDelivery = (): void => {
+    const finishDelivery = (recipient: BrokerConnectedSession, sender: ReceiptSender | undefined): void => {
+	  const notify = (frame: BrokerMessage): void => {
+		if (sender !== undefined) write(sender.socket, frame);
+	  };
+	  const senderAttemptId = sender?.attemptId;
 	  let accepted: ReturnType<DeliveredMessageCache["accept"]>;
 	  try {
 		accepted = deliveredMessages.accept(message.id, signature, targetIdentity);
 	  } catch {
-		write(socket, {
+		notify({
 			type: "delivery_failed",
 			messageId: message.id,
-			attemptId,
+			attemptId: senderAttemptId,
 			reason: "Intercom could not durably confirm the forwarded operation; refusing a possibly unsafe retry",
 		});
 		return;
 	  }
 	  if (accepted !== "accepted") {
-		write(socket, {
+		notify({
 			type: "delivery_failed",
 			messageId: message.id,
-			attemptId,
+			attemptId: senderAttemptId,
 			reason: "Intercom could not durably confirm the forwarded operation; refusing a possibly unsafe retry",
 			...(accepted === "conflict" ? { reasonCode: "message_id_conflict" as const } : {}),
 		});
@@ -542,27 +711,58 @@ export function handleBrokerSend(
 	  }
       // A terminal presence frame can arrive while the socket write callback is pending.
       // Retain accepted-delivery authority, but never open a reply route after termination.
-      if (message.expectsReply === true && target.info.replyCapability === "terminal") {
-        write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: TERMINAL_CHILD_ASK_REFUSAL });
+      if (message.expectsReply === true && recipient.info.replyCapability === "terminal") {
+        notify({ type: "delivery_failed", messageId: message.id, attemptId: senderAttemptId, reason: TERMINAL_CHILD_ASK_REFUSAL });
         return;
       }
-      if (message.expectsReply === true && sessions.get(target.info.id) !== target) {
-        write(socket, { type: "delivery_failed", messageId: message.id, attemptId,
-          reason: `Session "${target.info.name ?? target.info.id}" disconnected before replying` });
+      if (message.expectsReply === true && sessions.get(recipient.info.id) !== recipient) {
+        notify({ type: "delivery_failed", messageId: message.id, attemptId: senderAttemptId,
+          reason: `Session "${recipient.info.name ?? recipient.info.id}" disconnected before replying` });
         return;
       }
-      if (message.expectsReply === true) {
-        pendingQuestions.record(fromSession.info.id, target.info.id, message.id);
+      // A sender whose wait already ended was told the outcome is uncertain; its retry opens the reply route.
+      if (message.expectsReply === true && sender !== undefined) {
+        pendingQuestions.record(fromSession.info.id, recipient.info.id, message.id);
+        // #3761: a recipient that reconnected before confirming answers under its new session id.
+        if (recipient.info.id !== target.info.id && clientMessage.resolveReplyTarget === true && senderAttemptId !== undefined)
+          notify({ type: "question_target", messageId: message.id, attemptId: senderAttemptId, sessionId: recipient.info.id });
 	  }
-      if (message.replyTo !== undefined && pendingQuestions.clearReply(fromSession.info.id, target.info.id, message.replyTo)) {
+      if (message.replyTo !== undefined && pendingQuestions.clearReply(fromSession.info.id, recipient.info.id, message.replyTo)) {
         deliveredMessages.settleQuestion(message.replyTo);
       }
-      if (supervisorSend) supervisorCache.record(message.id, fromSession.info.id, target.info.id);
-      write(socket, { type: "delivered", messageId: message.id, attemptId });
+      if (supervisorSend) supervisorCache.record(message.id, fromSession.info.id, recipient.info.id);
+      notify({ type: "delivered", messageId: message.id, attemptId: senderAttemptId });
     };
+    const senderWaiting: ReceiptSender = { socket, ...(attemptId === undefined ? {} : { attemptId }) };
+    if (confirmsSaves && receipts !== undefined) {
+      receipts.await(
+        {
+          messageId: message.id,
+          targetIdentity,
+          frame: outbound,
+          complete: finishDelivery,
+          expire: (waiting) => {
+            write(waiting.socket, { type: "delivery_failed", messageId: message.id, attemptId: waiting.attemptId, reason: UNCERTAIN_RECEIPT_REASON });
+          },
+        },
+        senderWaiting,
+      );
+      const unwritten = (): void => {
+        receipts.drop(message.id);
+        failDelivery();
+      };
+      if (writeConfirmed !== undefined) {
+        writeConfirmed(target.socket, outbound, (written) => {
+          if (!written) unwritten();
+        });
+        return;
+      }
+      if (!write(target.socket, outbound)) unwritten();
+      return;
+    }
     if (writeConfirmed !== undefined) {
       writeConfirmed(target.socket, outbound, (written) => {
-        if (written) finishDelivery();
+        if (written) finishDelivery(target, senderWaiting);
         else failDelivery();
       });
       return;
@@ -573,13 +773,29 @@ export function handleBrokerSend(
       failDelivery();
       return;
     }
-    finishDelivery();
+    finishDelivery(target, senderWaiting);
     return;
   }
 	if (resolution.kind === "not_found" && visibleCandidates.some((info) => !isAgentRecipient(info) && info.name?.toLowerCase() === trimmedTo.toLowerCase())) {
 		write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: NON_AGENT_RECIPIENT_REFUSAL });
 		return;
 	}
+	if (
+		resolution.kind === "not_found" &&
+		!supervisorSend &&
+		!requirePendingReply &&
+		workflowTarget === undefined &&
+		holdForRestoringRecipient?.({
+			socket,
+			from: fromSession,
+			clientMessage: clientMessage as SendClientMessage & { readonly to: string },
+			target: trimmedTo,
+			messageId: message.id,
+			...(attemptId ? { attemptId } : {}),
+		})
+	) {
+		return;
+	}
 	if (
 		resolution.kind === "not_found" &&
 		!supervisorSend &&

package/dist/builtin/intercom/broker/session-id-reclaim.ts

@@ -0,0 +1,41 @@
+/** Broker session ids are lowercase canonical UUIDs; only that form may be requested back. */
+const CANONICAL_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const DEFAULT_MAX_ENTRIES = 10_000;
+
+/**
+ * Lets a restarted or reconnected session register under the Intercom id peers already know (#3760).
+ *
+ * A requested id is granted only when no live session holds it, so a registration never displaces a
+ * live session. While this broker remembers who last held an id, only a registration with that same
+ * return address (the host's session identity) gets it back. A broker that restarted remembers
+ * nothing; its sessions and their routing state are gone too, so a free id carries no authority.
+ */
+export class SessionIdReclaim {
+	private readonly retired = new Map<string, string | undefined>();
+
+	constructor(private readonly maxEntries = DEFAULT_MAX_ENTRIES) {}
+
+	/** Remember who held a departed session id. */
+	retire(sessionId: string, returnAddress: string | undefined): void {
+		this.retired.delete(sessionId);
+		this.retired.set(sessionId, returnAddress);
+		while (this.retired.size > this.maxEntries) {
+			const oldest = this.retired.keys().next().value as string | undefined;
+			if (oldest === undefined) break;
+			this.retired.delete(oldest);
+		}
+	}
+
+	/** The requested id when it can be granted, otherwise undefined (the caller assigns a fresh id). */
+	grant(
+		preferredSessionId: string | undefined,
+		returnAddress: string | undefined,
+		isLive: (sessionId: string) => boolean,
+	): string | undefined {
+		if (preferredSessionId === undefined || returnAddress === undefined) return undefined;
+		if (!CANONICAL_SESSION_ID.test(preferredSessionId) || isLive(preferredSessionId)) return undefined;
+		if (this.retired.has(preferredSessionId) && this.retired.get(preferredSessionId) !== returnAddress) return undefined;
+		this.retired.delete(preferredSessionId);
+		return preferredSessionId;
+	}
+}

package/dist/builtin/intercom/broker/socket-writes.ts

@@ -58,6 +58,15 @@ export type BrokerOutboundFrame =
 			notInKnownSet?: true;
 	  };
 
+/** A frame written while its socket's writes were held, with the outcome callback of a confirmed write. */
+export interface HeldWrite {
+	readonly message: BrokerOutboundFrame;
+	readonly onSettled?: (written: boolean) => void;
+}
+
+/** Multi-node S5: sockets whose frames are held until their deferred `registered` is written. */
+const heldWrites = new WeakMap<net.Socket, HeldWrite[]>();
+
 /**
  * Write one broker frame unless the socket's writable side is already gone.
  *
@@ -69,6 +78,11 @@ export type BrokerOutboundFrame =
  */
 export function writeMessageIfOpen(socket: net.Socket, message: BrokerOutboundFrame): boolean {
 	if (!isSocketOpenForWrite(socket)) return false;
+	const held = heldWrites.get(socket);
+	if (held !== undefined) {
+		held.push({ message });
+		return true;
+	}
 	writeMessage(socket, message);
 	return true;
 }
@@ -89,6 +103,11 @@ export function writeMessageWithOutcome(
 		onSettled(false);
 		return;
 	}
+	const held = heldWrites.get(socket);
+	if (held !== undefined) {
+		held.push({ message, onSettled });
+		return;
+	}
 	let settled = false;
 	const finish = (written: boolean): void => {
 		if (settled) return;
@@ -101,3 +120,31 @@ export function writeMessageWithOutcome(
 		finish(false);
 	}
 }
+
+/**
+ * Multi-node S5: hold every frame written to `socket` until `releaseHeldWrites`. A session whose registration
+ * completes asynchronously is already routable, but its client accepts no frame before `registered`.
+ */
+export function holdWrites(socket: net.Socket): void {
+	if (!heldWrites.has(socket)) heldWrites.set(socket, []);
+}
+
+/** Stop holding frames for `socket`; returns the frames held, in the order they were written. */
+export function releaseHeldWrites(socket: net.Socket): HeldWrite[] {
+	const held = heldWrites.get(socket) ?? [];
+	heldWrites.delete(socket);
+	return held;
+}
+
+/** Write released frames in order; a confirmed write to a closed socket reports `false`, as any write does. */
+export function flushHeldWrites(socket: net.Socket, held: readonly HeldWrite[]): void {
+	for (const { message, onSettled } of held) {
+		if (onSettled === undefined) writeMessageIfOpen(socket, message);
+		else writeMessageWithOutcome(socket, message, onSettled);
+	}
+}
+
+/** Drop released frames that will never be written; each confirmed write reports `false`. */
+export function discardHeldWrites(held: readonly HeldWrite[]): void {
+	for (const { onSettled } of held) onSettled?.(false);
+}

package/dist/builtin/intercom/broker/spawn.ts

@@ -4,8 +4,9 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
 import { isSocketAnswering } from "./socket-liveness.js";
-import { createChildProcessEnvironment, isBunBinary } from "@bastani/atomic";
+import { createChildProcessEnvironment, isBunBinary, processSharedStorageSelection } from "@bastani/atomic";
 import {
+  BROKER_STORAGE_ENV,
   getBrokerLogPath,
   getBrokerPidPath,
   getBrokerSocketPath,
@@ -243,6 +244,9 @@ export function getBrokerLaunchSpec(
  * The broker is detached and outlives this process, so its stderr goes to an already-open file
  * descriptor rather than a pipe: a long-lived pipe would keep the parent's event loop attached
  * and break once the parent exits.
+ *
+ * The broker routes through the shared storage this process was launched with (`--storage`,
+ * `--storage-file` or `ATOMIC_STORAGE`), passed as `ATOMIC_STORAGE`; without one it reads settings.
  */
 export function getBrokerSpawnOptions(
   extensionDir: string = EXTENSION_DIR,
@@ -254,11 +258,15 @@ export function getBrokerSpawnOptions(
   env: NodeJS.ProcessEnv;
   windowsHide: true;
 } {
+  const storage = processSharedStorageSelection();
   return {
     detached: true,
     stdio: ["ignore", "ignore", stderr],
     cwd: extensionDir,
-    env: createChildProcessEnvironment({ NODE_NO_WARNINGS: "1" }),
+    env: createChildProcessEnvironment({
+      NODE_NO_WARNINGS: "1",
+      ...(storage === undefined ? {} : { [BROKER_STORAGE_ENV]: storage }),
+    }),
     windowsHide: true,
   };
 }

package/dist/builtin/intercom/broker/sql-held-send-store.ts

@@ -0,0 +1,96 @@
+import { type SqliteRow, validateStoragePrefix } from "@bastani/atomic/storage";
+import type {
+	HeldSend,
+	HeldSendDropResult,
+	HeldSendHoldResult,
+	HeldSendListResult,
+	HeldSendRequest,
+	HeldSendStore,
+	HeldSendTakeResult,
+	IntercomBrokerStateOptions,
+	InvalidStateInput,
+	StateStoreInvalidReason,
+} from "./multinode-state-store.js";
+
+type HeldRow = SqliteRow & {
+	reservation_key: string;
+	origin_broker_id: string;
+	sender_session_id: string;
+	request_json: string;
+};
+
+const STORE_NOW = "CAST(unixepoch('subsec') * 1000 AS INTEGER)";
+
+const invalid = (reason: StateStoreInvalidReason): InvalidStateInput => ({ status: "invalid", reason });
+
+function heldSendOf(row: HeldRow): HeldSend {
+	return {
+		reservationKey: row.reservation_key,
+		originBrokerId: row.origin_broker_id,
+		senderSessionId: row.sender_session_id,
+		request: JSON.parse(row.request_json) as HeldSendRequest,
+	};
+}
+
+/**
+ * S3: `HeldSendStore` on the shared storage adapter's database, table `<prefix>intercom_held_sends`. Sends are keyed
+ * by `reservationKeyFor(capability)`; the capability itself is never stored.
+ */
+export async function openSqlHeldSendStore({ database, prefix }: IntercomBrokerStateOptions): Promise<HeldSendStore> {
+	const table = `${validateStoragePrefix(prefix)}intercom_held_sends`;
+	await database.transaction((tx) =>
+		tx.exec(`
+			CREATE TABLE IF NOT EXISTS ${table}(
+				"order" INTEGER PRIMARY KEY AUTOINCREMENT,
+				message_id TEXT NOT NULL UNIQUE,
+				reservation_key TEXT NOT NULL,
+				origin_broker_id TEXT NOT NULL,
+				sender_session_id TEXT NOT NULL,
+				request_json TEXT NOT NULL,
+				held_at INTEGER NOT NULL
+			);
+			CREATE INDEX IF NOT EXISTS ${table}_reservation ON ${table}(reservation_key, "order");
+		`),
+	);
+	const selectForReservation = `SELECT reservation_key, origin_broker_id, sender_session_id, request_json FROM ${table}
+		WHERE reservation_key = ? ORDER BY "order"`;
+
+	return {
+		async hold(send): Promise<HeldSendHoldResult> {
+			if (send.reservationKey.length === 0) return invalid("empty-reservation-key");
+			if (send.originBrokerId.length === 0) return invalid("empty-broker-id");
+			if (send.senderSessionId.length === 0) return invalid("empty-session-id");
+			const messageId = send.request.message.id;
+			if (messageId.length === 0) return invalid("empty-message-id");
+			const { changes } = await database.run(
+				`INSERT INTO ${table}(message_id, reservation_key, origin_broker_id, sender_session_id, request_json, held_at)
+				 VALUES (?, ?, ?, ?, ?, ${STORE_NOW}) ON CONFLICT(message_id) DO NOTHING`,
+				messageId,
+				send.reservationKey,
+				send.originBrokerId,
+				send.senderSessionId,
+				JSON.stringify(send.request),
+			);
+			return changes === 0 ? { status: "duplicate" } : { status: "held" };
+		},
+		async list(reservationKey): Promise<HeldSendListResult> {
+			if (reservationKey.length === 0) return invalid("empty-reservation-key");
+			const rows = await database.all<HeldRow>(selectForReservation, reservationKey);
+			return { status: "listed", sends: rows.map(heldSendOf) };
+		},
+		async take(reservationKey): Promise<HeldSendTakeResult> {
+			if (reservationKey.length === 0) return invalid("empty-reservation-key");
+			const rows = await database.transaction(async (tx) => {
+				const taken = await tx.all<HeldRow>(selectForReservation, reservationKey);
+				await tx.run(`DELETE FROM ${table} WHERE reservation_key = ?`, reservationKey);
+				return taken;
+			});
+			return { status: "taken", sends: rows.map(heldSendOf) };
+		},
+		async drop(messageId): Promise<HeldSendDropResult> {
+			if (messageId.length === 0) return invalid("empty-message-id");
+			const { changes } = await database.run(`DELETE FROM ${table} WHERE message_id = ?`, messageId);
+			return changes === 0 ? { status: "missing" } : { status: "dropped" };
+		},
+	};
+}