serverless-ircd 0.3.0 → 0.5.0

package/packages/irc-server/tests/actor.test.ts

@@ -12,16 +12,21 @@ import {
   FakeClock,
   type FloodControlConfig,
   InMemoryMessageStore,
+  InMemoryNickHistoryStore,
   LogLevel,
   type Logger,
   type MessageStore,
+  type MtlsIdentityProvider,
   type Nick,
+  type NickHistoryStore,
   Numerics,
   type RawLine,
   type SaslPayload,
   type SaslResult,
   SequentialIdFactory,
   type ServerConfig,
+  type ServerStats,
+  type ServerStatsSnapshot,
   type StoredMessage,
   applyChannelDelta as applyDelta,
   createChannel,
@@ -32,8 +37,12 @@ import {
   toSnapshot,
 } from '@serverless-ircd/irc-core';
 import { describe, expect, it } from 'vitest';
-import { ConnectionActor } from '../src/actor';
+import { ConnectionActor, channelTargetsForMessage } from '../src/actor';
+import type { ActorChannelAccess } from '../src/actor';
+import actorSource from '../src/actor.ts?raw';
 import type { IrcRuntime } from '../src/runtime';
+import { TcpByteStreamTransport, WsTextFrameTransport } from '../src/transport';
+import type { Transport } from '../src/transport';
 
 // ---------------------------------------------------------------------------
 // Fakes
@@ -49,6 +58,14 @@ class FakeRuntime implements IrcRuntime {
   private readonly channels = new Map<string, ChannelState>();
   private readonly testConnections = new Map<ConnId, ConnectionState>();
   private readonly nicks = new Map<string, ConnId>();
+  /**
+   * Configurable `reloadConfig` result. When set, the next `reloadConfig()`
+   * call returns this value; when `reloadConfigError` is set instead it
+   * throws. Leaving both unset throws so a test that drives `REHASH` without
+   * configuring the fake fails loudly.
+   */
+  reloadConfigResult: ServerConfig | undefined;
+  reloadConfigError: unknown;
 
   constructor(private readonly clock: { now(): number }) {}
 
@@ -59,6 +76,16 @@ class FakeRuntime implements IrcRuntime {
     }
   }
 
+  /**
+   * Drops a connection from the live-connection store while leaving its nick
+   * registered. Simulates the race a reducer sees when `lookupNick` resolves
+   * a nick but `getConnection` returns null (the connection tore down between
+   * the two awaits).
+   */
+  dropConnection(id: ConnId): void {
+    this.testConnections.delete(id);
+  }
+
   // Channel-state access (used by the actor's `channels` dep).
   getOrCreateChannel(name: ChanName): ChannelState {
     const key = name.toLowerCase();
@@ -79,6 +106,9 @@ class FakeRuntime implements IrcRuntime {
   async broadcast(chan: ChanName, lines: RawLine[], except?: ConnId): Promise<void> {
     this.calls.push({ method: 'broadcast', args: [chan, lines, except] });
   }
+  async broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void> {
+    this.calls.push({ method: 'broadcastWallops', args: [lines, except] });
+  }
   async disconnect(conn: ConnId, reason?: string): Promise<void> {
     this.calls.push({ method: 'disconnect', args: [conn, reason] });
   }
@@ -151,6 +181,15 @@ class FakeRuntime implements IrcRuntime {
     }
     return out;
   }
+
+  async reloadConfig(): Promise<ServerConfig> {
+    this.calls.push({ method: 'reloadConfig', args: [] });
+    if (this.reloadConfigError !== undefined) throw this.reloadConfigError;
+    if (this.reloadConfigResult === undefined) {
+      throw new Error('FakeRuntime.reloadConfigResult not configured');
+    }
+    return this.reloadConfigResult;
+  }
 }
 
 function makeActor(opts: {
@@ -161,7 +200,12 @@ function makeActor(opts: {
   traceId?: string;
   messages?: MessageStore;
   accounts?: AccountStore;
+  mtlsIdentity?: MtlsIdentityProvider;
+  history?: NickHistoryStore;
+  stats?: ServerStats;
   operCreds?: ReadonlyArray<{ user: string; password: string }>;
+  transport?: Transport;
+  configSource?: string;
 }): { actor: ConnectionActor; runtime: FakeRuntime; conn: ConnectionState } {
   const clock = opts.clock ?? new FakeClock(1_000);
   const conn = createConnection({ id: 'c1', connectedSince: 0 });
@@ -215,6 +259,21 @@ function makeActor(opts: {
   if (opts.accounts !== undefined) {
     finalOpts.accounts = opts.accounts;
   }
+  if (opts.mtlsIdentity !== undefined) {
+    finalOpts.mtlsIdentity = opts.mtlsIdentity;
+  }
+  if (opts.history !== undefined) {
+    finalOpts.history = opts.history;
+  }
+  if (opts.stats !== undefined) {
+    finalOpts.stats = opts.stats;
+  }
+  if (opts.transport !== undefined) {
+    finalOpts.transport = opts.transport;
+  }
+  if (opts.configSource !== undefined) {
+    finalOpts.configSource = opts.configSource;
+  }
   const actor = new ConnectionActor(finalOpts);
   return { actor, runtime, conn };
 }
@@ -278,6 +337,112 @@ describe('ConnectionActor — framing', () => {
   });
 });
 
+describe('ConnectionActor — TCP byte-stream transport seam', () => {
+  it('two TCP chunks split mid-line produce exactly one PRIVMSG broadcast', async () => {
+    const { actor, runtime } = makeActor({ transport: new TcpByteStreamTransport() });
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    // Split the single message mid-payload across two chunks. The partial
+    // line is buffered across the first chunk; only the second completes it.
+    await actor.receive('PRIVMSG #foo :hel');
+    expect(runtime.calls).toHaveLength(0);
+    await actor.receive('lo\r\n');
+
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]?.args[0]).toBe('#foo');
+    const lines = broadcasts[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe(':alice!alice@example.com PRIVMSG #foo :hello');
+  });
+
+  it('one message per WS text frame and one per CRLF over TCP produce identical effects', async () => {
+    // Same bytes, same connection setup, two transports. The WS actor gets
+    // the whole frame in one receiveTextFrame; the TCP actor gets the same
+    // bytes split across arbitrary chunks via receive().
+    const wsSetup = makeActor({});
+    const tcpSetup = makeActor({ transport: new TcpByteStreamTransport() });
+    for (const rt of [wsSetup.runtime, tcpSetup.runtime]) {
+      await rt.applyChannelDelta('#foo', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+      });
+    }
+    wsSetup.runtime.calls.length = 0;
+    tcpSetup.runtime.calls.length = 0;
+
+    const stream = 'PRIVMSG #foo :hello\r\n';
+    await wsSetup.actor.receiveTextFrame(stream);
+    // Feed the TCP actor the same bytes in 4-byte chunks.
+    for (let i = 0; i < stream.length; i += 4) {
+      await tcpSetup.actor.receive(stream.slice(i, i + 4));
+    }
+
+    const wsBroadcast = wsSetup.runtime.calls.filter((c) => c.method === 'broadcast');
+    const tcpBroadcast = tcpSetup.runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(tcpBroadcast).toHaveLength(wsBroadcast.length);
+    expect((tcpBroadcast[0]?.args[1] as RawLine[])[0]?.text).toBe(
+      (wsBroadcast[0]?.args[1] as RawLine[])[0]?.text,
+    );
+  });
+
+  it('buffers a partial line across multiple chunks with no loss or duplication', async () => {
+    const { actor, runtime } = makeActor({ transport: new TcpByteStreamTransport() });
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    // Three messages, each fed byte-by-byte. Every complete line is emitted
+    // exactly once; nothing is lost or duplicated at the chunk boundaries.
+    const stream = 'PING :a\r\nPRIVMSG #foo :b\r\nPING :c\r\n';
+    for (const ch of stream) {
+      await actor.receive(ch);
+    }
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(sends).toHaveLength(2); // PONG :a, PONG :c
+    expect((sends[0]?.args[1] as RawLine[])[0]?.text).toBe('PONG :a');
+    expect((sends[1]?.args[1] as RawLine[])[0]?.text).toBe('PONG :c');
+    expect(broadcasts).toHaveLength(1); // PRIVMSG #foo :b
+    expect((broadcasts[0]?.args[1] as RawLine[])[0]?.text).toBe(
+      ':alice!alice@example.com PRIVMSG #foo :b',
+    );
+  });
+
+  it('uses the default WS-frame transport when none is injected (backward compat)', () => {
+    // No `transport` option → the actor still frames WS text frames exactly
+    // as before. Confirms the default is the stateless WS transport.
+    const { actor, runtime } = makeActor({});
+    // A trailing unterminated line is still emitted by the WS transport
+    // (frame = complete unit), so this produces one PONG with no terminator.
+    return actor.receiveTextFrame('PING :tok').then(() => {
+      const sends = runtime.calls.filter((c) => c.method === 'send');
+      expect(sends).toHaveLength(1);
+      expect((sends[0]?.args[1] as RawLine[])[0]?.text).toBe('PONG :tok');
+    });
+  });
+
+  it('a TCP actor does NOT emit a trailing unterminated line until the terminator arrives', async () => {
+    const tcpActor = makeActor({ transport: new TcpByteStreamTransport() });
+    const wsActor = makeActor({ transport: new WsTextFrameTransport() });
+    tcpActor.runtime.calls.length = 0;
+    wsActor.runtime.calls.length = 0;
+
+    // WS treats the frame as complete → emits a PONG. TCP buffers the
+    // unterminated line → emits nothing yet. This is the defining
+    // behavioural difference of stateful byte-stream framing.
+    await wsActor.actor.receiveTextFrame('PING :unterminated');
+    await tcpActor.actor.receive('PING :unterminated');
+    expect(wsActor.runtime.calls.filter((c) => c.method === 'send')).toHaveLength(1);
+    expect(tcpActor.runtime.calls).toHaveLength(0);
+    // …until the terminator completes the line.
+    await tcpActor.actor.receive('\r\n');
+    expect(tcpActor.runtime.calls.filter((c) => c.method === 'send')).toHaveLength(1);
+  });
+});
+
 describe('ConnectionActor — malformed input', () => {
   it('emits 421 for an unparseable line and continues processing the rest', async () => {
     const { actor, runtime } = makeActor({});
@@ -512,9 +677,7 @@ describe('ConnectionActor — additional routing', () => {
 
     // Cap-gated broadcast dispatches per-recipient via send (only to
     // message-tags-enabled members, excluding the sender).
-    const sends = runtime.calls.filter(
-      (c) => c.method === 'send' && c.args[0] === 'c2',
-    );
+    const sends = runtime.calls.filter((c) => c.method === 'send' && c.args[0] === 'c2');
     expect(sends).toHaveLength(1);
     const lines = sends[0]?.args[1] as RawLine[];
     expect(lines[0]?.text).toBe('@+typing=active :alice!alice@example.com TAGMSG #foo');
@@ -664,6 +827,94 @@ describe('ConnectionActor — additional routing', () => {
     }
   });
 
+  it('routes WHOIS with no parameter through whoisReducer (just 318, never 421)', async () => {
+    // Covers the `targetNick.length > 0` false branch in routeWhois:
+    // a bare `WHOIS` resolves no target and defers to the reducer, which
+    // emits only the 318 end marker.
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOIS\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(allLines.some((l) => l.text.includes(' 318 '))).toBe(true);
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('routes WHOWAS of a quit nick through whowasReducer (314 + 369, never 421)', async () => {
+    const history = new InMemoryNickHistoryStore(new FakeClock(1_000));
+    history.record({
+      nick: 'bob',
+      connId: 'c2',
+      username: 'bob',
+      hostname: 'example.com',
+      realname: 'Bob',
+      signoffTime: 500,
+    });
+    const { actor, runtime } = makeActor({ history });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOWAS bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(2);
+    const firstBatch = sends[0]?.args[1] as RawLine[];
+    expect(firstBatch[0]?.text).toContain(' 314 ');
+    expect(firstBatch[0]?.text).toContain(' bob ');
+    const endBatch = sends[sends.length - 1]?.args[1] as RawLine[];
+    expect(endBatch[0]?.text).toContain(' 369 ');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes WHOWAS of an unknown nick to 406 then 369 (never 421)', async () => {
+    const history = new InMemoryNickHistoryStore(new FakeClock(1_000));
+    const { actor, runtime } = makeActor({ history });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOWAS ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const notFound = sends[0]?.args[1] as RawLine[];
+    expect(notFound[0]?.text).toContain(' 406 ');
+    expect(notFound[0]?.text).toContain(' ghost ');
+    const end = sends[1]?.args[1] as RawLine[];
+    expect(end[0]?.text).toContain(' 369 ');
+  });
+
+  it('still emits 406 + 369 for WHOWAS when no history store is bound (no crash)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOWAS ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const notFound = sends[0]?.args[1] as RawLine[];
+    expect(notFound[0]?.text).toContain(' 406 ');
+    const end = sends[1]?.args[1] as RawLine[];
+    expect(end[0]?.text).toContain(' 369 ');
+  });
+
+  it('records a nick into history on QUIT when a store is bound', async () => {
+    const history = new InMemoryNickHistoryStore(new FakeClock(1_000));
+    const { actor } = makeActor({ history });
+
+    await actor.receiveTextFrame('QUIT\r\n');
+
+    const entries = history.query('alice', 10);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.nick).toBe('alice');
+  });
+
   it('routes AUTHENTICATE PLAIN (post CAP REQ sasl) through authenticateReducer, never 421', async () => {
     // Pre-registration: client has opened CAP negotiation and requested sasl.
     // AUTHENTICATE must reach the SASL reducer, not the 421 fallthrough.
@@ -777,6 +1028,34 @@ describe('ConnectionActor — additional routing', () => {
     }
   });
 
+  it('routes SETNAME :<realname> through setnameReducer, mutating state.realname (never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('SETNAME :New Name\r\n');
+
+    expect(conn.realname).toBe('New Name');
+    // Silent update: no Send reply and no broadcast, just the state mutation.
+    expect(runtime.calls).toHaveLength(0);
+  });
+
+  it('routes SETNAME with no param to 461 (never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('SETNAME\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe(':irc.example.com 461 alice SETNAME :Not enough parameters');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
   it('routes OPER with matching creds through operReducer (381, never 421)', async () => {
     const { actor, runtime, conn } = makeActor({
       operCreds: [{ user: 'alice', password: 'secret' }],
@@ -855,6 +1134,212 @@ describe('ConnectionActor — additional routing', () => {
     expect(lines[0]?.text).toBe(':irc.example.com 421 alice :Unknown command');
   });
 
+  it('routes WALLOPS from an oper through wallopsReducer (broadcastWallops, never 421)', async () => {
+    const { actor, runtime } = makeActor({
+      conn: { userModes: { invisible: false, oper: true, wallops: false, serverNotices: false } },
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WALLOPS :reboot in 5\r\n');
+
+    // Oper happy path: one broadcastWallops runtime call, carrying the
+    // oper-attributed line and excepting the sender.
+    const wallops = runtime.calls.filter((c) => c.method === 'broadcastWallops');
+    expect(wallops).toHaveLength(1);
+    const lines = wallops[0]?.args[0] as RawLine[];
+    const except = wallops[0]?.args[1];
+    expect(lines[0]?.text).toBe(':alice!alice@example.com WALLOPS :reboot in 5');
+    expect(except).toBe('c1');
+    // Critical: WALLOPS must reach the reducer, never the 421 fallthrough.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes WALLOPS from a non-oper through wallopsReducer (481, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WALLOPS :hi\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 481 ');
+    // A non-oper must never trigger global fanout.
+    expect(runtime.calls.some((c) => c.method === 'broadcastWallops')).toBe(false);
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes WALLOPS with no message through wallopsReducer (412, never 421)', async () => {
+    const { actor, runtime } = makeActor({
+      conn: { userModes: { invisible: false, oper: true, wallops: false, serverNotices: false } },
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WALLOPS\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 412 ');
+    expect(runtime.calls.some((c) => c.method === 'broadcastWallops')).toBe(false);
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes REHASH from an oper through rehashReducer (382, never 421) and re-invokes the loader', async () => {
+    const { actor, runtime, conn } = makeActor({
+      conn: { userModes: { invisible: false, oper: true, wallops: false, serverNotices: false } },
+      configSource: 'KV',
+    });
+    runtime.reloadConfigResult = {
+      serverName: 'irc.reloaded.test',
+      networkName: 'ExampleNet',
+      maxChannelsPerUser: 30,
+      maxTargetsPerCommand: 10,
+      maxListEntries: 50,
+      nickLen: 30,
+      channelLen: 50,
+      topicLen: 390,
+      quitMessage: 'Client Quit',
+    };
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('REHASH\r\n');
+
+    // 382 emitted, never 421.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const firstLines = sends[0]?.args[1] as RawLine[];
+    expect(firstLines[0]?.text).toBe(':irc.example.com 382 alice :Rehashing from KV');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+    // The bound loader was actually re-invoked.
+    expect(runtime.calls.some((c) => c.method === 'reloadConfig')).toBe(true);
+    void conn;
+    // The live config was swapped: a subsequent REHASH's 382 carries the
+    // reloaded server name (ctx is rebuilt from the swapped serverConfig).
+    runtime.calls.length = 0;
+    await actor.receiveTextFrame('REHASH\r\n');
+    const secondSends = runtime.calls.filter((c) => c.method === 'send');
+    const secondLines = secondSends[0]?.args[1] as RawLine[];
+    expect(secondLines[0]?.text).toBe(':irc.reloaded.test 382 alice :Rehashing from KV');
+  });
+
+  it('routes REHASH from a non-oper through rehashReducer (481) and does NOT reload', async () => {
+    const { actor, runtime } = makeActor({ configSource: 'KV' });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('REHASH\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 481 ');
+    // Critical: a non-oper must not trigger a config reload.
+    expect(runtime.calls.some((c) => c.method === 'reloadConfig')).toBe(false);
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('keeps the oper connected and retains the prior config when the loader rejects', async () => {
+    const { actor, runtime } = makeActor({
+      conn: { userModes: { invisible: false, oper: true, wallops: false, serverNotices: false } },
+      configSource: 'KV',
+    });
+    runtime.reloadConfigError = new Error('store unreachable');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('REHASH\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    // Optimistic 382 + graceful error-suffixed 382; oper NOT disconnected.
+    expect(sends).toHaveLength(2);
+    const lines = [
+      ...((sends[0]?.args[1] as RawLine[]) ?? []),
+      ...((sends[1]?.args[1] as RawLine[]) ?? []),
+    ];
+    expect(lines[0]?.text).toBe(':irc.example.com 382 alice :Rehashing from KV');
+    expect(lines[1]?.text).toBe(
+      ':irc.example.com 382 alice :Rehashing from KV failed: store unreachable',
+    );
+    // The oper is never disconnected on a reload failure.
+    expect(runtime.calls.some((c) => c.method === 'disconnect')).toBe(false);
+    // Prior config retained: a subsequent command still sees the old name.
+    runtime.calls.length = 0;
+    await actor.receiveTextFrame('REHASH\r\n');
+    const retrySends = runtime.calls.filter((c) => c.method === 'send');
+    const retryLines = retrySends[0]?.args[1] as RawLine[];
+    expect(retryLines[0]?.text).toBe(':irc.example.com 382 alice :Rehashing from KV');
+  });
+
+  it('stringifies a non-Error rejection in the graceful 382 suffix', async () => {
+    const { actor, runtime } = makeActor({
+      conn: { userModes: { invisible: false, oper: true, wallops: false, serverNotices: false } },
+      configSource: 'KV',
+    });
+    // A non-Error throw exercises the `String(err)` branch of the suffix
+    // formatting (vs. `err.message` for a real Error).
+    runtime.reloadConfigError = 'totally broken';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('REHASH\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const errorLine = (sends[1]?.args[1] as RawLine[])[0];
+    expect(errorLine?.text).toBe(
+      ':irc.example.com 382 alice :Rehashing from KV failed: totally broken',
+    );
+    expect(runtime.calls.some((c) => c.method === 'disconnect')).toBe(false);
+  });
+
+  it('falls back to "*" in the graceful 382 suffix when the oper has no nick', async () => {
+    // Covers the `this.state.nick ?? '*'` fallback in routeRehash's catch
+    // block. Oper state without a nick is unusual (registration normally
+    // sets the nick before OPER can succeed) but the actor must still
+    // format a valid numeric addressed to "*" rather than crash.
+    const { actor, runtime, conn } = makeActor({
+      conn: { userModes: { invisible: false, oper: true, wallops: false, serverNotices: false } },
+      configSource: 'KV',
+    });
+    // Clear the nick post-construction (exactOptionalPropertyTypes forbids
+    // assigning undefined; delete is the idiomatic way to unset an optional).
+    // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+    delete conn.nick;
+    runtime.reloadConfigError = new Error('store unreachable');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('REHASH\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        // Addressed to "*" (no nick), never 421.
+        expect(line.text).toContain(' 382 * ');
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
   it('covers JOIN with no params (splitCsv("") → [])', async () => {
     const { actor, runtime } = makeActor({});
     await actor.receiveTextFrame('JOIN\r\n');
@@ -1361,6 +1846,27 @@ describe('ConnectionActor — CHATHISTORY', () => {
     expect(sends).toHaveLength(0);
   });
 
+  it('handles a missing target parameter gracefully (no 421)', async () => {
+    // Covers the `target !== undefined` false branch in routeChathistory:
+    // a CHATHISTORY message with only the subcommand and no target param.
+    // peekChannel is not called; the reducer surfaces the param error.
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({
+      conn: { caps: CHATHISTORY_CAPS },
+      messages: store,
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
   it('records a channel PRIVMSG into the bound store (JOIN auto-playback data source)', async () => {
     const store = new InMemoryMessageStore();
     const { actor, runtime } = makeActor({ messages: store });
@@ -1489,3 +1995,982 @@ describe('ConnectionActor — SASL AccountStore plumbing', () => {
     expect(conn.account).toBeUndefined();
   });
 });
+
+describe('ConnectionActor — SASL EXTERNAL + mTLS plumbing', () => {
+  /** Fake AccountStore that accepts EXTERNAL with a known cert subject. */
+  class FakeAccountStore implements AccountStore {
+    readonly calls: Array<{ mech: string; payload: SaslPayload }> = [];
+    constructor(private readonly result: SaslResult) {}
+    verify(mech: string, payload: SaslPayload): SaslResult {
+      this.calls.push({ mech, payload });
+      return this.result;
+    }
+  }
+
+  /** Fake MtlsIdentityProvider returning a canned subject for 'c1'. */
+  class FakeMtlsProvider implements MtlsIdentityProvider {
+    constructor(private readonly identity: string | undefined) {}
+    getIdentity(connId: string): string | undefined {
+      return connId === 'c1' ? this.identity : undefined;
+    }
+  }
+
+  function saslReadyConn(): Partial<ConnectionState> {
+    return {
+      registration: 'pre-registration',
+      capNegotiating: true,
+      caps: new Set<string>(['sasl']),
+    };
+  }
+
+  it('completes SASL EXTERNAL with 900/903 when mTLS provider and store accept', async () => {
+    const accounts = new FakeAccountStore({ ok: true, account: 'alice' });
+    const mtlsIdentity = new FakeMtlsProvider('CN=alice');
+    const { actor, runtime, conn } = makeActor({
+      conn: saslReadyConn(),
+      accounts,
+      mtlsIdentity,
+    });
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE EXTERNAL\r\n');
+    await actor.receiveTextFrame('AUTHENTICATE +\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(lines.some((l) => l.text.includes(' 900 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 903 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 904 '))).toBe(false);
+    expect(accounts.calls).toEqual([
+      { mech: 'EXTERNAL', payload: { kind: 'EXTERNAL', identity: 'CN=alice' } },
+    ]);
+    expect(conn.account).toBe('alice');
+  });
+
+  it('returns 908 for EXTERNAL when no mTLS provider is bound', async () => {
+    const accounts = new FakeAccountStore({ ok: true, account: 'alice' });
+    const { actor, runtime, conn } = makeActor({
+      conn: saslReadyConn(),
+      accounts,
+      // No mtlsIdentity → EXTERNAL should 908 at mechanism phase.
+    });
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE EXTERNAL\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(lines.some((l) => l.text.includes(' 908 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 904 '))).toBe(false);
+    expect(conn.account).toBeUndefined();
+  });
+});
+
+describe('ConnectionActor — server-info commands (VERSION/TIME/ADMIN/INFO/USERHOST/ISON)', () => {
+  it('routes VERSION through versionReducer (351, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('VERSION\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 351 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('routes TIME through timeReducer (391, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('TIME\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 391 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('routes ADMIN through adminReducer (256, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('ADMIN\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 256 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('routes INFO through infoReducer (371 + 374, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('INFO\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines.some((l) => l.text.includes(' 371 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 374 '))).toBe(true);
+    expect(lines.every((l) => !l.text.includes(' 421 '))).toBe(true);
+  });
+
+  it('routes USERHOST resolving online nicks (302, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bobuser';
+    bobState.host = 'bobhost';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('USERHOST bob ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 302 ');
+    expect(lines[0]?.text).toContain('bob=+bobuser@bobhost');
+    // Offline nick `ghost` is omitted from the reply.
+    expect(lines[0]?.text).not.toContain('ghost');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('USERHOST marks away users with - and opers with *', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bobuser';
+    bobState.host = 'bobhost';
+    bobState.away = 'brb';
+    bobState.userModes.oper = true;
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('USERHOST bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain('bob*=-bobuser@bobhost');
+  });
+
+  it('USERHOST treats a nick whose conn tore down mid-resolve as offline', async () => {
+    // Covers the `conn === null` branch in routeUserhost: lookupNick
+    // resolves but the live connection is gone (race between the two
+    // awaits). The reducer must treat the nick as offline rather than
+    // crash.
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bobuser';
+    bobState.host = 'bobhost';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.dropConnection('c2'); // race: nick map lags the connection map
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('USERHOST bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 302 ');
+    expect(lines[0]?.text).not.toContain('bobuser@bobhost');
+  });
+
+  it('routes ISON resolving online nicks (303, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('ISON bob ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 303 ');
+    expect(lines[0]?.text).toContain('bob');
+    expect(lines[0]?.text).not.toContain('ghost');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('ISON matches case-insensitively and reports the registered spelling', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'Bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('ISON BOB\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(':Bob');
+  });
+
+  it('skips a nick whose connection has torn down between lookupNick and getConnection (race)', async () => {
+    // Covers the `conn?.nick !== undefined` false branch in routeIson:
+    // lookupNick resolves because the nick map still holds the entry, but
+    // the connection is already gone from the live-connection store.
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    // Drop the live connection but leave the nick registered.
+    runtime.dropConnection('c2');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('ISON bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends[0]?.args[1] as RawLine[];
+    // 303 reply lists no nicks (bob was dropped mid-resolve).
+    expect(lines[0]?.text).toContain(' 303 ');
+    expect(lines[0]?.text).not.toContain('bob');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+});
+
+describe('ConnectionActor — KILL (oper force-disconnect)', () => {
+  it('routes an oper KILL through killReducer, invoking runtime.disconnect for the target (never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.userModes.oper = true;
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bob';
+    bobState.host = 'example.com';
+    bobState.realname = 'Bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('KILL bob :flooding\r\n');
+
+    const disconnects = runtime.calls.filter((c) => c.method === 'disconnect');
+    expect(disconnects).toHaveLength(1);
+    expect(disconnects[0]?.args[0]).toBe('c2');
+    expect(disconnects[0]?.args[1]).toBe('Killed (alice (flooding))');
+    // Critical: never 421 for a routed KILL.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('emits 481 ERR_NOPRIVILEGES (never 421, no disconnect) when the sender is not an oper', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('KILL bob :flooding\r\n');
+
+    const disconnects = runtime.calls.filter((c) => c.method === 'disconnect');
+    expect(disconnects).toHaveLength(0);
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 481 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('emits 401 ERR_NOSUCHNICK for an unknown target (never 421, no disconnect)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.userModes.oper = true;
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('KILL ghost :nope\r\n');
+
+    const disconnects = runtime.calls.filter((c) => c.method === 'disconnect');
+    expect(disconnects).toHaveLength(0);
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 401 ');
+    expect(lines[0]?.text).toContain(' ghost ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('emits 461 ERR_NEEDMOREPARAMS when the comment is missing (never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.userModes.oper = true;
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('KILL bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 461 ');
+    expect(lines[0]?.text).toContain(' KILL ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('emits 461 when an oper sends KILL with no params at all (never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.userModes.oper = true;
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('KILL\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 461 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('treats a nick whose connection vanished mid-route as unknown (401, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.userModes.oper = true;
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    // lookupNick will still resolve bob, but getConnection returns null.
+    runtime.dropConnection('c2');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('KILL bob :flooding\r\n');
+
+    const disconnects = runtime.calls.filter((c) => c.method === 'disconnect');
+    expect(disconnects).toHaveLength(0);
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 401 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+});
+
+describe('ConnectionActor — TRACE (routing diagnostics)', () => {
+  it('emits the 262 terminator and never 421 for TRACE with no target', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('TRACE\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(allLines[allLines.length - 1]?.text).toContain(' 262 ');
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('routes oper TRACE <nick> through traceReducer (205 + 262, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.userModes.oper = true;
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bob';
+    bobState.host = 'example.com';
+    bobState.realname = 'Bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('TRACE bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const firstBatch = sends[0]?.args[1] as RawLine[];
+    expect(firstBatch[0]?.text).toContain(' 205 ');
+    expect(firstBatch[0]?.text).toContain(' bob ');
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(allLines[allLines.length - 1]?.text).toContain(' 262 ');
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('emits 402 ERR_NOSUCHSERVER for a non-local server target (never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('TRACE remote.example.org\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 402 ');
+    expect(lines[0]?.text).toContain(' remote.example.org ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('treats the local server name as the local server (no 402, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('TRACE irc.example.com\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(allLines[allLines.length - 1]?.text).toContain(' 262 ');
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 402 ');
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('treats a nick whose connection vanished mid-route as the no-target path (262, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.userModes.oper = true;
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    // lookupNick resolves bob, but getConnection returns null.
+    runtime.dropConnection('c2');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('TRACE bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(allLines[allLines.length - 1]?.text).toContain(' 262 ');
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+});
+
+describe('ConnectionActor — dropped S2S and obsolete verbs', () => {
+  // These verbs are formally dropped (not deferred):
+  //   - S2S (PLAN non-goal): CONNECT, SQUIT, LINKS
+  //   - RFC 2812 obsolete (never widely implemented): SERVICE, SUMMON, USERS
+  // They keep returning `421 ERR_UNKNOWNCOMMAND` (the correct response for an
+  // unimplemented command); the regression guard below pins that behaviour so
+  // a future accidental `case` label is caught.
+  const droppedVerbs = ['CONNECT', 'SQUIT', 'LINKS', 'SERVICE', 'SUMMON', 'USERS'];
+
+  it.each(droppedVerbs)('emits 421 for the dropped verb %s', async (verb) => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame(`${verb} ignored-arg\r\n`);
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 421 ');
+    expect(lines[0]?.text).toContain(` ${verb} `);
+  });
+
+  it('documents the deliberate drop at the default branch (no "deferred" framing)', () => {
+    // The default branch must explain these verbs are deliberately dropped,
+    // not still "deferred" (the framing removed by the S2S / obsolete-verb
+    // drop).
+    expect(actorSource).toMatch(/S2S/);
+    expect(actorSource).toMatch(/non-goal/);
+    expect(actorSource).toMatch(/obsolete/i);
+    // The CONNECT/SQUIT/LINKS and SERVICE/SUMMON/USERS lines must not be
+    // framed as deferred.
+    expect(actorSource).not.toMatch(/deferred LINKS/);
+    expect(actorSource).not.toMatch(/deferred SQUIT/);
+    expect(actorSource).not.toMatch(/deferred SERVICE/);
+    expect(actorSource).not.toMatch(/deferred SUMMON/);
+    expect(actorSource).not.toMatch(/deferred USERS/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FakeServerStats + helpers
+// ---------------------------------------------------------------------------
+
+/** Stats backend double that returns a fixed snapshot. */
+class FakeServerStats implements ServerStats {
+  constructor(readonly snapshot: ServerStatsSnapshot) {}
+  async getStats(): Promise<ServerStatsSnapshot> {
+    return this.snapshot;
+  }
+}
+
+const populatedSnapshot: ServerStatsSnapshot = {
+  users: 4,
+  invisible: 1,
+  opers: 2,
+  unknownConnections: 1,
+  channels: 3,
+  servers: 1,
+  localConns: 6,
+  globalConns: 6,
+  maxLocalConns: 9,
+  maxGlobalConns: 9,
+  uptimeStartedAt: 0,
+};
+
+// ---------------------------------------------------------------------------
+// LUSERS actor routing
+// ---------------------------------------------------------------------------
+
+describe('ConnectionActor — LUSERS (network statistics)', () => {
+  it('emits 251–255 from the bound ServerStats snapshot and never 421', async () => {
+    const { actor, runtime } = makeActor({ stats: new FakeServerStats(populatedSnapshot) });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LUSERS\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    const codes = allLines.map((l) => Number(l.text.split(' ')[1]));
+    expect(codes).toContain(251);
+    expect(codes).toContain(252);
+    expect(codes).toContain(253);
+    expect(codes).toContain(254);
+    expect(codes).toContain(255);
+    expect(codes).toContain(265);
+    expect(codes).toContain(266);
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('awaits the stats backend before invoking the reducer (async getStats)', async () => {
+    let calls = 0;
+    const stats: ServerStats = {
+      async getStats() {
+        calls++;
+        return populatedSnapshot;
+      },
+    };
+    const { actor, runtime } = makeActor({ stats });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LUSERS\r\n');
+
+    expect(calls).toBe(1);
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    // The 251 line carries the snapshot's user/invisible/server counts.
+    expect(allLines.some((l) => l.text.includes(' 251 ') && l.text.includes('4 users'))).toBe(true);
+  });
+
+  it('emits 402 ERR_NOSUCHSERVER for a non-local server target (never 421)', async () => {
+    const { actor, runtime } = makeActor({ stats: new FakeServerStats(populatedSnapshot) });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LUSERS * remote.example.org\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 402 ');
+    expect(lines[0]?.text).toContain(' remote.example.org ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('treats the local server name as the local server (no 402, never 421)', async () => {
+    const { actor, runtime } = makeActor({ stats: new FakeServerStats(populatedSnapshot) });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LUSERS * irc.example.com\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 402 ');
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('falls back to a zero-count snapshot when no stats backend is bound (never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LUSERS\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    // 251 still emitted with zero counts; 252/253/254 suppressed (zero).
+    expect(allLines.some((l) => l.text.includes(' 251 '))).toBe(true);
+    expect(allLines.some((l) => l.text.includes(' 255 '))).toBe(true);
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 252 ');
+      expect(line.text).not.toContain(' 253 ');
+      expect(line.text).not.toContain(' 254 ');
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// STATS actor routing
+// ---------------------------------------------------------------------------
+
+describe('ConnectionActor — STATS (server statistics)', () => {
+  it('routes STATS u to a 242 + 219 reply (never 421)', async () => {
+    const clock = new FakeClock(5_000);
+    const { actor, runtime } = makeActor({
+      stats: new FakeServerStats({ ...populatedSnapshot, uptimeStartedAt: 0 }),
+      clock,
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('STATS u\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(allLines.some((l) => l.text.includes(' 242 '))).toBe(true);
+    expect(allLines[allLines.length - 1]?.text).toContain(' 219 ');
+    expect(allLines[allLines.length - 1]?.text).toContain(' u ');
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('routes STATS l to a 211 + 219 reply (never 421)', async () => {
+    const { actor, runtime } = makeActor({ stats: new FakeServerStats(populatedSnapshot) });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('STATS l\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(allLines.some((l) => l.text.includes(' 211 '))).toBe(true);
+    expect(allLines[allLines.length - 1]?.text).toContain(' 219 ');
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('routes an unknown STATS letter to a charybdis-style empty body + 219 (never 421)', async () => {
+    const { actor, runtime } = makeActor({ stats: new FakeServerStats(populatedSnapshot) });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('STATS z\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 219 ');
+    expect(lines[0]?.text).toContain(' z ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('emits 402 ERR_NOSUCHSERVER for a non-local server target (never 421)', async () => {
+    const { actor, runtime } = makeActor({ stats: new FakeServerStats(populatedSnapshot) });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('STATS u remote.example.org\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 402 ');
+    expect(lines[0]?.text).toContain(' remote.example.org ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('treats the local server name as the local server (no 402, never 421)', async () => {
+    const { actor, runtime } = makeActor({ stats: new FakeServerStats(populatedSnapshot) });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('STATS u irc.example.com\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 402 ');
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+});
+
+// ============================================================================
+// channelTargetsForMessage — pure dispatch table for prefetch
+// ============================================================================
+
+describe('channelTargetsForMessage', () => {
+  it('returns the channel list for each channel-touching verb', () => {
+    // Covers every case clause in the switch.
+    expect(channelTargetsForMessage({ command: 'PART', params: ['#a,#b'], tags: {} })).toEqual([
+      '#a',
+      '#b',
+    ]);
+    expect(channelTargetsForMessage({ command: 'TOPIC', params: ['#foo'], tags: {} })).toEqual([
+      '#foo',
+    ]);
+    expect(channelTargetsForMessage({ command: 'NAMES', params: ['#foo'], tags: {} })).toEqual([
+      '#foo',
+    ]);
+    expect(
+      channelTargetsForMessage({ command: 'KICK', params: ['#foo', 'bob'], tags: {} }),
+    ).toEqual(['#foo']);
+    expect(channelTargetsForMessage({ command: 'MODE', params: ['#foo', '+t'], tags: {} })).toEqual(
+      ['#foo'],
+    );
+    expect(
+      channelTargetsForMessage({ command: 'PRIVMSG', params: ['#foo', 'hi'], tags: {} }),
+    ).toEqual(['#foo']);
+    expect(
+      channelTargetsForMessage({ command: 'NOTICE', params: ['#foo', 'hi'], tags: {} }),
+    ).toEqual(['#foo']);
+    expect(channelTargetsForMessage({ command: 'TAGMSG', params: ['#foo'], tags: {} })).toEqual([
+      '#foo',
+    ]);
+  });
+
+  it('returns the JOIN channel(s), skipping the `JOIN 0` sentinel', () => {
+    expect(channelTargetsForMessage({ command: 'JOIN', params: ['#a,#b'], tags: {} })).toEqual([
+      '#a',
+      '#b',
+    ]);
+    // `JOIN 0` is the part-everything sentinel; reducer reads
+    // joinedChannels directly, so no prefetch target.
+    expect(channelTargetsForMessage({ command: 'JOIN', params: ['0'], tags: {} })).toEqual([]);
+  });
+
+  it('reads the channel from the SECOND param for INVITE (<nick> <channel>)', () => {
+    expect(
+      channelTargetsForMessage({ command: 'INVITE', params: ['bob', '#room'], tags: {} }),
+    ).toEqual(['#room']);
+  });
+
+  it('returns an empty list for commands with no channel target', () => {
+    // Covers the default branch (PING, NICK, QUIT, …).
+    expect(channelTargetsForMessage({ command: 'PING', params: ['t'], tags: {} })).toEqual([]);
+    expect(channelTargetsForMessage({ command: 'NICK', params: ['alice'], tags: {} })).toEqual([]);
+  });
+
+  it('ignores non-channel targets in the comma-split list', () => {
+    // A PRIVMSG to a nick (not a #channel) yields no prefetch targets.
+    expect(
+      channelTargetsForMessage({ command: 'PRIVMSG', params: ['bob,#foo', 'hi'], tags: {} }),
+    ).toEqual(['#foo']);
+  });
+
+  it('handles a missing first parameter gracefully', () => {
+    // Defensive: params[0] is absent → empty string → empty split.
+    expect(channelTargetsForMessage({ command: 'PART', params: [], tags: {} })).toEqual([]);
+  });
+
+  it('returns an empty list for JOIN / INVITE when their channel param is absent', () => {
+    // Covers the `?? ''` fallbacks on the JOIN and INVITE branches.
+    expect(channelTargetsForMessage({ command: 'JOIN', params: [], tags: {} })).toEqual([]);
+    expect(channelTargetsForMessage({ command: 'INVITE', params: ['bob'], tags: {} })).toEqual([]);
+  });
+});
+
+// ============================================================================
+// prefetchChannelState — refresh hook for distributed runtimes
+// ============================================================================
+
+describe('ConnectionActor — prefetchChannelState (refresh hook)', () => {
+  it('invokes refreshChannel for each channel-targeted command when the hook is bound', async () => {
+    // Covers the body of prefetchChannelState (refresh !== undefined path)
+    // and the call to channelTargetsForMessage for PART. Distributed
+    // runtimes (CF ChannelDO) wire `refreshChannel`; the in-memory fake
+    // does not, so we inject a custom channel-access here.
+    const refreshed: string[] = [];
+    const channelsAccess: ActorChannelAccess = {
+      getOrCreateChannel: (name: ChanName) => {
+        const key = name.toLowerCase();
+        const existing = fakeChannels.get(key);
+        if (existing) return existing;
+        const chan = createChannel({ name, nameLower: key, createdAt: 0 });
+        fakeChannels.set(key, chan);
+        return chan;
+      },
+      refreshChannel: async (name: ChanName) => {
+        refreshed.push(name);
+      },
+    };
+    const fakeChannels = new Map<string, ChannelState>();
+    const { actor, runtime } = makeActor({});
+    // Swap in the channel access with the refresh hook.
+    (actor as unknown as { channels: ActorChannelAccess }).channels = channelsAccess;
+    // Pre-add membership so PART can find the channel.
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('PART #foo :leaving\r\n');
+
+    expect(refreshed).toEqual(['#foo']);
+  });
+
+  it('is a no-op when refreshChannel is not bound (in-memory runtime)', async () => {
+    // Covers the early-return path. The default FakeRuntime has no
+    // refreshChannel; the actor must not throw and the PART still routes.
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await expect(actor.receiveTextFrame('PART #foo\r\n')).resolves.toBeUndefined();
+    expect(runtime.calls.some((c) => c.method === 'applyChannelDelta')).toBe(true);
+  });
+
+  it('skips refresh for commands with no channel target (empty targets list)', async () => {
+    // Covers the `targets.length === 0` early-return in
+    // prefetchChannelState: refreshChannel is bound but the command (PING)
+    // has no channel argument, so the refresh hook must not fire.
+    const refreshed: string[] = [];
+    const { actor, runtime } = makeActor({});
+    const accessWithRefresh: ActorChannelAccess = {
+      getOrCreateChannel: (name: ChanName) => runtime.getOrCreateChannel(name),
+      refreshChannel: async (name: ChanName) => {
+        refreshed.push(name);
+      },
+    };
+    (actor as unknown as { channels: ActorChannelAccess }).channels = accessWithRefresh;
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('PING :token\r\n');
+
+    expect(refreshed).toEqual([]);
+  });
+});
+
+// ============================================================================
+// peekChannel — getChannel fallback
+// ============================================================================
+
+describe('ConnectionActor — peekChannel fallback', () => {
+  it('falls back to getOrCreateChannel when getChannel is not implemented', async () => {
+    // Covers the fallback branch in peekChannel: a channel-access object
+    // that omits `getChannel` (the legacy shape before peek-only lookup) must
+    // still resolve CHATHISTORY targets via getOrCreateChannel. The actor
+    // is reconstructed with a wrapper that delegates everything except
+    // getChannel (which is intentionally absent).
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({
+      conn: {
+        caps: new Set<string>(['draft/chathistory', 'server-time', 'message-tags', 'batch']),
+      },
+      messages: store,
+    });
+    // Replace the channel access with a wrapper that lacks getChannel.
+    // The actor holds `channels` by reference, so this swap takes effect.
+    const accessWithoutGetChannel: ActorChannelAccess = {
+      getOrCreateChannel: (name: ChanName) => runtime.getOrCreateChannel(name),
+    };
+    (actor as unknown as { channels: ActorChannelAccess }).channels = accessWithoutGetChannel;
+    // Pre-create the channel so getOrCreateChannel returns it, and seed
+    // one stored message so the reducer has something to replay.
+    runtime.getOrCreateChannel('#foo');
+    store.record({
+      msgid: 'm1',
+      time: 1_000,
+      chan: '#foo',
+      command: 'PRIVMSG',
+      nick: 'bob',
+      user: 'bob',
+      host: 'ex.org',
+      text: 'hello',
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #foo * 1\r\n');
+
+    // The reducer should be reached (no 421) and emit a BATCH frame,
+    // proving peekChannel resolved the channel via the getOrCreateChannel
+    // fallback rather than 403/421.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+      expect(line.text).not.toContain(' 403 ');
+    }
+    expect(allLines.some((l) => l.text.startsWith('BATCH +'))).toBe(true);
+  });
+});
+
+// ============================================================================
+// WHOIS — channel-list branch (target with joinedChannels)
+// ============================================================================
+
+describe('ConnectionActor — WHOIS channel list', () => {
+  it("includes the target's joined channels in the 319 reply", async () => {
+    // Covers the Array.from(target.joinedChannels, ...) branch in
+    // routeWhois: when the target has joinedChannels, each is resolved to
+    // a ChannelState and passed to whoisReducer for the 319 list.
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bob';
+    bobState.host = 'example.com';
+    bobState.realname = 'Bob';
+    bobState.registration = 'registered';
+    bobState.joinedChannels.add('#room1');
+    bobState.joinedChannels.add('#room2');
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    // Materialize the channels so getOrCreateChannel resolves them.
+    await runtime.applyChannelDelta('#room1', {
+      memberships: [{ type: 'add', conn: 'c2', nick: 'bob' }],
+    });
+    await runtime.applyChannelDelta('#room2', {
+      memberships: [{ type: 'add', conn: 'c2', nick: 'bob' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOIS bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    // 319 RPL_WHOISCHANNELS lists at least one of the target's channels.
+    const chanLines = allLines.filter((l) => l.text.includes(' 319 '));
+    expect(chanLines.length).toBeGreaterThan(0);
+    const joined = chanLines.some((l) => l.text.includes('#room1') || l.text.includes('#room2'));
+    expect(joined).toBe(true);
+  });
+
+  it('treats a target whose conn tore down mid-resolve as offline (401 + 318, never 421)', async () => {
+    // Covers the `?? undefined` branch in routeWhois: lookupNick resolved
+    // the nick but getConnection returned null (race). The reducer must
+    // emit the unknown-nick path (401 + 318), not crash.
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.dropConnection('c2');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOIS bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const allLines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(allLines.some((l) => l.text.includes(' 401 '))).toBe(true);
+    expect(allLines.some((l) => l.text.includes(' 318 '))).toBe(true);
+    for (const line of allLines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+});