serverless-ircd 0.4.0 → 0.5.0

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

@@ -123,18 +123,18 @@ export class AdmissionStats {
     if (rec === undefined) return;
     this.records.delete(recordId);
 
-    const ipCount = this.perIpCount.get(rec.ip);
-    if (ipCount !== undefined) {
-      const next = ipCount - 1;
-      if (next <= 0) this.perIpCount.delete(rec.ip);
-      else this.perIpCount.set(rec.ip, next);
-    }
-    const userCount = this.perUserCount.get(rec.user);
-    if (userCount !== undefined) {
-      const next = userCount - 1;
-      if (next <= 0) this.perUserCount.delete(rec.user);
-      else this.perUserCount.set(rec.user, next);
-    }
+    // recordAdmission always sets both counters, so they are present for
+    // any id found in `records`. The decrement-and-delete-if-zero keeps
+    // the maps compact (no zero entries hanging around).
+    const ipCount = this.perIpCount.get(rec.ip) as number;
+    const ipNext = ipCount - 1;
+    if (ipNext <= 0) this.perIpCount.delete(rec.ip);
+    else this.perIpCount.set(rec.ip, ipNext);
+
+    const userCount = this.perUserCount.get(rec.user) as number;
+    const userNext = userCount - 1;
+    if (userNext <= 0) this.perUserCount.delete(rec.user);
+    else this.perUserCount.set(rec.user, userNext);
   }
 
   /**
@@ -147,9 +147,10 @@ export class AdmissionStats {
     if (times === undefined || times.length === 0) return 0;
     const cutoff = this.clock.now() - windowMs;
     let writeIdx = 0;
-    for (let i = 0; i < times.length; i++) {
-      const t = times[i];
-      if (t === undefined) continue;
+    // `times` is dense (only ever appended to via push, never spliced), so
+    // iterating values via for-of avoids the noUncheckedIndexedAccess trap
+    // while still allowing in-place compaction of stale entries.
+    for (const t of times) {
       if (t >= cutoff) {
         times[writeIdx++] = t;
       }

package/packages/irc-core/src/caps/capabilities.ts

@@ -3,7 +3,7 @@
  *
  * The CAP *negotiation reducer* ships separately; this module is the
  * pure-data table that advertises what caps this server supports. PLAN §3
- * lists the v1 cap set; later tickets implement each cap's behavior.
+ * lists the v1 cap set; later phases implement each cap's behavior.
  *
  * The table is exposed as a frozen, sorted list so the `CAP LS` response
  * (and any future `CAP NEW` push) serializes deterministically.

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

@@ -19,6 +19,8 @@ export { handleJoinZero, isValidChannelName, joinReducer } from './join.js';
 export { partReducer } from './part.js';
 export { motdReducer } from './motd.js';
 export { operReducer, matchOperCred } from './oper.js';
+export { rehashReducer, rehashLine, buildRehashTrailing } from './rehash.js';
+export type { RehashResult } from './rehash.js';
 export {
   isChannelTarget,
   noticeChannelReducer,
@@ -27,6 +29,8 @@ export {
   privmsgUserReducer,
 } from './privmsg.js';
 export { kickReducer } from './kick.js';
+export { killReducer, formatKillReason } from './kill.js';
+export { wallopsReducer, wallopsLine } from './wallops.js';
 export { topicReducer } from './topic.js';
 export { namesReducer } from './names.js';
 export { listReducer } from './list.js';
@@ -35,11 +39,15 @@ export { inviteReducer } from './invite.js';
 export { whoReducer } from './who.js';
 export { whoisReducer } from './whois.js';
 export { whowasReducer } from './whowas.js';
+export { traceReducer } from './trace.js';
+export { lusersReducer } from './lusers.js';
+export { statsReducer } from './stats.js';
 export { generateIsupport } from './isupport.js';
 export { capReducer } from './cap.js';
 export { emitChghost } from './chghost.js';
 export type { ChgHostInput } from './chghost.js';
 export { awayReducer } from './away.js';
+export { setnameReducer } from './setname.js';
 export { authenticateReducer } from './sasl.js';
 export {
   chathistoryReducer,

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

@@ -42,12 +42,10 @@ function callerHostmask(conn: ConnectionState): string {
 }
 
 /** Formats a numeric error/reply line addressed to the connection's nick. */
