serverless-ircd 0.1.0

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

@@ -0,0 +1,449 @@
+/**
+ * Per-connection actor: bytes → framed messages → reducer → dispatch.
+ *
+ * PLAN §2.1 + §9 — the actor owns one connection's lifecycle. It receives
+ * WebSocket text frames (one IRC message per frame, or N `\r\n`-joined
+ * messages per frame), splits them into lines, parses each line, routes by
+ * command to the right reducer per the location-of-authority table, and
+ * `dispatch`es the resulting `Effect[]` against the bound {@link IrcRuntime}.
+ *
+ * Invariants (acceptance criteria):
+ *   - One message per frame → one reducer invocation.
+ *   - Joined frame with N `\r\n` → N invocations, in order.
+ *   - Parser failures produce `421 ERR_UNKNOWNCOMMAND` and processing
+ *     continues (the actor never crashes on a single bad line).
+ *
+ * Location-of-authority:
+ *   - Connection commands (PING/NICK/USER/…/QUIT) run against the actor's
+ *     own {@link ConnectionState}.
+ *   - Channel commands (JOIN/PART/…) run against the authoritative
+ *     {@link ChannelState} the runtime exposes via {@link ActorChannelAccess}.
+ *   - Target-dependent commands (PRIVMSG/NOTICE/MODE) are routed by the
+ *     first param's shape (`#`/`&` prefix → channel).
+ *
+ * The actor is transport-agnostic by design: it processes text frames. The
+ * CF / AWS adapters wrap it with platform-specific socket glue.
+ */
+
+import {
+  type ChanName,
+  type ChannelState,
+  type Clock,
+  type ConnectionState,
+  Effect,
+  type Effect as EffectType,
+  EmptyMotdProvider,
+  type IdFactory,
+  type IrcMessage,
+  type MotdProvider,
+  Numerics,
+  type RawLine,
+  type ServerConfig,
+  buildCtx,
+  capReducer,
+  channelModeReducer,
+  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 { IrcRuntime } from './runtime.js';
+
+/**
+ * Channel-state access for the actor.
+ *
+ * For the in-memory runtime this is `runtime.getOrCreateChannel`. CF / AWS
+ * adapters will not use this actor — they forward channel-authority
+ * commands to a ChannelDO / Lambda — so this interface only needs to cover
+ * the local-execution case.
+ *
+ * `refreshChannel` is optional: in-memory runtimes omit it (their state is
+ * already authoritative). Distributed runtimes implement it so the actor
+ * can pull the current roster / modes / topic from the channel authority
+ * before running a reducer that needs to observe them (NAMES, MODE, KICK,
+ * cross-connection JOIN checks, …). The actor awaits `refreshChannel`
+ * once per parsed message, before routing.
+ */
+export interface ActorChannelAccess {
+  getOrCreateChannel(name: ChanName): ChannelState;
+  refreshChannel?(name: ChanName): Promise<void>;
+}
+
+export interface ConnectionActorOptions {
+  state: ConnectionState;
+  runtime: IrcRuntime;
+  channels: ActorChannelAccess;
+  serverConfig: ServerConfig;
+  clock: Clock;
+  ids: IdFactory;
+  motd?: MotdProvider;
+}
+
+export class ConnectionActor {
+  private readonly state: ConnectionState;
+  private readonly runtime: IrcRuntime;
+  private readonly channels: ActorChannelAccess;
+  private readonly serverConfig: ServerConfig;
+  private readonly clock: Clock;
+  private readonly ids: IdFactory;
+  private readonly motd: MotdProvider;
+
+  constructor(opts: ConnectionActorOptions) {
+    this.state = opts.state;
+    this.runtime = opts.runtime;
+    this.channels = opts.channels;
+    this.serverConfig = opts.serverConfig;
+    this.clock = opts.clock;
+    this.ids = opts.ids;
+    this.motd = opts.motd ?? EmptyMotdProvider;
+  }
+
+  /**
+   * Processes one WebSocket text frame. Splits on `\r\n` (tolerating bare
+   * `\n`) and dispatches each non-empty line in order. A parse failure on
+   * one line emits a `421` and processing continues with the next line.
+   */
+  async receiveTextFrame(text: string): Promise<void> {
+    for (const line of splitFrameLines(text)) {
+      if (line.length === 0) continue;
+      await this.processLine(line);
+    }
+  }
+
+  private async processLine(line: string): Promise<void> {
+    let msg: IrcMessage;
+    let parseFailed = false;
+    try {
+      msg = parse(line);
+    } catch {
+      // `parse` only throws `IrcParseError` (every throw inside the parser
+      // constructs one); the untyped catch is the strict-mode narrowing
+      // artifact for `unknown`. Every parse failure becomes a `421` so the
+      // actor never crashes on a single bad line (acceptance criteria).
+      parseFailed = true;
+      msg = { tags: {}, command: '', params: [] };
+    }
+    if (parseFailed) {
+      const token = firstToken(line);
+      await dispatch([this.unknownCommandEffect(token)], this.runtime);
+      return;
+    }
+    // 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);
+  }
+
+  /**
+   * Awaits {@link ActorChannelAccess.refreshChannel} for every channel
+   * referenced by `msg`, if the bound channel-access implementation opted
+   * in. No-op for in-memory runtimes.
+   */
+  private async prefetchChannelState(msg: IrcMessage): Promise<void> {
+    const refresh = this.channels.refreshChannel;
+    if (refresh === undefined) return;
+    const targets = channelTargetsForMessage(msg);
+    if (targets.length === 0) return;
+    await Promise.all(targets.map((name) => refresh.call(this.channels, name)));
+  }
+
+  private async route(msg: IrcMessage): Promise<EffectType[]> {
+    const ctx = buildCtx({
+      serverConfig: this.serverConfig,
+      clock: this.clock,
+      ids: this.ids,
+      motd: this.motd,
+      connection: this.state,
+    });
+
+    switch (msg.command) {
+      // -------- Connection-authority commands --------
+      case 'PING':
+        return pingReducer(this.state, msg, ctx).effects;
+      case 'PONG':
+        return pongReducer(this.state, msg, ctx).effects;
+      case 'NICK':
+        return nickReducer(this.state, msg, ctx).effects;
+      case 'USER':
+        return userReducer(this.state, msg, ctx).effects;
+      case 'PASS':
+        return passReducer(this.state, msg, ctx).effects;
+      case 'QUIT':
+        return quitReducer(this.state, msg, ctx).effects;
+      case 'MOTD':
+        return motdReducer(this.state, msg, ctx).effects;
+      case 'CAP':
+        return capReducer(this.state, msg, ctx).effects;
+
+      // -------- Channel-authority commands --------
+      case 'JOIN':
+        return this.routeJoin(msg, ctx);
+      case 'PART':
+        return this.routeMultiChannel(
+          msg,
+          (chan, singleParamMsg) => partReducer(chan, singleParamMsg, ctx).effects,
+        );
+      case 'TOPIC':
+        return this.routeSingleChannel(msg, (chan) => topicReducer(chan, msg, ctx).effects);
+      case 'NAMES':
+        return this.routeSingleChannel(msg, (chan) => namesReducer(chan, msg, ctx).effects);
+      case 'KICK':
+        return this.routeSingleChannel(msg, (chan) => kickReducer(chan, msg, ctx).effects);
+      case 'INVITE':
+        return this.routeSingleChannel(msg, (chan) => inviteReducer(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);
+
+      // -------- Target-dependent commands --------
+      case 'PRIVMSG':
+        return this.routeMessageTarget(msg, privmsgChannelReducer, privmsgUserReducer, ctx);
+      case 'NOTICE':
+        return this.routeMessageTarget(msg, noticeChannelReducer, noticeUserReducer, ctx);
+      case 'MODE':
+        return isChannelTarget(msg.params[0] ?? '')
+          ? this.routeSingleChannel(msg, (chan) => channelModeReducer(chan, msg, ctx).effects)
+          : userModeReducer(this.state, msg, ctx).effects;
+
+      default:
+        return [this.unknownCommandEffect(msg.command)];
+    }
+  }
+
+  private async routeList(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const snapshots = await this.runtime.listChannels();
+    return listReducer(snapshots, msg, ctx).effects;
+  }
+
+  private async routeWho(msg: IrcMessage, ctx: ReturnType<typeof buildCtx>): Promise<EffectType[]> {
+    const target = msg.params[0] ?? '';
+    if (target.length === 0) {
+      return whoReducer(this.channels.getOrCreateChannel(''), new Map(), msg, ctx).effects;
+    }
+    const chan = this.channels.getOrCreateChannel(target);
+    const connections = await this.runtime.getChannelConnections(target);
+    return whoReducer(chan, connections, msg, ctx).effects;
+  }
+
+  /**
+   * Resolves the WHOIS target via the nick registry, fetches its live
+   * {@link ConnectionState} from the runtime, and gathers the
+   * {@link ChannelState}s the target belongs to so the reducer can build
+   * the `319` channel list. Unknown / no-arg cases pass `undefined` to
+   * the reducer, which emits `401`+`318` (with a nick) or just `318`.
+   */
+  private async routeWhois(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const targetNick = msg.params[0] ?? '';
+    let target: ConnectionState | undefined;
+    if (targetNick.length > 0) {
+      const connId = await this.runtime.lookupNick(targetNick);
+      if (connId !== null) {
+        target = (await this.runtime.getConnection(connId)) ?? undefined;
+      }
+    }
+    const channels =
+      target === undefined
+        ? []
+        : Array.from(target.joinedChannels, (name) => this.channels.getOrCreateChannel(name));
+    return whoisReducer(target, channels, msg, ctx).effects;
+  }
+
+  private routeJoin(msg: IrcMessage, ctx: ReturnType<typeof buildCtx>): EffectType[] {
+    if (msg.params[0] === '0') {
+      return handleJoinZero(ctx);
+    }
+    const effects: EffectType[] = [];
+    const names = splitCsv(msg.params[0] ?? '');
+    const keys = splitCsv(msg.params[1] ?? '');
+    if (names.length === 0) {
+      // 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;
+    }
+    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);
+    }
+    return effects;
+  }
+
+  private routeSingleChannel(
+    msg: IrcMessage,
+    run: (chan: ChannelState) => EffectType[],
+  ): EffectType[] {
+    const name = msg.params[0] ?? '';
+    if (name.length === 0) {
+      return [this.unknownCommandEffect(msg.command)];
+    }
+    const chan = this.channels.getOrCreateChannel(name);
+    return run(chan);
+  }
+
+  private routeMultiChannel(
+    msg: IrcMessage,
+    run: (chan: ChannelState, singleParamMsg: IrcMessage) => EffectType[],
+  ): EffectType[] {
+    const effects: EffectType[] = [];
+    const rawParam = msg.params[0] ?? '';
+    const names = splitCsv(rawParam);
+    const tail = msg.params.slice(1);
+    // No channel argument: defer to the reducer so it can emit the proper
+    // 461 ERR_NEEDMOREPARAMS rather than the actor silently doing nothing.
+    if (names.length === 0) {
+      // No channel argument: defer to the reducer so it can emit the proper
+      // 461 ERR_NEEDMOREPARAMS rather than the actor silently doing nothing.
+      return run(this.channels.getOrCreateChannel(''), msg);
+    }
+    for (const name of names) {
+      const chan = this.channels.getOrCreateChannel(name);
+      const singleParamMsg: IrcMessage = { ...msg, params: [name, ...tail] };
+      effects.push(...run(chan, singleParamMsg));
+    }
+    return effects;
+  }
+
+  private routeMessageTarget(
+    msg: IrcMessage,
+    channelReducer: (
+      chan: ChannelState,
+      msg: IrcMessage,
+      ctx: ReturnType<typeof buildCtx>,
+    ) => {
+      effects: EffectType[];
+    },
+    userReducer: (
+      state: ConnectionState,
+      msg: IrcMessage,
+      ctx: ReturnType<typeof buildCtx>,
+    ) => {
+      effects: EffectType[];
+    },
+    ctx: ReturnType<typeof buildCtx>,
+  ): EffectType[] {
+    const effects: EffectType[] = [];
+    const targets = splitCsv(msg.params[0] ?? '');
+    const tail = msg.params.slice(1);
+    if (targets.length === 0) {
+      // No target argument: defer to the user-target reducer so it emits the
+      // proper 411 ERR_NORECIPIENT rather than silently doing nothing.
+      return userReducer(this.state, msg, ctx).effects;
+    }
+    for (const target of targets) {
+      const singleParamMsg: IrcMessage = { ...msg, params: [target, ...tail] };
+      if (isChannelTarget(target)) {
+        const chan = this.channels.getOrCreateChannel(target);
+        effects.push(...channelReducer(chan, singleParamMsg, ctx).effects);
+      } else {
+        effects.push(...userReducer(this.state, singleParamMsg, ctx).effects);
+      }
+    }
+    return effects;
+  }
+
+  private unknownCommandEffect(command: string): EffectType {
+    const nick = this.state.nick ?? '*';
+    const code = Numerics.ERR_UNKNOWNCOMMAND.toString().padStart(3, '0');
+    const line: RawLine = {
+      text:
+        command.length === 0
+          ? `:${this.serverConfig.serverName} ${code} ${nick} :Unknown command`
+          : `:${this.serverConfig.serverName} ${code} ${nick} ${command} :Unknown command`,
+    };
+    return Effect.send(this.state.id, [line]);
+  }
+}
+
+/**
+ * Splits a WebSocket text frame into IRC lines. Tolerates `\r\n`, bare `\n`,
+ * and missing trailing terminators. Returns each line bare (no CRLF).
+ */
+export function splitFrameLines(text: string): string[] {
+  if (text.length === 0) return [];
+  return text.split(/\r?\n/u);
+}
+
+/** Returns the first whitespace-delimited token of `line`, or `''`. */
+function firstToken(line: string): string {
+  const m = line.match(/^\S+/u);
+  if (m === null) return '';
+  // `m[0]` is `string | undefined` per `noUncheckedIndexedAccess`, but a
+  // successful match always has `m[0]` defined (regex contract).
+  return m[0] as string;
+}
+
+/** Splits a comma-separated IRC parameter list. */
+function splitCsv(param: string): string[] {
+  if (param.length === 0) return [];
+  return param.split(',').filter((p) => p.length > 0);
+}
+
+/**
+ * Extracts the channel names a reducer will read for the supplied command.
+ * Used by `prefetchChannelState` to refresh only the channels the upcoming
+ * route will touch. Returns the bare names as they appear in the message
+ * (no lowercasing — `refreshChannel` will lowercase on its own).
+ *
+ * Commands not listed here either have no channel target (PING, NICK, …)
+ * or read channel membership from `ctx.connection.joinedChannels` directly
+ * (QUIT), so they don't need a prefetch.
+ */
+function channelTargetsForMessage(msg: IrcMessage): ChanName[] {
+  const cmd = msg.command;
+  switch (cmd) {
+    case 'JOIN':
+      // `JOIN 0` parts every joined channel; the reducer reads
+      // joinedChannels off the connection directly, no prefetch needed.
+      if (msg.params[0] === '0') return [];
+      return splitCsv(msg.params[0] ?? '').filter(isChannelTarget) as ChanName[];
+    case 'PART':
+    case 'TOPIC':
+    case 'NAMES':
+    case 'KICK':
+    case 'MODE':
+    case 'PRIVMSG':
+    case 'NOTICE':
+      return splitCsv(msg.params[0] ?? '').filter(isChannelTarget) as ChanName[];
+    case 'INVITE':
+      // INVITE <nick> <channel> — the channel is the second param.
+      return splitCsv(msg.params[1] ?? '').filter(isChannelTarget) as ChanName[];
+    default:
+      return [];
+  }
+}

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

