serverless-ircd 0.3.0 → 0.5.0

package/packages/cf-adapter/src/connection-do.ts

@@ -6,8 +6,8 @@
  * `HibernatingWebSocketHandler` so idle WebSocket connections cost
  * nothing between messages. When a message arrives the DO wakes, replays
  * the persisted {@link ConnectionState} from `state.storage`, runs the
- * frame through {@link ConnectionActor} with a stub {@link CfRuntime},
- * and persists the updated state back.
+ * frame through {@link ConnectionActor} with the {@link CfRuntime}, and
+ * persists the updated state back.
  *
  * Lifecycle:
  *   - `fetch()`                       WebSocket upgrade; `acceptWebSocket`.
@@ -16,15 +16,15 @@
  *   - `alarm()`                       PING sweep; missing PONG disconnects.
  *
  * Cross-DO coordination:
- *   - `REGISTRY_DO` (RPC stub today, real in 034).
- *   - `CHANNEL_DO` per lowercased channel (stub today, real in 035).
+ *   - `REGISTRY_DO` — sharded nick registry.
+ *   - `CHANNEL_DO` per lowercased channel — authoritative roster/modes.
  *
  * The actor's `ActorChannelAccess` is a passthrough that returns
  * throwaway {@link ChannelState} objects — reducers mutate the local
  * view and emit `ApplyChannelDelta` effects that the CfRuntime forwards
- * to the authoritative ChannelDO. Sufficient for connection-authority
- * commands and JOIN/QUIT fan-out; richer channel reads (NAMES of remote
- * state) ship in 036.
+ * to the authoritative ChannelDO. Connection-authority commands and
+ * JOIN/QUIT fan-out are fully wired; richer channel reads (NAMES of
+ * remote state) are served via the ChannelDO snapshot RPC.
  */
 
 import { DurableObject } from 'cloudflare:workers';
@@ -37,46 +37,54 @@ import {
   type ConnectionState,
   ConsoleLogger,
   type IdFactory,
-  InMemoryAccountStore,
   InMemoryMessageStore,
+  InMemoryMtlsIdentityProvider,
+  InMemoryNickHistoryStore,
   LogLevel,
   type Logger,
   type MessageStore,
   type MotdProvider,
+  type MtlsIdentityProvider,
+  type NickHistoryStore,
   type RawLine,
   type SaslAccountCredential,
   type ServerConfig,
   SystemClock,
   UuidIdFactory,
-  applyChannelDelta,
+  type WsFrameMode,
   createChannel,
   createConnection,
+  frameToLines,
+  isWithinWsByteBudget,
+  parseSecWsProtocolOffers,
+  sanitizeForTextMode,
+  selectSubprotocol,
   toSnapshot,
+  wsFrameModeFor,
 } from '@serverless-ircd/irc-core';
-import { ConnectionActor } from '@serverless-ircd/irc-server';
+import { ConnectionActor, type Transport } from '@serverless-ircd/irc-server';
 import { makeCfRuntime } from './cf-runtime.js';
 import type { CfConnectionHandlers } from './cf-runtime.js';
+import { loadServerConfigFromCfEnv } from './config-loader.js';
+import { resolveAccountStore } from './d1-account-store.js';
 import type { Env } from './env.js';
-import { PERSISTED_STATE_VERSION, STATE_STORAGE_KEY, deserialize, serialize } from './serialize.js';
+import { STATE_STORAGE_KEY, deserialize, serialize } from './serialize.js';
 import type { PersistedConnectionState } from './serialize.js';
+import { CfStats } from './stats.js';
 
 /** Default PING cadence (ms) — tuned for typical IRC client behavior. */
 export const DEFAULT_PING_INTERVAL_MS = 60_000;
 /** Default no-PONG disconnect threshold (ms). */
 export const DEFAULT_PONG_TIMEOUT_MS = 90_000;
 