-function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+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}`);
+  const parts = [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`];
   return { text: parts.join(' ') };
 }
 

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

@@ -82,6 +82,10 @@ function buildTokens(cfg: ServerConfig): string[] {
  * batch. The caller appends the trailer separately.
  *
  * Each batch returns just the joined token string (no `005`, no trailer).
+ *
+ * Contract: `tokens` is non-empty. The only caller (`generateIsupport`)
+ * satisfies this — `buildTokens` always emits at least the network/casing
+ * tokens — so no defensive empty-input handling is needed here.
  */
 function packTokens(tokens: ReadonlyArray<string>, baseLen: number): string[] {
   const batches: string[] = [];
@@ -96,7 +100,7 @@ function packTokens(tokens: ReadonlyArray<string>, baseLen: number): string[] {
       current = candidate;
     }
   }
-  if (current !== '') batches.push(current);
+  batches.push(current);
   return batches;
 }
 
@@ -106,7 +110,7 @@ function packTokens(tokens: ReadonlyArray<string>, baseLen: number): string[] {
  * @param cfg          Server configuration (size limits, network name).
  * @param _connCaps    IRCv3 capabilities negotiated by the connection
  *                     (reserved for `BOT=` and similar v3 tokens; currently
- *                     unused — kept in the signature per the ticket spec).
+ *                     unused — kept in the signature for forward compatibility).
  * @param nick         Optional nick for the reply target; defaults to `*`.
  * @returns One or more {@link RawLine}s, each within the 510-byte ceiling.
  *          Only the final line carries the `:are supported by this server`

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

@@ -35,12 +35,10 @@ function isValidChannelName(name: string, maxLen: number): boolean {
  * nick (or `*` when unregistered). Optional `middle` is emitted before the
  * trailing `:`-prefixed text.
  */
-function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+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}`);
+  const parts = [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`];
   return { text: parts.join(' ') };
 }
 

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