@@ -0,0 +1,120 @@
+/**
+ * Effect dispatcher.
+ *
+ * `dispatch(effects, runtime)` interprets each {@link Effect} against the
+ * bound {@link IrcRuntime} port. The pure core emits the effect list; only
+ * this function awaits. Invariants:
+ *
+ *   - Effects are processed in array order (the test named "ordering").
+ *   - Consecutive identical Send effects coalesce into one runtime call
+ *     (the test named "dedup").
+ *   - The first runtime rejection propagates and stops processing.
+ */
+
+import type { BroadcastEffect, Effect, RawLine } from '@serverless-ircd/irc-core';
+import type { IrcRuntime } from './runtime.js';
+
+/** Discriminated-union handler: each Effect tag maps to one runtime call. */
+type Handler<E extends Effect> = (effect: E, runtime: IrcRuntime) => Promise<void>;
+
+const handlers: { [K in Effect['tag']]: Handler<Extract<Effect, { tag: K }>> } = {
+  Send: (e, r) => r.send(e.to, e.lines),
+  Broadcast: (e, r) => broadcast(e, r),
+  Disconnect: (e, r) => r.disconnect(e.conn, e.reason),
+  SendToNick: (e, r) => r.sendToNick(e.nick, e.sender, e.lines, e.notFoundLines),
+  ReserveNick: (e, r) => r.reserveNick(e.nick, e.conn).then(noop),
+  ChangeNick: (e, r) => r.changeNick(e.conn, e.oldNick, e.newNick).then(noop),
+  ReleaseNick: (e, r) => r.releaseNick(e.nick),
+  ApplyChannelDelta: (e, r) => r.applyChannelDelta(e.chan, e.delta),
+  LookupNick: (e, r) => r.lookupNick(e.nick).then(noop),
+  GetConnectionInfo: (e, r) => r.getConnectionInfo(e.conn).then(noop),
+  GetChannelSnapshot: (e, r) => r.getChannelSnapshot(e.chan).then(noop),
+};
+
+function noop(): void {}
+
+/**
+ * Returns true iff two effects are interchangeable — used to coalesce
+ * consecutive duplicates so a reducer's accidental double-send is a no-op.
+ *
+ * Only `Send` is deduped today: it's the only effect where exact-equality
+ * coalescing is always safe (same bytes to the same target). Broadcasts
+ * carry `except?` and channel-delta semantics that make blind coalescing
+ * risky; we leave them alone.
+ */
+function isSameSend(a: Effect, b: Effect): boolean {
+  if (a.tag !== 'Send' || b.tag !== 'Send') return false;
+  if (a.to !== b.to) return false;
+  return linesEqual(a.lines, b.lines);
+}
+
+function linesEqual(a: RawLine[], b: RawLine[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === undefined || y === undefined || x.text !== y.text) return false;
+  }
+  return true;
+}
+
+/**
+ * Interprets `effects` in order against `runtime`. Returns when every
+ * effect has been performed; the first rejection propagates.
+ */
+export async function dispatch(effects: Effect[], runtime: IrcRuntime): Promise<void> {
+  let previous: Effect | undefined;
+  for (const effect of effects) {
+    if (previous !== undefined && isSameSend(previous, effect)) {
+      previous = effect;
+      continue;
+    }
+    await handle(effect, runtime);
+    previous = effect;
+  }
+}
+
+async function handle(effect: Effect, runtime: IrcRuntime): Promise<void> {
+  // The dispatch table is keyed by tag; the cast is the standard TS pattern
+  // for exhaustive-union dispatch.
+  const handler = handlers[effect.tag] as Handler<Effect>;
+  await handler(effect, runtime);
+}
+
+/**
+ * Cap-aware Broadcast fanout.
+ *
+ * When `cap` is unset the reducer has no per-recipient preference, so we
+ * take the runtime's `broadcast` fast path. When `cap` is set dispatch
+ * routes per-recipient instead, consulting each member's advertised caps:
+ *
+ *   - `cap` + `capLines` (split mode): cap-enabled members receive
+ *     `capLines`, everyone else receives `lines`.
+ *   - `cap` without `capLines` (cap-only mode): `lines` go ONLY to
+ *     cap-enabled members; the rest receive nothing.
+ *
+ * `except` is always honored. A member whose connection info is unavailable
+ * (the connection has gone) is treated as lacking the cap.
+ */
+async function broadcast(e: BroadcastEffect, r: IrcRuntime): Promise<void> {
+  if (e.cap === undefined) {
+    await r.broadcast(e.chan, e.lines, e.except);
+    return;
+  }
+
+  const snapshot = await r.getChannelSnapshot(e.chan);
+  if (snapshot === null) return;
+
+  for (const connId of snapshot.members.keys()) {
+    if (connId === e.except) continue;
+
+    const info = await r.getConnectionInfo(connId);
+    const hasCap = info?.caps.has(e.cap) ?? false;
+
+    if (e.capLines !== undefined) {
+      await r.send(connId, hasCap ? e.capLines : e.lines);
+    } else if (hasCap) {
+      await r.send(connId, e.lines);
+    }
+  }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * @serverless-ircd/irc-server
+ *
+ * Orchestration layer: defines the {@link IrcRuntime} port, the {@link dispatch}
+ * interpreter that runs an `Effect[]` against it, and the {@link ConnectionActor}
+ * that turns a WebSocket text frame into reducer invocations + dispatch.
+ */
+export type { IrcRuntime } from './runtime.js';
+export { dispatch } from './dispatch.js';
+export { ConnectionActor, splitFrameLines } from './actor.js';
+export type { ActorChannelAccess, ConnectionActorOptions } from './actor.js';

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

@@ -0,0 +1,61 @@
+/**
+ * The {@link IrcRuntime} port.
+ *
+ * Every adapter (in-memory, CF, AWS) implements this interface. The pure
+ * core's `Effect[]` is interpreted against it by {@link dispatch}.
+ *
+ * Method-for-method compatibility with the {@link Effect} union is enforced
+ * by `dispatch.ts`'s handler table.
+ */
+
+import type {
+  ChanName,
+  ChanSnapshot,
+  ChannelDelta,
+  ConnId,
+  ConnSnapshot,
+  ConnectionState,
+  Nick,
+  RawLine,
+} from '@serverless-ircd/irc-core';
+
+export interface IrcRuntime {
+  // transport
+  send(to: ConnId, lines: RawLine[]): Promise<void>;
+  broadcast(chan: ChanName, lines: RawLine[], except?: ConnId): Promise<void>;
+  disconnect(conn: ConnId, reason?: string): Promise<void>;
+  /**
+   * Routes `lines` to whichever connection currently owns `nick`. If the
+   * nick is offline and `notFoundLines` is supplied, those lines are sent
+   * to `sender` (PRIVMSG's `401`; NOTICE omits the fallback entirely).
+   */
+  sendToNick(
+    nick: Nick,
+    sender: ConnId,
+    lines: RawLine[],
+    notFoundLines?: RawLine[],
+  ): Promise<void>;
+
+  // nickname registry
+  reserveNick(nick: Nick, conn: ConnId): Promise<{ ok: true } | { ok: false }>;
+  changeNick(conn: ConnId, oldNick: Nick, newNick: Nick): Promise<boolean>;
+  releaseNick(nick: Nick): Promise<void>;
+
+  // channel ownership
+  applyChannelDelta(chan: ChanName, delta: ChannelDelta): Promise<void>;
+
+  // lookups (NAMES, WHOIS, routing)
+  lookupNick(nick: Nick): Promise<ConnId | null>;
+  getConnectionInfo(conn: ConnId): Promise<ConnSnapshot | null>;
+  /**
+   * Returns the live {@link ConnectionState} for `conn`, or `null` if the
+   * connection is unknown / offline. Used by reducers that need a peer's
+   * full state (e.g. WHOIS) — the returned object is the authority-owned
+   * reference for in-memory runtimes and a materialized view for
+   * distributed runtimes.
+   */
+  getConnection(conn: ConnId): Promise<ConnectionState | null>;
+  getChannelSnapshot(chan: ChanName): Promise<ChanSnapshot | null>;
+  getChannelConnections(chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>>;
+  listChannels(): Promise<ChanSnapshot[]>;
+}