-/** Server config defaults; production deployments override via env. */
-const DEFAULT_SERVER_CONFIG: ServerConfig = {
-  serverName: 'irc.example.com',
-  networkName: 'ServerlessIRCd',
-  maxChannelsPerUser: 30,
-  maxTargetsPerCommand: 10,
-  maxListEntries: 50,
-  nickLen: 30,
-  channelLen: 50,
-  topicLen: 390,
-  quitMessage: 'Client Quit',
-};
+/**
+ * Wall-clock timestamp captured at this worker isolate's first module load
+ * (cold start). Used as the `uptimeStartedAt` anchor for {@link CfStats} so
+ * `STATS u` reports uptime for the current isolate. A dedicated stats DO
+ * would supply a deployment-wide uptime (future work); for now each
+ * isolate reports its own.
+ */
+const WORKER_STARTUP_AT = Date.now();
 
 /**
  * ConnectionDO instance.
@@ -87,6 +95,13 @@ const DEFAULT_SERVER_CONFIG: ServerConfig = {
 export class ConnectionDO extends DurableObject<Env> {
   /** Cached connection state; reloaded from storage after hibernation. */
   private cached: ConnectionState | undefined;
+  /**
+   * Cached reducer-facing server config. Parsed once from `this.env`
+   * (bindings are stable for the DO's lifetime) so the schema-validated
+   * `loadServerConfigFromCfEnv` runs a single time rather than on every
+   * WebSocket frame.
+   */
+  private cachedServerConfig: ServerConfig | undefined;
   /**
    * Per-instance channel-state cache. Reused across every WebSocket frame
    * the connection handles (within a single hibernation cycle) so that
@@ -109,18 +124,54 @@ export class ConnectionDO extends DurableObject<Env> {
    */
   private messages: MessageStore | undefined;
   /**
-   * In-worker SASL account store seeded from the `SASL_ACCOUNTS` env var.
-   * Lazily constructed so the first frame that needs it parses the env once.
-   * A Durable-Object / D1-backed persistent variant is a documented
-   * follow-up; swapping it in means replacing {@link accountStore}.
+   * Per-connection nick-history store backing `WHOWAS`. The minimum-viable
+   * in-worker ring buffer is scoped to this connection: sign-offs this
+   * connection records are queryable by the same connection. A
+   * Durable-Object-backed persistent variant (shared across connections,
+   * keyed by nick) is a documented follow-up. Lazily constructed.
+   */
+  private history: NickHistoryStore | undefined;
+  /**
+   * SASL account store, resolved once via {@link loadAccountStore} before the
+   * first frame dispatches. The two-phase load mirrors AWS's
+   * `loadDynamoAccountStore`: D1 `accounts` table (authoritative when it has
+   * rows) is queried at boot; when empty/unreachable the `SASL_ACCOUNTS`
+   * env-var seed provides the fallback `InMemoryAccountStore`. The
+   * `AccountStore.verify` port is synchronous, so pre-loading MUST complete
+   * before the first reducer runs.
    */
   private accounts: AccountStore | undefined;
+  /** Guards {@link loadAccountStore} so the D1 query runs at most once. */
+  private accountsResolved = false;
+  /**
+   * Verified client-cert subject captured at WebSocket upgrade time when
+   * CF API Shield mTLS is configured. Surfaced to the SASL EXTERNAL reducer
+   * via an {@link MtlsIdentityProvider} so `AUTHENTICATE EXTERNAL` can map
+   * the cert subject to an account.
+   *
+   * CF API Shield mTLS setup:
+   * 1. Upload the client CA to API Shield (dashboard → Security → API Shield).
+   * 2. Create an mTLS policy on the custom hostname that requires client certs.
+   * 3. The verified subject is injected into `request.cf.tlsClientAuthCertSubject`
+   *    on every request, which the Worker reads at upgrade time.
+   * When unset (no mTLS configured), EXTERNAL auth fails with `904`.
+   */
+  private mtlsCertSubject: string | undefined;
   private readonly clock: Clock = SystemClock;
   private readonly ids: IdFactory = new UuidIdFactory();
   private readonly pingIntervalMs: number = DEFAULT_PING_INTERVAL_MS;
   private readonly pongTimeoutMs: number = DEFAULT_PONG_TIMEOUT_MS;