@@ -0,0 +1,127 @@
+/**
+ * Pure reducer for the IRC `KILL` command (oper-gated force-disconnect).
+ *
+ * PLAN §2.1 location-of-authority: KILL runs against the *target*'s
+ * connection. The actor layer resolves `<nick>` to a live
+ * {@link ConnectionState} via the nick registry and passes it here. The
+ * reducer performs the oper gate, validates parameters, and emits a single
+ * {@link DisconnectEffect} for the target. The runtime's `disconnect`
+ * method is responsible for closing the target's transport and fanning the
+ * QUIT out to shared-channel peers — the reducer does not model that
+ * fanout itself.
+ *
+ * Wire format (RFC 2812 §4.6.1):
+ *   - `KILL <nickname> <comment>`
+ *   - The target receives an `ERROR` / `QUIT` carrying a reason formatted
+ *     as `Killed (<oper> (<comment>))`.
+ *   - `481 ERR_NOPRIVILEGES`: `:<server> 481 <nick> :Permission Denied - ...`
+ *   - `461 ERR_NEEDMOREPARAMS`:
+ *     `:<server> 461 <nick> KILL :Not enough parameters`
+ *   - `401 ERR_NOSUCHNICK`: `:<server> 401 <nick> <target> :No such nick/channel`
+ *
+ * Behaviour:
+ *   - Non-oper sender → `481` (checked before parameters so a non-oper
+ *     cannot probe which nicks are online).
+ *   - Missing `<nickname>` or `<comment>` → `461`.
+ *   - Unknown nick → `401`.
+ *   - Otherwise emit `Disconnect(targetConnId, "Killed (<oper> (<comment>))")`.
+ *   - An oper may `KILL` themselves (RFC-permitted); no special-casing.
+ *
+ * Platform asymmetry: the emitted `Disconnect` is interpreted by the bound
+ * runtime. On CF the `disconnect` RPC closes the target DO's socket
+ * immediately; on AWS a `$default` invocation cannot close a remote APIGW
+ * WebSocket, so QUIT fanout to peers fires but the target's live socket
+ * only closes on its next `$disconnect`/sweeper cycle. The reducer is
+ * identical across adapters — only the runtime's `disconnect` semantics
+ * differ.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `481 ERR_NOPRIVILEGES`. */
+const NOPRIVILEGES_TRAILING_TEXT = "Permission Denied - You're not an IRC operator";
+
+/** Fixed text emitted for `461 ERR_NEEDMOREPARAMS`. */
+const NEEDMOREPARAMS_TRAILING_TEXT = 'Not enough parameters';
+
+/** Fixed text emitted for `401 ERR_NOSUCHNICK`. */
+const NOSUCHNICK_TRAILING_TEXT = 'No such nick/channel';
+
+/**
+ * Formats the canonical kill reason, `Killed (<oper> (<comment>))`, that
+ * the target receives on its closing transport. `<oper>` is the killing
+ * oper's display nick; `<comment>` is the oper-supplied reason verbatim.
+ */
+export function formatKillReason(operNick: string, comment: string): string {
+  return `Killed (${operNick} (${comment}))`;
+}
+
+/**
+ * Handles `KILL <nick> <comment>`.
+ *
+ * `target` is the live {@link ConnectionState} the actor resolved for
+ * `<nick>`, or `undefined` when the nick is offline / unknown. The
+ * signature is bespoke (not {@link Reducer}) because the actor must
+ * resolve the target asynchronously — mirrors `whoisReducer`.
+ */
+export function killReducer(
+  target: ConnectionState | undefined,
+  msg: { command: string; params: readonly string[] },
+  ctx: Ctx,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  if (!ctx.connection.userModes.oper) {
+    return {
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOPRIVILEGES, NOPRIVILEGES_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
+  const targetNick = msg.params[0];
+  const comment = msg.params[1];
+
+  if (targetNick === undefined || comment === undefined) {
+    return {
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NEEDMOREPARAMS, NEEDMOREPARAMS_TRAILING_TEXT, 'KILL'),
+        ]),
+      ],
+    };
+  }
+
+  if (target === undefined) {
+    return {
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOSUCHNICK, NOSUCHNICK_TRAILING_TEXT, targetNick),
+        ]),
+      ],
+    };
+  }
+
+  const operNick = ctx.connection.nick ?? '*';
+  return { effects: [Effect.disconnect(target.id, formatKillReason(operNick, comment))] };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` line. The nick
+ * falls back to `*` when the connection has not yet registered one,
+ * matching the rest of the codebase's numeric formatting.
+ */
+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 !== undefined) parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}

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

@@ -11,7 +11,7 @@
  *   - `322 RPL_LIST`       — `:<server> 322 <nick> <chan> <#users> :<topic>`
  *   - `323 RPL_LISTEND`    — `:<server> 323 <nick> :End of /LIST`
  *
- * Visibility rules (ticket spec):
+ * Visibility rules:
  *   - Secret (`+s`) channels are hidden from non-members.
  *   - Membership is checked against `chan.members` using `ctx.connId`.
  *

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

