serverless-ircd 0.1.0 → 0.3.0

package/packages/irc-core/tests/ports.test.ts

@@ -1,8 +1,15 @@
 import { describe, expect, it } from 'vitest';
 import {
+  CapturingLogger,
   type Clock,
+  ConsoleLogger,
   FakeClock,
   type IdFactory,
+  LogLevel,
+  type LogRecord,
+  type Logger,
+  NoopLogger,
+  NoopLoggerInstance,
   SequentialIdFactory,
   SystemClock,
   UuidIdFactory,
@@ -99,3 +106,259 @@ describe('SequentialIdFactory', () => {
     expect(f.sessionId()).toBe('session-2');
   });
 });
+
+describe('IdFactory.traceId', () => {
+  it('UuidIdFactory returns unique trace ids', () => {
+    const f: IdFactory = new UuidIdFactory();
+    expect(typeof f.traceId()).toBe('string');
+    expect(f.traceId()).not.toBe(f.traceId());
+  });
+
+  it('SequentialIdFactory returns deterministic trace ids', () => {
+    const f = new SequentialIdFactory();
+    expect(f.traceId()).toBe('trace-0');
+    expect(f.traceId()).toBe('trace-1');
+  });
+});
+
+describe('LogLevel', () => {
+  it('orders levels debug < info < warn < error', () => {
+    expect(LogLevel.Debug).toBeLessThan(LogLevel.Info);
+    expect(LogLevel.Info).toBeLessThan(LogLevel.Warn);
+    expect(LogLevel.Warn).toBeLessThan(LogLevel.Error);
+  });
+});
+
+describe('NoopLogger', () => {
+  it('implements the Logger port without throwing', () => {
+    const log: Logger = NoopLoggerInstance;
+    expect(() => log.debug('m')).not.toThrow();
+    expect(() => log.info('m')).not.toThrow();
+    expect(() => log.warn('m')).not.toThrow();
+    expect(() => log.error('m')).not.toThrow();
+  });
+
+  it('filters out levels below its threshold', () => {
+    const called = 0;
+    const log = new NoopLogger(LogLevel.Warn);
+    log.on(LogLevel.Debug, 'm');
+    log.info('m');
+    // The NoopLogger body is empty; the only contract is "no observable
+    // side-effect", which the count staying zero demonstrates.
+    expect(called).toBe(0);
+  });
+
+  it('child() returns an equivalent no-op logger', () => {
+    const child = new NoopLogger().child({ traceId: 't-1' });
+    expect(() => child.info('m')).not.toThrow();
+  });
+});
+
+describe('CapturingLogger', () => {
+  it('captures every record in order', () => {
+    const log = new CapturingLogger();
+    log.info('one', { a: 1 });
+    log.warn('two');
+    log.error('three', { e: 'boom' });
+    expect(log.records).toHaveLength(3);
+    expect(log.records[0]?.msg).toBe('one');
+    expect(log.records[1]?.level).toBe(LogLevel.Warn);
+    expect(log.records[2]?.fields).toEqual({ e: 'boom' });
+  });
+
+  it('stamps each record with the supplied traceId and connectionId', () => {
+    const log = new CapturingLogger({ traceId: 't-1', connectionId: 'c-1' });
+    log.info('hi');
+    const rec = log.records[0];
+    expect(rec?.traceId).toBe('t-1');
+    expect(rec?.connectionId).toBe('c-1');
+  });
+
+  it('child() inherits the parent traceId and connectionId and merges new fields', () => {
+    const log = new CapturingLogger({ traceId: 't-1', connectionId: 'c-1' });
+    const child = log.child({ connectionId: 'c-2' });
+    child.info('hi');
+    expect(log.records).toHaveLength(1);
+    expect(log.records[0]?.traceId).toBe('t-1');
+    expect(log.records[0]?.connectionId).toBe('c-2');
+  });
+
+  it('respects a minimum level', () => {
+    const log = new CapturingLogger(undefined, LogLevel.Warn);
+    log.info('skipped');
+    log.warn('kept');
+    expect(log.records.map((r) => r.msg)).toEqual(['kept']);
+  });
+
+  it('merges ctx fields with per-call fields', () => {
+    const log = new CapturingLogger({ traceId: 't-1', connectionId: 'c-1', chan: '#foo' });
+    log.info('hi', { lines: 3 });
+    expect(log.records[0]?.fields).toEqual({ chan: '#foo', lines: 3 });
+  });
+
+  it('records a debug entry via debug()', () => {
+    const log = new CapturingLogger();
+    log.debug('dbg');
+    expect(log.records[0]?.level).toBe(LogLevel.Debug);
+  });
+
+  it('routes through on() at any level', () => {
+    const log = new CapturingLogger();
+    log.on(LogLevel.Warn, 'manual');
+    expect(log.records[0]?.level).toBe(LogLevel.Warn);
+  });
+
+  it('uses the injected clock for ts', () => {
+    const clock = new FakeClock(42_000);
+    const log = new CapturingLogger({}, LogLevel.Debug, clock);
+    log.info('t');
+    expect(log.records[0]?.ts).toBe(42_000);
+  });
+
+  it('per-call traceId/connectionId overrides take precedence over ctx (used by dispatch)', () => {
+    // dispatch() calls logger.on(level, msg, { traceId, connectionId, ... })
+    // rather than constructing a child logger per call — both ctx-bound and
+    // per-call ids surface as top-level record fields, with per-call values
+    // winning. This keeps the dispatch path allocation-free while still
+    // stamping the correct ids on every record.
+    const log = new CapturingLogger({ traceId: 't-1', connectionId: 'c-1' });
+    log.info('hi', { traceId: 't-2', connectionId: 'c-2', chan: '#foo' });
+    expect(log.records[0]?.traceId).toBe('t-2');
+    expect(log.records[0]?.connectionId).toBe('c-2');
+    // chan is ordinary structured context → stays in fields.
+    expect(log.records[0]?.fields).toEqual({ chan: '#foo' });
+  });
+});
+
+describe('ConsoleLogger', () => {
+  function stubSinks(): {
+    sinks: {
+      debug(p: string): void;
+      info(p: string): void;
+      warn(p: string): void;
+      error(p: string): void;
+    };
+    calls: string[];
+  } {
+    const calls: string[] = [];
+    const sinks = {
+      debug: (p: string) => {
+        calls.push(`debug:${p}`);
+      },
+      info: (p: string) => {
+        calls.push(`info:${p}`);
+      },
+      warn: (p: string) => {
+        calls.push(`warn:${p}`);
+      },
+      error: (p: string) => {
+        calls.push(`error:${p}`);
+      },
+    };
+    return { sinks, calls };
+  }
+
+  it('serializes each record as a single line of JSON to console.<level>', () => {
+    const { sinks, calls } = stubSinks();
+    const log = new ConsoleLogger({ traceId: 't-1', connectionId: 'c-1' }, sinks);
+    log.info('hello', { lines: 1 });
+    log.error('boom');
+
+    expect(calls).toHaveLength(2);
+    expect(calls[0]).toMatch(/^info:/);
+    const infoLine = calls[0] ?? '';
+    const parsed0 = JSON.parse(infoLine.slice('info:'.length)) as Record<string, unknown>;
+    expect(parsed0.msg).toBe('hello');
+    expect(parsed0.level).toBe('info');
+    expect(parsed0.traceId).toBe('t-1');
+    expect(parsed0.connectionId).toBe('c-1');
+    expect(parsed0.lines).toBe(1);
+    expect(parsed0.ts).toEqual(expect.any(String));
+    // Single line — every record must be one JSON object on one physical line.
+    expect(infoLine.includes('\n')).toBe(false);
+  });
+
+  it('routes debug/warn through their dedicated sinks', () => {
+    const { sinks, calls } = stubSinks();
+    const log = new ConsoleLogger({ traceId: 't-1' }, sinks);
+    log.debug('d');
+    log.warn('w');
+    expect(calls[0]).toMatch(/^debug:/);
+    expect(calls[1]).toMatch(/^warn:/);
+    const debugLine = calls[0] ?? '';
+    const warnLine = calls[1] ?? '';
+    const parsed0 = JSON.parse(debugLine.slice('debug:'.length)) as Record<string, unknown>;
+    expect(parsed0.level).toBe('debug');
+    const parsed1 = JSON.parse(warnLine.slice('warn:'.length)) as Record<string, unknown>;
+    expect(parsed1.level).toBe('warn');
+  });
+
+  it('routes through on() at any level', () => {
+    const { sinks, calls } = stubSinks();
+    const log = new ConsoleLogger({}, sinks);
+    log.on(LogLevel.Warn, 'manual');
+    expect(calls[0]).toMatch(/^warn:/);
+  });
+
+  it('respects a minimum level', () => {
+    const { sinks, calls } = stubSinks();
+    const log = new ConsoleLogger({}, sinks, LogLevel.Error);
+    log.info('skipped');
+    log.error('kept');
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatch(/^error:/);
+  });
+
+  it('child inherits traceId/connectionId', () => {
+    const { sinks, calls } = stubSinks();
+    const log = new ConsoleLogger({ traceId: 't-1', connectionId: 'c-1' }, sinks);
+    const child = log.child({ connectionId: 'c-2' });
+    child.info('hi');
+    expect(calls[0]).toBeDefined();
+    const parsed = JSON.parse((calls[0] ?? '').slice('info:'.length)) as Record<string, unknown>;
+    expect(parsed.traceId).toBe('t-1');
+    expect(parsed.connectionId).toBe('c-2');
+  });
+
+  it('stamps ts from the injected clock', () => {
+    const { sinks, calls } = stubSinks();
+    const clock = new FakeClock(1_700_000_000_000);
+    const log = new ConsoleLogger({}, sinks, LogLevel.Debug, clock);
+    log.info('t');
+    expect(calls[0]).toBeDefined();
+    const parsed = JSON.parse((calls[0] ?? '').slice('info:'.length)) as Record<string, unknown>;
+    expect(parsed.ts).toBe(new Date(1_700_000_000_000).toISOString());
+  });
+
+  it('defaults to the global console when no sink is supplied', () => {
+    const log: Logger = new ConsoleLogger();
+    // Exercise every level so the globalThis.console wrapper's four
+    // bound arrows are all hit at least once.
+    expect(() => {
+      log.debug('d');
+      log.info('i');
+      log.warn('w');
+      log.error('e');
+    }).not.toThrow();
+  });
+
+  it('falls back to no-op sinks when globalThis.console is absent', () => {
+    const original = (globalThis as { console?: unknown }).console;
+    try {
+      // Simulate a runtime where `globalThis.console` is undefined.
+      (globalThis as { console?: unknown }).console = undefined;
+      const log = new ConsoleLogger();
+      expect(() => log.info('m')).not.toThrow();
+    } finally {
+      (globalThis as { console?: unknown }).console = original;
+    }
+  });
+});
+
+// Compile-time assertion: LogRecord includes the required observability fields.
+const _assertLogRecord: LogRecord = {
+  ts: 0,
+  level: LogLevel.Info,
+  msg: '',
+};
+void _assertLogRecord;

