serverless-ircd 0.1.0

package/packages/cf-adapter/src/cf-runtime.ts

@@ -0,0 +1,308 @@
+/**
+ * Cloudflare {@link IrcRuntime} adapter.
+ *
+ * Wires the three Durable Object namespaces (ConnectionDO, RegistryDO,
+ * ChannelDO) together behind a single {@link IrcRuntime} surface. Each
+ * method issues the correct DO `stub()` call:
+ *
+ *   - Nick registry ops route to `REGISTRY_DO` sharded by
+ *     {@link registryKeyForNick} so two clients racing on the same nick
+ *     always land on the same shard.
+ *   - Channel ops route to `CHANNEL_DO` keyed by lowercased channel name.
+ *   - Cross-connection `send` / `getConnectionInfo` route to the target
+ *     connection's `ConnectionDO` via RPC (`deliver`, `getConnSnapshot`).
+ *   - Calls whose target *is* the bound connection shortcut through the
+ *     injected {@link CfConnectionHandlers} — no RPC-to-self.
+ *
+ * The class is constructed per `ConnectionDO.webSocketMessage` event:
+ *
+ * ```ts
+ * const runtime = new CfRuntime(this.env, state.id, handlers);
+ * ```
+ *
+ * `state.id` is the DO's hex id (`ctx.id.toString()`), which is the same
+ * string other connections see when they look up a nick in the registry
+ * — so cross-connection routing is symmetric.
+ */
+
+import {
+  type ChanName,
+  type ChanSnapshot,
+  type ChannelDelta,
+  type ConnId,
+  type ConnSnapshot,
+  type ConnectionState,
+  type Nick,
+  type RawLine,
+  type RosterEntry,
+  toSnapshot,
+} from '@serverless-ircd/irc-core';
+import type { IrcRuntime } from '@serverless-ircd/irc-server';
+import type { Env, RegistryRpc } from './env.js';
+import { DEFAULT_REGISTRY_SHARDS, registryKeyForNick, shardNick } from './sharding.js';
+
+/** Per-connection transport callbacks the ConnectionDO wires up. */
+export interface CfConnectionHandlers {
+  /** Outbound IRC lines (already framed by the caller) written to the WS. */
+  send: (lines: RawLine[]) => void;
+  /** Close the underlying transport. */
+  disconnect: (reason?: string) => void;
+  /** Snapshot of the live ConnectionState, used by getConnectionInfo. */
+  snapshot(): ConnectionState | undefined;
+}
+
+/**
+ * RPC contract the {@link CfRuntime} expects on every `ConnectionDO`
+ * instance. ConnectionDO implements this in addition to its WebSocket
+ * handlers so that *other* connections' runtimes can route `Send` and
+ * `GetConnectionInfo` effects to it. The shape matches the
+ * {@link ConnectionDeliveryRpc} the ChannelDO uses, so a single RPC
+ * method (`deliver`) covers both fanout and point-to-point send paths.
+ */
+export interface ConnectionRpc {
+  /** Delivers `lines` to the live (or hibernated) WebSocket. */
+  deliver(lines: RawLine[]): Promise<{ delivered: number }>;
+  /** Returns a serializable snapshot of the connection state. */
+  getConnSnapshot(): Promise<ConnSnapshot | null>;
+}
+
+/**
+ * Cloudflare {@link IrcRuntime} bound to one connection.
+ *
+ * Construct one per inbound frame: cheap to build, no caching across
+ * events (every call hits the authoritative DO so state can never drift
+ * between the runtime and the DOs).
+ */
+export class CfRuntime implements IrcRuntime {
+  private readonly env: Env;
+  private readonly connId: ConnId;
+  private readonly handlers: CfConnectionHandlers;
+  private readonly registryShards: number;
+
+  constructor(
+    env: Env,
+    connId: ConnId,
+    handlers: CfConnectionHandlers,
+    opts: { registryShards?: number } = {},
+  ) {
+    this.env = env;
+    this.connId = connId;
+    this.handlers = handlers;
+    this.registryShards = opts.registryShards ?? DEFAULT_REGISTRY_SHARDS;
+  }
+
+  // -------------------------------------------------------------------------
+  // Transport
+  // -------------------------------------------------------------------------
+
+  async send(to: ConnId, lines: RawLine[]): Promise<void> {
+    if (to === this.connId) {
+      this.handlers.send(lines);
+      return;
+    }
+    // Cross-connection: route via the target's ConnectionDO RPC. The DO
+    // id (hex string) is exactly what the registry stores as the conn
+    // id, so `idFromString` resolves it directly.
+    const stub = this.env.CONNECTION_DO.get(this.env.CONNECTION_DO.idFromString(to));
+    await (stub as unknown as ConnectionRpc).deliver(lines);
+  }
+
+  async broadcast(chan: ChanName, lines: RawLine[], except?: ConnId): Promise<void> {
+    const payload = lines.map((l) => l.text);
+    await this.channelRpc(chan).broadcast(payload, except);
+  }
+
+  async disconnect(conn: ConnId, reason?: string): Promise<void> {
+    if (conn === this.connId) {
+      this.handlers.disconnect(reason);
+      return;
+    }
+    // Cross-connection disconnect is a teardown signal; we route it via
+    // the target's ConnectionDO RPC as well. (ConnectionDO doesn't expose
+    // a dedicated `disconnect` RPC today — the canonical teardown path is
+    // the WebSocket close, which is owned by the connection itself. We
+    // therefore no-op for cross-connection disconnects; this preserves
+    // the IrcRuntime contract without inventing a new RPC.)
+  }
+
+  async sendToNick(
+    nick: Nick,
+    _sender: ConnId,
+    lines: RawLine[],
+    notFoundLines?: RawLine[],
+  ): Promise<void> {
+    const owner = await this.registryRpc(nick).lookupNick(nick);
+    if (owner !== null) {
+      const stub = this.env.CONNECTION_DO.get(this.env.CONNECTION_DO.idFromString(owner));
+      await (stub as unknown as ConnectionRpc).deliver(lines);
+      return;
+    }
+    if (notFoundLines !== undefined) {
+      this.handlers.send(notFoundLines);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Nick registry
+  // -------------------------------------------------------------------------
+
+  async reserveNick(nick: Nick, conn: ConnId): Promise<{ ok: true } | { ok: false }> {
+    return this.registryRpc(nick).reserveNick(nick, conn);
+  }
+
+  async changeNick(conn: ConnId, oldNick: Nick, newNick: Nick): Promise<boolean> {
+    // Two-phase when the shards differ: reserve-new first; on success,
+    // release-old on the old shard. The new-nick shard wins the race;
+    // any concurrent contender that beats us to `newNick` makes the
+    // first phase fail and we leave `oldNick` untouched.
+    if (this.shardOf(oldNick) === this.shardOf(newNick)) {
+      return this.registryRpc(newNick).changeNick(conn, oldNick, newNick);
+    }
+    const reserved = await this.registryRpc(newNick).reserveNick(newNick, conn);
+    if (!reserved.ok) return false;
+    await this.registryRpc(oldNick).releaseNick(oldNick);
+    return true;
+  }
+
+  async releaseNick(nick: Nick): Promise<void> {
+    await this.registryRpc(nick).releaseNick(nick);
+  }
+
+  async lookupNick(nick: Nick): Promise<ConnId | null> {
+    return this.registryRpc(nick).lookupNick(nick);
+  }
+
+  // -------------------------------------------------------------------------
+  // Channel ownership
+  // -------------------------------------------------------------------------
+
+  async applyChannelDelta(chan: ChanName, delta: ChannelDelta): Promise<void> {
+    await this.channelRpc(chan).applyChannelDelta(delta);
+  }
+
+  async getChannelSnapshot(chan: ChanName): Promise<ChanSnapshot | null> {
+    // ChannelDO returns a JSON-friendly DTO (members/banMasks/pendingInvites
+    // as arrays). Rehydrate into a proper ChanSnapshot so callers can treat
+    // `members` as a ReadonlyMap keyed by ConnId and `banMasks`/pendingInvites
+    // as Sets.
+    const dto = (await this.channelRpc(chan).getChannelSnapshot()) as {
+      name: ChanName;
+      nameLower: string;
+      modes: ChanSnapshot['modes'];
+      banMasks: string[];
+      topic?: ChanSnapshot['topic'];
+      members: Array<RosterEntry & { conn: ConnId }>;
+      pendingInvites: string[];
+      createdAt: number;
+    } | null;
+    if (dto === null) return null;
+    const members = new Map<ConnId, RosterEntry>();
+    for (const entry of dto.members) {
+      members.set(entry.conn, {
+        conn: entry.conn,
+        nick: entry.nick,
+        op: entry.op,
+        voice: entry.voice,
+      });
+    }
+    const snap: ChanSnapshot = {
+      name: dto.name,
+      nameLower: dto.nameLower,
+      modes: { ...dto.modes },
+      banMasks: new Set(dto.banMasks),
+      ...(dto.topic !== undefined ? { topic: dto.topic } : {}),
+      members,
+      pendingInvites: new Set(dto.pendingInvites),
+      createdAt: dto.createdAt,
+    };
+    return snap;
+  }
+
+  // -------------------------------------------------------------------------
+  // Lookups
+  // -------------------------------------------------------------------------
+
+  async getConnectionInfo(conn: ConnId): Promise<ConnSnapshot | null> {
+    if (conn === this.connId) {
+      const live = this.handlers.snapshot();
+      return live === undefined ? null : toSnapshot(live);
+    }
+    const stub = this.env.CONNECTION_DO.get(this.env.CONNECTION_DO.idFromString(conn));
+    return (stub as unknown as ConnectionRpc).getConnSnapshot();
+  }
+
+  async getConnection(conn: ConnId): Promise<ConnectionState | null> {
+    // CF stores ConnectionState inside each ConnectionDO; the only
+    // authoritative view this runtime can hand out without a new RPC is
+    // the local connection's live state. Remote connections return null
+    // until a dedicated `getConnState` RPC lands alongside the broader
+    // WHOIS-over-CF work — the actor degrades to "unknown nick" for them.
+    if (conn === this.connId) {
+      return this.handlers.snapshot() ?? null;
+    }
+    return null;
+  }
+
+  async getChannelConnections(_chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>> {
+    // CF has no single source of truth for full ConnectionStates across
+    // all ConnectionDOs. The WHO command (the only current consumer)
+    // ships in a later ticket; return an empty map until then.
+    return new Map();
+  }
+
+  async listChannels(): Promise<ChanSnapshot[]> {
+    // CF has no central channel registry; each ChannelDO is independent.
+    // The LIST command (the only current consumer) ships in a later
+    // ticket; return an empty array until then.
+    return [];
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal
+  // -------------------------------------------------------------------------
+
+  /** Shard index for a nick under the configured fleet size. */
+  private shardOf(nick: Nick): number {
+    return shardNick(nick, this.registryShards);
+  }
+
+  /** Returns the registry DO RPC stub for the shard owning `nick`. */
+  private registryRpc(nick: Nick): RegistryRpc {
+    const key = registryKeyForNick(nick, this.registryShards);
+    const stub = this.env.REGISTRY_DO.get(this.env.REGISTRY_DO.idFromName(key));
+    return stub as unknown as RegistryRpc;
+  }
+
+  /** Returns the channel DO RPC stub for `name` (keyed by lowercased name). */
+  private channelRpc(name: ChanName): {
+    broadcast(lines: unknown[], except?: string): Promise<void>;
+    applyChannelDelta(delta: unknown): Promise<void>;
+    getChannelSnapshot(): Promise<unknown>;
+  } {
+    const lower = name.toLowerCase();
+    const stub = this.env.CHANNEL_DO.get(this.env.CHANNEL_DO.idFromName(lower));
+    return stub as unknown as {
+      broadcast(lines: unknown[], except?: string): Promise<void>;
+      applyChannelDelta(delta: unknown): Promise<void>;
+      getChannelSnapshot(): Promise<unknown>;
+    };
+  }
+}
+
+/**
+ * Legacy factory retained for backward compatibility with code that
+ * constructs the per-connection runtime inline (e.g. {@link ConnectionDO}'s
+ * own build path). Equivalent to `new CfRuntime(env, connId, handlers)`.
+ */
+export function makeCfRuntime(
+  env: Env,
+  connId: ConnId,
+  _registryKey: string,
+  handlers: CfConnectionHandlers,
+): IrcRuntime {
+  // `_registryKey` is ignored — the production CfRuntime always shards the
+  // registry by nick (the prior per-conn key was a 033 scaffolding
+  // convention that the real RegistryDO does not use).
+  void _registryKey;
+  return new CfRuntime(env, connId, handlers);
+}

package/packages/cf-adapter/src/channel-do.ts

@@ -0,0 +1,374 @@
+/**
+ * `ChannelDO` — Cloudflare Durable Object owning one IRC channel's
+ * authoritative state: roster, modes, topic, ban list.
+ *
+ * PLAN §6.1 — one DO instance per lowercased channel name
+ * (`env.CHANNEL_DO.idFromName(chanLower)`). The DO is the single
+ * serialized authority for that channel's roster; concurrent JOINs,
+ * MODEs, and broadcasts are serialized by the DO's request loop, so
+ * invariants (unique membership, consistent ban list, atomic topic
+ * swaps) hold without external locking.
+ *
+ * State is persisted to {@link DurableObjectState["storage"]} so it
+ * survives eviction. The persisted shape is a JSON-friendly
+ * {@link PersistedChannelState}; `Set`s and `Map`s are rebuilt on
+ * load (mirrors the trick used by `ConnectionDO`'s serialize module).
+ *
+ * Fanout model:
+ *   - `broadcast(lines, except)` walks the live roster and calls each
+ *     member's `ConnectionDO.deliver(lines)` via service-binding RPC.
+ *   - `deliver` returns `{ delivered: number }`; zero means the member
+ *     has no live WebSocket. The ChannelDO prunes those entries lazily
+ *     on every broadcast (and via the explicit {@link sweep} method)
+ *     so the roster cannot accumulate ghost members.
+ *
+ * Coordinates with ConnectionDO via the `applyChannelDelta` RPC: the
+ * ConnectionDO-side CfRuntime forwards every `ApplyChannelDelta` effect
+ * here, where the mutation lands on the authoritative state. The same
+ * delta shape from `@serverless-ircd/irc-core` flows both ways.
+ *
+ * RPC return-type note: snapshot reads return the JSON-friendly
+ * {@link ChannelSnapshotDto} (members/banMasks/pendingInvites as
+ * arrays) so they survive the DO RPC boundary without relying on
+ * structured-clone of `Map`/`Set`. The CfRuntime (036)
+ * rehydrates these into a full {@link ChanSnapshot} at the call site.
+ */
+
+import { DurableObject } from 'cloudflare:workers';
+import {
+  type ChanName,
+  type ChannelDelta,
+  type ChannelState,
+  type ChannelTopic,
+  type ConnId,
+  type RosterEntry,
+  applyChannelDelta,
+  createChannel,
+  toSnapshot,
+} from '@serverless-ircd/irc-core';
+import type { Env } from './env.js';
+
+/** Storage key under which the per-channel state is persisted. */
+const STATE_STORAGE_KEY = 'channel-state';
+
+/**
+ * JSON-friendly persisted shape. `members` (a `Map`) and `banMasks`
+ * (a `Set`) are serialized as arrays; everything else survives
+ * `JSON.stringify` verbatim. `pendingInvites` is similarly serialized
+ * as an array of lowercased nicks.
+ */
+interface PersistedChannelState {
+  name: ChanName;
+  nameLower: string;
+  modes: ChannelState['modes'];
+  banMasks: string[];
+  topic?: ChannelTopic;
+  members: Array<Omit<RosterEntry, 'conn'> & { conn: ConnId }>;
+  pendingInvites: string[];
+  createdAt: number;
+}
+
+/**
+ * Result returned by `ConnectionDO.deliver`. The ChannelDO prunes any
+ * member whose `deliver` returns `delivered: 0`.
+ */
+export interface DeliverResult {
+  delivered: number;
+}
+
+/**
+ * RPC contract `ChannelDO` calls on each member's `ConnectionDO`. The
+ * real `ConnectionDO` implements this; tests use the same shape against
+ * the production `ConnectionDO` instance.
+ */
+export interface ConnectionDeliveryRpc {
+  deliver(lines: Array<{ text: string }>): Promise<DeliverResult>;
+}
+
+/**
+ * JSON-friendly snapshot DTO returned by `getChannelSnapshot`. Maps and
+ * Sets are flattened to arrays so the value survives the DO RPC
+ * boundary in both production and the test pool. The CfRuntime
+ * (036) rehydrates this into a {@link ChanSnapshot} at the
+ * call site.
+ */
+export interface ChannelSnapshotDto {
+  name: ChanName;
+  nameLower: string;
+  modes: ChannelState['modes'];
+  banMasks: string[];
+  topic?: ChannelTopic;
+  members: RosterEntry[];
+  pendingInvites: string[];
+  createdAt: number;
+}
+
+/**
+ * ChannelDO instance.
+ *
+ * The class is exported as the binding target in `wrangler.toml`; the
+ * Workers runtime instantiates it with `(ctx, env)` per DO id.
+ */
+export class ChannelDO extends DurableObject<Env> {
+  /** Cached authoritative channel state; reloaded from storage on miss. */
+  private cached: ChannelState | undefined;
+
+  // -------------------------------------------------------------------------
+  // RPC — roster / modes / topic mutations
+  // -------------------------------------------------------------------------
+
+  /**
+   * Applies a {@link ChannelDelta} atomically: memberships, modeChanges,
+   * banMaskChanges, and topic. Idempotent for no-op deltas (empty
+   * membership lists, missing members, etc.).
+   *
+   * This is the single entry point ConnectionDO uses (via CfRuntime)
+   * to mutate channel state in response to JOIN / PART / KICK / MODE /
+   * TOPIC reducers. The reducer builds the delta; this method applies
+   * it against the authoritative state and persists the result.
+   */
+  async applyChannelDelta(delta: ChannelDelta): Promise<void> {
+    const state = await this.loadState();
+    const next = applyChannelDelta(state, delta);
+    await this.persistState(next);
+  }
+
+  // -------------------------------------------------------------------------
+  // RPC — fanout
+  // -------------------------------------------------------------------------
+
+  /**
+   * Fans `lines` out to every member of the channel (optionally
+   * skipping `except`). For each member the DO calls
+   * `ConnectionDO.deliver(lines)` via service-binding RPC; members
+   * whose `deliver` returns `{ delivered: 0 }` are pruned from the
+   * roster (lazy gone-connection sweep).
+   *
+   * The fan-out runs in parallel via `Promise.all` so a 1k-member
+   * channel completes within a single event-loop tick budget. Member
+   * order in the resulting prune set is non-deterministic but the
+   * prune delta is order-independent (removes are idempotent).
+   *
+   * @param lines Raw IRC line texts to deliver.
+   * @param except Optional ConnId to skip (e.g. the sender of a PRIVMSG).
+   */
+  async broadcast(lines: string[], except?: ConnId): Promise<void> {
+    if (lines.length === 0) return;
+    const state = await this.loadState();
+    if (state.members.size === 0) return;
+
+    const payload = lines.map((text) => ({ text }));
+    const pruned = await this.fanoutAndCollect(state, payload, except);
+    if (pruned.length > 0) {
+      const next = applyChannelDelta(state, {
+        memberships: pruned.map((conn) => ({ type: 'remove' as const, conn })),
+      });
+      await this.persistState(next);
+    }
+  }
+
+  /**
+   * Explicit gone-connection sweep. Walks every roster entry and prunes
+   * those whose ConnectionDO reports `delivered: 0` (no live WebSocket).
+   * Returns the number of members pruned.
+   *
+   * Useful for periodic alarm-driven cleanup; the `broadcast` path
+   * performs the same pruning lazily on every fan-out.
+   */
+  async sweep(): Promise<number> {
+    const state = await this.loadState();
+    if (state.members.size === 0) return 0;
+    // Probe each member with an empty payload (deliver returns the
+    // OPEN-socket count without sending bytes).
+    const pruned = await this.fanoutAndCollect(state, [], undefined);
+    if (pruned.length > 0) {
+      const next = applyChannelDelta(state, {
+        memberships: pruned.map((conn) => ({ type: 'remove' as const, conn })),
+      });
+      await this.persistState(next);
+    }
+    return pruned.length;
+  }
+
+  // -------------------------------------------------------------------------
+  // RPC — reads
+  // -------------------------------------------------------------------------
+
+  /**
+   * Returns a read-only snapshot of the channel state as a
+   * JSON-friendly DTO ({@link ChannelSnapshotDto}). Suitable for
+   * NAMES, WHO, and PRIVMSG fanout routing decisions. The DTO uses
+   * arrays instead of `Map`/`Set` so it survives DO RPC in both
+   * production and the test pool.
+   */
+  async getChannelSnapshot(): Promise<ChannelSnapshotDto> {
+    const state = await this.loadState();
+    return toDto(state);
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+
+  /** Loads the authoritative state from storage, caching on first read. */
+  private async loadState(): Promise<ChannelState> {
+    if (this.cached !== undefined) return this.cached;
+    const record = await this.ctx.storage.get<PersistedChannelState>(STATE_STORAGE_KEY);
+    if (record === undefined) {
+      const key = this.ctx.id.name ?? this.ctx.id.toString();
+      this.cached = createChannel({
+        name: key,
+        nameLower: key,
+        createdAt: Date.now(),
+      });
+    } else {
+      this.cached = deserializeChannel(record);
+    }
+    return this.cached;
+  }
+
+  /** Persists the authoritative state and refreshes the cache. */
+  private async persistState(state: ChannelState): Promise<void> {
+    this.cached = state;
+    await this.ctx.storage.put(STATE_STORAGE_KEY, serializeChannel(state));
+  }
+
+  /**
+   * Iterates roster entries, calling `deliver` on each member's
+   * ConnectionDO **in parallel** via `Promise.all`. Returns the list
+   * of ConnIds whose deliver reported `delivered: 0` (i.e. gone
+   * connections). The caller is responsible for applying the prune as
+   * a delta so the persisted state stays consistent with the cache.
+   *
+   * Parallel fan-out keeps a 1k-member broadcast within a single
+   * event-loop tick budget. Per-member deliver is independent (no
+   * shared mutable state), so parallelization is safe; the resulting
+   * prune set order is non-deterministic but the prune delta is
+   * order-independent (removes are idempotent).
+   *
+   * Defensive note: thrown RPCs are treated as "delivered: 0" — we do
+   * not want a transient failure to wedge the roster, but the safest
+   * interpretation of a thrown cross-DO call is "the member is gone".
+   */
+  private async fanoutAndCollect(
+    state: ChannelState,
+    payload: Array<{ text: string }>,
+    except: ConnId | undefined,
+  ): Promise<ConnId[]> {
+    const targets: ConnId[] = [];
+    for (const connId of state.members.keys()) {
+      if (except !== undefined && connId === except) continue;
+      targets.push(connId);
+    }
+    const results = await Promise.all(
+      targets.map(async (connId) => ({
+        connId,
+        delivered: await this.deliverToMember(connId, payload),
+      })),
+    );
+    return results.filter((r) => r.delivered === 0).map((r) => r.connId);
+  }
+
+  /**
+   * Calls `deliver` on the member's ConnectionDO. Returns the
+   * `delivered` count reported by the ConnectionDO, or `0` if the RPC
+   * throws (defensive: a totally missing DO instance still reports 0,
+   * which the caller interprets as "prune me").
+   */
+  private async deliverToMember(connId: ConnId, lines: Array<{ text: string }>): Promise<number> {
+    try {
+      // `connId` is the hex form of the existing ConnectionDO id; use
+      // `idFromString` so the same DO instance is addressed (hashing it
+      // via `idFromName` would point at a different, empty DO).
+      const id = this.env.CONNECTION_DO.idFromString(connId);
+      const stub = this.env.CONNECTION_DO.get(id);
+      const result = await (stub as unknown as ConnectionDeliveryRpc).deliver(lines);
+      return result.delivered;
+    } catch {
+      return 0;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Test hooks (only invoked from `runInDurableObject` in tests)
+  // -------------------------------------------------------------------------
+
+  /** Drops the in-memory state cache, simulating wake-from-eviction. */
+  public __resetCache(): void {
+    this.cached = undefined;
+  }
+
+  /**
+   * Returns the live cached state (without forcing a storage read).
+   * Exposed for tests that need to inspect Map/Set fields directly
+   * without going through the JSON-friendly DTO.
+   */
+  public async __peekState(): Promise<ChannelState | undefined> {
+    return this.cached;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// (De)serialization — Set/Map ↔ array round-trip for state.storage.
+// ---------------------------------------------------------------------------
+
+function serializeChannel(chan: ChannelState): PersistedChannelState {
+  const out: PersistedChannelState = {
+    name: chan.name,
+    nameLower: chan.nameLower,
+    modes: { ...chan.modes },
+    banMasks: [...chan.banMasks],
+    members: [...chan.members.values()].map((e) => ({
+      conn: e.conn,
+      nick: e.nick,
+      op: e.op,
+      voice: e.voice,
+    })),
+    pendingInvites: [...chan.pendingInvites],
+    createdAt: chan.createdAt,
+  };
+  if (chan.topic !== undefined) out.topic = chan.topic;
+  return out;
+}
+
+function deserializeChannel(record: PersistedChannelState): ChannelState {
+  const chan: ChannelState = {
+    name: record.name,
+    nameLower: record.nameLower,
+    modes: { ...record.modes },
+    banMasks: new Set<string>(record.banMasks),
+    members: new Map<ConnId, RosterEntry>(
+      record.members.map((e) => [
+        e.conn,
+        { conn: e.conn, nick: e.nick, op: e.op ?? false, voice: e.voice ?? false },
+      ]),
+    ),
+    pendingInvites: new Set<string>(record.pendingInvites),
+    createdAt: record.createdAt,
+  };
+  if (record.topic !== undefined) chan.topic = record.topic;
+  return chan;
+}
+
+/**
+ * Builds a JSON-friendly {@link ChannelSnapshotDto} from a live
+ * {@link ChannelState}. Uses {@link toSnapshot} for the immutable
+ * view, then flattens the `Map`/`Set` fields to arrays.
+ */
+function toDto(chan: ChannelState): ChannelSnapshotDto {
+  // Defensively rebuild arrays; in some test-pool code paths the cached
+  // state's Set/Map fields may be missing if the channel was created
+  // via an unusual path (e.g. direct storage put without going through
+  // createChannel).
+  const dto: ChannelSnapshotDto = {
+    name: chan.name,
+    nameLower: chan.nameLower,
+    modes: { ...chan.modes },
+    banMasks: chan.banMasks ? [...chan.banMasks] : [],
+    members: chan.members ? [...chan.members.values()].map((e) => ({ ...e })) : [],
+    pendingInvites: chan.pendingInvites ? [...chan.pendingInvites] : [],
+    createdAt: chan.createdAt,
+  };
+  if (chan.topic !== undefined) dto.topic = chan.topic;
+  return dto;
+}