@@ -0,0 +1,204 @@
+/**
+ * Pure reducer for the IRC `LUSERS` command (RFC 2812 §4.6.2).
+ *
+ * PLAN §2.1 location-of-authority: LUSERS is a read-only diagnostic that
+ * reports network-wide counts. The reducer takes an already-aggregated
+ * {@link ServerStatsSnapshot} (the actor layer awaits a {@link ServerStats}
+ * backend before calling here — same pattern as `listChannels` →
+ * `listReducer`). The reducer never mutates anything but the requester's
+ * `lastSeen`.
+ *
+ * Wire format (RFC 2812 §5.1):
+ *   - `LUSERS [<mask> [<server>]]`
+ *   - `251 RPL_LUSERCLIENT`:
+ *     `:<server> 251 <nick> :There are <users> users and <invisible>
+ *      invisible on <servers> servers`
+ *   - `252 RPL_LUSEROP`:
+ *     `:<server> 252 <nick> <count> :operator(s) online` (only when non-zero)
+ *   - `253 RPL_LUSERUNKNOWN`:
+ *     `:<server> 253 <nick> <count> :unknown connection(s)` (only when
+ *     non-zero)
+ *   - `254 RPL_LUSERCHANNELS`:
+ *     `:<server> 254 <nick> <count> :channel(s) formed` (only when non-zero)
+ *   - `255 RPL_LUSERME`:
+ *     `:<server> 255 <nick> :I have <localConns> clients and <servers>
+ *      servers`
+ *   - `265 RPL_LOCALUSERS`:
+ *     `:<server> 265 <nick> <cur> <max> :Current local users <cur>, max
+ *      <max>`
+ *   - `266 RPL_GLOBALUSERS`:
+ *     `:<server> 266 <nick> <cur> <max> :Current global users <cur>, max
+ *      <max>`
+ *   - `402 ERR_NOSUCHSERVER`:
+ *     `:<server> 402 <nick> <server> :No such server`
+ *
+ * Non-zero omission: 252/253/254 are suppressed when their count is zero
+ * (per RFC 2812). 251, 255, 265, and 266 are always emitted — modern
+ * clients rely on 265/266 for the user-list count and charybdis emits
+ * them unconditionally.
+ *
+ * Single-server deployment: `servers` is always 1 (PLAN §1 — S2S linking
+ * is a non-goal). `<mask>` is accepted for RFC compliance but not applied
+ * (the serverless deployment has one server, so a wildcard match is
+ * trivially true).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { ServerStatsSnapshot } from '../ports.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `402 ERR_NOSUCHSERVER`. */
+const NOSUCHSERVER_TRAILING_TEXT = 'No such server';
+
+/** Human-readable trailing templates per numeric. */
+const LUSERCLIENT_TEXT = (users: number, invisible: number, servers: number): string =>
+  `There are ${users} users and ${invisible} invisible on ${servers} servers`;
+const LUSEROP_TEXT = 'operator(s) online';
+const LUSERUNKNOWN_TEXT = 'unknown connection(s)';
+const LUSERCHANNELS_TEXT = 'channel(s) formed';
+const LUSERME_TEXT = (localConns: number, servers: number): string =>
+  `I have ${localConns} clients and ${servers} servers`;
+const LOCALUSERS_TEXT = (cur: number, max: number): string =>
+  `Current local users ${cur}, max ${max}`;
+const GLOBALUSERS_TEXT = (cur: number, max: number): string =>
+  `Current global users ${cur}, max ${max}`;
+
+/**
+ * Builds a `:<server> <code> <nick> :<trailing>` line. The middle field is
+ * empty for the summary numerics; the count-formatting helpers below carry
+ * a `<count>` middle for 252/253/254.
+ */
+function trailingLine(ctx: Ctx, code: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${nick} :${trailing}`,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> <count> :<trailing>` line for the
+ * count-carrying numerics (252/253/254).
+ */
+function countLine(ctx: Ctx, code: number, count: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${nick} ${count} :${trailing}`,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> <cur> <max> :<trailing>` line for
+ * 265/266.
+ */
+function usageLine(ctx: Ctx, code: number, cur: number, max: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${nick} ${cur} ${max} :${trailing}`,
+  };
+}
+
+/**
+ * Handles `LUSERS [<mask> [<server>]]`.
+ *
+ * @param snapshot      The aggregated network statistics (counts).
+ * @param _msg          The parsed `LUSERS` message. The optional `<mask>`
+ *   is accepted for RFC compliance but not applied — single-server
+ *   deployments collapse any wildcard match to the local server.
+ * @param ctx           The per-invocation context.
+ * @param serverTarget  When set, the actor determined `<server>` names a
+ *   non-local server; the reducer emits `402 ERR_NOSUCHSERVER` against this
+ *   name and nothing else.
+ */
+export function lusersReducer(
+  snapshot: ServerStatsSnapshot,
+  _msg: { command: string; params: readonly string[] },
+  ctx: Ctx,
+  serverTarget?: string,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (serverTarget !== undefined) {
+    const nick = ctx.connection.nick ?? '*';
+    const code = Numerics.ERR_NOSUCHSERVER.toString().padStart(3, '0');
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${code} ${nick} ${serverTarget} :${NOSUCHSERVER_TRAILING_TEXT}`,
+        },
+      ]),
+    );
+    return { effects };
+  }
+
+  // 251 always.
+  effects.push(
+    Effect.send(ctx.connId, [
+      trailingLine(
+        ctx,
+        Numerics.RPL_LUSERCLIENT,
+        LUSERCLIENT_TEXT(snapshot.users, snapshot.invisible, snapshot.servers),
+      ),
+    ]),
+  );
+
+  // 252/253/254 only when non-zero (RFC: omit zero-count summary lines).
+  if (snapshot.opers > 0) {
+    effects.push(
+      Effect.send(ctx.connId, [countLine(ctx, Numerics.RPL_LUSEROP, snapshot.opers, LUSEROP_TEXT)]),
+    );
+  }
+  if (snapshot.unknownConnections > 0) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        countLine(ctx, Numerics.RPL_LUSERUNKNOWN, snapshot.unknownConnections, LUSERUNKNOWN_TEXT),
+      ]),
+    );
+  }
+  if (snapshot.channels > 0) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        countLine(ctx, Numerics.RPL_LUSERCHANNELS, snapshot.channels, LUSERCHANNELS_TEXT),
+      ]),
+    );
+  }
+
+  // 255 always.
+  effects.push(
+    Effect.send(ctx.connId, [
+      trailingLine(ctx, Numerics.RPL_LUSERME, LUSERME_TEXT(snapshot.localConns, snapshot.servers)),
+    ]),
+  );
+
+  // 265/266 always (modern clients depend on them).
+  effects.push(
+    Effect.send(ctx.connId, [
+      usageLine(
+        ctx,
+        Numerics.RPL_LOCALUSERS,
+        snapshot.localConns,
+        snapshot.maxLocalConns,
+        LOCALUSERS_TEXT(snapshot.localConns, snapshot.maxLocalConns),
+      ),
+    ]),
+  );
+  effects.push(
+    Effect.send(ctx.connId, [
+      usageLine(
+        ctx,
+        Numerics.RPL_GLOBALUSERS,
+        snapshot.globalConns,
+        snapshot.maxGlobalConns,
+        GLOBALUSERS_TEXT(snapshot.globalConns, snapshot.maxGlobalConns),
+      ),
+    ]),
+  );
+
+  return { effects };
+}

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