package/packages/irc-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-server",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": true,
   "description": "Orchestration layer: IrcRuntime port, dispatch interpreter, ConnectionActor",
   "license": "BSD-3-Clause",

package/packages/irc-server/src/actor.ts

@@ -26,6 +26,7 @@
  */
 
 import {
+  type AccountStore,
   type ChanName,
   type ChannelState,
   type Clock,
@@ -35,39 +36,25 @@ import {
   EmptyMotdProvider,
   type IdFactory,
   type IrcMessage,
+  type Logger,
+  type MessageStore,
   type MotdProvider,
+  NoopLoggerInstance,
   Numerics,
   type RawLine,
   type ServerConfig,
   buildCtx,
-  capReducer,
-  channelModeReducer,
+  chathistoryReducer,
   handleJoinZero,
-  inviteReducer,
   isChannelTarget,
-  joinReducer,
-  kickReducer,
   listReducer,
-  motdReducer,
-  namesReducer,
-  nickReducer,
-  noticeChannelReducer,
-  noticeUserReducer,
   parse,
-  partReducer,
-  passReducer,
-  pingReducer,
-  pongReducer,
-  privmsgChannelReducer,
-  privmsgUserReducer,
-  quitReducer,
-  topicReducer,
-  userModeReducer,
-  userReducer,
   whoReducer,
   whoisReducer,
 } from '@serverless-ircd/irc-core';
 import { dispatch } from './dispatch.js';
+import type { DispatchOptions } from './dispatch.js';
+import { type RoutedReducers, buildRoutedReducers } from './routing.js';
 import type { IrcRuntime } from './runtime.js';
 
 /**
@@ -87,6 +74,16 @@ import type { IrcRuntime } from './runtime.js';
  */
 export interface ActorChannelAccess {
   getOrCreateChannel(name: ChanName): ChannelState;
+  /**
+   * Peek-only channel lookup that does NOT create the channel as a side
+   * effect (unlike {@link getOrCreateChannel}). Returns the authoritative
+   * {@link ChannelState} when the channel exists, or `undefined` otherwise.
+   *
+   * Used by query-only commands (CHATHISTORY) that must distinguish "no
+   * such channel" from an empty one. Optional: runtimes that have not
+   * implemented it fall back to {@link getOrCreateChannel} in the actor.
+   */
+  getChannel?(name: ChanName): ChannelState | undefined;
   refreshChannel?(name: ChanName): Promise<void>;
 }
 
@@ -98,6 +95,38 @@ export interface ConnectionActorOptions {
   clock: Clock;
   ids: IdFactory;
   motd?: MotdProvider;
+  /**
+   * Chat-history persistence source (absent when chathistory playback is
+   * disabled). When bound, `ctx.messages` is defined so the CHATHISTORY
+   * reducer can query backlog and the PRIVMSG/NOTICE channel reducer
+   * records accepted messages. Omitted (→ `ctx.messages` undefined)
+   * preserves the no-store behaviour for deployments/tests that do not
+   * opt in.
+   */
+  readonly messages?: MessageStore;
+  /**
+   * SASL account verification source (absent when no accounts are
+   * configured). When bound, `ctx.accounts` is defined so the
+   * `AUTHENTICATE` reducer can verify PLAIN credentials end-to-end.
+   * Omitted (→ `ctx.accounts` undefined) preserves the existing
+   * behaviour for callers/tests that do not opt in: a client completing
+   * `AUTHENTICATE PLAIN` receives `904 ERR_SASLFAIL` because no store
+   * can vouch for the credentials.
+   */
+  readonly accounts?: AccountStore;
+  /**
+   * Structured-logger port. When omitted the actor runs
+   * silently — observability is purely opt-in. When supplied, every
+   * frame.receive / frame.parse-error / dispatch record carries the
+   * actor's bound `traceId` and `connectionId`.
+   */
+  readonly logger?: Logger;
+  /**
+   * Per-request trace id. When omitted the actor allocates
+   * one fresh per inbound frame via `ids.traceId()` so every frame is
+   * still uniquely identifiable in logs.
+   */
+  readonly traceId?: string;
 }
 
 export class ConnectionActor {
@@ -108,6 +137,21 @@ export class ConnectionActor {
   private readonly clock: Clock;
   private readonly ids: IdFactory;
   private readonly motd: MotdProvider;
+  private readonly messages: MessageStore | undefined;
+  private readonly accounts: AccountStore | undefined;
+  private readonly reducers: RoutedReducers;
+  /**
+   * Bound logger. Defaults to a no-op so the actor pipeline has no
+   * observable side effects when callers do not opt in.
+   */
+  private readonly logger: Logger;
+  /**
+   * Pinned trace id. When the caller did not supply one the actor generates
+   * a fresh one per inbound frame via {@link IdFactory.traceId}; this pinned
+   * value is only used in that latter case as a fallback for code paths
+   * that need a non-undefined id in test assertions.
+   */
+  private readonly pinnedTraceId: string | undefined;
 
   constructor(opts: ConnectionActorOptions) {
     this.state = opts.state;
@@ -117,6 +161,21 @@ export class ConnectionActor {
     this.clock = opts.clock;
     this.ids = opts.ids;
     this.motd = opts.motd ?? EmptyMotdProvider;
+    this.messages = opts.messages;
+    this.accounts = opts.accounts;
+    this.logger = opts.logger ?? NoopLoggerInstance;
+    this.pinnedTraceId = opts.traceId;
+    // Bind the connection id once so every record the actor emits carries
+    // the cross-cutting connection identifier. The child inherits traceId
+    // and rebinds per-frame; connectionId stays constant for the actor's
+    // lifetime.
+    if (opts.logger !== undefined) {
+      this.logger = opts.logger.child({ connectionId: this.state.id });
+    }
+    // Build once: every routed reducer is flood-control-wrapped (or the raw
+    // reducer when flood control is disabled) so a flooding client is bounded
+    // regardless of which authority owns the command's state.
+    this.reducers = buildRoutedReducers(opts.serverConfig);
   }
 
   /**
@@ -125,13 +184,17 @@ export class ConnectionActor {
    * one line emits a `421` and processing continues with the next line.
    */
   async receiveTextFrame(text: string): Promise<void> {
-    for (const line of splitFrameLines(text)) {
+    const lines = splitFrameLines(text);
+    if (lines.length === 0) return;
+    const traceId = this.pinnedTraceId ?? this.ids.traceId();
+    const log = this.logger.child({ traceId });
+    for (const line of lines) {
       if (line.length === 0) continue;
-      await this.processLine(line);
+      await this.processLine(line, log, traceId);
     }
   }
 
-  private async processLine(line: string): Promise<void> {
+  private async processLine(line: string, log: Logger, traceId: string): Promise<void> {
     let msg: IrcMessage;
     let parseFailed = false;
     try {
@@ -145,17 +208,30 @@ export class ConnectionActor {
       msg = { tags: {}, command: '', params: [] };
     }
     if (parseFailed) {
+      log.warn('frame.parse-error', {
+        line,
+        token: firstToken(line),
+      });
       const token = firstToken(line);
-      await dispatch([this.unknownCommandEffect(token)], this.runtime);
+      await dispatch(
+        [this.unknownCommandEffect(token)],
+        this.runtime,
+        this.dispatchOpts(log, traceId),
+      );
       return;
     }
+    log.debug('frame.receive', { command: msg.command, lines: 1 });
     // Pull authoritative channel state for any channel the upcoming reducer
     // will read. In-memory runtimes no-op; distributed runtimes fetch from
     // the channel authority (e.g. CF ChannelDO). Done before `route` so the
     // synchronous reducers observe up-to-date rosters / modes / topics.
     await this.prefetchChannelState(msg);
     const effects = await this.route(msg);
-    await dispatch(effects, this.runtime);
+    await dispatch(effects, this.runtime, this.dispatchOpts(log, traceId));
+  }
+
+  private dispatchOpts(log: Logger, traceId: string): DispatchOptions {
+    return { logger: log, traceId, connectionId: this.state.id };
   }
 
   /**
@@ -178,26 +254,34 @@ export class ConnectionActor {
       ids: this.ids,
       motd: this.motd,
       connection: this.state,
+      ...(this.messages !== undefined ? { messages: this.messages } : {}),
+      ...(this.accounts !== undefined ? { accounts: this.accounts } : {}),
     });
 
     switch (msg.command) {
       // -------- Connection-authority commands --------
       case 'PING':
-        return pingReducer(this.state, msg, ctx).effects;
+        return this.reducers.ping(this.state, msg, ctx).effects;
       case 'PONG':
-        return pongReducer(this.state, msg, ctx).effects;
+        return this.reducers.pong(this.state, msg, ctx).effects;
       case 'NICK':
-        return nickReducer(this.state, msg, ctx).effects;
+        return this.reducers.nick(this.state, msg, ctx).effects;
       case 'USER':
-        return userReducer(this.state, msg, ctx).effects;
+        return this.reducers.user(this.state, msg, ctx).effects;
       case 'PASS':
-        return passReducer(this.state, msg, ctx).effects;
+        return this.reducers.pass(this.state, msg, ctx).effects;
       case 'QUIT':
-        return quitReducer(this.state, msg, ctx).effects;
+        return this.reducers.quit(this.state, msg, ctx).effects;
       case 'MOTD':
-        return motdReducer(this.state, msg, ctx).effects;
+        return this.reducers.motd(this.state, msg, ctx).effects;
+      case 'OPER':
+        return this.reducers.oper(this.state, msg, ctx).effects;
       case 'CAP':
-        return capReducer(this.state, msg, ctx).effects;
+        return this.reducers.cap(this.state, msg, ctx).effects;
+      case 'AUTHENTICATE':
+        return this.reducers.authenticate(this.state, msg, ctx).effects;
+      case 'AWAY':
+        return this.reducers.away(this.state, msg, ctx).effects;
 
       // -------- Channel-authority commands --------
       case 'JOIN':
@@ -205,32 +289,54 @@ export class ConnectionActor {
       case 'PART':
         return this.routeMultiChannel(
           msg,
-          (chan, singleParamMsg) => partReducer(chan, singleParamMsg, ctx).effects,
+          (chan, singleParamMsg) => this.reducers.part(chan, singleParamMsg, ctx).effects,
         );
       case 'TOPIC':
-        return this.routeSingleChannel(msg, (chan) => topicReducer(chan, msg, ctx).effects);
+        return this.routeSingleChannel(msg, (chan) => this.reducers.topic(chan, msg, ctx).effects);
       case 'NAMES':
-        return this.routeSingleChannel(msg, (chan) => namesReducer(chan, msg, ctx).effects);
+        return this.routeSingleChannel(msg, (chan) => this.reducers.names(chan, msg, ctx).effects);
       case 'KICK':
-        return this.routeSingleChannel(msg, (chan) => kickReducer(chan, msg, ctx).effects);
+        return this.routeSingleChannel(msg, (chan) => this.reducers.kick(chan, msg, ctx).effects);
       case 'INVITE':
-        return this.routeSingleChannel(msg, (chan) => inviteReducer(chan, msg, ctx).effects);
+        return this.routeSingleChannel(msg, (chan) => this.reducers.invite(chan, msg, ctx).effects);
       case 'LIST':
         return this.routeList(msg, ctx);
       case 'WHO':
         return this.routeWho(msg, ctx);
       case 'WHOIS':
         return this.routeWhois(msg, ctx);
+      case 'CHATHISTORY':
+        return this.routeChathistory(msg, ctx);
 
       // -------- Target-dependent commands --------
       case 'PRIVMSG':
-        return this.routeMessageTarget(msg, privmsgChannelReducer, privmsgUserReducer, ctx);
+        return this.routeMessageTarget(
+          msg,
+          this.reducers.privmsgChannel,
+          this.reducers.privmsgUser,
+          ctx,
+        );
       case 'NOTICE':
-        return this.routeMessageTarget(msg, noticeChannelReducer, noticeUserReducer, ctx);
+        return this.routeMessageTarget(
+          msg,
+          this.reducers.noticeChannel,
+          this.reducers.noticeUser,
+          ctx,
+        );
+      case 'TAGMSG':
+        return this.routeMessageTarget(
+          msg,
+          this.reducers.tagmsgChannel,
+          this.reducers.tagmsgUser,
+          ctx,
+        );
       case 'MODE':
         return isChannelTarget(msg.params[0] ?? '')
-          ? this.routeSingleChannel(msg, (chan) => channelModeReducer(chan, msg, ctx).effects)
-          : userModeReducer(this.state, msg, ctx).effects;
+          ? this.routeSingleChannel(
+              msg,
+              (chan) => this.reducers.channelMode(chan, msg, ctx).effects,
+            )
+          : this.reducers.userMode(this.state, msg, ctx).effects;
 
       default:
         return [this.unknownCommandEffect(msg.command)];
@@ -281,6 +387,41 @@ export class ConnectionActor {
     return whoisReducer(target, channels, msg, ctx).effects;
   }
 
+  /**
+   * Routes `CHATHISTORY <sub> <target> [<args>...]` to the chathistory
+   * reducer. The command is query-only and must NOT create a channel as a
+   * side effect: the target channel (`msg.params[1]`) is resolved via the
+   * peek-only {@link ActorChannelAccess.getChannel} when the runtime
+   * implements it, so a non-existent channel yields `undefined` → the
+   * reducer emits `403 ERR_NOSUCHCHANNEL`. The `TARGETS` subcommand uses a
+   * timestamp in that position; `getChannel` simply returns `undefined`
+   * for it, which the reducer ignores (TARGETS never reads the channel).
+   *
+   * Cap-gating, param validation, and batch framing all live in the pure
+   * reducer — this method only resolves the channel and delegates.
+   */
+  private async routeChathistory(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const target = msg.params[1];
+    const channel = target !== undefined ? this.peekChannel(target) : undefined;
+    return chathistoryReducer(channel, msg, ctx).effects;
+  }
+
+  /**
+   * Resolves a channel by name WITHOUT creating it. Prefers the
+   * peek-only {@link ActorChannelAccess.getChannel}; falls back to
+   * {@link ActorChannelAccess.getOrCreateChannel} for runtimes that have
+   * not implemented the peek.
+   */
+  private peekChannel(name: ChanName): ChannelState | undefined {
+    if (this.channels.getChannel !== undefined) {
+      return this.channels.getChannel(name);
+    }
+    return this.channels.getOrCreateChannel(name);
+  }
+
   private routeJoin(msg: IrcMessage, ctx: ReturnType<typeof buildCtx>): EffectType[] {
     if (msg.params[0] === '0') {
       return handleJoinZero(ctx);
@@ -292,14 +433,14 @@ export class ConnectionActor {
       // No channel argument: defer to the reducer so it emits the proper
       // 461 ERR_NEEDMOREPARAMS rather than the actor silently doing nothing.
       const chan = this.channels.getOrCreateChannel('');
-      return joinReducer(chan, msg, ctx).effects;
+      return this.reducers.join(chan, msg, ctx).effects;
     }
     for (const [i, name] of names.entries()) {
       const chan = this.channels.getOrCreateChannel(name);
       const key = keys[i];
       const singleParamMsg: IrcMessage =
         key === undefined ? { ...msg, params: [name] } : { ...msg, params: [name, key] };
-      effects.push(...joinReducer(chan, singleParamMsg, ctx).effects);
+      effects.push(...this.reducers.join(chan, singleParamMsg, ctx).effects);
     }
     return effects;
   }
@@ -439,6 +580,7 @@ function channelTargetsForMessage(msg: IrcMessage): ChanName[] {
     case 'MODE':
     case 'PRIVMSG':
     case 'NOTICE':
+    case 'TAGMSG':
       return splitCsv(msg.params[0] ?? '').filter(isChannelTarget) as ChanName[];
     case 'INVITE':
       // INVITE <nick> <channel> — the channel is the second param.