serverless-ircd 0.1.0 → 0.2.0

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

@@ -1,4 +1,5 @@
 import {
+  CapturingLogger,
   type ChanName,
   type ChanSnapshot,
   type ChannelDelta,
@@ -8,10 +9,17 @@ import {
   type ConnectionState,
   EmptyMotdProvider,
   FakeClock,
+  type FloodControlConfig,
+  InMemoryMessageStore,
+  LogLevel,
+  type Logger,
+  type MessageStore,
   type Nick,
   Numerics,
   type RawLine,
   SequentialIdFactory,
+  type ServerConfig,
+  type StoredMessage,
   applyChannelDelta as applyDelta,
   createChannel,
   createConnection,
@@ -56,6 +64,10 @@ class FakeRuntime implements IrcRuntime {
     return chan;
   }
 
+  getChannel(name: ChanName): ChannelState | undefined {
+    return this.channels.get(name.toLowerCase());
+  }
+
   async send(to: ConnId, lines: RawLine[]): Promise<void> {
     this.calls.push({ method: 'send', args: [to, lines] });
   }
@@ -138,6 +150,10 @@ class FakeRuntime implements IrcRuntime {
 function makeActor(opts: {
   conn?: Partial<ConnectionState>;
   clock?: FakeClock;
+  floodControl?: FloodControlConfig | null;
+  logger?: Logger;
+  traceId?: string;
+  messages?: MessageStore;
 }): { actor: ConnectionActor; runtime: FakeRuntime; conn: ConnectionState } {
   const clock = opts.clock ?? new FakeClock(1_000);
   const conn = createConnection({ id: 'c1', connectedSince: 0 });
@@ -149,25 +165,45 @@ function makeActor(opts: {
   if (opts.conn) Object.assign(conn, opts.conn);
 
   const runtime = new FakeRuntime(clock);
-  const actor = new ConnectionActor({
+  // Build in one expression: `floodControl` is readonly, and only stamp it
+  // when the caller supplied a value so `undefined` (omit → default) stays
+  // distinct from `null` (explicit disable).
+  const serverConfig: ServerConfig = {
+    serverName: 'irc.example.com',
+    networkName: 'ExampleNet',
+    maxChannelsPerUser: 30,
+    maxTargetsPerCommand: 10,
+    maxListEntries: 50,
+    nickLen: 30,
+    channelLen: 50,
+    topicLen: 390,
+    quitMessage: 'Client Quit',
+    ...(opts.floodControl !== undefined ? { floodControl: opts.floodControl } : {}),
+  };
+  const ids = new SequentialIdFactory();
+  type ActorOpts = ConstructorParameters<typeof ConnectionActor>[0];
+  // Strip readonly modifiers so we can conditionally assign `logger` /
+  // `traceId` without tripping the readonly guards on `ConnectionActorOptions`.
+  type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+  const finalOpts: Mutable<ActorOpts> = {
     state: conn,
     runtime,
     channels: runtime,
-    serverConfig: {
-      serverName: 'irc.example.com',
-      networkName: 'ExampleNet',
-      maxChannelsPerUser: 30,
-      maxTargetsPerCommand: 10,
-      maxListEntries: 50,
-      nickLen: 30,
-      channelLen: 50,
-      topicLen: 390,
-      quitMessage: 'Client Quit',
-    },
+    serverConfig,
     clock,
-    ids: new SequentialIdFactory(),
+    ids,
     motd: EmptyMotdProvider,
-  });
+  };
+  if (opts.logger !== undefined) {
+    finalOpts.logger = opts.logger;
+  }
+  if (opts.traceId !== undefined) {
+    finalOpts.traceId = opts.traceId;
+  }
+  if (opts.messages !== undefined) {
+    finalOpts.messages = opts.messages;
+  }
+  const actor = new ConnectionActor(finalOpts);
   return { actor, runtime, conn };
 }
 
@@ -563,6 +599,119 @@ describe('ConnectionActor — additional routing', () => {
     }
   });
 
+  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.
+    const { actor, runtime, conn } = makeActor({
+      conn: {
+        registration: 'pre-registration',
+        capNegotiating: true,
+        caps: new Set<string>(['sasl']),
+      },
+    });
+    // The connection needs a nick for the reducer's `nickOf(ctx)` fallback.
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE PLAIN\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    // SASL reducer responds with `AUTHENTICATE +` to request the payload.
+    expect(lines[0]?.text).toBe('AUTHENTICATE +');
+    // Critical: never 421 for AUTHENTICATE.
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes AUTHENTICATE * (abort) through authenticateReducer, never 421', async () => {
+    const { actor, runtime } = makeActor({
+      conn: {
+        registration: 'pre-registration',
+        capNegotiating: true,
+        caps: new Set<string>(['sasl']),
+        saslMech: 'PLAIN',
+      },
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE *\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    // Abort → 906 ERR_SASLABORT.
+    expect(lines[0]?.text).toContain(' 906 ');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes AWAY :reason through awayReducer, emitting 306 RPL_NOWAWAY (never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AWAY :gone\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 306 alice :You have been marked as being away');
+    // Critical: never 421 for AWAY.
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes AWAY with no params through awayReducer, emitting 305 RPL_UNAWAY (never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    // Start from an away state so the unset path is observable.
+    conn.away = 'previously away';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AWAY\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 305 alice :You are no longer marked as being away',
+    );
+    expect(conn.away).toBeUndefined();
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes AWAY with an empty reason through awayReducer, emitting 305 RPL_UNAWAY (never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.away = 'previously away';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AWAY :\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(' 305 ');
+    expect(conn.away).toBeUndefined();
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
   it('emits 421 with empty command when routeSingleChannel gets no channel (TOPIC)', async () => {
     const { actor, runtime } = makeActor({});
     await actor.receiveTextFrame('TOPIC\r\n');
@@ -814,3 +963,310 @@ describe('ConnectionActor — WHO', () => {
     expect(lines[0]?.text).toBe(':irc.example.com 403 alice badname :No such channel');
   });
 });
+
+describe('ConnectionActor — flood control', () => {
+  // Pre-add the connection to #foo so under-limit PRIVMSG frames broadcast
+  // (makes the pass-through vs. disconnect contrast observable).
+  async function joinFoo(runtime: FakeRuntime): Promise<void> {
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+  }
+
+  it('disconnects a client bursting PRIVMSG past the bucket capacity with "Excess Flood"', async () => {
+    const { actor, runtime } = makeActor({});
+    await joinFoo(runtime);
+
+    // Default bucket (capacity 10, threshold 0): the first 10 PRIVMSG pass,
+    // the 11th onward trip the Disconnect path.
+    for (let i = 0; i < 20; i++) {
+      await actor.receiveTextFrame('PRIVMSG #foo :flood\r\n');
+    }
+
+    const disconnects = runtime.calls.filter((c) => c.method === 'disconnect');
+    expect(disconnects.length).toBeGreaterThan(0);
+    expect(disconnects[0]?.args[1]).toBe('Excess Flood');
+    // The close path targets the actor's own connection.
+    expect(disconnects[0]?.args[0]).toBe('c1');
+  });
+
+  it('lets the same burst pass through unchanged when flood control is disabled (floodControl: null)', async () => {
+    const { actor, runtime } = makeActor({ floodControl: null });
+    await joinFoo(runtime);
+
+    for (let i = 0; i < 20; i++) {
+      await actor.receiveTextFrame('PRIVMSG #foo :flood\r\n');
+    }
+
+    // Disabled → every frame reaches the inner reducer and broadcasts; the
+    // close path is never invoked.
+    expect(runtime.calls.filter((c) => c.method === 'disconnect')).toHaveLength(0);
+    expect(runtime.calls.filter((c) => c.method === 'broadcast')).toHaveLength(20);
+  });
+
+  it('does not let an interleaved PING advance the bucket (control-plane exemption plumbed through)', async () => {
+    const { actor, runtime } = makeActor({});
+    await joinFoo(runtime);
+
+    // 10 PRIVMSG drain the default bucket exactly to zero (no disconnect yet).
+    for (let i = 0; i < 10; i++) {
+      await actor.receiveTextFrame('PRIVMSG #foo :flood\r\n');
+    }
+    expect(runtime.calls.filter((c) => c.method === 'disconnect')).toHaveLength(0);
+
+    // A PING is control-plane traffic: it must not decrement the bucket, so
+    // it neither disconnects here nor consumes the last token. (A flat-cost
+    // wrapper would trip the Disconnect on this very frame.)
+    await actor.receiveTextFrame('PING :keepalive\r\n');
+    expect(runtime.calls.filter((c) => c.method === 'disconnect')).toHaveLength(0);
+
+    // The bucket is still at zero, so the next PRIVMSG is the one that trips
+    // the disconnect — proving the PING was free.
+    await actor.receiveTextFrame('PRIVMSG #foo :one-more\r\n');
+    const disconnects = runtime.calls.filter((c) => c.method === 'disconnect');
+    expect(disconnects).toHaveLength(1);
+    expect(disconnects[0]?.args[1]).toBe('Excess Flood');
+  });
+});
+
+// ===========================================================================
+// Observability: structured logs + traceId/connectionId
+// ===========================================================================
+
+describe('ConnectionActor — observability', () => {
+  it('emits a structured log record with traceId and connectionId for a processed frame', async () => {
+    const logger = new CapturingLogger();
+    const { actor } = makeActor({ logger, traceId: 'trace-xyz' });
+
+    await actor.receiveTextFrame('PING :tok\r\n');
+
+    const received = logger.records.filter((r) => r.msg === 'frame.receive');
+    expect(received).toHaveLength(1);
+    const rec = received[0];
+    expect(rec?.level).toBe(LogLevel.Debug);
+    expect(rec?.traceId).toBe('trace-xyz');
+    expect(rec?.connectionId).toBe('c1');
+    expect(rec?.fields?.command).toBe('PING');
+    expect(rec?.fields?.lines).toBe(1);
+  });
+
+  it('stamps the same traceId on every record emitted while processing one frame', async () => {
+    const logger = new CapturingLogger();
+    const { actor } = makeActor({ logger, traceId: 'trace-abc' });
+
+    // A joined frame exercises the per-line path; a successful reducer
+    // followed by a parse failure exercises both frame.receive and
+    // frame.parse-error records on the same trace.
+    await actor.receiveTextFrame('PING :tok\r\nBADLINE_7_DIGITS\r\n');
+
+    expect(logger.records.length).toBeGreaterThan(0);
+    for (const rec of logger.records) {
+      expect(rec.traceId).toBe('trace-abc');
+      expect(rec.connectionId).toBe('c1');
+    }
+  });
+
+  it('emits a warn-level frame.parse-error record on a malformed line', async () => {
+    const logger = new CapturingLogger();
+    const { actor } = makeActor({ logger, traceId: 't1' });
+
+    // 5-digit numeric prefix is not a legal IRC command → parse fails.
+    await actor.receiveTextFrame('12345\r\n');
+
+    const errs = logger.records.filter((r) => r.msg === 'frame.parse-error');
+    expect(errs).toHaveLength(1);
+    expect(errs[0]?.level).toBe(LogLevel.Warn);
+    expect(errs[0]?.traceId).toBe('t1');
+    expect(typeof errs[0]?.fields?.line).toBe('string');
+  });
+
+  it('falls back to a NoopLogger and unknown traceId when omitted', async () => {
+    // The actor must still function when no logger/traceId is supplied — the
+    // codebase's default. No exceptions, no observable output.
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PING :tok\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+  });
+
+  it('allocates a fresh traceId per receiveTextFrame call when none was supplied', async () => {
+    // Each inbound frame gets its own trace id; the actor generates one
+    // itself via IdFactory.traceId() when the caller did not pin one. Two
+    // frames → two distinct ids.
+    const logger = new CapturingLogger();
+    const { actor } = makeActor({ logger });
+
+    await actor.receiveTextFrame('PING :a\r\n');
+    await actor.receiveTextFrame('PING :b\r\n');
+
+    const ids = new Set(logger.records.map((r) => r.traceId));
+    expect(ids.size).toBe(2);
+  });
+
+  it('logs dispatch effects with the bound traceId', async () => {
+    const logger = new CapturingLogger();
+    const { actor, runtime } = makeActor({ logger, traceId: 'trace-d1' });
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+
+    await actor.receiveTextFrame('PRIVMSG #foo :hello\r\n');
+
+    const dispatchLogs = logger.records.filter((r) => r.msg === 'dispatch');
+    expect(dispatchLogs.length).toBeGreaterThan(0);
+    for (const rec of dispatchLogs) {
+      expect(rec.traceId).toBe('trace-d1');
+      expect(rec.fields?.effects).toEqual(expect.any(Array));
+    }
+  });
+});
+
+// ===========================================================================
+// CHATHISTORY — dispatcher routing + MessageStore plumbing
+// ===========================================================================
+
+describe('ConnectionActor — CHATHISTORY', () => {
+  /** The full cap set a chathistory-capable client negotiates. */
+  const CHATHISTORY_CAPS = new Set<string>([
+    'draft/chathistory',
+    'server-time',
+    'message-tags',
+    'batch',
+  ]);
+
+  /** Records `count` chronological PRIVMSG messages into `store` for `chan`. */
+  function seedMessages(store: MessageStore, chan: string, count: number): StoredMessage[] {
+    const out: StoredMessage[] = [];
+    for (let i = 1; i <= count; i++) {
+      const m: StoredMessage = {
+        msgid: `m${i}`,
+        time: i * 1_000,
+        chan: chan.toLowerCase(),
+        command: 'PRIVMSG',
+        nick: 'bob',
+        user: 'bob',
+        host: 'ex.org',
+        text: `msg ${i}`,
+      };
+      store.record(m);
+      out.push(m);
+    }
+    return out;
+  }
+
+  it('routes CHATHISTORY LATEST to the reducer, emitting a BATCH chathistory frame (never 421)', async () => {
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({
+      conn: { caps: CHATHISTORY_CAPS },
+      messages: store,
+    });
+    // Create the channel so the peek resolves it (no creation side-effect
+    // during the query itself).
+    runtime.getOrCreateChannel('#foo');
+    seedMessages(store, '#foo', 2);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #foo * 2\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    // BATCH +id chathistory #foo … BATCH -id (id from the shared id factory).
+    expect(lines[0]?.text).toMatch(/^BATCH \+batch-\d+ chathistory #foo$/);
+    const batchId = lines[0]?.text.match(/^BATCH \+batch-(\d+)/)?.[1];
+    expect(lines[lines.length - 1]?.text).toBe(`BATCH -batch-${batchId}`);
+    // Two replay lines between the batch markers.
+    expect(lines).toHaveLength(4);
+    expect(lines[1]?.text).toContain('PRIVMSG #foo :msg 1');
+    expect(lines[2]?.text).toContain('PRIVMSG #foo :msg 2');
+    // Critical: never 421 for a cap-enabled CHATHISTORY query.
+    for (const line of lines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('still emits 421 for CHATHISTORY when the cap is not negotiated (reducer cap-gating)', async () => {
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({
+      conn: { caps: new Set<string>() },
+      messages: store,
+    });
+    runtime.getOrCreateChannel('#foo');
+    seedMessages(store, '#foo', 2);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #foo * 2\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('CHATHISTORY');
+  });
+
+  it('emits 403 ERR_NOSUCHCHANNEL for an unknown channel target', async () => {
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({
+      conn: { caps: CHATHISTORY_CAPS },
+      messages: store,
+    });
+    // Deliberately do NOT create #nope.
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #nope * 2\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(' 403 ');
+    expect(lines[0]?.text).toContain('#nope');
+  });
+
+  it('does not crash and emits nothing when no store is bound (ctx.messages undefined)', async () => {
+    const { actor, runtime } = makeActor({
+      conn: { caps: CHATHISTORY_CAPS },
+      // No `messages` option → ctx.messages is undefined.
+    });
+    runtime.getOrCreateChannel('#foo');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #foo * 2\r\n');
+
+    // No store → the reducer's query returns [] → empty batch elided → no
+    // Send effects. Proves the no-store path is a graceful no-op.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(0);
+  });
+
+  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 });
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('PRIVMSG #foo :hello\r\n');
+
+    const recorded = store.query({ chan: '#foo', direction: 'latest', limit: 10 });
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0]?.text).toBe('hello');
+    expect(recorded[0]?.command).toBe('PRIVMSG');
+    expect(recorded[0]?.nick).toBe('alice');
+  });
+
+  it('does not record a PRIVMSG when no store is bound (unchanged behaviour)', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('PRIVMSG #foo :hello\r\n');
+
+    // Broadcast still happens (the message is delivered live)…
+    expect(runtime.calls.filter((c) => c.method === 'broadcast')).toHaveLength(1);
+    // …but there is no store to record into.
+  });
+});

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

@@ -1,4 +1,5 @@
 import { Effect } from '@serverless-ircd/irc-core';
+import { CapturingLogger, LogLevel } from '@serverless-ircd/irc-core';
 import type { ChannelDelta, ConnId, RawLine } from '@serverless-ircd/irc-core';
 import { describe, expect, it } from 'vitest';
 import { dispatch } from '../src/dispatch';
@@ -510,3 +511,86 @@ describe('dispatch — Broadcast cap / capLines', () => {
     expect(sends.map((s) => s.to)).toEqual(['c1']);
   });
 });
+
+// ===========================================================================
+// dispatch observability
+// ===========================================================================
+describe('dispatch — observability', () => {
+  it('emits a `dispatch` debug record with traceId/connectionId and effect tags', async () => {
+    const calls: RecordedCall[] = [];
+    const runtime = fakeRuntime(calls);
+    const logger = new CapturingLogger();
+
+    await dispatch(
+      [Effect.send('c1', [L('PING :1')]), Effect.send('c1', [L('PONG :1')])],
+      runtime,
+      { logger, traceId: 't-1', connectionId: 'c1' },
+    );
+
+    const records = logger.records.filter((r) => r.msg === 'dispatch');
+    expect(records).toHaveLength(1);
+    const rec = records[0];
+    expect(rec?.level).toBe(LogLevel.Debug);
+    expect(rec?.traceId).toBe('t-1');
+    expect(rec?.connectionId).toBe('c1');
+    expect(rec?.fields?.effects).toEqual(['Send', 'Send']);
+    expect(rec?.fields?.histogram).toEqual({ Send: 2 });
+  });
+
+  it('is silent when no logger is supplied (backwards-compatible default)', async () => {
+    const calls: RecordedCall[] = [];
+    const runtime = fakeRuntime(calls);
+    // Default silent call signature still works.
+    await expect(dispatch([Effect.send('c1', [L('x')])], runtime)).resolves.toBeUndefined();
+  });
+
+  it('emits a dispatch.error warn record and rethrows when a handler rejects', async () => {
+    const runtime: IrcRuntime = {
+      ...fakeRuntime([]),
+      async send() {
+        throw new Error('boom');
+      },
+    };
+    const logger = new CapturingLogger();
+
+    await expect(
+      dispatch([Effect.send('c1', [L('x')])], runtime, {
+        logger,
+        traceId: 't-2',
+        connectionId: 'c1',
+      }),
+    ).rejects.toThrow('boom');
+
+    const errs = logger.records.filter((r) => r.msg === 'dispatch.error');
+    expect(errs).toHaveLength(1);
+    expect(errs[0]?.level).toBe(LogLevel.Warn);
+    expect(errs[0]?.traceId).toBe('t-2');
+    expect(errs[0]?.connectionId).toBe('c1');
+    expect(errs[0]?.fields?.effect).toBe('Send');
+    const err = errs[0]?.fields?.err as { name: string; message: string };
+    expect(err.name).toBe('Error');
+    expect(err.message).toBe('boom');
+  });
+
+  it('stringifies non-Error rejections in the dispatch.error record', async () => {
+    const runtime: IrcRuntime = {
+      ...fakeRuntime([]),
+      async send() {
+        throw 'string-error';
+      },
+    };
+    const logger = new CapturingLogger();
+
+    await expect(
+      dispatch([Effect.send('c1', [L('x')])], runtime, {
+        logger,
+        traceId: 't-3',
+        connectionId: 'c1',
+      }),
+    ).rejects.toBe('string-error');
+
+    const errs = logger.records.filter((r) => r.msg === 'dispatch.error');
+    expect(errs).toHaveLength(1);
+    expect(errs[0]?.fields?.err).toBe('string-error');
+  });
+});