@@ -191,14 +191,10 @@ export const channelModeReducer: Reducer<ChannelState> = (state, msg, ctx) => {
     // authority BEFORE the broadcast so distributed runtimes (CF
     // ChannelDO) have persisted the change before any peer's next
     // prefetch observes it. In the in-memory runtime the actor's
-    // `state` IS authoritative so this is redundant.
-    if (
-      (delta.modeChanges !== undefined && delta.modeChanges.length > 0) ||
-      (delta.banMaskChanges !== undefined && delta.banMaskChanges.length > 0) ||
-      (delta.memberships !== undefined && delta.memberships.length > 0)
-    ) {
-      effects.push(Effect.applyChannelDelta(state.name, delta));
-    }
+    // `state` IS authoritative so this is redundant. Every non-null
+    // `applyChannelOp` result is paired with at least one delta push,
+    // so `delta` is guaranteed non-empty here.
+    effects.push(Effect.applyChannelDelta(state.name, delta));
     const hostmask = callerHostmask(ctx.connection);
     effects.push(Effect.broadcast(state.name, [buildModeBroadcast(hostmask, state.name, applied)]));
   }

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

@@ -14,7 +14,7 @@
  * `@` (private `+p`). Private wins over secret when both are set, matching
  * the JOIN reducer's NAMES reply and RFC 2812 §3.2.4.
  *
- * Visibility rules (PLAN §3 + ticket spec):
+ * Visibility rules (PLAN §3):
  *   - `+s` or `+p` set: requester must be a member to receive the NAMES list.
  *     Otherwise `442 ERR_NOTONCHANNEL`.
  *   - Otherwise: any connection may list.
@@ -44,12 +44,10 @@ function isValidChannelName(name: string, maxLen: number): boolean {
 }
 
 /** Formats a numeric error/reply line addressed to the connection's nick. */
-function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+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}`);
+  const parts = [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`];
   return { text: parts.join(' ') };
 }
 

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

@@ -33,12 +33,10 @@ function isValidChannelName(name: string, maxLen: number): boolean {
  * nick (or `*` when unregistered). Optional `middle` is emitted before the
  * trailing `:`-prefixed text.
  */
-function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+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}`);
+  const parts = [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`];
   return { text: parts.join(' ') };
 }
 

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

