serverless-ircd 0.1.0

package/packages/irc-core/src/commands/topic.ts

@@ -0,0 +1,171 @@
+/**
+ * Pure reducer for the IRC `TOPIC` command.
+ *
+ * PLAN §2.1 location-of-authority: TOPIC runs in the Channel entity. The
+ * reducer's `state` argument is the channel's authoritative state; the
+ * caller's identity is `ctx.connection`.
+ *
+ * Read form (`TOPIC <chan>` with no trailing topic):
+ *   - `331 RPL_NOTOPIC` when no topic is set.
+ *   - `332 RPL_TOPIC` + `333 RPL_TOPICWHOTIME` when a topic is set.
+ *
+ * Write form (`TOPIC <chan> :<topic>`):
+ *   - Sets `state.topic` (clearing it for an empty trailing param).
+ *   - Honors `+t` (topic lock): only ops may change the topic; non-op
+ *     members get `482 ERR_CHANOPRIVSNEEDED`.
+ *   - Truncates the topic to `serverConfig.topicLen` to keep wire lines
+ *     within the 512-byte budget.
+ *   - Broadcasts `:hostmask TOPIC <chan> :<topic>` to the channel.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ChannelState, ChannelTopic } from '../state/channel.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/** Channel-name grammar; mirrors {@link isValidChannelName} in `join.ts`. */
+const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
+
+function isValidChannelName(name: string, maxLen: number): boolean {
+  if (name.length === 0 || name.length > maxLen) return false;
+  return CHANNEL_NAME_RE.test(name);
+}
+
+/** Formats a numeric error/reply line addressed to the connection's nick. */
+function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== undefined) parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/** Returns the caller's hostmask, falling back to nick then `?`. */
+function callerHostmask(conn: ConnectionState): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/**
+ * Handles `TOPIC <chan> [:<topic>]`.
+ *
+ * Validation order (deliberate): missing-param → invalid-name →
+ * not-on-channel → write-authorization (+t) → success.
+ */
+export const topicReducer: Reducer<ChannelState> = (state, msg, ctx) => {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  const rawName = msg.params[0];
+  if (rawName === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'TOPIC'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  if (!isValidChannelName(rawName, ctx.serverConfig.channelLen)) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOSUCHCHANNEL, 'No such channel', rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Must be a member to read or write the topic.
+  const entry = state.members.get(ctx.connId);
+  if (entry === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOTONCHANNEL, "You're not on that channel", state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Read form: no topic param supplied. We check `params[1]` directly
+  // (rather than `params.length`) because it cleanly handles both
+  // `TOPIC #foo` and any defensive "params is shorter than expected" case.
+  const newTopic = msg.params[1];
+  if (newTopic === undefined) {
+    return readTopic(state, ctx, effects);
+  }
+
+  // Write form. +t (topic lock) requires op.
+  if (state.modes.topicLock && !entry.op) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_CHANOPRIVSNEEDED, "You're not channel operator", state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const truncated =
+    newTopic.length > ctx.serverConfig.topicLen
+      ? newTopic.slice(0, ctx.serverConfig.topicLen)
+      : newTopic;
+
+  // Empty topic clears; non-empty sets.
+  if (truncated.length === 0) {
+    // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `=undefined`.
+    delete state.topic;
+    // Mirror the topic clear to the runtime's channel authority. In the
+    // in-memory runtime the actor's `state` IS authoritative so this is
+    // redundant; in distributed runtimes (CF ChannelDO) this is the only
+    // path that persists the change, so subsequent reads by other
+    // connections observe the cleared topic.
+    effects.push(Effect.applyChannelDelta(state.name, { topic: null }));
+  } else {
+    const topic: ChannelTopic = {
+      text: truncated,
+      setter: callerHostmask(ctx.connection),
+      setAt: ctx.clock.now(),
+    };
+    state.topic = topic;
+    // Mirror the topic set to the channel authority (see comment above).
+    effects.push(Effect.applyChannelDelta(state.name, { topic }));
+  }
+
+  const hostmask = callerHostmask(ctx.connection);
+  const line: RawLine = { text: `:${hostmask} TOPIC ${state.name} :${truncated}` };
+  effects.push(Effect.broadcast(state.name, [line]));
+
+  return { state, effects };
+};
+
+/** Emits the read-form numeric block: `331` (no topic) or `332` + `333`. */
+function readTopic(
+  state: ChannelState,
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ChannelState; effects: EffectType[] } {
+  if (state.topic === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.RPL_NOTOPIC, 'No topic is set', state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr332 = Numerics.RPL_TOPIC.toString().padStart(3, '0');
+  const codeStr333 = Numerics.RPL_TOPICWHOTIME.toString().padStart(3, '0');
+  effects.push(
+    Effect.send(ctx.connId, [
+      { text: `:${ctx.serverName} ${codeStr332} ${nick} ${state.name} :${state.topic.text}` },
+      {
+        text: `:${ctx.serverName} ${codeStr333} ${nick} ${state.name} ${state.topic.setter} ${state.topic.setAt}`,
+      },
+    ]),
+  );
+  return { state, effects };
+}

package/packages/irc-core/src/commands/who.ts

@@ -0,0 +1,169 @@
+/**
+ * Pure reducer for the IRC `WHO` command.
+ *
+ * PLAN §2.1 location-of-authority: WHO reads channel + connection state but
+ * does not mutate either, so the reducer takes the channel snapshot (state
+ * arg) and a separate `connections` map keyed by ConnId. The requester is
+ * `ctx.connection`.
+ *
+ * Wire format (RFC 1459/2812 §3.6.1):
+ *   - `352 RPL_WHOREPLY`:
+ *     `:<server> 352 <nick> <chan> <user> <host> <server> <nick> <flags> :<hops> <real>`
+ *     - `<flags>` starts with `H` (here) or `G` (gone/away), optionally
+ *       followed by `*` (oper), then channel-prefix chars (`@`, `+`).
+ *   - `315 RPL_ENDOFWHO`: `:<server> 315 <nick> <mask> :End of /WHO list`
+ *
+ * Visibility rules:
+ *   - `+s` (secret) channels: members only. Non-members get an empty list
+ *     (no 403 — modern IRC daemons treat WHO of a +s channel as "no match"
+ *     for non-members to avoid leaking existence).
+ *   - `+i` (invisible user mode): only shown when the requester shares a
+ *     channel with the invisible user. Within a single WHO #chan call the
+ *     requester is by construction on `#chan`, so invisible members of that
+ *     channel are listed.
+ *
+ * The actor layer routes WHO by target type:
+ *   - Channel target (`#foo`): handled here, against the channel snapshot.
+ *   - Nick target / wildcards: handled by the actor layer against the nick
+ *     registry and connection snapshots; this reducer is channel-scoped.
+ *
+ * For v1 the `<server>` field in 352 is the configured local server name
+ * (PLAN §1: single-server, no S2S linking).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ChannelState, RosterEntry } from '../state/channel.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Channel-name grammar; mirrors {@link isValidChannelName} in `join.ts`. */
+const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
+
+function isValidChannelName(name: string, maxLen: number): boolean {
+  if (name.length === 0 || name.length > maxLen) return false;
+  return CHANNEL_NAME_RE.test(name);
+}
+
+/** Formats a numeric error/reply line addressed to the connection's nick. */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== '') parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Builds the `<flags>` field for one 352 line.
+ *
+ * Channel-prefix chars follow the away/oper markers. With `multi-prefix`
+ * every applicable prefix is emitted (`@+` for an op+voice user); without
+ * the cap only the highest-priority prefix is emitted (`@`), matching the
+ * NAMES reducer's behavior and IRCv3 `multi-prefix` spec.
+ */
+function whoFlags(conn: ConnectionState, entry: RosterEntry, ctx: Ctx): string {
+  let flags = conn.away !== undefined ? 'G' : 'H';
+  if (conn.userModes.oper) flags += '*';
+  if (ctx.connection.caps.has('multi-prefix')) {
+    if (entry.op) flags += '@';
+    if (entry.voice) flags += '+';
+  } else if (entry.op) {
+    flags += '@';
+  } else if (entry.voice) {
+    flags += '+';
+  }
+  return flags;
+}
+
+/**
+ * Builds one 352 line for a single member.
+ *
+ * `hops` is hard-coded to 0 (single-server v1, no S2S hops).
+ */
+function whoLine(chanName: string, conn: ConnectionState, entry: RosterEntry, ctx: Ctx): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const user = conn.user;
+  const host = conn.host;
+  const server = ctx.serverName;
+  const memberNick = conn.nick;
+  const flags = whoFlags(conn, entry, ctx);
+  const hops = 0;
+  const real = conn.realname;
+  const codeStr = Numerics.RPL_WHOREPLY.toString().padStart(3, '0');
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${nick} ${chanName} ${user} ${host} ${server} ${memberNick} ${flags} :${hops} ${real}`,
+  };
+}
+
+/**
+ * Handles `WHO <chan> [o]`.
+ *
+ * Returns the empty-list reply when visibility checks fail; otherwise emits
+ * one 352 per visible member then a 315. The `o` filter restricts output to
+ * IRC operators (server operators, not channel ops).
+ */
+export function whoReducer(
+  state: ChannelState,
+  connections: ReadonlyMap<string, ConnectionState>,
+  msg: { command: string; params: string[] },
+  ctx: Ctx,
+): { state: ChannelState; effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  const rawMask = msg.params[0];
+  if (rawMask === undefined) {
+    // No mask: modern daemons reply with end-of-WHO for the empty mask.
+    // We mirror that and emit no 461 (matches test spec).
+    effects.push(
+      Effect.send(ctx.connId, [numericLine(ctx, Numerics.RPL_ENDOFWHO, 'End of /WHO list', '')]),
+    );
+    return { state, effects };
+  }
+
+  if (!isValidChannelName(rawMask, ctx.serverConfig.channelLen)) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOSUCHCHANNEL, 'No such channel', rawMask),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // +s channel: non-members get an empty reply (no 403 — avoid leaking).
+  const isMember = state.members.has(ctx.connId);
+  if ((state.modes.secret || state.modes.private) && !isMember) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.RPL_ENDOFWHO, 'End of /WHO list', state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // `o` filter: operators only.
+  const opsOnly = msg.params[1] === 'o';
+
+  const lines: RawLine[] = [];
+  for (const entry of state.members.values()) {
+    const conn = connections.get(entry.conn);
+    if (conn === undefined) continue;
+    if (opsOnly && !conn.userModes.oper) continue;
+    lines.push(whoLine(state.name, conn, entry, ctx));
+  }
+
+  if (lines.length > 0) {
+    effects.push(Effect.send(ctx.connId, lines));
+  }
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericLine(ctx, Numerics.RPL_ENDOFWHO, 'End of /WHO list', state.name),
+    ]),
+  );
+
+  return { state, effects };
+}

package/packages/irc-core/src/commands/whois.ts

@@ -0,0 +1,165 @@
+/**
+ * Pure reducer for the IRC `WHOIS` command.
+ *
+ * PLAN §2.1 location-of-authority: WHOIS reads connection + channel state but
+ * does not mutate the target, so the reducer takes the target ConnectionState
+ * (resolved by the actor layer via the nick registry) and the channels the
+ * target is a member of. The requester is `ctx.connection`.
+ *
+ * Wire format (RFC 1459/2812 §3.6.2):
+ *   - `311 RPL_WHOISUSER`:
+ *     `:<server> 311 <nick> <target> <user> <host> * :<real>`
+ *   - `319 RPL_WHOISCHANNELS`:
+ *     `:<server> 319 <nick> <target> :<channels>` (space-separated, prefixed)
+ *   - `312 RPL_WHOISSERVER`:
+ *     `:<server> 312 <nick> <target> <server> :<network>`
+ *   - `317 RPL_WHOISIDLE`:
+ *     `:<server> 317 <nick> <target> <idle-secs> <signon-secs> :seconds idle, signon time`
+ *   - `330 RPL_WHOISACCOUNT` (IRCv3):
+ *     `:<server> 330 <nick> <target> <account> :is logged in as`
+ *   - `313 RPL_WHOISOPERATOR`:
+ *     `:<server> 313 <nick> <target> :is an IRC operator`
+ *   - `318 RPL_ENDOFWHOIS`:
+ *     `:<server> 318 <nick> <target> :End of /WHOIS list`
+ *   - `401 ERR_NOSUCHNICK`:
+ *     `:<server> 401 <nick> <target> :No such nick/channel`
+ *
+ * Channel visibility:
+ *   - Secret (+s) and private (+p) channels are hidden unless the requester
+ *     is also a member.
+ *
+ * Idle and signon math:
+ *   - `idle` = `floor((ctx.clock.now() - target.lastSeen) / 1000)`
+ *   - `signon` = `floor(target.connectedSince / 1000)`
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ChannelState, RosterEntry } from '../state/channel.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Formats a numeric line addressed to the requester. */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== '') parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/** Returns the roster sigil (`@`, `+`, or '') for the target on a channel. */
+function prefixOf(entry: RosterEntry): string {
+  if (entry.op) return '@';
+  if (entry.voice) return '+';
+  return '';
+}
+
+/**
+ * Builds the 319 channel list, applying +s/+p visibility filtering.
+ *
+ * Channels are sorted alphabetically (by lowercase name) for deterministic
+ * output. Each entry is prefixed with the target's mode sigil on that channel.
+ */
+function visibleChannels(
+  target: ConnectionState,
+  channels: ReadonlyArray<ChannelState>,
+  ctx: Ctx,
+): string {
+  const visible: Array<{ name: string; sort: string; prefix: string }> = [];
+  for (const chan of channels) {
+    const entry = chan.members.get(target.id);
+    if (entry === undefined) continue;
+    const hidden = chan.modes.secret || chan.modes.private;
+    if (hidden && !chan.members.has(ctx.connId)) continue;
+    visible.push({ name: chan.name, sort: chan.nameLower, prefix: prefixOf(entry) });
+  }
+  visible.sort((a, b) => a.sort.localeCompare(b.sort));
+  return visible.map((c) => `${c.prefix}${c.name}`).join(' ');
+}
+
+/**
+ * Handles `WHOIS <nick>`.
+ *
+ * The actor layer resolves `<nick>` to a target ConnectionState via the nick
+ * registry, collects the channels the target is a member of, and passes both
+ * here. If `target` is `undefined`, the reducer emits 401 then 318.
+ */
+export function whoisReducer(
+  target: ConnectionState | undefined,
+  channels: ReadonlyArray<ChannelState>,
+  msg: { command: string; params: string[] },
+  ctx: Ctx,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+  const targetNick = msg.params[0] ?? '';
+
+  if (target === undefined) {
+    if (targetNick !== '') {
+      effects.push(
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOSUCHNICK, 'No such nick/channel', targetNick),
+        ]),
+      );
+    }
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.RPL_ENDOFWHOIS, 'End of /WHOIS list', targetNick),
+      ]),
+    );
+    return { effects };
+  }
+
+  const lines: RawLine[] = [];
+  const requesterNick = ctx.connection.nick ?? '*';
+  const tNick = target.nick ?? '*';
+  const tUser = target.user ?? '?';
+  const tHost = target.host ?? '?';
+  const tReal = target.realname ?? tNick;
+  const idleSecs = Math.floor((ctx.clock.now() - target.lastSeen) / 1000);
+  const signonSecs = Math.floor(target.connectedSince / 1000);
+
+  lines.push({
+    text: `:${ctx.serverName} ${Numerics.RPL_WHOISUSER.toString().padStart(3, '0')} ${requesterNick} ${tNick} ${tUser} ${tHost} * :${tReal}`,
+  });
+  lines.push({
+    text: `:${ctx.serverName} ${Numerics.RPL_WHOISSERVER.toString().padStart(3, '0')} ${requesterNick} ${tNick} ${ctx.serverName} :${ctx.networkName}`,
+  });
+  if (target.userModes.oper) {
+    lines.push({
+      text: `:${ctx.serverName} ${Numerics.RPL_WHOISOPERATOR.toString().padStart(3, '0')} ${requesterNick} ${tNick} :is an IRC operator`,
+    });
+  }
+  if (target.account !== undefined) {
+    lines.push({
+      text: `:${ctx.serverName} ${Numerics.RPL_WHOISACCOUNT.toString().padStart(3, '0')} ${requesterNick} ${tNick} ${target.account} :is logged in as`,
+    });
+  }
+  lines.push({
+    text: `:${ctx.serverName} ${Numerics.RPL_WHOISIDLE.toString().padStart(3, '0')} ${requesterNick} ${tNick} ${idleSecs} ${signonSecs} :seconds idle, signon time`,
+  });
+  effects.push(Effect.send(ctx.connId, lines));
+
+  const channelList = visibleChannels(target, channels, ctx);
+  if (channelList !== '') {
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${Numerics.RPL_WHOISCHANNELS.toString().padStart(3, '0')} ${requesterNick} ${tNick} :${channelList}`,
+        },
+      ]),
+    );
+  }
+
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericLine(ctx, Numerics.RPL_ENDOFWHOIS, 'End of /WHOIS list', tNick),
+    ]),
+  );
+
+  return { effects };
+}

