serverless-ircd 0.3.0 → 0.5.0

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

@@ -14,8 +14,12 @@
  *   - nick registry: {@link ReserveNickEffect}, {@link ChangeNickEffect},
  *     {@link ReleaseNickEffect}
  *   - channel ownership: {@link ApplyChannelDeltaEffect}
- *   - lookups: {@link LookupNickEffect}, {@link GetConnectionInfoEffect},
- *     {@link GetChannelSnapshotEffect}
+ *
+ *   Lookup-shaped runtime methods (`lookupNick`, `getConnectionInfo`,
+ *   `getChannelSnapshot`) are consumed directly inside `dispatch`'s
+ *   broadcast helper and the actor — they are request/response and cannot
+ *   be modelled as pure fire-and-forget effects, so no Effect variants
+ *   wrap them.
  */
 
 import type { ChanName, ChannelDelta } from './state/channel.js';
@@ -71,21 +75,6 @@ export interface ApplyChannelDeltaEffect {
   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` —
@@ -100,6 +89,26 @@ export interface SendToNickEffect {
   notFoundLines?: RawLine[];
 }
 
+/**
+ * Global cross-connection fanout for `WALLOPS`. Unlike
+ * {@link BroadcastEffect} (channel-scoped via the roster), this reaches
+ * every live connection whose `+w` user mode is set, regardless of shared
+ * channel membership. `except` skips a single connection — by convention
+ * the originator, so an oper never receives their own wallops back
+ * (matching NOTICE/PRIVMSG channel-broadcast semantics).
+ *
+ * The reducer does not know which connections carry `+w`; the bound
+ * runtime's `broadcastWallops` method owns that enumeration. On the
+ * in-memory runtime that is a scan of its connection map; on CF it walks
+ * the registry shards; on AWS it scans the `Connections` table. Each
+ * adapter applies its own cost cap (documented at the method).
+ */
+export interface BroadcastWallopsEffect {
+  tag: 'BroadcastWallops';
+  lines: RawLine[];
+  except?: ConnId;
+}
+
 /** Discriminated union of every effect the dispatch interpreter knows. */
 export type Effect =
   | SendEffect
@@ -109,10 +118,8 @@ export type Effect =
   | ChangeNickEffect
   | ReleaseNickEffect
   | ApplyChannelDeltaEffect
-  | LookupNickEffect
-  | GetConnectionInfoEffect
-  | GetChannelSnapshotEffect
-  | SendToNickEffect;
+  | SendToNickEffect
+  | BroadcastWallopsEffect;
 
 /** Literal string tag of every {@link Effect} variant. */
 export type EffectTag = Effect['tag'];
@@ -167,18 +174,14 @@ export const Effect = {
   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;
   },
+  broadcastWallops(lines: RawLine[], except?: ConnId): Effect {
+    const e: BroadcastWallopsEffect = { tag: 'BroadcastWallops', lines };
+    if (except !== undefined) e.except = except;
+    return e;
+  },
 } as const;

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

@@ -10,9 +10,12 @@ export * from './caps/index.js';
 export * from './commands/index.js';
 export * from './effects.js';
 export * from './ports.js';
+export * from './credential-hashing.js';
 export * from './flood-control.js';
 export * from './cloak.js';
 export * from './case-fold.js';
+export * from './ws-subprotocol.js';
+export * from './ws-framing.js';
 export * from './admission.js';
 export * from './config.js';
 export type {

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

@@ -7,6 +7,8 @@
  */
 
 import { caseFold } from './case-fold.js';
+import type { ChannelState } from './state/channel.js';
+import type { ConnId, ConnectionState } from './state/connection.js';
 
 /** Read-only wall clock, epoch milliseconds. */
 export interface Clock {
@@ -57,7 +59,7 @@ export interface IdFactory {
 
 /**
  * Production id factory. Generates UUIDv4-shaped strings without relying
- * on `crypto` so the same code runs on Node 20, Cloudflare Workers, and
+ * on `crypto` so the same code runs on Node 24, Cloudflare Workers, and
  * Lambda without per-platform type wrangling. Uniqueness is statistical;
  * for cryptographic IDs, adapters can supply their own {@link IdFactory}.
  */
@@ -171,7 +173,8 @@ export const EmptyMotdProvider: MotdProvider = new StaticMotdProvider([]);
  */
 export type SaslPayload =
   | { kind: 'PLAIN'; username: string; password: string }
-  | { kind: 'RAW'; data: string };
+  | { kind: 'RAW'; data: string }
+  | { kind: 'EXTERNAL'; identity: string };
 
 /**
  * Outcome of an {@link AccountStore.verify} call: either the canonical
@@ -202,6 +205,12 @@ export interface AccountStore {
 export interface SaslAccountCredential {
   username: string;
   password: string;
+  /**
+   * Optional mTLS client-certificate subject (e.g. `CN=alice` or a
+   * fingerprint hash). When set, SASL `EXTERNAL` authentications that
+   * present this subject are mapped to {@link username} as the account.
+   */
+  certSubject?: string;
 }
 
 /**
@@ -221,23 +230,37 @@ export interface SaslAccountCredential {
  */
 export class InMemoryAccountStore implements AccountStore {
   private readonly creds: ReadonlyMap<string, string>;
+  private readonly certMap: ReadonlyMap<string, string>;
 
   constructor(credentials: ReadonlyArray<SaslAccountCredential>) {
     this.creds = new Map(credentials.map((c) => [c.username, c.password]));
+    this.certMap = new Map(
+      credentials
+        .filter((c) => c.certSubject !== undefined)
+        .map((c) => [c.certSubject as string, c.username]),
+    );
   }
 
   verify(mech: string, payload: SaslPayload): SaslResult {
-    if (mech.toUpperCase() !== 'PLAIN' || payload.kind !== 'PLAIN') {
-      return { ok: false, reason: `unsupported mechanism: ${mech}` };
-    }
-    const expected = this.creds.get(payload.username);
-    if (expected === undefined) {
-      return { ok: false, reason: 'invalid credentials' };
+    const m = mech.toUpperCase();
+    if (m === 'PLAIN' && payload.kind === 'PLAIN') {
+      const expected = this.creds.get(payload.username);
+      if (expected === undefined) {
+        return { ok: false, reason: 'invalid credentials' };
+      }
+      if (!constantTimeEquals(payload.password, expected)) {
+        return { ok: false, reason: 'invalid credentials' };
+      }
+      return { ok: true, account: payload.username };
     }
-    if (!constantTimeEquals(payload.password, expected)) {
-      return { ok: false, reason: 'invalid credentials' };
+    if (m === 'EXTERNAL' && payload.kind === 'EXTERNAL') {
+      const account = this.certMap.get(payload.identity);
+      if (account === undefined) {
+        return { ok: false, reason: 'untrusted certificate' };
+      }
+      return { ok: true, account };
     }
-    return { ok: true, account: payload.username };
+    return { ok: false, reason: `unsupported mechanism: ${mech}` };
   }
 }
 
@@ -256,6 +279,52 @@ function constantTimeEquals(a: string, b: string): boolean {
   return diff === 0;
 }
 
+// ============================================================================
+// mTLS identity (SASL EXTERNAL)
+// ============================================================================
+
+/**
+ * Port that resolves the verified client-certificate identity for a
+ * connection.
+ *
+ * At the edge (CF API Shield mTLS, AWS API Gateway custom-domain mTLS) the
+ * platform terminates TLS, validates the client certificate against the
+ * configured trust store, and surfaces the certificate subject to the
+ * Worker/Lambda. The adapter captures this at connection-admission time
+ * and stores it keyed by connection ID.
+ *
+ * The method is **synchronous** — adapters pre-populate the identity at
+ * admission time (before the first reducer runs), so the SASL EXTERNAL
+ * reducer can look it up without awaiting. When no client certificate was
+ * presented (or mTLS is not configured), `getIdentity` returns `undefined`
+ * and EXTERNAL authentication fails with `904`.
+ */
+export interface MtlsIdentityProvider {
+  /**
+   * @returns the verified client-cert subject for `connId`, or `undefined`
+   *   when no trusted certificate was presented.
+   */
+  getIdentity(connId: string): string | undefined;
+}
+
+/**
+ * Reference in-memory {@link MtlsIdentityProvider} backed by a static map
+ * of connection IDs to certificate subjects. Useful for tests and the
+ * local-cli adapter; cloud adapters replace this with a lookup keyed by
+ * the platform's connection identifier.
+ */
+export class InMemoryMtlsIdentityProvider implements MtlsIdentityProvider {
+  private readonly identities: ReadonlyMap<string, string>;
+
+  constructor(entries: ReadonlyArray<{ connId: string; identity: string }>) {
+    this.identities = new Map(entries.map((e) => [e.connId, e.identity]));
+  }
+
+  getIdentity(connId: string): string | undefined {
+    return this.identities.get(connId);
+  }
+}
+
 // ============================================================================
 // Chat-history persistence (IRCv3 draft/chathistory)
 // ============================================================================
@@ -501,6 +570,285 @@ function tail<T>(arr: readonly T[], n: number): T[] {
   return arr.slice(start);
 }
 
+// ============================================================================
+// Nick history (WHOWAS)
+// ============================================================================
+
+/**
+ * One persisted sign-off record for a nick, written by the QUIT and
+ * post-registration NICK-change reducers and replayed by `WHOWAS`.
+ *
+ * `nick` preserves the original case the client used; `connId` is the
+ * connection that owned the nick at sign-off. `username` / `hostname` /
+ * `realname` mirror the {@link ConnectionState} fields at sign-off time
+ * (optional because a never-fully-registered connection may still quit with
+ * a nick). `signoffTime` is epoch milliseconds from the injected
+ * {@link Clock}.
+ */
+export interface NickHistoryEntry {
+  nick: string;
+  connId: string;
+  username?: string;
+  hostname?: string;
+  realname?: string;
+  signoffTime: number;
+}
+
+/**
+ * Persistence port for the IRC `WHOWAS` command.
+ *
+ * Mirrors the {@link MessageStore} pattern: the port is **synchronous**
+ * (reducers must stay pure and free of IO) and injected via {@link Ctx}.
+ * Adapters that need async storage (D1, DynamoDB) pre-load the relevant
+ * slice into a synchronously-readable store; Phase 8 ships the in-memory
+ * reference implementation only.
+ *
+ * `query` always returns matches most-recent-first (the order `WHOWAS`
+ * emits `314 RPL_WHOWASUSER` lines in), capped at `count`.
+ */
+export interface NickHistoryStore {
+  /** Records a sign-off entry for a nick (TTL eviction is impl-defined). */
+  record(entry: NickHistoryEntry): void;
+  /** Returns up to `count` most-recent entries for `nick` (case-insensitive). */
+  query(nick: string, count: number): NickHistoryEntry[];
+}
+
+/** Default retention window for nick-history entries: 24 hours. */
+const DEFAULT_NICK_HISTORY_MAX_AGE = 24 * 60 * 60 * 1000;
+
+/**
+ * Reference in-memory {@link NickHistoryStore} backed by a per-nick
+ * chronological array with a configurable TTL.
+ *
+ * Used by the local CLI and by tests. Each nick keeps its sign-off records
+ * in arrival order; entries older than `maxAge` (measured against the
+ * injected {@link Clock}) are dropped lazily on `record` and `query` so the
+ * per-nick buffers do not grow unbounded.
+ *
+ * Nicks are keyed via {@link caseFold} (`rfc1459`) so lookups are
+ * case-insensitive, matching the IRC nick-comparison semantics advertised
+ * via `005 RPL_ISUPPORT CASEMAPPING=rfc1459`.
+ */
+export class InMemoryNickHistoryStore implements NickHistoryStore {
+  private readonly byNick = new Map<string, NickHistoryEntry[]>();
+  private readonly clock: Clock;
+  private readonly maxAge: number;
+
+  constructor(clock: Clock, opts?: { maxAge?: number }) {
+    this.clock = clock;
+    this.maxAge = opts?.maxAge ?? DEFAULT_NICK_HISTORY_MAX_AGE;
+  }
+
+  record(entry: NickHistoryEntry): void {
+    const key = caseFold('rfc1459', entry.nick);
+    let arr = this.byNick.get(key);
+    if (arr === undefined) {
+      arr = [];
+      this.byNick.set(key, arr);
+    }
+    this.purgeExpired(arr);
+    arr.push(entry);
+  }
+
+  query(nick: string, count: number): NickHistoryEntry[] {
+    if (count <= 0) return [];
+    const arr = this.byNick.get(caseFold('rfc1459', nick));
+    if (arr === undefined) return [];
+    this.purgeExpired(arr);
+    if (arr.length === 0) return [];
+    return arr.slice(Math.max(0, arr.length - count)).reverse();
+  }
+
+  /**
+   * Drops entries whose `signoffTime` is older than `now - maxAge`, in place.
+   * Entries arrive in chronological order (append-only), so the first alive
+   * entry marks the boundary; everything before it is expired.
+   */
+  private purgeExpired(arr: NickHistoryEntry[]): void {
+    const cutoff = this.clock.now() - this.maxAge;
+    let firstAlive = arr.findIndex((e) => e.signoffTime >= cutoff);
+    if (firstAlive === -1) firstAlive = arr.length;
+    arr.splice(0, firstAlive);
+  }
+}
+
+// ============================================================================
+// Network statistics (LUSERS / STATS)
+// ============================================================================
+
+/**
+ * Snapshot of network-wide counts returned by a {@link ServerStats} backend.
+ *
+ * The shape mirrors the fields the `LUSERS` and `STATS` reducers need to
+ * format their numerics:
+ *   - `users` / `invisible`: the split registered-user counts that drive
+ *     `251 RPL_LUSERCLIENT` ("There are X users and Y invisible on Z
+ *     servers"). `users` is the *visible* (non-`+i`) registered count;
+ *     `invisible` is the `+i` registered count. Total registered users
+ *     is `users + invisible`.
+ *   - `opers`: count of IRC operators; emitted as `252 RPL_LUSEROP` when
+ *     non-zero. An oper counts here regardless of `+i` (an `+o` oper who
+ *     is also `+i` still bumps `opers`, `invisible`, and `users` is
+ *     computed as visible = total-registered − invisible).
+ *   - `unknownConnections`: pre-registration connection count; emitted as
+ *     `253 RPL_LUSERUNKNOWN` when non-zero.
+ *   - `channels`: live channel count; emitted as `254 RPL_LUSERCHANNELS`
+ *     when non-zero.
+ *   - `servers`: server count seen by `251`/`255`. Always 1 for the
+ *     single-server serverless deployment; S2S aggregation is a PLAN
+ *     non-goal.
+ *   - `localConns` / `globalConns`: total connection counts (registered
+ *     + pre-registration) for the optional `265 RPL_LOCALUSERS` /
+ *     `266 RPL_GLOBALUSERS` numerics. Equal for a single-server network.
+ *   - `maxLocalConns` / `maxGlobalConns`: high-water marks accompanying
+ *     `265`/`266`. When the backend has no recorded max it reports the
+ *     current count (so the wire numeric never claims a max below live).
+ *   - `uptimeStartedAt`: epoch-ms the server (or stats backend) started
+ *     counting from. Drives the `STATS u` uptime line.
+ */
+export interface ServerStatsSnapshot {
+  users: number;
+  invisible: number;
+  opers: number;
+  unknownConnections: number;
+  channels: number;
+  servers: number;
+  localConns: number;
+  globalConns: number;
+  maxLocalConns: number;
+  maxGlobalConns: number;
+  uptimeStartedAt: number;
+}
+
+/**
+ * Port that aggregates network-wide statistics for `LUSERS` and `STATS`.
+ *
+ * Unlike the synchronous {@link MotdProvider} / {@link AccountStore} ports
+ * (which reducers consume directly via {@link Ctx}), this port is
+ * **asynchronous** (`Promise`-returning) because the aggregation crosses
+ * every connection and channel in the deployment — it cannot be pre-loaded
+ * into a synchronous view the way MOTD or a credential table can. The
+ * actor layer awaits {@link getStats} once per `LUSERS` / `STATS`
+ * invocation, then passes the resulting {@link ServerStatsSnapshot} to the
+ * pure reducers (`lusersReducer`, `statsReducer`). This mirrors the
+ * `listChannels` → `listReducer` pattern.
+ *
+ * Each adapter implements this against its authoritative store:
+ *   - in-memory runtime: derive from its `Map`s (reference impl
+ *     {@link InMemoryStats}).
+ *   - CF: aggregate via `listChannels` / connection-enumeration RPCs.
+ *   - AWS: `Scan` / `Count` queries against `Connections` / `ChannelMeta`.
+ */
+export interface ServerStats {
+  getStats(): Promise<ServerStatsSnapshot>;
+}
+
+/**
+ * Aggregates a snapshot from already-collected connection state and a
+ * channel count.
+ *
+ * Pure: backends that gather their data through async I/O (CF RPC fan-out,
+ * AWS DynamoDB `Scan`) call this once they have the raw inputs. The
+ * {@link InMemoryStats} reference backend delegates here so the
+ * classification logic (oper / invisible / unknown) lives in exactly one
+ * place and is unit-tested independently of any adapter's I/O.
+ *
+ * Counting rules (RFC 2812 §4.6.2 + modern practice):
+ *   - `users` is the **visible** registered count (total registered minus
+ *     `+i`); the first number in "There are X users and Y invisible".
+ *   - `invisible` is the `+i` registered count; the second number.
+ *   - An oper who is also `+i` increments `opers`, `invisible`, and
+ *     reduces `users` (because they are invisible) — matching charybdis.
+ *   - `localConns` is every tracked connection (registered + unknown).
+ */
+export function computeStatsSnapshot(
+  connections: Iterable<ConnectionState>,
+  channelCount: number,
+  uptimeStartedAt: number,
+  opts?: { maxLocalConns?: number; maxGlobalConns?: number; servers?: number },
+): ServerStatsSnapshot {
+  let registered = 0;
+  let invisible = 0;
+  let opers = 0;
+  let unknown = 0;
+  let total = 0;
+  for (const conn of connections) {
+    total++;
+    if (conn.registration !== 'registered') {
+      unknown++;
+      continue;
+    }
+    registered++;
+    if (conn.userModes.invisible) invisible++;
+    if (conn.userModes.oper) opers++;
+  }
+  return {
+    users: registered - invisible,
+    invisible,
+    opers,
+    unknownConnections: unknown,
+    channels: channelCount,
+    servers: opts?.servers ?? 1,
+    localConns: total,
+    globalConns: total,
+    // The wire numeric must never claim a max below the current live count;
+    // when the backend's recorded max is stale (or never seeded) the live
+    // count is the lower bound.
+    maxLocalConns: Math.max(opts?.maxLocalConns ?? 0, total),
+    maxGlobalConns: Math.max(opts?.maxGlobalConns ?? 0, total),
+    uptimeStartedAt,
+  };
+}
+
+/**
+ * Reference in-memory {@link ServerStats} backed by the live `Map`s the
+ * {@link InMemoryRuntime} (and tests) already maintain.
+ *
+ * The constructor takes *references* to the runtime's mutable maps; later
+ * mutations are visible on the next {@link getStats} call without
+ * re-binding. Used by the local CLI, by integration tests, and as the
+ * contract spec the CF / AWS backends mirror.
+ *
+ * `uptimeStartedAt` is supplied at construction (typically the runtime's
+ * boot time). `maxLocalConns` / `maxGlobalConns` are optional high-water
+ * marks; when omitted the live count is reported as the max so `265`/`266`
+ * never regress below the current connection total.
+ */
+export class InMemoryStats implements ServerStats {
+  private readonly connections: ReadonlyMap<ConnId, ConnectionState>;
+  private readonly channels: ReadonlyMap<string, ChannelState>;
+  private readonly uptimeStartedAt: number;
+  private readonly maxLocalConns: number | undefined;
+  private readonly maxGlobalConns: number | undefined;
+
+  constructor(opts: {
+    connections: ReadonlyMap<ConnId, ConnectionState>;
+    channels: ReadonlyMap<string, ChannelState>;
+    uptimeStartedAt: number;
+    clock?: Clock;
+    maxLocalConns?: number;
+    maxGlobalConns?: number;
+  }) {
+    this.connections = opts.connections;
+    this.channels = opts.channels;
+    this.uptimeStartedAt = opts.uptimeStartedAt;
+    this.maxLocalConns = opts.maxLocalConns;
+    this.maxGlobalConns = opts.maxGlobalConns;
+  }
+
+  async getStats(): Promise<ServerStatsSnapshot> {
+    return computeStatsSnapshot(
+      this.connections.values(),
+      this.channels.size,
+      this.uptimeStartedAt,
+      {
+        ...(this.maxLocalConns !== undefined ? { maxLocalConns: this.maxLocalConns } : {}),
+        ...(this.maxGlobalConns !== undefined ? { maxGlobalConns: this.maxGlobalConns } : {}),
+      },
+    );
+  }
+}
+
 // ============================================================================
 // Observability — structured logger
 // ============================================================================
@@ -854,7 +1202,7 @@ export class ConsoleLogger implements Logger {
 
 /** Returns the global `console` as a {@link ConsoleLoggerSinks}. */
 function globalThisConsoleSinks(): ConsoleLoggerSinks {
-  // `globalThis.console` is universal across Node 20, Workers, and Lambda.
+  // `globalThis.console` is universal across Node 24, Workers, and Lambda.
   // Reference it lazily so tests that stub the logger do not need to
   // replace the global.
   const c = (globalThis as { console?: GlobalConsole }).console;

package/packages/irc-core/src/protocol/numerics.ts

@@ -13,9 +13,39 @@ export const Numerics = {
   RPL_ISUPPORT: 5,
   RPL_BOUNCE: 10,
 
-  // Capability / stats admin
+  // Capability / stats admin / version
   RPL_ADMINME: 256,
 
+  // LUSERS (RFC 2812 §4.6.2). Network-wide user/channel/server counts.
+  // 251 is the human-readable summary; 252–254 are emitted only when their
+  // count is non-zero (per RFC). 255 is the local-server summary. 265/266
+  // carry the optional local/global max-connection context.
+  RPL_LUSERCLIENT: 251,
+  RPL_LUSEROP: 252,
+  RPL_LUSERUNKNOWN: 253,
+  RPL_LUSERCHANNELS: 254,
+  RPL_LUSERME: 255,
+  RPL_LOCALUSERS: 265,
+  RPL_GLOBALUSERS: 266,
+
+  // STATS (RFC 2812 §4.6.3 / §5.1). 211 is link-info (the `l` query),
+  // 242 is the uptime line (the `u` query), and 219 terminates every
+  // STATS reply regardless of query letter. The remaining RPL_STATS*
+  // codes (212–218, 240–248) are deferred behind per-letter tests.
+  RPL_STATSLINKINFO: 211,
+  RPL_ENDOFSTATS: 219,
+  RPL_STATSUPTIME: 242,
+
+  // TRACE (RFC 2812 §4.6.3). In a single-server deployment TRACE collapses
+  // to a local-server line (200/206) plus optional per-connection detail
+  // (204 oper / 205 user), terminated by 262. Multi-hop S2S tracing is a
+  // PLAN non-goal.
+  RPL_TRACELINK: 200,
+  RPL_TRACEOPERATOR: 204,
+  RPL_TRACEUSER: 205,
+  RPL_TRACESERVER: 206,
+  RPL_ENDOFTRACE: 262,
+
   // Away / userhost / ison
   RPL_AWAY: 301,
   RPL_USERHOST: 302,
@@ -23,7 +53,10 @@ export const Numerics = {
   RPL_UNAWAY: 305,
   RPL_NOWAWAY: 306,
 
-  // WHOIS
+  // Version
+  RPL_VERSION: 351,
+
+  // WHOIS / WHOWAS
   RPL_WHOISUSER: 311,
   RPL_WHOISSERVER: 312,
   RPL_WHOISOPERATOR: 313,
@@ -31,6 +64,7 @@ export const Numerics = {
   RPL_ENDOFWHOIS: 318,
   RPL_WHOISCHANNELS: 319,
   RPL_WHOISACCOUNT: 330,
+  RPL_WHOWASUSER: 314,
 
   // LIST
   RPL_LISTSTART: 321,
@@ -57,9 +91,8 @@ export const Numerics = {
   RPL_NAMREPLY: 353,
   RPL_ENDOFNAMES: 366,
 
-  // Links / ban / whowas
-  RPL_LINKS: 364,
-  RPL_ENDOFLINKS: 365,
+  // Ban / whowas. (The S2S `LINKS` verb and its `RPL_LINKS`/`RPL_ENDOFLINKS`
+  // numerics were dropped — S2S is a PLAN non-goal.)
   RPL_BANLIST: 367,
   RPL_ENDOFBANLIST: 368,
   RPL_ENDOFWHOWAS: 369,
@@ -71,10 +104,12 @@ export const Numerics = {
   RPL_MOTDSTART: 375,
   RPL_ENDOFMOTD: 376,
 
-  // Oper
+  // Oper. RPL_REHASHING is emitted by the oper-gated `REHASH` reducer when a
+  // config reload is requested (the actor re-invokes the adapter's loader).
+  // (The RFC 2812 `SERVICE` verb and its `RPL_YOURESERVICE` numeric were
+  // dropped — obsolete, never widely implemented.)
   RPL_YOUREOPER: 381,
   RPL_REHASHING: 382,
-  RPL_YOURESERVICE: 383,
   RPL_TIME: 391,
 
   // SASL (IRCv3 sasl-3.2)
@@ -96,7 +131,8 @@ export const Numerics = {
   ERR_TOOMANYCHANNELS: 405,
   ERR_WASNOSUCHNICK: 406,
   ERR_TOOMANYTARGETS: 407,
-  ERR_NOSUCHSERVICE: 408,
+  // `ERR_NOSUCHSERVICE` (408) was dropped with the obsolete RFC 2812 `SERVICE`
+  // verb.
   ERR_INVALIDCAPCMD: 410,
   ERR_NORECIPIENT: 411,
   ERR_NOTEXTTOSEND: 412,
@@ -115,8 +151,8 @@ export const Numerics = {
   ERR_NOTONCHANNEL: 442,
   ERR_USERONCHANNEL: 443,
   ERR_NOLOGIN: 444,
-  ERR_SUMMONDISABLED: 445,
-  ERR_USERSDISABLED: 446,
+  // `ERR_SUMMONDISABLED` (445) / `ERR_USERSDISABLED` (446) were dropped with
+  // the obsolete RFC 2812 `SUMMON`/`USERS` verbs.
   ERR_NOTREGISTERED: 451,
   ERR_NEEDMOREPARAMS: 461,
   ERR_ALREADYREGISTRED: 462,
@@ -134,7 +170,8 @@ export const Numerics = {
   ERR_BANLISTFULL: 478,
   ERR_NOPRIVILEGES: 481,
   ERR_CHANOPRIVSNEEDED: 482,
-  ERR_CANTKILLSERVER: 483,
+  // `ERR_CANTKILLSERVER` (483) was dropped with the S2S `SQUIT` verb — S2S is
+  // a PLAN non-goal.
   ERR_NOOPERHOST: 491,
   ERR_UMODEUNKNOWNFLAG: 501,
   ERR_USERSDONTMATCH: 502,