@@ -0,0 +1,119 @@
+/**
+ * Pure reducer for the IRC `REHASH` command (oper-gated config reload).
+ *
+ * PLAN §2.1 location-of-authority: REHASH runs in the Connection entity. The
+ * reducer is pure — it only enforces the oper gate and emits the
+ * `382 RPL_REHASHING` reply. The actual config re-fetch is a request/response
+ * side effect (re-invoke the adapter's bound config loader and swap the live
+ * {@link ServerConfig} reference on the actor), so — exactly like
+ * `lookupNick` / `getConnection` — it is NOT modelled as a fire-and-forget
+ * `Effect`; the actor layer performs it and surfaces success/failure back to
+ * the oper via a second `382` line on failure.
+ *
+ * Wire format:
+ *   - `REHASH` (no params).
+ *   - `382 RPL_REHASHING`:
+ *     `:<server> 382 <nick> :Rehashing from <source>`
+ *   - `481 ERR_NOPRIVILEGES`:
+ *     `:<server> 481 <nick> :Permission Denied - You're not an IRC operator`
+ *
+ * Behaviour:
+ *   - Non-oper → `481 ERR_NOPRIVILEGES`; no reload is signalled.
+ *   - Oper → emits `382` noting the bound config source and signals
+ *     `shouldReload: true`. The actor re-invokes its loader and swaps the
+ *     live config; on failure the previous config stays in effect and a
+ *     graceful error-suffixed `382` follows (handled by the actor).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { IrcMessage } from '../protocol/messages.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `481 ERR_NOPRIVILEGES` (matches `mode.ts`). */
+const NOPRIVILEGES_TRAILING_TEXT = "Permission Denied - You're not an IRC operator";
+
+/**
+ * Result of {@link rehashReducer}. Adds a `shouldReload` intent flag on top of
+ * the standard reducer shape so the actor layer knows whether to perform the
+ * async config re-fetch (oper gate passed) without re-deriving the gate.
+ */
+export interface RehashResult {
+  state: ConnectionState;
+  effects: EffectType[];
+  shouldReload: boolean;
+}
+
+/**
+ * Composes the trailing text for the `382 RPL_REHASHING` line. The success
+ * form notes the bound config source; the failure form (used by the actor on
+ * reload rejection) appends the error so the oper sees what went wrong
+ * without being disconnected.
+ */
+export function buildRehashTrailing(configSource: string, error?: string): string {
+  const base = `Rehashing from ${configSource}`;
+  return error === undefined ? base : `${base} failed: ${error}`;
+}
+
+/**
+ * Renders the full `:<server> 382 <nick> :<trailing>` wire line. Shared by
+ * the reducer (optimistic success line) and the actor (error-suffixed line
+ * on reload failure) so the two paths cannot drift in formatting.
+ */
+export function rehashLine(
+  serverName: string,
+  nick: string,
+  configSource: string,
+  error?: string,
+): RawLine {
+  const code = Numerics.RPL_REHASHING.toString().padStart(3, '0');
+  return { text: `:${serverName} ${code} ${nick} :${buildRehashTrailing(configSource, error)}` };
+}
+
+/**
+ * Handles `REHASH`.
+ *
+ * Enforces the oper gate, stamps `lastSeen`, and — for an oper — emits the
+ * `382 RPL_REHASHING` reply and signals the actor to perform the reload via
+ * `shouldReload`. The reducer never performs IO.
+ */
+export function rehashReducer(
+  state: ConnectionState,
+  _msg: IrcMessage,
+  ctx: Ctx,
+  configSource: string,
+): RehashResult {
+  state.lastSeen = ctx.clock.now();
+
+  if (!state.userModes.oper) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOPRIVILEGES, NOPRIVILEGES_TRAILING_TEXT),
+        ]),
+      ],
+      shouldReload: false,
+    };
+  }
+
+  const nick = ctx.connection.nick ?? '*';
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [rehashLine(ctx.serverName, nick, configSource)])],
+    shouldReload: true,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> :<trailing>` line. The nick falls back to
+ * `*` for an unregistered connection, matching the rest of the codebase's
+ * numeric formatting.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: [`:${ctx.serverName}`, codeStr, nick, `:${trailing}`].join(' ') };
+}