serverless-ircd 0.2.0 → 0.4.0

package/apps/cf-tcp-container/tests/container-server.test.ts

@@ -0,0 +1,465 @@
+import { EventEmitter } from 'node:events';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { type Socket, createConnection } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { type ContainerServer, startContainerServer } from '../src/container-server.js';
+
+/**
+ * Minimal IRC-over-TCP test client. Writes lines with CRLF, parses inbound
+ * bytes into IRC lines (tolerant of CRLF and bare LF).
+ */
+class TcpClient extends EventEmitter {
+  readonly socket: Socket;
+  readonly received: string[] = [];
+
+  constructor(host: string, port: number) {
+    super();
+    this.socket = createConnection({ host, port });
+    this.socket.setEncoding('utf8');
+    this.socket.on('data', (text: string) => {
+      for (const line of text.split(/\r?\n/u)) {
+        if (line.length > 0) {
+          this.received.push(line);
+          this.emit('line', line);
+        }
+      }
+    });
+  }
+
+  opened(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.socket.readyState === 'open') resolve();
+      else {
+        this.socket.once('connect', () => resolve());
+        this.socket.once('error', reject);
+      }
+    });
+  }
+
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.socket.write(`${line}\r\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  writeRaw(chunk: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.socket.write(chunk, 'utf8', (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 2000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`timeout; received: ${JSON.stringify(this.received)}`));
+      }, timeoutMs);
+      const check = (line: string): void => {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          this.off('line', check);
+          resolve(line);
+        }
+      };
+      for (const line of this.received) {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          resolve(line);
+          return;
+        }
+      }
+      this.on('line', check);
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.socket.once('close', () => resolve());
+      this.socket.end();
+    });
+  }
+
+  destroy(): void {
+    this.socket.destroy();
+  }
+}
+
+describe('container-server — lifecycle', () => {
+  it('starts and exposes the bound port', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.test',
+      networkName: 'TestNet',
+    });
+    expect(srv.port).toBeGreaterThan(0);
+    expect(srv.host).toBe('127.0.0.1');
+    await srv.close();
+  });
+
+  it('close() is idempotent', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.test',
+      networkName: 'TestNet',
+    });
+    await srv.close();
+    await expect(srv.close()).resolves.toBeUndefined();
+  });
+
+  it('rejects when the port is already in use', async () => {
+    const first = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.test',
+      networkName: 'TestNet',
+    });
+    await expect(
+      startContainerServer({
+        port: first.port,
+        host: '127.0.0.1',
+        serverName: 'irc.test',
+        networkName: 'TestNet',
+      }),
+    ).rejects.toThrow();
+    await first.close();
+  });
+});
+
+describe('container-server — IRC flows over TCP', () => {
+  let server: ContainerServer;
+
+  beforeAll(async () => {
+    server = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.example.com',
+      networkName: 'ExampleNet',
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('completes register → join → privmsg → quit', async () => {
+    const alice = new TcpClient('127.0.0.1', server.port);
+    const bob = new TcpClient('127.0.0.1', server.port);
+    await alice.opened();
+    await bob.opened();
+
+    await alice.send('NICK alice');
+    await alice.send('USER alice 0 * :Alice');
+    await alice.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await bob.send('NICK bob');
+    await bob.send('USER bob 0 * :Bob');
+    await bob.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await alice.send('JOIN #container');
+    await alice.waitFor((l) => l.includes('JOIN #container'));
+    await bob.send('JOIN #container');
+    await bob.waitFor((l) => l.includes('JOIN #container'));
+
+    await alice.send('PRIVMSG #container :hello from tcp origin');
+    await bob.waitFor((l) => l.includes('PRIVMSG #container :hello from tcp origin'));
+
+    await alice.close();
+    await bob.close();
+  });
+
+  it('routes PING → PONG', async () => {
+    const client = new TcpClient('127.0.0.1', server.port);
+    await client.opened();
+    await client.send('NICK pinger');
+    await client.send('USER pinger 0 * :Pinger');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await client.send('PING :tok-123');
+    await client.waitFor((l) => l === 'PONG :tok-123');
+    await client.close();
+  });
+
+  it('reassembles a single IRC message split across two TCP chunks', async () => {
+    const client = new TcpClient('127.0.0.1', server.port);
+    await client.opened();
+    await client.send('NICK splitter');
+    await client.send('USER splitter 0 * :Splitter');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await client.writeRaw('PING :split');
+    await client.writeRaw('ted-tok\r\n');
+    await client.waitFor((l) => l === 'PONG :splitted-tok');
+    await client.close();
+  });
+
+  it('processes multiple IRC lines delivered in a single TCP chunk', async () => {
+    const client = new TcpClient('127.0.0.1', server.port);
+    await client.opened();
+    await client.writeRaw('NICK bundler\r\nUSER bundler 0 * :Bundler\r\n');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 bundler'));
+    await client.close();
+  });
+
+  it('cleans up the runtime connection on abrupt socket termination', async () => {
+    const client = new TcpClient('127.0.0.1', server.port);
+    await client.opened();
+    await client.send('NICK termUser');
+    await client.send('USER termUser 0 * :Term');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('termUser');
+    expect(connId).not.toBeNull();
+    expect(server.runtime.hasConnection(connId as string)).toBe(true);
+
+    client.destroy();
+    await new Promise((r) => setTimeout(r, 100));
+    expect(server.runtime.hasConnection(connId as string)).toBe(false);
+  });
+
+  it('delivers an ERROR notice when a reducer supplies a disconnect reason', async () => {
+    const client = new TcpClient('127.0.0.1', server.port);
+    await client.opened();
+    await client.send('NICK floodUser');
+    await client.send('USER floodUser 0 * :Flood');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('floodUser');
+    expect(connId).not.toBeNull();
+    const wait = client.waitFor((l) => l.startsWith('ERROR :Closing link:'));
+    await server.runtime.disconnect(connId as string, 'Excess Flood');
+    await expect(wait).resolves.toContain('Excess Flood');
+    await client.close();
+  });
+});
+
+describe('container-server — persistence across restart', () => {
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'sirc-container-'));
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('channel state survives a restart via snapshot file', async () => {
+    const statePath = join(dir, 'restart.json');
+
+    // Boot #1: register, join, set topic + modes, then close (snapshot).
+    const srv1 = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.persist',
+      networkName: 'PersistNet',
+      persistencePath: statePath,
+    });
+    const c1 = new TcpClient('127.0.0.1', srv1.port);
+    await c1.opened();
+    await c1.send('NICK op');
+    await c1.send('USER op 0 * :Op');
+    await c1.waitFor((l) => l.startsWith(':irc.persist 001 '));
+    await c1.send('JOIN #persist');
+    await c1.waitFor((l) => l.includes('JOIN #persist'));
+    await c1.send('TOPIC #persist :persisted topic');
+    await c1.waitFor((l) => l.includes('TOPIC #persist :persisted topic'));
+    await c1.send('MODE #persist +s');
+    await c1.waitFor((l) => l.includes('MODE #persist +s'));
+    await c1.close();
+    await srv1.close();
+
+    // Boot #2: a fresh client joins and sees the persisted topic + modes.
+    const srv2 = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.persist',
+      networkName: 'PersistNet',
+      persistencePath: statePath,
+    });
+    const c2 = new TcpClient('127.0.0.1', srv2.port);
+    await c2.opened();
+    await c2.send('NICK late');
+    await c2.send('USER late 0 * :Late');
+    await c2.waitFor((l) => l.startsWith(':irc.persist 001 '));
+    await c2.send('JOIN #persist');
+    await c2.waitFor((l) => l.includes('JOIN #persist'));
+    // The topic should be readable after restore.
+    await c2.send('TOPIC #persist');
+    await c2.waitFor((l) => l.includes('332') && l.includes('persisted topic'), 3000);
+    // The secret mode (+s) should be restored — verify via the runtime.
+    const snap = await srv2.runtime.getChannelSnapshot('#persist');
+    expect(snap?.modes.secret).toBe(true);
+    expect(snap?.topic?.text).toBe('persisted topic');
+    await c2.close();
+    await srv2.close();
+  });
+});
+
+describe('container-server — admission gate', () => {
+  it('rejects a connection when per-IP limit is reached', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.gate',
+      networkName: 'GateNet',
+      maxConnectionsPerIp: 1,
+    });
+    const c1 = new TcpClient('127.0.0.1', srv.port);
+    await c1.opened();
+    // Second connection from the same IP should be rejected.
+    const c2 = new TcpClient('127.0.0.1', srv.port);
+    const error = await new Promise<string | null>((resolve) => {
+      c2.socket.setEncoding('utf8');
+      c2.socket.once('data', (d: string) => resolve(d));
+      c2.socket.once('close', () => resolve(null));
+      setTimeout(() => resolve(null), 2000);
+    });
+    expect(error).toContain('Closing link');
+    await c1.close();
+    await srv.close();
+  });
+});
+
+describe('container-server — snapshot error resilience', () => {
+  it('logs and continues when the snapshot file is corrupt on boot', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'sirc-corrupt-'));
+    const path = join(dir, 'corrupt.json');
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(path, '{ this is not valid json', 'utf8');
+
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.corrupt',
+      networkName: 'CorruptNet',
+      persistencePath: path,
+    });
+    // Server should still work — starts fresh.
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    await c.send('NICK test');
+    await c.send('USER test 0 * :Test');
+    await c.waitFor((l) => l.startsWith(':irc.corrupt 001 '), 2000);
+    await c.close();
+    await srv.close();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('close() destroys live sockets before snapshotting', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'sirc-close-'));
+    const path = join(dir, 'close.json');
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.close',
+      networkName: 'CloseNet',
+      persistencePath: path,
+      snapshotIntervalMs: 999_999,
+    });
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    // Wait for the server-side socket to be registered in the sockets set.
+    for (let i = 0; i < 50 && srv.testSockets.size === 0; i++) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    expect(srv.testSockets.size).toBe(1);
+    // Closing the server should force-close the client's socket.
+    const closed = new Promise<void>((resolve) => c.socket.once('close', () => resolve()));
+    await srv.close();
+    await closed;
+    expect(c.socket.destroyed).toBe(true);
+    await rm(dir, { recursive: true, force: true });
+  });
+});
+
+describe('container-server — error paths', () => {
+  it('logs an actor failure without crashing the server', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.err',
+      networkName: 'ErrNet',
+    });
+    const original = srv.runtime.send.bind(srv.runtime);
+    srv.runtime.send = async () => {
+      throw new Error('synthetic send failure');
+    };
+    const client = new TcpClient('127.0.0.1', srv.port);
+    await client.opened();
+    await client.send('NICK errUser');
+    await client.send('USER errUser 0 * :Err');
+    // PING triggers a Send → synthetic throw → actor catch → logError.
+    await client.send('PING :will-throw');
+    await new Promise((r) => setTimeout(r, 100));
+
+    srv.runtime.send = original;
+    // Server should still serve new connections.
+    const next = new TcpClient('127.0.0.1', srv.port);
+    await next.opened();
+    await next.send('NICK recover');
+    await next.send('USER recover 0 * :Recover');
+    await next.waitFor((l) => l.startsWith(':irc.err 001 '), 3000);
+    await next.close();
+    await client.close();
+    await srv.close();
+  });
+
+  it('logs and recovers from a per-socket error', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.sockerr',
+      networkName: 'SockErrNet',
+    });
+    const client = new TcpClient('127.0.0.1', srv.port);
+    await client.opened();
+    for (let i = 0; i < 50 && srv.testSockets.size === 0; i++) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    const serverSideSocket = [...srv.testSockets][0];
+    if (serverSideSocket === undefined) throw new Error('no server-side socket');
+    serverSideSocket.emit('error', new Error('synthetic socket failure'));
+    await new Promise((r) => setImmediate(r));
+    // Server should still serve new connections.
+    const next = new TcpClient('127.0.0.1', srv.port);
+    await next.opened();
+    await next.close();
+    await client.close();
+    await srv.close();
+  });
+
+  it('auto-snapshots on the configured interval', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'sirc-auto-'));
+    const path = join(dir, 'auto.json');
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.auto',
+      networkName: 'AutoNet',
+      persistencePath: path,
+      snapshotIntervalMs: 100,
+    });
+    // Create a channel so the snapshot has content.
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    await c.send('NICK autoUser');
+    await c.send('USER autoUser 0 * :Auto');
+    await c.waitFor((l) => l.startsWith(':irc.auto 001 '), 2000);
+    await c.send('JOIN #auto-snap');
+    await c.waitFor((l) => l.includes('JOIN #auto-snap'));
+    // Wait for the interval to fire.
+    await new Promise((r) => setTimeout(r, 200));
+    await c.close();
+    await srv.close();
+
+    // Verify the snapshot was written by the timer.
+    const { readFile } = await import('node:fs/promises');
+    const raw = await readFile(path, 'utf8');
+    const snap = JSON.parse(raw);
+    expect(snap.channels.some((ch: { name: string }) => ch.name === '#auto-snap')).toBe(true);
+    await rm(dir, { recursive: true, force: true });
+  });
+});

package/apps/cf-tcp-container/tests/persistence.test.ts

@@ -0,0 +1,227 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
+import type { ChanSnapshot } from '@serverless-ircd/irc-core';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import {
+  type PersistedState,
+  deserializeState,
+  loadSnapshot,
+  restoreRuntime,
+  saveSnapshot,
+  serializeState,
+  snapshotRuntime,
+} from '../src/persistence.js';
+
+/**
+ * Builds a runtime with two channels carrying distinct modes, topics, and
+ * ban masks so every persisted field is exercised. Members are intentionally
+ * omitted — they are per-connection and cannot survive a restart.
+ */
+async function runtimeWithChannels(): Promise<InMemoryRuntime> {
+  const rt = new InMemoryRuntime({ clock: { now: () => 1_700_000_000_000 } });
+  // #dev: secret + key + limit, topic set, one ban mask.
+  const dev = rt.getOrCreateChannel('#dev');
+  dev.modes.secret = true;
+  dev.modes.topicLock = true;
+  dev.modes.key = 'hunter2';
+  dev.modes.limit = 42;
+  dev.banMasks.add('*!bad@*.evil');
+  dev.topic = { text: 'dev chat', setter: 'op!op@op', setAt: 1_700_000_001_000 };
+  // #lobby: plain channel, no topic, no modes.
+  rt.getOrCreateChannel('#lobby');
+  return rt;
+}
+
+describe('persistence — snapshotRuntime', () => {
+  it('extracts channel state (name, modes, topic, bans, createdAt) without members', async () => {
+    const rt = await runtimeWithChannels();
+    const state = await snapshotRuntime(rt);
+    expect(state.version).toBe(1);
+    expect(state.channels).toHaveLength(2);
+
+    const dev = state.channels.find((c) => c.name === '#dev');
+    expect(dev).toBeDefined();
+    expect(dev?.modes.secret).toBe(true);
+    expect(dev?.modes.topicLock).toBe(true);
+    expect(dev?.modes.key).toBe('hunter2');
+    expect(dev?.modes.limit).toBe(42);
+    expect(dev?.banMasks).toEqual(['*!bad@*.evil']);
+    expect(dev?.topic).toEqual({
+      text: 'dev chat',
+      setter: 'op!op@op',
+      setAt: 1_700_000_001_000,
+    });
+    expect(dev?.createdAt).toBe(1_700_000_000_000);
+  });
+
+  it('omits topic when the channel has none', async () => {
+    const rt = await runtimeWithChannels();
+    const state = await snapshotRuntime(rt);
+    const lobby = state.channels.find((c) => c.name === '#lobby');
+    expect(lobby).toBeDefined();
+    expect(lobby?.topic).toBeUndefined();
+    expect(lobby?.banMasks).toEqual([]);
+  });
+
+  it('snapshots an empty runtime as zero channels', async () => {
+    const rt = new InMemoryRuntime({ clock: { now: () => 0 } });
+    const state = await snapshotRuntime(rt);
+    expect(state.channels).toHaveLength(0);
+  });
+});
+
+describe('persistence — serialize / deserialize round-trip', () => {
+  it('round-trips through JSON without loss', async () => {
+    const rt = await runtimeWithChannels();
+    const original = await snapshotRuntime(rt);
+    const json = serializeState(original);
+    const restored = deserializeState(json);
+    expect(restored).toEqual(original);
+  });
+
+  it('produces valid JSON with version and savedAt', async () => {
+    const rt = await runtimeWithChannels();
+    const state = await snapshotRuntime(rt);
+    const json = serializeState(state);
+    const parsed = JSON.parse(json) as PersistedState;
+    expect(parsed.version).toBe(1);
+    expect(typeof parsed.savedAt).toBe('number');
+    expect(Array.isArray(parsed.channels)).toBe(true);
+  });
+
+  it('throws on malformed JSON', () => {
+    expect(() => deserializeState('{ not json')).toThrow();
+  });
+
+  it('throws on wrong version', () => {
+    const bad = JSON.stringify({ version: 999, savedAt: 0, channels: [] });
+    expect(() => deserializeState(bad)).toThrow(/version/i);
+  });
+
+  it('throws when the JSON value is a primitive (not an object)', () => {
+    expect(() => deserializeState('"hello"')).toThrow(/object/i);
+    expect(() => deserializeState('42')).toThrow(/object/i);
+    expect(() => deserializeState('null')).toThrow(/object/i);
+  });
+
+  it('throws when channels is not an array', () => {
+    const bad = JSON.stringify({ version: 1, savedAt: 0, channels: 'not-an-array' });
+    expect(() => deserializeState(bad)).toThrow(/channels/i);
+  });
+
+  it('uses savedAt=0 when the field is missing or non-numeric', () => {
+    const state = deserializeState(JSON.stringify({ version: 1, channels: [] }));
+    expect(state.savedAt).toBe(0);
+  });
+});
+
+describe('persistence — saveSnapshot / loadSnapshot file I/O', () => {
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'sirc-persist-'));
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('writes and reads a snapshot file round-trip', async () => {
+    const rt = await runtimeWithChannels();
+    const state = await snapshotRuntime(rt);
+    const path = join(dir, 'snap.json');
+    await saveSnapshot(path, state);
+    const loaded = await loadSnapshot(path);
+    expect(loaded).not.toBeNull();
+    expect(loaded?.channels).toHaveLength(2);
+  });
+
+  it('returns null when the file does not exist', async () => {
+    const loaded = await loadSnapshot(join(dir, 'nonexistent.json'));
+    expect(loaded).toBeNull();
+  });
+
+  it('overwrites a previous snapshot on re-save', async () => {
+    const path = join(dir, 'overwrite.json');
+    const rt1 = new InMemoryRuntime({ clock: { now: () => 0 } });
+    rt1.getOrCreateChannel('#first');
+    await saveSnapshot(path, await snapshotRuntime(rt1));
+
+    const rt2 = new InMemoryRuntime({ clock: { now: () => 0 } });
+    rt2.getOrCreateChannel('#second');
+    await saveSnapshot(path, await snapshotRuntime(rt2));
+
+    const loaded = await loadSnapshot(path);
+    expect(loaded?.channels).toHaveLength(1);
+    expect(loaded?.channels[0]?.name).toBe('#second');
+  });
+});
+
+describe('persistence — restoreRuntime', () => {
+  it('restores channels with correct modes, topic, and bans into a fresh runtime', async () => {
+    const original = await runtimeWithChannels();
+    const state = await snapshotRuntime(original);
+
+    const target = new InMemoryRuntime({ clock: { now: () => 9_999 } });
+    restoreRuntime(target, state);
+
+    const channels = await target.listChannels();
+    expect(channels).toHaveLength(2);
+
+    const dev = channels.find((c) => c.name === '#dev') as ChanSnapshot;
+    expect(dev.modes.secret).toBe(true);
+    expect(dev.modes.topicLock).toBe(true);
+    expect(dev.modes.key).toBe('hunter2');
+    expect(dev.modes.limit).toBe(42);
+    expect([...dev.banMasks]).toEqual(['*!bad@*.evil']);
+    expect(dev.topic?.text).toBe('dev chat');
+    expect(dev.createdAt).toBe(1_700_000_000_000);
+
+    // Members must NOT be restored (connections are gone on restart).
+    expect(dev.members.size).toBe(0);
+  });
+
+  it('preserves the original channel name casing', async () => {
+    const original = new InMemoryRuntime({ clock: { now: () => 0 } });
+    original.getOrCreateChannel('#MixedCase');
+    const state = await snapshotRuntime(original);
+
+    const target = new InMemoryRuntime({ clock: { now: () => 0 } });
+    restoreRuntime(target, state);
+
+    const channels = await target.listChannels();
+    expect(channels[0]?.name).toBe('#MixedCase');
+    expect(channels[0]?.nameLower).toBe('#mixedcase');
+  });
+
+  it('full round-trip: snapshot → serialize → deserialize → restore yields equivalent state', async () => {
+    const original = await runtimeWithChannels();
+    const json = serializeState(await snapshotRuntime(original));
+    const restored = deserializeState(json);
+
+    const target = new InMemoryRuntime({ clock: { now: () => 0 } });
+    restoreRuntime(target, restored);
+
+    const before = (await original.listChannels()).sort((a, b) => a.name.localeCompare(b.name));
+    const after = (await target.listChannels()).sort((a, b) => a.name.localeCompare(b.name));
+
+    expect(after).toHaveLength(before.length);
+    for (let i = 0; i < before.length; i++) {
+      const b = before[i] as ChanSnapshot;
+      const a = after[i] as ChanSnapshot;
+      expect(a.name).toBe(b.name);
+      expect(a.modes).toEqual(b.modes);
+      expect([...a.banMasks].sort()).toEqual([...b.banMasks].sort());
+      expect(a.topic).toEqual(b.topic);
+      expect(a.createdAt).toBe(b.createdAt);
+    }
+  });
+
+  it('is a no-op on an empty channels list', async () => {
+    const target = new InMemoryRuntime({ clock: { now: () => 0 } });
+    restoreRuntime(target, { version: 1, savedAt: 0, channels: [] });
+    expect((await target.listChannels()).length).toBe(0);
+  });
+});