-  /** Outstanding outbound lines, drained when the WS sends complete. */
-  // (Reserved for a future batching optimization; kept off until 036.)
+  // Outbound lines are batched per call (legacy mode), not via a reserved
+  // instance field: a legacy `deliver()` joins every line of a ChannelDO
+  // broadcast into a single `WebSocket.send()`, and the legacy actor `send`
+  // handler in `buildActor` does the same for one frame's response. An
+  // IRCv3 spec-mode connection instead sends one line per WS message with
+  // no trailing CR-LF (see `sendOutbound`). Cross-call per-microtask
+  // coalescing (the optimization previously reserved here) was dropped — it
+  // would add a drain queue and ordering hazards between independent
+  // fan-out calls for no measured benefit (see ADR-003 and the CF adapter
+  // load-test report). Revisit only if WS round-trips become a demonstrated
+  // bottleneck.
 
   // -------------------------------------------------------------------------
   // WebSocket upgrade
@@ -134,12 +185,31 @@ export class ConnectionDO extends DurableObject<Env> {
     const pair = new WebSocketPair();
     const server = pair[0];
     const client = pair[1];
+    // Capture the verified client-cert subject when CF API Shield mTLS is
+    // active. `request.cf` is a Cloudflare-specific extension; the property
+    // is present only when a client certificate was verified against the
+    // uploaded CA pool.
+    const cf = (request as Request & { cf?: Record<string, unknown> }).cf;
+    if (cf !== undefined && typeof cf.tlsClientAuthCertSubject === 'string') {
+      this.mtlsCertSubject = cf.tlsClientAuthCertSubject;
+    }
+    // IRCv3 WebSocket subprotocol negotiation: read the offered
+    // `Sec-WebSocket-Protocol` list, select the first supported entry, and
+    // echo it back when one was agreed. The negotiated frame mode is tagged
+    // onto the hibernated socket so it survives eviction and can be
+    // recovered in every event handler (webSocketMessage / deliver / alarm).
+    const offerHeader = request.headers.get('Sec-WebSocket-Protocol');
+    const chosen = selectSubprotocol(parseSecWsProtocolOffers(offerHeader));
+    const mode = wsFrameModeFor(chosen ?? undefined);
     // Hibernation: `acceptWebSocket` accepts the server side implicitly.
-    // Calling `server.accept()` first throws "already accepted".
-    this.ctx.acceptWebSocket(server);
+    // Calling `server.accept()` first throws "already accepted". The tag
+    // records the negotiated frame mode for the outbound + inbound paths.
+    this.ctx.acceptWebSocket(server, [`ws:${mode}`]);
     // Schedule the first PING sweep.
     await this.ctx.storage.setAlarm(Date.now() + this.pingIntervalMs);
-    return new Response(null, { status: 101, webSocket: client });
+    const headers = new Headers();
+    if (chosen !== null) headers.set('Sec-WebSocket-Protocol', chosen);
+    return new Response(null, { status: 101, webSocket: client, headers });
   }
 
   // -------------------------------------------------------------------------