package/packages/irc-core/src/effects.ts

@@ -0,0 +1,184 @@
+/**
+ * The `Effect` discriminated union.
+ *
+ * Reducers are pure: they emit a description of every side effect they
+ * need (transport sends, nick registry mutations, channel deltas, lookups)
+ * without performing them. The actor layer's `dispatch(effects, runtime)`
+ * interprets each effect against the bound {@link IrcRuntime}.
+ *
+ * Every effect tag corresponds one-to-one with an `IrcRuntime` method, so
+ * the dispatch table is mechanical.
+ *
+ * Coverage of side effects referenced in PLAN §2.1:
+ *   - transport: {@link SendEffect}, {@link BroadcastEffect}, {@link DisconnectEffect}
+ *   - nick registry: {@link ReserveNickEffect}, {@link ChangeNickEffect},
+ *     {@link ReleaseNickEffect}
+ *   - channel ownership: {@link ApplyChannelDeltaEffect}
+ *   - lookups: {@link LookupNickEffect}, {@link GetConnectionInfoEffect},
+ *     {@link GetChannelSnapshotEffect}
+ */
+
+import type { ChanName, ChannelDelta } from './state/channel.js';
+import type { ConnId, Nick } from './state/connection.js';
+
+/** A single wire-format IRC line, ready to ship to a transport. */
+export interface RawLine {
+  text: string;
+}
+
+export interface SendEffect {
+  tag: 'Send';
+  to: ConnId;
+  lines: RawLine[];
+}
+
+export interface BroadcastEffect {
+  tag: 'Broadcast';
+  chan: ChanName;
+  lines: RawLine[];
+  except?: ConnId;
+  cap?: string;
+  capLines?: RawLine[];
+}
+
+export interface DisconnectEffect {
+  tag: 'Disconnect';
+  conn: ConnId;
+  reason?: string;
+}
+
+export interface ReserveNickEffect {
+  tag: 'ReserveNick';
+  nick: Nick;
+  conn: ConnId;
+}
+
+export interface ChangeNickEffect {
+  tag: 'ChangeNick';
+  conn: ConnId;
+  oldNick: Nick;
+  newNick: Nick;
+}
+
+export interface ReleaseNickEffect {
+  tag: 'ReleaseNick';
+  nick: Nick;
+}
+
+export interface ApplyChannelDeltaEffect {
+  tag: 'ApplyChannelDelta';
+  chan: ChanName;
+  delta: ChannelDelta;
+}
+
+export interface LookupNickEffect {
+  tag: 'LookupNick';
+  nick: Nick;
+}
+
+export interface GetConnectionInfoEffect {
+  tag: 'GetConnectionInfo';
+  conn: ConnId;
+}
+
+export interface GetChannelSnapshotEffect {
+  tag: 'GetChannelSnapshot';
+  chan: ChanName;
+}
+
+/**
+ * Routes `lines` to whichever connection currently owns `nick`. If the nick
+ * is offline, `notFoundLines` (when supplied) is sent back to `sender` —
+ * this is how PRIVMSG surfaces `401 ERR_NOSUCHNICK`; NOTICE omits the
+ * fallback entirely (RFC: NOTICE MUST NEVER generate numerics).
+ */
+export interface SendToNickEffect {
+  tag: 'SendToNick';
+  nick: Nick;
+  sender: ConnId;
+  lines: RawLine[];
+  notFoundLines?: RawLine[];
+}
+
+/** Discriminated union of every effect the dispatch interpreter knows. */
+export type Effect =
+  | SendEffect
+  | BroadcastEffect
+  | DisconnectEffect
+  | ReserveNickEffect
+  | ChangeNickEffect
+  | ReleaseNickEffect
+  | ApplyChannelDeltaEffect
+  | LookupNickEffect
+  | GetConnectionInfoEffect
+  | GetChannelSnapshotEffect
+  | SendToNickEffect;
+
+/** Literal string tag of every {@link Effect} variant. */
+export type EffectTag = Effect['tag'];
+
+/**
+ * Per-effect success indicator returned by `dispatch` for effects whose
+ * runtime method yields a meaningful result. Lookup-shaped effects surface
+ * `null` when nothing matched; nick-reservation surfaces `{ ok: false }` on
+ * collision; everything else reports `{ ok: true }`.
+ */
+export type EffectDispatchResult =
+  | { ok: true }
+  | { ok: false }
+  | { ok: true; value: unknown } // optional payload (lookup result)
+  | null;
+
+/**
+ * Tagged-union constructors. Keeps reducer code terse and gives the test
+ * suite a single import surface to assert against.
+ */
+export const Effect = {
+  send(to: ConnId, lines: RawLine[]): Effect {
+    return { tag: 'Send', to, lines };
+  },
+  broadcast(
+    chan: ChanName,
+    lines: RawLine[],
+    except?: ConnId,
+    cap?: string,
+    capLines?: RawLine[],
+  ): Effect {
+    const e: BroadcastEffect = { tag: 'Broadcast', chan, lines };
+    if (except !== undefined) e.except = except;
+    if (cap !== undefined) e.cap = cap;
+    if (capLines !== undefined) e.capLines = capLines;
+    return e;
+  },
+  disconnect(conn: ConnId, reason?: string): Effect {
+    const e: DisconnectEffect = { tag: 'Disconnect', conn };
+    if (reason !== undefined) e.reason = reason;
+    return e;
+  },
+  reserveNick(nick: Nick, conn: ConnId): Effect {
+    return { tag: 'ReserveNick', nick, conn };
+  },
+  changeNick(conn: ConnId, oldNick: Nick, newNick: Nick): Effect {
+    return { tag: 'ChangeNick', conn, oldNick, newNick };
+  },
+  releaseNick(nick: Nick): Effect {
+    return { tag: 'ReleaseNick', nick };
+  },
+  applyChannelDelta(chan: ChanName, delta: ChannelDelta): Effect {
+    return { tag: 'ApplyChannelDelta', chan, delta };
+  },
+  lookupNick(nick: Nick): Effect {
+    return { tag: 'LookupNick', nick };
+  },
+  getConnectionInfo(conn: ConnId): Effect {
+    return { tag: 'GetConnectionInfo', conn };
+  },
+  getChannelSnapshot(chan: ChanName): Effect {
+    return { tag: 'GetChannelSnapshot', chan };
+  },
+  sendToNick(nick: Nick, sender: ConnId, lines: RawLine[], notFoundLines?: RawLine[]): Effect {
+    const e: SendToNickEffect = { tag: 'SendToNick', nick, sender, lines };
+    if (notFoundLines !== undefined) e.notFoundLines = notFoundLines;
+    return e;
+  },
+} as const;