agent-comms 8.15.9 → 8.15.10

package/src/core/mesh-graph.ts

@@ -0,0 +1,89 @@
+/**
+ * mesh-graph -- agent-comms#199's own mesh_graph/mesh_trace primitives, split from wire-mesh-transport.ts under the repo's max-lines cap, the same reason gossip-directory.ts/hub-forwarding.ts were each split from their own owning file. computeMeshGraph assembles this side's best-effort view of the mesh's connection graph out of every known device's own self-reported topology/peers gossip extension (wire-mesh#180); traceMeshPath sends the live path.trace verb (wire-mesh#181) to a specific device, direct or via the hub.
+ */
+
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import { assembleTopologyGraph } from "wire-mesh-core/domain/topology";
+import {
+  buildPathTraceResponse,
+  tracePath,
+} from "wire-mesh-core/domain/path-trace";
+import type {
+  AcceptedMeshSession,
+  DirectoryEntry,
+  IncomingManageRequest,
+  ManageOutcome,
+} from "wire-mesh-core/domain/mesh-session";
+import type { PeerAdvert } from "wire-mesh-core/generated/protocol";
+import type { HubSession } from "./hub-session.js";
+import type { RoomRequestOrigin } from "./room-router.js";
+import type {
+  ConnectionHandle,
+  MeshGraph,
+  MeshTraceResult,
+} from "./transport.js";
+
+/**
+ * Assembles this side's own best-effort view of the mesh's connection graph out of knownDevices (WireMeshTransport's own mesh-wide gossip aggregation, the identical map listKnownDevices already reads), converted to DirectoryEntry[]. Device-ids are hex-encoded, never raw wire-mesh-core DeviceId bytes, matching listKnownDevices' own precedent.
+ *
+ * assembleTopologyGraph's own nodes list is only devices this side holds a directory entry (gossip advert) for -- its edges are deliberately "unreconciled by design" (see its own doc comment) and can name a `to`/`via` endpoint reported by another device's advert that this side has never itself gossiped with directly, so that endpoint never gets its own directory entry and is absent from nodes. A MeshGraph whose edges reference an undeclared node isn't well-formed for any consumer (a force-directed layout, a table, anything), so every edge endpoint is unioned into the returned nodes list here, not left for each consumer to work around individually.
+ */
+export function computeMeshGraph(
+  knownDevices: ReadonlyMap<string, Readonly<PeerAdvert>>,
+): MeshGraph {
+  const directory: DirectoryEntry[] = [...knownDevices.values()].map(
+    (advert) => ({ device: advert.device, advert }),
+  );
+  const graph = assembleTopologyGraph(directory);
+  const edges = graph.edges.map((edge) => ({
+    kind: edge.kind,
+    from: deviceIdToHex(edge.from),
+    to: deviceIdToHex(edge.to),
+    ...(edge.kind === "relay" && edge.via !== undefined
+      ? { via: deviceIdToHex(edge.via) }
+      : {}),
+  }));
+  const nodes = new Set(graph.nodes.map(deviceIdToHex));
+  for (const edge of edges) {
+    nodes.add(edge.from);
+    nodes.add(edge.to);
+    if (edge.via !== undefined) nodes.add(edge.via);
+  }
+  return { nodes: [...nodes], edges };
+}
+
+/** Sends path.trace to targetDeviceHex, direct if a local peer session exists for it (peerSessions, WireMeshTransport's own addressing map), else via the hub's own relay pairing when connected to one, else resolving an ordinary not_connected outcome rather than throwing -- WireMeshTransport.sendRoomRequest's own identical direct-or-hub fallback, just for path.trace instead of a room-domain verb. Delegates the actual send/RTT-measurement/response-parsing to wire-mesh-core's own tracePath in the direct branch, and to HubSession.tracePath (which does the identical delegation on the hub's own session) in the relayed branch, so neither this function nor either of those duplicates that logic. */
+export async function traceMeshPath(
+  peerSessions: ReadonlyMap<string, AcceptedMeshSession>,
+  hub: Readonly<Pick<HubSession, "isConnected" | "tracePath">>,
+  targetDeviceHex: string,
+  timeoutMs?: number,
+): Promise<MeshTraceResult> {
+  const directSession = peerSessions.get(targetDeviceHex);
+  if (directSession !== undefined) {
+    return tracePath({
+      session: directSession,
+      clock: { now: () => Date.now() },
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+  }
+  if (hub.isConnected) {
+    return hub.tracePath(targetDeviceHex, timeoutMs);
+  }
+  return {
+    rttMs: 0,
+    local: { relayed: false },
+    outcome: { result: "error", code: "not_connected" },
+  };
+}
+
+/** Answers an incoming path.trace (agent-comms#199), registered as this side's own "path.trace" room-router handler (createRoomRouter's handlers are keyed by params.verb regardless of domain, despite the room-flavoured name -- see WireMeshTransport's own constructor for where this is wired in alongside the real room verbs). Reports origin?.relayHubAddress (agent-comms#216) as buildPathTraceResponse's own hubAddress parameter -- that function itself already gates inclusion on the request actually being relayed (request.fromDevice set), so this passes it through unconditionally rather than duplicating that check here; handle is unused, kept only to occupy RoomVerbHandler's own positional slot ahead of origin. */
+export async function handlePathTraceRequest(
+  request: Readonly<IncomingManageRequest>,
+  _handle: Readonly<ConnectionHandle>,
+  origin?: Readonly<RoomRequestOrigin>,
+): Promise<ManageOutcome> {
+  return Promise.resolve(
+    buildPathTraceResponse(request, origin?.relayHubAddress),
+  );
+}

package/src/core/mesh-network-actions.ts

@@ -0,0 +1,183 @@
+/**
+ * CommsTool's mesh discovery/advertise/interfaces/listener/visibility action handlers -- split out of tool.ts purely to keep that file under the repo's max-lines cap, the same reason gateway-trust-actions.ts/mesh-graph-trace-tool.ts were split from it. Free functions over an explicit DiscoveryManager/CommsStore pair rather than class methods, since CommsTool owns no state of its own for this concern.
+ */
+
+import type { CommsAction, NetworkInterface } from "./types.js";
+import type { ListenerInfo } from "./transport.js";
+import type { DiscoveryManager } from "./discovery.js";
+import type { CommsResult, MeshOnlyFeatures } from "./tool.js";
+import { notMeshBacked, tryMeshAction } from "./tool.js";
+
+/** Table column widths for the plain-text listing helpers below, matching tool.ts's own aligned-column convention for every other tabular action result. */
+const INTERFACE_NAME_COLUMN_WIDTH = 12;
+const INTERFACE_FAMILY_COLUMN_WIDTH = 4;
+const LISTENER_HOST_COLUMN_WIDTH = 15;
+const LISTENER_PORT_COLUMN_WIDTH = 6;
+const LISTENER_POLICY_COLUMN_WIDTH = 11;
+
+/** Default port the mesh coordinator listens on when advertising with no explicit port given. */
+const DEFAULT_MESH_COORDINATOR_PORT = 19876;
+
+export async function meshDiscoverAction(
+  discovery: DiscoveryManager | undefined,
+  action: CommsAction & { action: "mesh_discover" },
+): Promise<CommsResult> {
+  if (!discovery) {
+    return {
+      content: "Discovery is not available (no backends registered).",
+      isError: true,
+    };
+  }
+  const meshes = await discovery.discover({ backendName: action.method });
+  if (meshes.length === 0) {
+    return { content: "No meshes discovered.", isError: false };
+  }
+  const lines = meshes.map(
+    (m) =>
+      `  ${m.host}:${String(m.port)}  ${m.name}${m.agentCount !== undefined ? ` (${String(m.agentCount)} agents)` : ""}`,
+  );
+  return {
+    content: `Discovered meshes:\n${lines.join("\n")}`,
+    isError: false,
+  };
+}
+
+export async function meshAdvertiseAction(
+  discovery: DiscoveryManager | undefined,
+  action: CommsAction & { action: "mesh_advertise" },
+): Promise<CommsResult> {
+  if (!discovery) {
+    return {
+      content: "Discovery is not available (no backends registered).",
+      isError: true,
+    };
+  }
+  const port = action.port ?? DEFAULT_MESH_COORDINATOR_PORT;
+  const opts: { name: string; port: number; adapter?: string } = {
+    name: action.name,
+    port,
+  };
+  if (action.adapter !== undefined) opts.adapter = action.adapter;
+  const id = await discovery.advertise(action.method, opts);
+  return {
+    content: `Advertising mesh "${action.name}" on ${action.method} (port ${String(port)}). ID: ${id}`,
+    isError: false,
+  };
+}
+
+export function meshInterfacesAction(
+  store: Readonly<Pick<MeshOnlyFeatures, "getNetworkInterfaces">>,
+): CommsResult {
+  if (!store.getNetworkInterfaces) return notMeshBacked("mesh_interfaces");
+  const interfaces = store.getNetworkInterfaces();
+  if (interfaces.length === 0)
+    return { content: "No network interfaces found.", isError: false };
+
+  const lines = interfaces.map((iface: Readonly<NetworkInterface>) => {
+    const internal = iface.internal ? " (internal)" : "";
+    return `${iface.name.padEnd(INTERFACE_NAME_COLUMN_WIDTH)} ${iface.family.padEnd(INTERFACE_FAMILY_COLUMN_WIDTH)} ${iface.address}${internal}`;
+  });
+  return {
+    content: `Interfaces:\n${lines.join("\n")}`,
+    isError: false,
+  };
+}
+
+export async function meshUnadvertiseAction(
+  discovery: DiscoveryManager | undefined,
+  action: CommsAction & { action: "mesh_unadvertise" },
+): Promise<CommsResult> {
+  if (!discovery) {
+    return {
+      content: "Discovery is not available (no backends registered).",
+      isError: true,
+    };
+  }
+  await discovery.stopAdvertising(action.id);
+  return { content: `Stopped advertising ${action.id}.`, isError: false };
+}
+
+export async function meshListenAction(
+  store: Readonly<Pick<MeshOnlyFeatures, "addListener">>,
+  action: CommsAction & { action: "mesh_listen" },
+): Promise<CommsResult> {
+  const policy = action.policy ?? "full";
+  const validPolicies = ["full", "observe", "rooms-only", "gateway"];
+  if (!validPolicies.includes(policy)) {
+    return {
+      content: `Invalid policy "${policy}". Must be one of: ${validPolicies.join(", ")}`,
+      isError: true,
+    };
+  }
+  if (!store.addListener) return notMeshBacked("mesh_listen");
+  const addListener = store.addListener.bind(store);
+  return tryMeshAction("add listener", async () => {
+    const id = await addListener(action.host, action.port ?? 0, policy);
+    return `Listener added: ${id} on ${action.host}${String(action.port ?? "auto")} with policy ${policy}.`;
+  });
+}
+
+export async function meshUnlistenAction(
+  store: Readonly<Pick<MeshOnlyFeatures, "removeListener">>,
+  action: CommsAction & { action: "mesh_unlisten" },
+): Promise<CommsResult> {
+  if (!store.removeListener) return notMeshBacked("mesh_unlisten");
+  const removeListener = store.removeListener.bind(store);
+  return tryMeshAction("remove listener", async () => {
+    await removeListener(action.id);
+    return `Listener ${action.id} removed.`;
+  });
+}
+
+export function meshListenersAction(
+  store: Readonly<Pick<MeshOnlyFeatures, "listListeners">>,
+): CommsResult {
+  if (!store.listListeners) return notMeshBacked("mesh_listeners");
+  const listeners = store.listListeners();
+  if (listeners.length === 0)
+    return { content: "No listeners (not coordinator).", isError: false };
+
+  const lines = listeners.map((l: Readonly<ListenerInfo>) => {
+    const flag = l.isDefault ? " (default)" : "";
+    return `${l.id}  ${l.host.padEnd(LISTENER_HOST_COLUMN_WIDTH)} ${String(l.port).padEnd(LISTENER_PORT_COLUMN_WIDTH)} ${l.policy.padEnd(LISTENER_POLICY_COLUMN_WIDTH)}${flag}`;
+  });
+  return {
+    content: `Listeners:\n  ID      Host             Port   Policy      \n${lines.map((l) => `  ${l}`).join("\n")}`,
+    isError: false,
+  };
+}
+
+export async function meshSetVisibilityAction(
+  store: Readonly<Pick<MeshOnlyFeatures, "setVisibility">>,
+  action: CommsAction & { action: "mesh_set_visibility" },
+): Promise<CommsResult> {
+  if (!store.setVisibility) {
+    return {
+      content: "Visibility control is not available on this store.",
+      isError: true,
+    };
+  }
+  await store.setVisibility(action.visibility, action.adapter);
+  const adapter =
+    action.adapter !== undefined ? ` on adapter "${action.adapter}"` : "";
+  return {
+    content: `Mesh visibility set to "${action.visibility}"${adapter}.`,
+    isError: false,
+  };
+}
+
+export function meshGetVisibilityAction(
+  store: Readonly<Pick<MeshOnlyFeatures, "getVisibility">>,
+): CommsResult {
+  if (!store.getVisibility) {
+    return {
+      content: "Visibility control is not available on this store.",
+      isError: true,
+    };
+  }
+  const visibility = store.getVisibility();
+  return {
+    content: `Mesh visibility: ${visibility}`,
+    isError: false,
+  };
+}

package/src/core/mesh-store-options.ts

@@ -0,0 +1,23 @@
+/**
+ * MeshStore's own constructor options, split out purely to keep mesh-store.ts under the repo's max-lines cap, the same reason WireMeshTransportOptions was split into its own wire-mesh-transport-options.ts.
+ */
+
+import type { IdentitySlot } from "./identity-store.js";
+
+/** Construction options for MeshStore. */
+export interface MeshStoreOptions {
+  /** Localhost TCP port the coordinator role is contested on. Defaults to DEFAULT_COORDINATOR_PORT. */
+  readonly coordinatorPort?: number | undefined;
+  /** The relay hub this store holds its own session on from init until shutdown, so it is reachable from other machines whatever role it plays locally. Left out, the store never contacts a hub: only the bridge entry points name the production hub (bridge-mesh.ts), so a store built by anything else, a test included, stays local. */
+  readonly hubUrl?: string | undefined;
+  /** How long a room.join (including a first-contact DM request) may await a human decision, on this store as the receiver and on the transport it is wired to as the sender. Defaults to ROOM_JOIN_APPROVAL_TIMEOUT_MS; a test shortens it. */
+  readonly roomJoinApprovalTimeoutMs?: number | undefined;
+  /** How old a gossip-discovered device's own last-heard advert may be before listAgents stops trusting whatever presence status it last carried and reports the device offline instead (agent-comms#301). Defaults to DEFAULT_PRESENCE_STALE_AFTER_MS; a test shortens it to observe staleness without waiting out the real default. */
+  readonly presenceStaleAfterMs?: number | undefined;
+  /** The UDP port init() binds the first-contact presence on (agent-comms#341): beacons, probes, and discovered peers fed into the ordinary peer-list flood, so a mesh forms with no coordinator at all. Left out, the store runs no presence: only the bridge entry points set it (bridge-mesh.ts, FIRST_CONTACT_PORT by default), so a store built by anything else, a test included, stays inert and never cross-discovers another store. A bridge-level test overrides it with an OS-assigned free port. */
+  readonly firstContactPort?: number | undefined;
+  /** How long this store waits for an incumbent's coordinator claim to reach it before claiming the elected role itself (agent-comms#341): after the holder departs, after accepting a claim naming a holder it has no session to, and before a store that may meet others through first contact claims a vacant role. Defaults to ROOM_REQUEST_TIMEOUT_MS; a test shortens it. */
+  readonly coordinatorClaimWaitMs?: number | undefined;
+  /** Locates this store's persisted bootstrap state. The connectionCodes ledger is per slot. gatewayTrust is shared by every slot in the slot's identity directory, so all stores on a machine (each fronted session included) advertise under one operator decision. */
+  readonly slot?: Readonly<IdentitySlot>;
+}

package/src/core/mesh-store-shared.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared constants and helpers for MeshStore and its collaborator classes — module-level constants, types, and free functions with no `this` dependency, split out purely to keep mesh-store.ts under the repo's max-lines cap.
+ */
+
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import type { RevocationView } from "wire-mesh-core/domain/revocation-view";
+import type { KeyValueStorage } from "wire-mesh-core/ports/storage";
+import type { IdentitySlot } from "./identity-store.js";
+import type { AccountLedger } from "./account-ledger.js";
+import type { UserIdentityOptions } from "./user-identity.js";
+import type { MachineIdentityOptions } from "./machine-identity.js";
+
+/** The identity/clock/persistence collaborators MeshStore mints and persists room-membership grants against. Set via setIdentity(), mirroring the transport's own setTransport() contract. dataStorage backs this device's own room-notice oplog (P5, agent-comms#50): the same KeyValueStorage instance WireMeshTransport's own dataStorage constructor parameter is wired with, so a durable sendRoomMessage and the transport's own data-domain responder read and write the identical log. userIdentity/userIdentityOptions are the user-principal identity (user-identity.ts, agent-comms#160) this store's own bridge slot shares with every other bridge of this account, distinct from `identity`, which is this specific bridge's own per-slot device identity; userIdentity is what a dm:send grant (agent-comms#162) is minted and verified against. accountLedger is the account's replicated, encrypted grant ledger (account-ledger.ts, agent-comms#344), where every grant this principal mints is recorded so any machine holding the account key can revoke it. userIdentityOptions locates the file userIdentity was loaded from, which the account's own join flow (account-join.ts) reads to seal the key for a joining machine and writes to import one it joins. machineIdentity is this account's machine identity for the host (machine-identity.ts, agent-comms#343), shared by every bridge the account runs there: the second grouping issuer this store's device is vouched for by. machineIdentityOptions locates the file it was loaded from, where the machine's self display name (agent-comms#345) is kept. */
+export interface MeshStoreIdentity {
+  identity: IdentityPort;
+  clock: Clock;
+  slot: IdentitySlot;
+  revocation: RevocationView;
+  dataStorage: KeyValueStorage;
+  userIdentity: IdentityPort;
+  accountLedger: AccountLedger;
+  /** Where userIdentity's key lives on this machine, for the account's own join flow (account-join.ts) to seal it for a joining machine and to import one it joins. */
+  userIdentityOptions: Readonly<UserIdentityOptions>;
+  machineIdentity: IdentityPort;
+  machineIdentityOptions: Readonly<MachineIdentityOptions>;
+}
+
+/**
+ * Lifetime of a freshly minted room:member grant (owner root grant or member join/invite grant alike). Deliberately generous rather than the "short expires, periodic re-issue" pattern the design calls for to bound kick-convergence to gossip-independent expiry -- that re-issue mechanism is P3.7's own deliverable (riding room.members refreshes), and shipping a short expiry before it exists would let ordinary grants go stale with nothing to renew them. 30 days comfortably outlives any realistic room lifetime for now; P3.7 tightens this once re-issue-on-refresh lands.
+ */
+const ROOM_TOKEN_LIFETIME_DAYS = 30;
+const HOURS_PER_DAY = 24;
+const MINUTES_PER_HOUR = 60;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+export const ROOM_TOKEN_LIFETIME_MS =
+  ROOM_TOKEN_LIFETIME_DAYS *
+  HOURS_PER_DAY *
+  MINUTES_PER_HOUR *
+  SECONDS_PER_MINUTE *
+  MS_PER_SECOND;
+
+/** Lifetime of a freshly minted dm:send grant (agent-comms#162) -- the same 30-day generosity ROOM_TOKEN_LIFETIME_MS applies, for the same reason: no periodic re-issue-on-refresh mechanism exists yet for this grant kind either, so a short expiry would just let ordinary admissions go stale with nothing to renew them. */
+const DM_SEND_GRANT_LIFETIME_DAYS = 30;
+export const DM_SEND_GRANT_LIFETIME_MS =
+  DM_SEND_GRANT_LIFETIME_DAYS *
+  HOURS_PER_DAY *
+  MINUTES_PER_HOUR *
+  SECONDS_PER_MINUTE *
+  MS_PER_SECOND;
+
+/** The outcome of a pending room.join request: a human's accept or reject (reject carries an optional reason, mirroring rejectConnection's own equivalent room-independent decision), or expiry when nobody decided within the approval window. */
+export type RoomJoinDecision =
+  | { kind: "accept" }
+  | { kind: "reject"; reason?: string }
+  | { kind: "expired" };
+
+/**
+ * Bound on pending delivery events held per target agent. Events beyond the bound drop oldest-first: a long-offline agent's queue cannot grow without limit in memory or in synced snapshots (#28).
+ */
+export const MAX_QUEUED_DELIVERIES_PER_AGENT = 100;
+
+/** Bound on directed room-domain requests held for retry per unreachable member. Requests beyond the bound drop oldest-first, and each drop is reported to its own sender as a terminal delivery status, so a message given up on is never left looking merely pending. */
+export const MAX_PENDING_ROOM_REQUESTS_PER_MEMBER = 100;
+
+/** How long a directed room-domain request may sit in the retry queue before it is given up on and its sender told it expired. Generous enough to outlast a peer restarting, a laptop sleeping overnight, or a hub outage, all of which a retry genuinely does fix; short enough that a message to a device that is never coming back stops being reported as pending indefinitely. */
+const PENDING_ROOM_REQUEST_TTL_HOURS = 24;
+export const PENDING_ROOM_REQUEST_TTL_MS =
+  PENDING_ROOM_REQUEST_TTL_HOURS *
+  MINUTES_PER_HOUR *
+  SECONDS_PER_MINUTE *
+  MS_PER_SECOND;
+
+/** The coordinator's own bind host -- always loopback, since the mesh coordinator role only ever needs to be reachable from other local peers on this machine. Shared between mesh-store.ts's own init() and PeerLifecycle's handleBecomeCoordinator. */
+export const COORDINATOR_HOST = "127.0.0.1";
+
+/** The production relay hub this machine's gateway dials once it becomes the local mesh coordinator (agent-comms#154). Configuration: MeshStore's own constructor accepts an override, threaded from createBridgeMesh/createBridgeMeshSync, for tests and any future non-default deployment; a user picks a different hub for every bridge on the machine with HUB_URL_ENV_VAR (see resolveHubUrl) -- this is only the default. */
+export const DEFAULT_HUB_URL = "wss://mesh.exadev.io/";
+
+/** The environment variable that points every bridge started from this environment at a self-hosted hub (for example `npx wire-mesh`) instead of DEFAULT_HUB_URL. */
+export const HUB_URL_ENV_VAR = "AGENT_COMMS_HUB_URL";
+
+/**
+ * The hub a bridge dials when its caller passes no explicit hubUrl: HUB_URL_ENV_VAR when it is set and not blank, DEFAULT_HUB_URL otherwise.
+ *
+ * A value that is not a ws:// or wss:// URL throws rather than falling back to DEFAULT_HUB_URL: someone who set the variable meant to keep their traffic off the public hub, so silently dialling it anyway would be the worst outcome.
+ */
+export function resolveHubUrl(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): string {
+  const configured = env[HUB_URL_ENV_VAR]?.trim();
+  if (configured === undefined || configured === "") return DEFAULT_HUB_URL;
+  let protocol: string;
+  try {
+    protocol = new URL(configured).protocol;
+  } catch {
+    protocol = "";
+  }
+  if (protocol !== "ws:" && protocol !== "wss:") {
+    throw new Error(
+      `${HUB_URL_ENV_VAR} must be a ws:// or wss:// URL, got "${configured}"`,
+    );
+  }
+  return configured;
+}
+
+/** Shallow-clones an entry together with its own `readBy` array, so a merged history never shares mutable array references with either input it was built from. */
+function cloneWithReadBy<T extends { readBy: string[] }>(entry: T): T {
+  return { ...entry, readBy: [...entry.readBy] };
+}
+
+/**
+ * Merge an incoming append-only message history with the local one, returning a new array: entries the local list does not have are appended, and read receipts are unioned on the ones it does. Local ordering is preserved; unseen entries are appended. Neither input array (nor its entries) is mutated -- the caller is responsible for storing the returned array back wherever the local history is kept.
+ */
+export function mergeMessageHistories<
+  T extends { id: string; readBy: string[] },
+>(local: readonly T[], incoming: readonly T[]): T[] {
+  const merged = local.map((m) => cloneWithReadBy(m));
+  const byId = new Map(merged.map((m) => [m.id, m]));
+  for (const msg of incoming) {
+    const existing = byId.get(msg.id);
+    if (existing === undefined) {
+      const copy = cloneWithReadBy(msg);
+      merged.push(copy);
+      byId.set(msg.id, copy);
+      continue;
+    }
+    for (const reader of msg.readBy) {
+      if (!existing.readBy.includes(reader)) existing.readBy.push(reader);
+    }
+  }
+  return merged;
+}