@@ -148,12 +218,33 @@ export class ConnectionDO extends DurableObject<Env> {
 
   /** Frame → actor → dispatch → persist. */
   override async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
-    const text = typeof message === 'string' ? message : new TextDecoder().decode(message);
+    const mode = this.wsFrameMode(ws);
+    // text.ircv3.net is a text-only subprotocol: a binary frame on such a
+    // connection is a protocol violation. RFC 6455 close code 1003 (unsupported
+    // data) is the spec-mandated response.
+    if (mode === 'spec-text' && typeof message !== 'string') {
+      ws.close(1003, 'binary frame not permitted on text.ircv3.net');
+      return;
+    }
+    const raw = typeof message === 'string' ? message : new TextDecoder().decode(message);
+    // IRCv3 WebSocket spec: a single message MUST fit the 510-byte budget
+    // (the 512-byte IRC line limit minus the omitted trailing CR-LF). An
+    // oversize message is a protocol violation; RFC 6455 close code 1009
+    // (Message Too Big) is the spec-mandated response. Legacy connections
+    // keep the parser's existing 512-byte line cap, so the budget is
+    // enforced for negotiated spec modes only.
+    if ((mode === 'spec-text' || mode === 'spec-binary') && !isWithinWsByteBudget(raw)) {
+      ws.close(1009, 'Message Too Big');
+      return;
+    }
+    // text.ircv3.net frames are UTF-8 text; lone surrogates have no valid
+    // encoding and are substituted with U+FFFD before framing.
+    const text = mode === 'spec-text' ? sanitizeForTextMode(raw) : raw;
     const state = await this.loadState();
-    const before = new Set(state.joinedChannels);
     const beforeNick = state.nick;
 
-    const actor = this.buildActor(ws, state);
+    await this.loadAccountStore();
+    const actor = this.buildActor(ws, state, mode);
     try {
       await actor.receiveTextFrame(text);
     } finally {
@@ -165,17 +256,11 @@ export class ConnectionDO extends DurableObject<Env> {
     if (beforeNick === undefined && state.nick !== undefined) {
       await this.ctx.storage.setAlarm(Date.now() + this.pingIntervalMs);
     }
-    // Detect newly joined channels so we can register them with the
-    // channel DO — necessary for the close handler to fan out QUIT to
-    // them. The stub channel DO records the call; the real ChannelDO
-    // (035) maintains authoritative roster state.
-    for (const chan of state.joinedChannels) {
-      if (!before.has(chan)) {
-        // joinReducer already emitted an ApplyChannelDelta; the stub
-        // ChannelDO records it. No extra work needed here for 033.
-        void chan;
-      }
-    }
+    // No per-ConnectionDO channel-registration step is needed here: channel
+    // membership is driven solely by the `ApplyChannelDelta` effect the
+    // joinReducer emits, which the CfRuntime forwards to the authoritative
+    // ChannelDO. The ChannelDO roster IS the fan-out registration target, so
+    // a second loop over newly joined channels here would be redundant.
   }
 
   /** QUIT fanout + nick release. RFC 1459: a missing close is a QUIT. */
@@ -202,7 +287,7 @@ export class ConnectionDO extends DurableObject<Env> {
    * been idle past the PONG timeout, closes it.
    *
    * PLAN §6.1 — DO alarms are the canonical PING/idle mechanism on CF;
-   * equivalent to EventBridge Scheduler on AWS (042).
+   * equivalent to EventBridge Scheduler on AWS.
    */
   override async alarm(): Promise<void> {
     const state = await this.loadState();
@@ -220,7 +305,8 @@ export class ConnectionDO extends DurableObject<Env> {
     // Send PING. PONG replies update lastSeen via the actor.
     const token = this.ids.nonce();
     for (const ws of this.ctx.getWebSockets()) {
-      (ws as WebSocket).send(`PING :${token}\r\n`);
+      const socket = ws as WebSocket;
+      this.sendOutbound(socket, [{ text: `PING :${token}` }], this.wsFrameMode(socket));
     }
     await this.ctx.storage.setAlarm(now + this.pingIntervalMs);
   }
@@ -251,14 +337,11 @@ export class ConnectionDO extends DurableObject<Env> {
    */
   async deliver(lines: RawLine[]): Promise<{ delivered: number }> {
     let delivered = 0;
-    let text: string | undefined;
-    if (lines.length > 0) {
-      text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
-    }
     for (const ws of this.ctx.getWebSockets()) {
       const socket = ws as WebSocket;
       if (socket.readyState !== WebSocket.OPEN) continue;
-      if (text !== undefined) socket.send(text);
+      const mode = this.wsFrameMode(socket);
+      this.sendOutbound(socket, lines, mode);
       delivered++;
     }
     return { delivered };
@@ -268,6 +351,44 @@ export class ConnectionDO extends DurableObject<Env> {
   // Internal helpers
   // -------------------------------------------------------------------------
 
+  /**
+   * Recovers the negotiated WebSocket frame mode for `ws` from its
+   * hibernation tag. The tag is written once in `fetch` and survives DO
+   * eviction, so this returns the correct mode on every wake. Defaults to
+   * the legacy-tolerant mode when no tag is present (e.g. a socket accepted
+   * before subprotocol negotiation existed).
+   */
+  private wsFrameMode(ws: WebSocket): WsFrameMode {
+    return wsFrameModeFromTags(this.ctx.getTags(ws));
+  }
+
+  /**
+   * Writes `lines` to `ws` according to `mode`:
+   *   - `spec-text`   — one `ws.send` per line, no trailing CR-LF, lone
+   *                     surrogates substituted with U+FFFD (UTF-8 safety).
+   *   - `spec-binary` — one `ws.send` per line as a UTF-8 binary frame,
+   *                     no trailing CR-LF.
+   *   - `legacy`      — all lines joined with `\r\n` plus a trailing
+   *                     `\r\n`, sent as a single WebSocket message.
+   *
+   * No-ops when the socket is closed or `lines` is empty (preserving the
+   * empty-payload probe contract of {@link deliver}).
+   */
+  private sendOutbound(ws: WebSocket, lines: RawLine[], mode: WsFrameMode): void {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    if (lines.length === 0) return;
+    if (mode === 'spec-text') {
+      for (const line of lines) ws.send(sanitizeForTextMode(line.text));
+      return;
+    }
+    if (mode === 'spec-binary') {
+      const enc = new TextEncoder();
+      for (const line of lines) ws.send(enc.encode(line.text));
+      return;
+    }
+    ws.send(`${lines.map((l) => l.text).join('\r\n')}\r\n`);
+  }
+
   /** Loads the connection state from storage, caching for the event. */
   private async loadState(): Promise<ConnectionState> {
     if (this.cached !== undefined) return this.cached;
@@ -290,29 +411,30 @@ export class ConnectionDO extends DurableObject<Env> {
   }
 
   /**
-   * Constructs an actor wired to this DO's CfRuntime.
+   * Constructs an actor wired to this DO's CfRuntime. `mode` drives both the
+   * inbound line-framing transport (spec mode: one IRC message per frame,
+   * never split; legacy: split on `\r\n`) and the outbound delivery shape
+   * (spec mode: one `WebSocket.send` per line, no trailing CR-LF; legacy:
+   * batched into a single `\r\n`-joined frame).
    */
-  private buildActor(ws: WebSocket, state: ConnectionState): ConnectionActor {
+  private buildActor(ws: WebSocket, state: ConnectionState, mode: WsFrameMode): ConnectionActor {
     const serverConfig = this.serverConfig();
     const motd = this.motdProvider();
     const handlers = {
       send: (lines: RawLine[]): void => {
-        if (ws.readyState === WebSocket.OPEN) {
-          const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
-          ws.send(text);
-        }
+        this.sendOutbound(ws, lines, mode);
       },
       disconnect: (reason?: string): void => {
-        if (reason !== undefined && ws.readyState === WebSocket.OPEN) {
-          ws.send(`ERROR :Closing link: (${reason})\r\n`);
+        if (reason !== undefined) {
+          this.sendOutbound(ws, [{ text: `ERROR :Closing link: (${reason})` }], mode);
         }
         ws.close();
       },
       snapshot: (): ConnectionState | undefined => this.cached,
     };
-    // For 033 stub routing we look up the per-connection registry
-    // stub by the DO instance's hex id. Production (034) shards the
-    // registry by nick instead, at which point `registryKey` is unused.
+    // The CfRuntime shards the registry by nick; the per-connection
+    // key passed here is ignored by `makeCfRuntime` (kept in the signature
+    // for call-site stability).
     const registryKey = this.ctx.id.toString();
     const runtime = makeCfRuntime(this.env, state.id, registryKey, handlers);
     if (this.channelAccess === undefined) {
@@ -323,16 +445,29 @@ export class ConnectionDO extends DurableObject<Env> {
     // per-connection in the Workers dashboard.
     const logger: Logger = new ConsoleLogger({ connectionId: state.id }, undefined, LogLevel.Info);
     const accounts = this.accountStore();
+    const mtlsIdentity: MtlsIdentityProvider | undefined =
+      this.mtlsCertSubject !== undefined
+        ? new InMemoryMtlsIdentityProvider([{ connId: state.id, identity: this.mtlsCertSubject }])
+        : undefined;
     return new ConnectionActor({
       state,
       runtime,
       channels: this.channelAccess,
       serverConfig,
+      configSource: 'KV',
       clock: this.clock,
       ids: this.ids,
       motd,
       messages: this.messageStore(),
+      history: this.historyStore(),
+      // CfStats fans out across the channel + connection RPCs the runtime
+      // already exposes. `uptimeStartedAt` is captured at the worker's
+      // module load (cold start); a dedicated stats DO would give a
+      // deployment-wide uptime, tracked as future work.
+      stats: new CfStats(runtime, WORKER_STARTUP_AT),
+      transport: makeWsFrameTransport(mode),
       ...(accounts !== undefined ? { accounts } : {}),
+      ...(mtlsIdentity !== undefined ? { mtlsIdentity } : {}),
       logger,
     });
   }
@@ -340,7 +475,8 @@ export class ConnectionDO extends DurableObject<Env> {
   /** Tears down a connection: emit QUIT effects, release nick, close WS. */
   private async tearDown(ws: WebSocket): Promise<void> {
     const state = await this.loadState();
-    const actor = this.buildActor(ws, state);
+    await this.loadAccountStore();
+    const actor = this.buildActor(ws, state, this.wsFrameMode(ws));
     // Drive QUIT through the actor so the same effect pipeline handles
     // fanout as during normal operation.
     await actor.receiveTextFrame('QUIT\r\n');
@@ -368,11 +504,17 @@ export class ConnectionDO extends DurableObject<Env> {
   }
 
   private serverConfig(): ServerConfig {
-    return {
-      ...DEFAULT_SERVER_CONFIG,
-      ...(this.env.SERVER_NAME !== undefined ? { serverName: this.env.SERVER_NAME } : {}),
-      ...(this.env.NETWORK_NAME !== undefined ? { networkName: this.env.NETWORK_NAME } : {}),
-    };
+    // Single source of truth: delegate to the schema-validated loader so
+    // every reducer-facing field (operCreds, serverPassword, motdLines,
+    // limit knobs, …) is populated from `this.env` exactly as the shared
+    // `ServerConfigSchema` prescribes. The previous hand-rolled literal
+    // silently dropped fields like operCreds, which left OPER unable to
+    // authenticate (491 ERR_NOOPERHOST) even when OPER_USER/OPER_PASSWORD
+    // were bound. See config-loader.ts and config.ts.
+    if (this.cachedServerConfig === undefined) {
+      this.cachedServerConfig = loadServerConfigFromCfEnv(this.env);
+    }
+    return this.cachedServerConfig;
   }
 
   private motdProvider(): MotdProvider {
@@ -398,17 +540,37 @@ export class ConnectionDO extends DurableObject<Env> {
   }
 
   /**
-   * Lazily constructs the in-worker SASL account store from the
-   * `SASL_ACCOUNTS` env var. Returns `undefined` when no accounts are
-   * configured so the actor's `ctx.accounts` stays unset (preserving the
-   * no-store behaviour: `AUTHENTICATE PLAIN` → `904`). A Durable-Object /
-   * D1-backed persistent variant is a documented follow-up.
+   * Lazily constructs the per-connection nick-history store. A future
+   * persistent variant (DO/KV-backed, keyed by nick) will replace this
+   * without touching the actor wiring.
+   */
+  private historyStore(): NickHistoryStore {
+    if (this.history === undefined) {
+      this.history = new InMemoryNickHistoryStore(this.clock);
+    }
+    return this.history;
+  }
+
+  /**
+   * Resolves the SASL account store once (D1 table → `SASL_ACCOUNTS` seed),
+   * caching the result. Safe to call on every frame; the D1 query runs at
+   * most once per ConnectionDO instance. Must complete before the first
+   * reducer dispatches so the synchronous `AccountStore.verify` port has its
+   * data ready.
+   */
+  private async loadAccountStore(): Promise<void> {
+    if (this.accountsResolved) return;
+    this.accountsResolved = true;
+    this.accounts = await resolveAccountStore(this.env.ACCOUNTS_DB, this.env.SASL_ACCOUNTS);
+  }
+
+  /**
+   * Returns the resolved account store, or `undefined` when no accounts are
+   * configured (so the actor's `ctx.accounts` stays unset: `AUTHENTICATE
+   * PLAIN` → `904`). Populated by {@link loadAccountStore}; callers MUST
+   * `await loadAccountStore()` before reading this.
    */
   private accountStore(): AccountStore | undefined {
-    if (this.accounts !== undefined) return this.accounts;
-    const creds = parseSaslAccountsEnv(this.env.SASL_ACCOUNTS);
-    if (creds.length === 0) return undefined;
-    this.accounts = new InMemoryAccountStore(creds);
     return this.accounts;
   }
 
@@ -437,6 +599,7 @@ export class ConnectionDO extends DurableObject<Env> {
   private async tearDownNoSocket(state: ConnectionState): Promise<void> {
     // Emit QUIT effects without dispatching transport calls (the socket
     // is already gone). The cross-DO fanout still runs.
+    await this.loadAccountStore();
     const noOpHandlers: CfConnectionHandlers = {
       send: (): void => {},
       disconnect: (): void => {},
@@ -452,10 +615,12 @@ export class ConnectionDO extends DurableObject<Env> {
       runtime,
       channels: this.channelAccess,
       serverConfig: this.serverConfig(),
+      configSource: 'KV',
       clock: this.clock,
       ids: this.ids,
       motd: this.motdProvider(),
       messages: this.messageStore(),
+      history: this.historyStore(),
     });
     await actor.receiveTextFrame('QUIT\r\n');
     await this.releaseAndPersist(state);
@@ -629,12 +794,6 @@ class PassthroughChannelAccess {
   }
 }
 
-// Reference `applyChannelDelta` to ensure the import is used downstream by
-// tests that exercise state migrations; harmless if the symbol is unused
-// in production today. (Removed from the ConnectionDO path because the
-// authoritative delta application lives in the ChannelDO stub today.)
-export { applyChannelDelta, PERSISTED_STATE_VERSION };
-
 /**
  * Parses the `SASL_ACCOUNTS` env var into credential entries.
  *
@@ -659,3 +818,37 @@ export function parseSaslAccountsEnv(raw: string | undefined): SaslAccountCreden
   }
   return out;
 }
+
+/**
+ * Hibernation-tag prefixes written by {@link ConnectionDO.fetch}. Each tag
+ * encodes the negotiated {@link WsFrameMode} so it survives DO eviction and
+ * can be recovered in every WebSocket event handler via `ctx.getTags(ws)`.
+ */
+const WS_TAG_LEGACY = 'ws:legacy';
+const WS_TAG_SPEC_TEXT = 'ws:spec-text';
+const WS_TAG_SPEC_BINARY = 'ws:spec-binary';
+
+/**
+ * Recovers the {@link WsFrameMode} from a hibernated socket's tags.
+ * Defaults to the legacy-tolerant mode when no recognized tag is present.
+ */
+export function wsFrameModeFromTags(tags: readonly string[]): WsFrameMode {
+  for (const tag of tags) {
+    if (tag === WS_TAG_SPEC_TEXT) return 'spec-text';
+    if (tag === WS_TAG_SPEC_BINARY) return 'spec-binary';
+    if (tag === WS_TAG_LEGACY) return 'legacy';
+  }
+  return 'legacy';
+}
+
+/**
+ * Builds the inbound line-framing {@link Transport} for `mode`. Spec modes
+ * treat one WebSocket message as exactly one IRC line (a single trailing
+ * CR-LF is stripped and the frame is never split); legacy mode splits the
+ * frame on `\r\n` so older clients that concatenate messages keep working.
+ */
+export function makeWsFrameTransport(mode: WsFrameMode): Transport {
+  return {
+    feed: (chunk: string): string[] => frameToLines(chunk, mode),
+  };
+}