@llblab/pi-actors 0.42.3 → 0.43.0

package/lib/rooms.ts

@@ -1,939 +0,0 @@
-/**
- * Actor room persistence.
- * Zones: room timelines, rosters, branch inboxes, cross-branch discovery state
- * Owns file-backed room and branch-mailbox state; routing policy stays in tools/runtime adapters.
- */
-
-import * as fs from "node:fs";
-import { randomUUID } from "node:crypto";
-import * as path from "node:path";
-
-import type { ActorMessage } from "./messages.ts";
-import * as Limits from "./limits.ts";
-import { notifyRuntimeWake } from "./runtime-notifier.ts";
-import {
-  formatStateReadDiagnostics,
-  readJsonFileResilient,
-  readJsonlFileResilient,
-} from "./state-readers.ts";
-
-const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
-const STATE_LOCK_TIMEOUT_MS = 5000;
-const DEFAULT_ROOM_MAX_MESSAGES = 10000;
-const DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED = 2000;
-const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 250;
-
-export interface RoomMember {
-  address: string;
-  caps?: unknown;
-  claim?: unknown;
-  display?: unknown;
-  joined_at: string;
-  last_seen: string;
-  parent?: unknown;
-  role?: unknown;
-  status?: string;
-}
-
-export interface RoomTimelineEntry extends ActorMessage {
-  received_at: string;
-}
-
-export interface RoomAppendResult {
-  room: string;
-  message_count: number;
-  roster_count: number;
-  sent: true;
-}
-
-export interface RoomMessagePreview {
-  body_preview?: string;
-  from?: string;
-  summary?: string;
-  timestamp: string;
-  to: string;
-  type: string;
-}
-
-export interface RoomCompactionInfo {
-  compacted_at: string;
-  dropped_count: number;
-  first_kept_at?: string;
-  last_kept_at?: string;
-  max_messages: number;
-}
-
-export interface RoomStatus {
-  room: string;
-  message_count: number;
-  roster_count: number;
-  compaction?: RoomCompactionInfo;
-  diagnostics?: string[];
-  diagnostics_count?: number;
-  last_message_at?: string;
-  last_message_from?: string;
-  last_message_summary?: string;
-  last_message_type?: string;
-}
-
-export interface RoomContact {
-  address: string;
-  caps?: unknown;
-  claim?: unknown;
-  parent?: unknown;
-  role?: unknown;
-  status?: string;
-}
-
-export interface ActorCommunicationSnapshot {
-  contacts?: RoomContact[];
-  parent?: string;
-  root: string;
-  self: string;
-  rooms: Array<{
-    address: string;
-    members?: RoomMember[];
-    name: string;
-  }>;
-  updated_at: string;
-}
-
-function roomDir(stateDir: string, room: string): string {
-  return path.join(stateDir, "rooms", room);
-}
-
-function messagesFile(stateDir: string, room: string): string {
-  return path.join(roomDir(stateDir, room), "messages.jsonl");
-}
-
-function rosterFile(stateDir: string, room: string): string {
-  return path.join(roomDir(stateDir, room), "roster.json");
-}
-
-function snapshotFile(stateDir: string): string {
-  return path.join(stateDir, "communication.json");
-}
-
-function branchSnapshotFile(stateDir: string, branch: string): string {
-  return path.join(stateDir, "branches", branch, "communication.json");
-}
-
-function branchInboxFile(stateDir: string, branch: string): string {
-  return path.join(stateDir, "branches", branch, "inbox.jsonl");
-}
-
-function branchIdFromAddress(
-  address: string | undefined,
-  run: string,
-): string | undefined {
-  if (!address) return undefined;
-  const match = new RegExp(`^branch:${run}/(.+)$`).exec(address);
-  return match?.[1];
-}
-
-function ensureRoomDir(stateDir: string, room: string): void {
-  fs.mkdirSync(roomDir(stateDir, room), { recursive: true });
-}
-
-function sleepSync(ms: number): void {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-function acquireStateLock(
-  parentDir: string,
-  name: string,
-  label: string,
-): () => void {
-  fs.mkdirSync(parentDir, { recursive: true });
-  const lockDir = path.join(parentDir, name);
-  const started = Date.now();
-  while (true) {
-    try {
-      fs.mkdirSync(lockDir);
-      fs.writeFileSync(
-        path.join(lockDir, "owner.json"),
-        `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`,
-      );
-      return () => fs.rmSync(lockDir, { recursive: true, force: true });
-    } catch (error) {
-      try {
-        const stat = fs.statSync(lockDir);
-        if (Date.now() - stat.mtimeMs > STATE_LOCK_MAX_AGE_MS) {
-          fs.rmSync(lockDir, { recursive: true, force: true });
-          continue;
-        }
-      } catch {
-        continue;
-      }
-      if (Date.now() - started > STATE_LOCK_TIMEOUT_MS) {
-        throw new Error(`${label} lock timed out.`, { cause: error });
-      }
-      sleepSync(10);
-    }
-  }
-}
-
-function acquireRoomLock(stateDir: string, room: string): () => void {
-  return acquireStateLock(
-    roomDir(stateDir, room),
-    ".append.lock",
-    `Room append ${room}`,
-  );
-}
-
-function acquireBranchInboxLock(stateDir: string, branch: string): () => void {
-  return acquireStateLock(
-    path.dirname(branchInboxFile(stateDir, branch)),
-    ".inbox.lock",
-    `Branch inbox ${branch}`,
-  );
-}
-
-function asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : {};
-}
-
-function runFromRoomAddress(address: string): string | undefined {
-  const match = /^room:([^/]+)(?:\/main)?$/.exec(address);
-  return match?.[1];
-}
-
-function readJsonFile<T>(file: string, fallback: T): T {
-  return readJsonFileResilient<T>(file, fallback).value;
-}
-
-function writeJsonFile(file: string, value: unknown): void {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
-}
-
-function notifyActorWake(
-  stateDir: string,
-  actor: string,
-  reason: string,
-  metadata: Record<string, unknown> = {},
-): void {
-  try {
-    notifyRuntimeWake(stateDir, { actor, metadata, reason });
-  } catch {
-    // Runtime wakes are advisory; durable room/inbox state remains canonical.
-  }
-}
-
-function positiveEnvInt(name: string, fallback: number): number {
-  const value = Number(process.env[name] ?? fallback);
-  return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
-}
-
-function roomMaxMessages(): number {
-  return positiveEnvInt(
-    "PI_ACTORS_ROOM_MAX_MESSAGES",
-    DEFAULT_ROOM_MAX_MESSAGES,
-  );
-}
-
-function snapshotMinIntervalMs(): number {
-  return positiveEnvInt(
-    "PI_ACTORS_COMMUNICATION_SNAPSHOT_MIN_MS",
-    DEFAULT_SNAPSHOT_MIN_INTERVAL_MS,
-  );
-}
-
-function rosterMinIntervalMs(): number {
-  return positiveEnvInt(
-    "PI_ACTORS_ROOM_ROSTER_MIN_MS",
-    DEFAULT_SNAPSHOT_MIN_INTERVAL_MS,
-  );
-}
-
-function compactRoomMessages(stateDir: string, room: string): void {
-  const maxMessages = roomMaxMessages();
-  const file = messagesFile(stateDir, room);
-  const lines = readJsonlTailLines(file, maxMessages + 1);
-  if (lines.length <= maxMessages) return;
-  const kept = lines.slice(-maxMessages);
-  fs.writeFileSync(file, `${kept.join("\n")}\n`);
-  const keptMessages = kept.flatMap((line) => {
-    try {
-      return [JSON.parse(line) as RoomTimelineEntry];
-    } catch {
-      return [];
-    }
-  });
-  writeJsonFile(path.join(roomDir(stateDir, room), "compaction.json"), {
-    compacted_at: new Date().toISOString(),
-    dropped_count: lines.length - kept.length,
-    ...(keptMessages[0]?.received_at
-      ? { first_kept_at: keptMessages[0].received_at }
-      : {}),
-    ...(keptMessages.at(-1)?.received_at
-      ? { last_kept_at: keptMessages.at(-1)?.received_at }
-      : {}),
-    max_messages: maxMessages,
-  });
-}
-
-function readJsonlLineCount(file: string): number {
-  const stat = fs.statSync(file);
-  if (stat.size === 0) return 0;
-  const fd = fs.openSync(file, "r");
-  try {
-    const chunkSize = 64 * 1024;
-    const chunk = Buffer.allocUnsafe(chunkSize);
-    let position = 0;
-    let count = 0;
-    let lastByte: number | undefined;
-    while (position < stat.size) {
-      const bytesRead = fs.readSync(
-        fd,
-        chunk,
-        0,
-        Math.min(chunkSize, stat.size - position),
-        position,
-      );
-      if (bytesRead <= 0) break;
-      position += bytesRead;
-      for (let index = 0; index < bytesRead; index += 1) {
-        if (chunk[index] === 10) count += 1;
-      }
-      lastByte = chunk[bytesRead - 1];
-    }
-    return lastByte === 10 ? count : count + 1;
-  } finally {
-    fs.closeSync(fd);
-  }
-}
-
-function readRoomMessageCount(stateDir: string, room: string): number {
-  try {
-    return readJsonlLineCount(messagesFile(stateDir, room));
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0;
-    throw error;
-  }
-}
-
-function readJsonlTailLines(file: string, limit: number): string[] {
-  const lineLimit = Math.max(1, limit);
-  const stat = fs.statSync(file);
-  if (stat.size === 0) return [];
-  const fd = fs.openSync(file, "r");
-  try {
-    const chunkSize = 64 * 1024;
-    const chunks: Buffer[] = [];
-    let position = stat.size;
-    let newlines = 0;
-    while (position > 0 && newlines <= lineLimit) {
-      const size = Math.min(chunkSize, position);
-      position -= size;
-      const chunk = Buffer.allocUnsafe(size);
-      fs.readSync(fd, chunk, 0, size, position);
-      chunks.unshift(chunk);
-      for (let index = size - 1; index >= 0; index -= 1) {
-        if (chunk[index] === 10) newlines += 1;
-      }
-    }
-    return Buffer.concat(chunks)
-      .toString("utf8")
-      .split("\n")
-      .filter(Boolean)
-      .slice(-lineLimit);
-  } finally {
-    fs.closeSync(fd);
-  }
-}
-
-export function readRoomRoster(
-  stateDir: string,
-  room: string,
-): Record<string, RoomMember> {
-  return readJsonFile<Record<string, RoomMember>>(
-    rosterFile(stateDir, room),
-    {},
-  );
-}
-
-function writeRoomRoster(
-  stateDir: string,
-  room: string,
-  roster: Record<string, RoomMember>,
-): void {
-  ensureRoomDir(stateDir, room);
-  writeJsonFile(rosterFile(stateDir, room), roster);
-}
-
-function shouldDebounceFile(file: string, minIntervalMs: number): boolean {
-  try {
-    return Date.now() - fs.statSync(file).mtimeMs < minIntervalMs;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-function shouldDebounceSnapshot(file: string): boolean {
-  return shouldDebounceFile(file, snapshotMinIntervalMs());
-}
-
-function comparableRosterMember(member: RoomMember | undefined): string {
-  if (!member) return "";
-  const { last_seen: _lastSeen, ...semantic } = member;
-  return JSON.stringify(semantic);
-}
-
-function shouldWriteRoomRosterMember(
-  stateDir: string,
-  room: string,
-  before: RoomMember | undefined,
-  after: RoomMember,
-): boolean {
-  if (!before) return true;
-  if (comparableRosterMember(before) !== comparableRosterMember(after)) {
-    return true;
-  }
-  return !shouldDebounceFile(rosterFile(stateDir, room), rosterMinIntervalMs());
-}
-
-function updateRosterForMessage(
-  stateDir: string,
-  room: string,
-  message: ActorMessage,
-  receivedAt: string,
-): Record<string, RoomMember> {
-  const roster = readRoomRoster(stateDir, room);
-  if (!message.from) return roster;
-  const body = asRecord(message.body);
-  const current = roster[message.from];
-  const next =
-    message.type === "actor.leave"
-      ? {
-          address: message.from,
-          joined_at: current?.joined_at ?? receivedAt,
-          last_seen: receivedAt,
-          ...(current?.caps !== undefined ? { caps: current.caps } : {}),
-          ...(current?.claim !== undefined ? { claim: current.claim } : {}),
-          ...(current?.display !== undefined
-            ? { display: current.display }
-            : {}),
-          ...(current?.parent !== undefined ? { parent: current.parent } : {}),
-          ...(current?.role !== undefined
-            ? { role: current.role }
-            : { role: "actor" }),
-          status: String(body.status ?? "left"),
-        }
-      : {
-          address: message.from,
-          joined_at: current?.joined_at ?? receivedAt,
-          last_seen: receivedAt,
-          ...(body.caps !== undefined
-            ? { caps: body.caps }
-            : current?.caps !== undefined
-              ? { caps: current.caps }
-              : {}),
-          ...(body.claim !== undefined
-            ? { claim: body.claim }
-            : current?.claim !== undefined
-              ? { claim: current.claim }
-              : {}),
-          ...(body.display !== undefined
-            ? { display: body.display }
-            : current?.display !== undefined
-              ? { display: current.display }
-              : {}),
-          ...(body.parent !== undefined
-            ? { parent: body.parent }
-            : current?.parent !== undefined
-              ? { parent: current.parent }
-              : {}),
-          ...(body.role !== undefined
-            ? { role: body.role }
-            : current?.role !== undefined
-              ? { role: current.role }
-              : { role: "actor" }),
-          status: String(body.status ?? current?.status ?? "present"),
-        };
-  roster[message.from] = next;
-  if (shouldWriteRoomRosterMember(stateDir, room, current, next)) {
-    writeRoomRoster(stateDir, room, roster);
-  }
-  return roster;
-}
-
-export interface BranchInboxRecord extends ActorMessage {
-  claimed_at?: string;
-  claimed_by?: string;
-  error?: string;
-  failed_at?: string;
-  handled_at?: string;
-  id?: string;
-  queued_at?: string;
-  status?: string;
-}
-
-export interface BranchInboxReadResult {
-  corrupted: number;
-  messages: BranchInboxRecord[];
-}
-
-function readBranchInboxFile(
-  stateDir: string,
-  run: string,
-  address: string,
-  limit = 40,
-): BranchInboxReadResult {
-  const branch = branchIdFromAddress(address, run);
-  if (!branch)
-    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
-  try {
-    const lines = readJsonlTailLines(branchInboxFile(stateDir, branch), limit);
-    const messages: BranchInboxRecord[] = [];
-    let corrupted = 0;
-    for (const line of lines) {
-      try {
-        messages.push(JSON.parse(line));
-      } catch {
-        corrupted += 1;
-      }
-    }
-    return { corrupted, messages };
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT")
-      return { corrupted: 0, messages: [] };
-    throw error;
-  }
-}
-
-function readAllBranchInboxLines(
-  stateDir: string,
-  run: string,
-  address: string,
-): Array<{ raw: string } | { message: BranchInboxRecord }> {
-  const branch = branchIdFromAddress(address, run);
-  if (!branch)
-    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
-  try {
-    const content = fs.readFileSync(branchInboxFile(stateDir, branch), "utf8");
-    return content
-      .split("\n")
-      .filter((line) => line.length > 0)
-      .map((line) => {
-        try {
-          return { message: JSON.parse(line) as BranchInboxRecord };
-        } catch {
-          return { raw: line };
-        }
-      });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-    throw error;
-  }
-}
-
-export function readBranchInboxMessages(
-  stateDir: string,
-  run: string,
-  address: string,
-  limit = 40,
-): BranchInboxRecord[] {
-  return readBranchInboxFile(stateDir, run, address, limit).messages;
-}
-
-export function readBranchInboxDiagnostics(
-  stateDir: string,
-  run: string,
-  address: string,
-  limit = 40,
-): BranchInboxReadResult {
-  return readBranchInboxFile(stateDir, run, address, limit);
-}
-
-export function getBranchInboxTerminalRetainLimit(): number {
-  const value = Number(
-    process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "",
-  );
-  return Number.isInteger(value) && value >= 0
-    ? value
-    : DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED;
-}
-
-function compactBranchInboxMessages<T extends { status?: string }>(
-  messages: T[],
-): T[] {
-  const retainTerminal = getBranchInboxTerminalRetainLimit();
-  const active = messages.filter(
-    (message) => message.status !== "handled" && message.status !== "failed",
-  );
-  const terminal = messages.filter(
-    (message) => message.status === "handled" || message.status === "failed",
-  );
-  return [...terminal.slice(-retainTerminal), ...active];
-}
-
-export function appendBranchInboxMessage(
-  stateDir: string,
-  run: string,
-  address: string,
-  message: ActorMessage,
-): void {
-  const branch = branchIdFromAddress(address, run);
-  if (!branch)
-    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
-  const releaseLock = acquireBranchInboxLock(stateDir, branch);
-  try {
-    fs.writeFileSync(
-      branchInboxFile(stateDir, branch),
-      `${JSON.stringify({ ...message, id: randomUUID(), queued_at: new Date().toISOString(), status: "queued" })}\n`,
-      { flag: "a" },
-    );
-    notifyActorWake(stateDir, address, "branch.message", {
-      ...(message.from ? { from: message.from } : {}),
-      type: message.type,
-    });
-  } finally {
-    releaseLock();
-  }
-}
-
-export function claimBranchInboxMessage(
-  stateDir: string,
-  run: string,
-  address: string,
-  owner = "runtime",
-  statuses: string[] = ["queued"],
-): BranchInboxRecord | undefined {
-  const branch = branchIdFromAddress(address, run);
-  if (!branch)
-    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
-  const releaseLock = acquireBranchInboxLock(stateDir, branch);
-  try {
-    const file = branchInboxFile(stateDir, branch);
-    const records = readAllBranchInboxLines(stateDir, run, address);
-    let claimed: BranchInboxRecord | undefined;
-    const now = new Date().toISOString();
-    const updated = records.map((record) => {
-      if (claimed || !("message" in record)) return record;
-      const status = record.message.status ?? "queued";
-      if (!statuses.includes(status)) return record;
-      claimed = {
-        ...record.message,
-        claimed_at: now,
-        claimed_by: owner,
-        status: "claimed",
-      };
-      return { message: claimed };
-    });
-    if (!claimed) return undefined;
-    fs.writeFileSync(
-      file,
-      `${updated.map((record) => ("raw" in record ? record.raw : JSON.stringify(record.message))).join("\n")}\n`,
-    );
-    notifyActorWake(stateDir, address, "branch.inbox.claim", {
-      id: claimed.id,
-      owner,
-    });
-    return claimed;
-  } finally {
-    releaseLock();
-  }
-}
-
-export function updateBranchInboxMessageStatus(
-  stateDir: string,
-  run: string,
-  address: string,
-  id: string,
-  status: "claimed" | "handled" | "failed",
-  metadata: Record<string, unknown> = {},
-): boolean {
-  const branch = branchIdFromAddress(address, run);
-  if (!branch)
-    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
-  const releaseLock = acquireBranchInboxLock(stateDir, branch);
-  try {
-    const file = branchInboxFile(stateDir, branch);
-    const records = readAllBranchInboxLines(stateDir, run, address);
-    let changed = false;
-    const timestampKey = `${status}_at`;
-    const updated = records.map((record) => {
-      if (!("message" in record) || record.message.id !== id) return record;
-      changed = true;
-      return {
-        message: {
-          ...record.message,
-          ...metadata,
-          [timestampKey]: new Date().toISOString(),
-          status,
-        },
-      };
-    });
-    if (!changed) return false;
-    const validMessages = updated.flatMap((record) =>
-      "message" in record ? [record.message] : [],
-    );
-    const compactedIds = new Set(
-      compactBranchInboxMessages(validMessages).map((message) => message.id),
-    );
-    const lines = updated.flatMap((record) => {
-      if ("raw" in record) return [record.raw];
-      if (record.message.id && !compactedIds.has(record.message.id)) return [];
-      return [JSON.stringify(record.message)];
-    });
-    fs.writeFileSync(file, lines.length ? `${lines.join("\n")}\n` : "");
-    notifyActorWake(stateDir, address, "branch.inbox.status", { id, status });
-    return true;
-  } finally {
-    releaseLock();
-  }
-}
-
-export function appendRoomMessage(
-  stateDir: string,
-  room: string,
-  message: ActorMessage,
-): RoomAppendResult {
-  const releaseLock = acquireRoomLock(stateDir, room);
-  try {
-    const receivedAt = new Date().toISOString();
-    const entry: RoomTimelineEntry = { ...message, received_at: receivedAt };
-    fs.appendFileSync(
-      messagesFile(stateDir, room),
-      `${JSON.stringify(entry)}\n`,
-    );
-    compactRoomMessages(stateDir, room);
-    const roster = updateRosterForMessage(stateDir, room, message, receivedAt);
-    const run = runFromRoomAddress(message.to);
-    if (run) {
-      writeCommunicationSnapshot(stateDir, run);
-      notifyActorWake(stateDir, message.to, "room.message", {
-        ...(message.from ? { from: message.from } : {}),
-        type: message.type,
-      });
-      if (message.from && branchIdFromAddress(message.from, run)) {
-        writeBranchCommunicationSnapshotDebounced(stateDir, run, message.from);
-      }
-    }
-    return {
-      message_count: readRoomMessageCount(stateDir, room),
-      room,
-      roster_count: Object.keys(roster).length,
-      sent: true,
-    };
-  } finally {
-    releaseLock();
-  }
-}
-
-export function readRoomMessages(
-  stateDir: string,
-  room: string,
-  limit = 40,
-): RoomTimelineEntry[] {
-  try {
-    const lines = readJsonlTailLines(messagesFile(stateDir, room), limit);
-    return lines.flatMap((line) => {
-      try {
-        return [JSON.parse(line) as RoomTimelineEntry];
-      } catch {
-        return [];
-      }
-    });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-    throw error;
-  }
-}
-
-function previewValue(
-  value: unknown,
-  maxLength = Limits.ROOM_MESSAGE_PREVIEW_CHARS,
-): string | undefined {
-  if (value === undefined) return undefined;
-  const text = typeof value === "string" ? value : JSON.stringify(value);
-  const compact = text.replaceAll(/\s+/g, " ").trim();
-  if (!compact) return undefined;
-  return compact.length > maxLength
-    ? `${compact.slice(0, Math.max(0, maxLength - 1))}…`
-    : compact;
-}
-
-export function readRoomMessagePreviews(
-  stateDir: string,
-  room: string,
-  limit = 40,
-): RoomMessagePreview[] {
-  return readRoomMessages(stateDir, room, limit).map((message) => ({
-    ...(previewValue(message.body)
-      ? { body_preview: previewValue(message.body) }
-      : {}),
-    ...(message.from ? { from: message.from } : {}),
-    ...(message.summary ? { summary: message.summary } : {}),
-    timestamp: message.received_at,
-    to: message.to,
-    type: message.type,
-  }));
-}
-
-export function getRoomStatus(stateDir: string, room: string): RoomStatus {
-  const messageCount = readRoomMessageCount(stateDir, room);
-  const [last] = readRoomMessages(stateDir, room, 1);
-  const compactionRead = readJsonFileResilient<RoomCompactionInfo | undefined>(
-    path.join(roomDir(stateDir, room), "compaction.json"),
-    undefined,
-  );
-  const rosterRead = readJsonFileResilient<Record<string, RoomMember>>(
-    rosterFile(stateDir, room),
-    {},
-  );
-  const messageRead = readJsonlFileResilient<RoomTimelineEntry>(
-    messagesFile(stateDir, room),
-  );
-  const diagnostics = [
-    ...messageRead.diagnostics,
-    ...rosterRead.diagnostics,
-    ...compactionRead.diagnostics,
-  ];
-  return {
-    ...(last
-      ? {
-          last_message_at: last.received_at,
-          ...(last.from ? { last_message_from: last.from } : {}),
-          ...(last.summary ? { last_message_summary: last.summary } : {}),
-          last_message_type: last.type,
-        }
-      : {}),
-    ...(compactionRead.value ? { compaction: compactionRead.value } : {}),
-    ...(diagnostics.length
-      ? {
-          diagnostics: formatStateReadDiagnostics(diagnostics),
-          diagnostics_count: diagnostics.length,
-        }
-      : {}),
-    message_count: messageCount,
-    room,
-    roster_count: Object.keys(rosterRead.value).length,
-  };
-}
-
-export function ensureRoomMember(
-  stateDir: string,
-  run: string,
-  room: string,
-  address: string,
-  body: Record<string, unknown>,
-  summary: string,
-): RoomAppendResult {
-  const roster = readRoomRoster(stateDir, room);
-  if (roster[address]) {
-    return {
-      message_count: readRoomMessageCount(stateDir, room),
-      room,
-      roster_count: Object.keys(roster).length,
-      sent: true,
-    };
-  }
-  return appendRoomMessage(stateDir, room, {
-    body,
-    from: address,
-    summary,
-    to: `room:${run}`,
-    type: "actor.join",
-  });
-}
-
-export function ensureDefaultRoom(
-  stateDir: string,
-  run: string,
-): RoomAppendResult {
-  return ensureRoomMember(
-    stateDir,
-    run,
-    "main",
-    `run:${run}`,
-    { role: "run", status: "present" },
-    "Run joined default room",
-  );
-}
-
-export function readCommunicationSnapshot(
-  stateDir: string,
-): ActorCommunicationSnapshot | undefined {
-  return readJsonFileResilient<ActorCommunicationSnapshot | undefined>(
-    snapshotFile(stateDir),
-    undefined,
-  ).value;
-}
-
-export function readRoomContacts(
-  stateDir: string,
-  room: string,
-  self?: string,
-): RoomContact[] {
-  return Object.values(readRoomRoster(stateDir, room))
-    .filter((member) => member.address !== self)
-    .map((member) => ({
-      address: member.address,
-      ...(member.caps !== undefined ? { caps: member.caps } : {}),
-      ...(member.claim !== undefined ? { claim: member.claim } : {}),
-      ...(member.parent !== undefined ? { parent: member.parent } : {}),
-      ...(member.role !== undefined ? { role: member.role } : {}),
-      ...(member.status !== undefined ? { status: member.status } : {}),
-    }));
-}
-
-function buildCommunicationSnapshot(
-  stateDir: string,
-  run: string,
-  self: string,
-): ActorCommunicationSnapshot {
-  const mainRoster = Object.values(readRoomRoster(stateDir, "main"));
-  const contacts = readRoomContacts(stateDir, "main", self);
-  return {
-    ...(contacts.length > 0 ? { contacts } : {}),
-    ...(self !== `run:${run}` ? { parent: `run:${run}` } : {}),
-    root: `run:${run}`,
-    self,
-    rooms: [
-      {
-        address: `room:${run}`,
-        ...(mainRoster.length > 0 ? { members: mainRoster } : {}),
-        name: "main",
-      },
-    ],
-    updated_at: new Date().toISOString(),
-  };
-}
-
-export function writeCommunicationSnapshot(
-  stateDir: string,
-  run: string,
-): ActorCommunicationSnapshot {
-  const snapshot = buildCommunicationSnapshot(stateDir, run, `run:${run}`);
-  writeJsonFile(snapshotFile(stateDir), snapshot);
-  return snapshot;
-}
-
-export function writeBranchCommunicationSnapshot(
-  stateDir: string,
-  run: string,
-  self: string,
-): ActorCommunicationSnapshot {
-  const branch = branchIdFromAddress(self, run);
-  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${self}`);
-  const snapshot = buildCommunicationSnapshot(stateDir, run, self);
-  writeJsonFile(branchSnapshotFile(stateDir, branch), snapshot);
-  return snapshot;
-}
-
-function writeBranchCommunicationSnapshotDebounced(
-  stateDir: string,
-  run: string,
-  self: string,
-): ActorCommunicationSnapshot | undefined {
-  const branch = branchIdFromAddress(self, run);
-  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${self}`);
-  if (shouldDebounceSnapshot(branchSnapshotFile(stateDir, branch)))
-    return undefined;
-  return writeBranchCommunicationSnapshot(stateDir, run, self);
-}