serverless-ircd 0.4.0 → 0.6.0

package/apps/local-cli/tests/tcp.test.ts

@@ -92,7 +92,13 @@ class TcpTestClient extends EventEmitter {
 
 describe('local-cli TCP transport — startLocalServer tcpPort option', () => {
   it('exposes tcpPort and testTcpSockets when tcpPort is provided', async () => {
-    const srv = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     expect(srv.tcpPort).toBeGreaterThan(0);
     expect(srv.testTcpSockets).toBeDefined();
     expect(srv.testTcpSockets?.size).toBe(0);
@@ -100,16 +106,33 @@ describe('local-cli TCP transport — startLocalServer tcpPort option', () => {
   });
 
   it('omits tcpPort / testTcpSockets when tcpPort is not provided', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     expect(srv.tcpPort).toBeUndefined();
     expect(srv.testTcpSockets).toBeUndefined();
     await srv.close();
   });
 
   it('rejects when the TCP port is already in use', async () => {
-    const first = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    const first = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     await expect(
-      startLocalServer({ port: 0, tcpPort: first.tcpPort, hostname: '127.0.0.1' }),
+      startLocalServer({
+        port: 0,
+        tcpPort: first.tcpPort,
+        hostname: '127.0.0.1',
+        serverName: 'irc.local.example.com',
+        networkName: 'LocalNet',
+      }),
     ).rejects.toThrow();
     await first.close();
   });
@@ -119,7 +142,13 @@ describe('local-cli TCP transport — IRC flows', () => {
   let server: LocalServer;
 
   beforeAll(async () => {
-    server = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    server = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
   });
 
   afterAll(async () => {
@@ -141,11 +170,11 @@ describe('local-cli TCP transport — IRC flows', () => {
 
     await alice.send('NICK alice');
     await alice.send('USER alice 0 * :Alice');
-    await alice.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await alice.waitFor((l) => l.startsWith(':irc.local.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 bob.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     await alice.send('JOIN #tcp-e2e');
     await alice.waitFor((l) => l.includes('JOIN #tcp-e2e'));
@@ -164,7 +193,7 @@ describe('local-cli TCP transport — IRC flows', () => {
     await client.opened();
     await client.send('NICK pingUser');
     await client.send('USER pingUser 0 * :Ping');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     await client.send('PING :tcp-tok');
     await client.waitFor((l) => l === 'PONG :tcp-tok');
@@ -176,7 +205,7 @@ describe('local-cli TCP transport — IRC flows', () => {
     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.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     // Split a PING line mid-token across two writes. The server's LineScanner
     // must buffer the partial line and emit one PONG when the terminator lands.
@@ -191,7 +220,7 @@ describe('local-cli TCP transport — IRC flows', () => {
     await client.opened();
     // NICK and USER bundled into one write, CRLF-separated.
     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.waitFor((l) => l.startsWith(':irc.local.example.com 001 bundler'));
     await client.close();
   });
 
@@ -200,7 +229,7 @@ describe('local-cli TCP transport — IRC flows', () => {
     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 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     const connId = await server.runtime.lookupNick('termUser');
     expect(connId).not.toBeNull();
@@ -217,7 +246,7 @@ describe('local-cli TCP transport — IRC flows', () => {
     await client.opened();
     await client.send('NICK reasonUser');
     await client.send('USER reasonUser 0 * :Reason');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     // Synthesize a flood-control / oper-kill style disconnect with a reason.
     const connId = await server.runtime.lookupNick('reasonUser');
@@ -247,7 +276,7 @@ describe('local-cli TCP transport — IRC flows', () => {
     await next.opened();
     await next.send('NICK tcpRecover');
     await next.send('USER tcpRecover 0 * :TcpRecover');
-    await next.waitFor((l) => l.startsWith(':irc.example.com 001 '), 2000);
+    await next.waitFor((l) => l.startsWith(':irc.local.example.com 001 '), 2000);
     await next.close();
     await client.close();
   });
@@ -255,7 +284,13 @@ describe('local-cli TCP transport — IRC flows', () => {
 
 describe('local-cli TCP × WS cross-transport interop', () => {
   it('delivers a TCP PRIVMSG to a WS client in the same channel', async () => {
-    const srv = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
 
     // WS side.
     const wsClient = new WebSocket(`ws://127.0.0.1:${srv.port}/`);
@@ -288,7 +323,7 @@ describe('local-cli TCP × WS cross-transport interop', () => {
 
     wsSend('NICK wsUser');
     wsSend('USER wsUser 0 * :WS');
-    await wsWaitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await wsWaitFor((l) => l.startsWith(':irc.local.example.com 001 '));
     wsSend('JOIN #interop');
     await wsWaitFor((l) => l.includes('JOIN #interop'));
 
@@ -297,7 +332,7 @@ describe('local-cli TCP × WS cross-transport interop', () => {
     await tcp.opened();
     await tcp.send('NICK tcpUser');
     await tcp.send('USER tcpUser 0 * :TCP');
-    await tcp.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await tcp.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
     await tcp.send('JOIN #interop');
     await tcp.waitFor((l) => l.includes('JOIN #interop'));
 
@@ -315,7 +350,13 @@ describe('local-cli TCP × WS cross-transport interop', () => {
 
 describe('local-cli TCP transport — shutdown', () => {
   it('close() tears down the TCP server and live TCP sockets', async () => {
-    const srv = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     const client = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
     await client.opened();
     // Closing the server destroys the server-side socket; the client side
@@ -327,12 +368,23 @@ describe('local-cli TCP transport — shutdown', () => {
   });
 
   it('close() is a no-op for TCP when tcpPort was never enabled', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     await expect(srv.close()).resolves.toBeUndefined();
   });
 
   it('logs and recovers from a per-TCP-socket error without crashing the server', async () => {
-    const srv = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     const client = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
     await client.opened();
     // Wait for the server-side 'connection' handler to register the socket

package/apps/local-cli/tests/ws-subprotocol.test.ts

@@ -0,0 +1,262 @@
+import { EventEmitter } from 'node:events';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { type LocalServer, startLocalServer } from '../src/server';
+
+/**
+ * IRCv3 WebSocket subprotocol negotiation + per-message framing e2e.
+ *
+ * A spec-mode (`text.ircv3.net` / `binary.ircv3.net`) connection MUST:
+ *   - have its offered subprotocol echoed back in the handshake;
+ *   - exchange exactly one IRC message per WebSocket message, with NO
+ *     trailing CR-LF on either direction.
+ *
+ * A legacy (un-negotiated) connection keeps the original `\r\n`-batched
+ * framing, so the existing integration suite stays green.
+ */
+
+/** A spec-mode client: one IRC line per WS message, no trailing CRLF. */
+class SpecClient extends EventEmitter {
+  readonly ws: WebSocket;
+  readonly received: string[] = [];
+
+  constructor(url: string, protocols: string | string[]) {
+    super();
+    this.ws = new WebSocket(url, protocols);
+    // Each inbound WS message is exactly one IRC line in spec mode (no CRLF).
+    this.ws.on('message', (data) => {
+      const line = data.toString('utf8');
+      if (line.length > 0) {
+        this.received.push(line);
+        this.emit('line', line);
+      }
+    });
+  }
+
+  /** Resolves once the WS handshake completes. */
+  opened(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.ws.readyState === WebSocket.OPEN) resolve();
+      else {
+        this.ws.once('open', () => resolve());
+        this.ws.once('error', reject);
+      }
+    });
+  }
+
+  /** Sends one bare IRC line as its own WS message (no trailing CRLF). */
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws.send(line, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  /** Waits until a received line satisfies `predicate` (substring match). */
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 1000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error(`timeout; received: ${JSON.stringify(this.received)}`)),
+        timeoutMs,
+      );
+      const check = (line: string) => {
+        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) => {
+      if (this.ws.readyState === WebSocket.CLOSED) {
+        resolve();
+        return;
+      }
+      this.ws.once('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+describe('local-cli IRCv3 WebSocket subprotocol', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('echoes text.ircv3.net when offered', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    expect(client.ws.protocol).toBe('text.ircv3.net');
+    await client.close();
+  });
+
+  it('echoes binary.ircv3.net when offered', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'binary.ircv3.net');
+    await client.opened();
+    expect(client.ws.protocol).toBe('binary.ircv3.net');
+    await client.close();
+  });
+
+  it('completes a full session over binary.ircv3.net (binary frames)', async () => {
+    // binary.ircv3.net exchanges binary WebSocket frames. The server emits
+    // binary outbound frames (Buffer) and decodes inbound as UTF-8; the
+    // round-trip must decode to valid IRC lines with no trailing CRLF.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'binary.ircv3.net');
+    await client.opened();
+    await client.send('NICK spec-bin');
+    await client.send('USER spec-bin 0 * :Spec Bin');
+    const welcome = await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+    expect(welcome).toContain('spec-bin');
+
+    await client.send('PING :bin-tok');
+    const pong = await client.waitFor((l) => l === 'PONG :bin-tok');
+    expect(pong).toBe('PONG :bin-tok');
+
+    // Every decoded outbound message is a single bare IRC line.
+    for (const line of client.received) {
+      expect(line.includes('\r')).toBe(false);
+      expect(line.includes('\n')).toBe(false);
+    }
+    await client.close();
+  });
+
+  it('selects the first-listed supported subprotocol (client preference)', async () => {
+    // Client prefers binary over text; server honours the order.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, [
+      'binary.ircv3.net',
+      'text.ircv3.net',
+    ]);
+    await client.opened();
+    expect(client.ws.protocol).toBe('binary.ircv3.net');
+    await client.close();
+  });
+
+  it('ignores unsupported offers and still selects a supported one', async () => {
+    // Client lists an unsupported protocol first, then a supported one. The
+    // server MUST select the supported entry, not blindly echo the first.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, ['chat', 'text.ircv3.net']);
+    await client.opened();
+    expect(client.ws.protocol).toBe('text.ircv3.net');
+    await client.close();
+  });
+
+  it('connects in legacy mode when no subprotocol is offered', async () => {
+    // A plain client (no Sec-WebSocket-Protocol) is the legacy path: the
+    // server does not negotiate and the existing integration suite keeps
+    // working unchanged.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, []);
+    await client.opened();
+    expect(client.ws.protocol).toBe('');
+    await client.close();
+  });
+
+  it('completes registration with one IRC message per WebSocket message (text mode)', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    // One bare line per WS message (no trailing CRLF).
+    await client.send('NICK spec-alice');
+    await client.send('USER spec-alice 0 * :Spec Alice');
+    const welcome = await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+    expect(welcome).toContain('spec-alice');
+
+    // Every received message must be a single IRC line with no trailing CRLF
+    // and no embedded line break (one IRC message per WS message).
+    for (const line of client.received) {
+      expect(line.includes('\r')).toBe(false);
+      expect(line.includes('\n')).toBe(false);
+    }
+    await client.close();
+  });
+
+  it('delivers each outbound line as a distinct WebSocket message in spec mode', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK spec-bob');
+    await client.send('USER spec-bob 0 * :Spec Bob');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    // The welcome sequence is many numerics (001..005, 375/372/376). In spec
+    // mode each arrives as its own WS message; a legacy batch would have
+    // concatenated them with CRLF inside one message. Assert we observed
+    // several distinct messages.
+    expect(client.received.length).toBeGreaterThan(1);
+    await client.close();
+  });
+
+  it('routes PING → PONG as a single-message frame in spec mode', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK spec-ping');
+    await client.send('USER spec-ping 0 * :Spec Ping');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    await client.send('PING :spec-tok');
+    const pong = await client.waitFor((l) => l === 'PONG :spec-tok');
+    expect(pong).toBe('PONG :spec-tok');
+    await client.close();
+  });
+
+  it('rejects an inbound message exceeding the 510-byte budget in spec mode', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK spec-budget');
+    await client.send('USER spec-budget 0 * :Spec Budget');
+    // Drain the entire registration burst (001..376) so delayed numerics
+    // don't pollute the post-overlong-message assertion below.
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 376 '));
+
+    client.received.length = 0;
+    // 511-byte payload: `PRIVMSG #x :` (12 bytes) + 499 chars = 511 total.
+    const overlong = `PRIVMSG #x :${'a'.repeat(499)}`;
+    expect(overlong.length).toBe(511);
+    await client.send(overlong);
+    // Give the server a moment to process + close. An over-budget message
+    // MUST NOT produce a PRIVMSG broadcast or numeric reply.
+    await new Promise((r) => setTimeout(r, 80));
+    expect(client.received.length).toBe(0);
+    await client.close();
+  });
+
+  // A reducer-driven disconnect with a reason (e.g. flood control / oper
+  // kill) emits the RFC-style ERROR notice. In spec mode it MUST arrive as
+  // its own WebSocket message with no trailing CR-LF, for both text and
+  // binary negotiated connections.
+  for (const subproto of ['text.ircv3.net', 'binary.ircv3.net'] as const) {
+    it(`delivers the ERROR notice as a single message on a ${subproto} connection`, async () => {
+      const nick = subproto === 'text.ircv3.net' ? 'spec-disc-text' : 'spec-disc-bin';
+      const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, subproto);
+      await client.opened();
+      await client.send(`NICK ${nick}`);
+      await client.send(`USER ${nick} 0 * :Spec Disc`);
+      await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+      const connId = await server.runtime.lookupNick(nick);
+      expect(connId).not.toBeNull();
+      await server.runtime.disconnect(connId as string, 'Excess Flood');
+      const notice = await client.waitFor((l) => l.startsWith('ERROR :Closing link:'));
+      expect(notice).toBe('ERROR :Closing link: (Excess Flood)');
+      await client.close();
+    });
+  }
+});

package/biome.json

@@ -10,6 +10,7 @@
     "ignore": [
       "**/dist/**",
       "**/coverage/**",
+      "**/coverage-self-test/**",
       "**/node_modules/**",
       "**/.turbo/**",
       "pnpm-lock.yaml",

package/docs/ADR-001-pure-reducers-and-effect-system.md

@@ -0,0 +1,74 @@
+# ADR-001: Pure reducers and the effect system
+
+**Date:** 2025-01-15 (Phase 1)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+Every IRC daemon must decide where side effects happen. A traditional ircd
+threads mutable state and IO through command handlers — the handler reads a
+channel roster, sends messages, mutates a user record, and returns. That makes
+handlers hard to unit-test (they require a live socket, a real timer, a
+populated data store) and hard to reason about (the handler's observable
+behaviour is inseparable from its IO).
+
+ServerlessIRCd targets two cloud adapters (Cloudflare Workers, AWS Lambda)
+that share one protocol core. If the core performed IO directly, each adapter
+would need its own mock surface for every core test — or worse, the core
+would grow adapter-specific code paths.
+
+## Decision
+
+Every command handler is a **pure function** with the signature:
+
+```ts
+type Reducer<S> = (state: S, msg: IrcMessage, ctx: Ctx) => { state: S; effects: Effect[] };
+```
+
+- **No IO in the reducer.** No `await`, no `fetch`, no `setTimeout`, no
+  `Date.now()`, no `Math.random()`. The reducer reads `ctx.clock.now()` and
+  `ctx.ids.nonce()` instead (see ADR-007).
+- **Side effects are values.** The reducer returns an `Effect[]` — a
+  discriminated union (`Send`, `Broadcast`, `Disconnect`, `ReserveNick`,
+  `ChangeNick`, `ReleaseNick`, `ApplyChannelDelta`, `SendToNick`, …). Each
+  effect tag maps one-to-one to an `IrcRuntime` method.
+- **A single `dispatch(effects, runtime)` function** in `irc-server`
+  interprets the effects against the bound runtime. Only `dispatch` awaits.
+- **Reducer purity is enforced by convention and testability, not by a
+  sandbox.** The type system carries the contract; the 100% coverage gate on
+  `irc-core` verifies it empirically.
+
+## Consequences
+
+**Positive:**
+- Every reducer is a trivial unit test: arrange state, apply message, assert
+  `state` and `effects`. No mocks, no fakes beyond an injected `Clock` and
+  `IdFactory`.
+- The same reducer code runs unchanged on in-memory, CF, and AWS runtimes.
+  Adapter work is "wire the runtime", not "rewrite the handler".
+- Reducer behaviour is deterministic and reproducible — critical for the
+  parametrized contract suite (TICKET-032) that runs identical scenarios
+  across all three runtimes.
+- Mutation testing (Stryker, TICKET-048) is meaningful because reducers have
+  no hidden IO to mask a mutation's effect.
+
+**Negative:**
+- The `Effect` union grows with every new side-effect type. Adding a novel
+  effect (e.g. `QueryHistory` for chathistory) requires touching `effects.ts`,
+  `dispatch.ts`, and every runtime implementation. This is by design (the
+  type system makes missing-runtime-support a compile error) but adds
+  ceremony.
+- Reducers cannot directly observe the result of a side effect they emit
+  (e.g. "did the broadcast actually reach anyone?"). Cross-effect
+  coordination is deferred to the actor layer, which can pre-fetch runtime
+  state before invoking the reducer.
+
+## References
+
+- PLAN §2.1 — "The key idea: pure reducers + location-of-authority"
+- PLAN §2.2 — `IrcRuntime` port
+- `packages/irc-core/src/effects.ts` — `Effect` union
+- `packages/irc-core/src/types.ts` — `Reducer<S>` signature
+- `packages/irc-server/src/dispatch.ts` — `dispatch(effects, runtime)`

package/docs/ADR-002-location-of-authority.md

@@ -0,0 +1,82 @@
+# ADR-002: Location-of-authority state split
+
+**Date:** 2025-01-15 (Phase 1)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+An IRC server manages several kinds of state: connection records (nick, caps,
+away status), channel rosters (who is in `#foo`, with what prefix), channel
+metadata (topic, modes, ban lists), and the nick registry (nick → connection
+map). In a single-process ircd all of this lives in one address space, so
+read-modify-write races are handled with locks or a single event loop.
+
+ServerlessIRCd runs on stateless-per-request compute (Lambda) or
+per-entity-isolated compute (Durable Objects). There is no global lock. If
+two connections race to JOIN the same channel, or two clients race to claim
+the same nick, the outcome must still be correct. Traditional locking is
+impossible across instances.
+
+## Decision
+
+Each piece of state has **exactly one authority** — the single entity that
+owns the canonical copy and serializes all mutations to it. Reducers are
+routed to the authority that owns the state they mutate:
+
+| Command family | Authority | Primary state |
+|---|---|---|
+| Registration (NICK/USER/PASS) | Connection entity | `ConnectionState` |
+| PING/PONG, QUIT, AWAY, user MODE | Connection entity | `ConnectionState` |
+| JOIN/PART/channel MODE/TOPIC/KICK/INVITE | Channel entity | `ChannelState` + roster |
+| PRIVMSG/NOTICE to channel | Channel entity | Fanout (reads roster) |
+| PRIVMSG/NOTICE to user | Sender Connection | Nick → Connection route |
+| Nick reservation | Registry entity | Nick → Connection map |
+
+Cross-authority coordination is done via **effects**, not direct mutation.
+When a connection accepts a JOIN, the connection-authority reducer emits an
+`ApplyChannelDelta` effect that the channel authority consumes. The channel
+authority is the sole writer of its roster; the connection never touches it
+directly.
+
+Platform mapping:
+- **Cloudflare:** each authority is a Durable Object (`ConnectionDO`,
+  `ChannelDO`, `RegistryDO`). DO single-threaded serial execution gives the
+  uniqueness invariant for free — two concurrent requests to the same DO are
+  queued, not racing.
+- **AWS:** each authority is a DynamoDB table with conditional writes
+  (`ConditionExpression`) or `TransactWriteItems` for multi-row atomicity
+  (e.g. JOIN spans `Connections` and `ChannelMembers`).
+
+## Consequences
+
+**Positive:**
+- Races are structurally impossible, not defended against. Two clients
+  claiming the same nick both route to the same `RegistryDO` shard (or the
+  same `Nicks` row with a conditional PutItem) — exactly one wins.
+- The reducer signature stays uniform (`Reducer<S>`) regardless of which
+  authority it runs in. The actor layer routes; the reducer does not know or
+  care whether it is running in a DO or a Lambda.
+- Each authority can be tested in isolation. The channel reducer tests
+  arrange a `ChannelState` and assert effects; they never need a live
+  connection registry.
+
+**Negative:**
+- Cross-authority coordination requires a round-trip (DO `stub()` call on CF;
+  extra DynamoDB write on AWS). A JOIN that updates both the connection's
+  joined-list and the channel roster is two writes, not one.
+- The actor layer must pre-fetch authoritative state before invoking a
+  reducer (e.g. WHOIS needs the target connection's state from a different
+  authority). This adds a `prefetchChannelState` step in the actor pipeline.
+- Listing all channels (LIST) or resolving every member of a channel (WHO)
+  requires aggregating across authorities — there is no global view. The CF
+  adapter needs a channel registry (TICKET-073); the AWS adapter does a
+  DynamoDB scan.
+
+## References
+
+- PLAN §2.1 — location-of-authority table
+- PLAN §4 — state model & authoritative ownership
+- ADR-001 — pure reducers (how effects flow between authorities)
+- `packages/irc-server/src/actor.ts` — `route()` switch (authority routing)