serverless-ircd 0.7.0 → 0.8.0

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

@@ -7,6 +7,11 @@
  */
 
 import { caseFold } from './case-fold.js';
+import {
+  type HashedAccountCredential,
+  hashAccountCredential,
+  verifyHashedPassword,
+} from './credential-hashing.js';
 import type { ChannelState } from './state/channel.js';
 import type { ConnId, ConnectionState } from './state/connection.js';
 
@@ -414,6 +419,23 @@ export interface MessageStore {
   recent(chan: string, sinceMsgid: string | undefined, limit: number): StoredMessage[];
   /** Returns true iff `msgid` is currently retained for `chan`. */
   hasMsgid(chan: string, msgid: string): boolean;
+  /**
+   * Returns the message currently retained for `chan` under `msgid`, or
+   * `undefined` when it is absent (never recorded, or evicted by the
+   * retention cap). Used by `draft/read-marker` `MARKREAD` to resolve a
+   * stored marker msgid back to its message — both for the server's
+   * `MARKREAD` echo (the message's `time` tag) and for the monotonic
+   * timestamp comparison.
+   */
+  getMsg(chan: string, msgid: string): StoredMessage | undefined;
+  /**
+   * Returns the most recent retained message in `chan` whose `time` is less
+   * than or equal to `ts` (epoch ms), or `undefined` when no such message
+   * exists. Used by `draft/read-marker` `MARKREAD` to translate a
+   * client-supplied server-time timestamp into the msgid the
+   * msgid-based marker store keys on.
+   */
+  findAtOrBefore(chan: string, ts: number): StoredMessage | undefined;
   /** Enumerates channels with activity inside `[since, until]`, newest-first. */
   targets(since: number, until: number): TargetEntry[];
 }
@@ -481,6 +503,24 @@ export class InMemoryMessageStore implements MessageStore {
     return arr.some((m) => m.msgid === msgid);
   }
 
+  getMsg(chan: string, msgid: string): StoredMessage | undefined {
+    const arr = this.byChan.get(caseFold('rfc1459', chan));
+    if (arr === undefined) return undefined;
+    return arr.find((m) => m.msgid === msgid);
+  }
+
+  findAtOrBefore(chan: string, ts: number): StoredMessage | undefined {
+    const arr = this.byChan.get(caseFold('rfc1459', chan));
+    if (arr === undefined || arr.length === 0) return undefined;
+    // `arr` is chronological (oldest-first); walk from the newest back so the
+    // first hit is the most recent message at or before `ts`.
+    for (let i = arr.length - 1; i >= 0; i--) {
+      const m = arr[i];
+      if (m !== undefined && m.time <= ts) return m;
+    }
+    return undefined;
+  }
+
   recent(chan: string, sinceMsgid: string | undefined, limit: number): StoredMessage[] {
     if (limit <= 0) return [];
     const arr = this.byChan.get(caseFold('rfc1459', chan));
@@ -587,7 +627,7 @@ function tail<T>(arr: readonly T[], n: number): T[] {
  *
  * `channel` is the lowercased channel name (the storage key); `msgid` is the
  * msgid of the most recent message the account has read in that channel.
- * Returned by {@link ReadMarkerStore.forAccount} when seeding a fresh
+ * Returned by {@link ServicesStore.listReadMarkers} when seeding a fresh
  * connection at identify time.
  */
 export interface ReadMarkerEntry {
@@ -599,93 +639,15 @@ export interface ReadMarkerEntry {
   msgid: string;
 }
 
-/**
- * Persistence port for IRCv3 `draft/read-marker`.
- *
- * The chathistory command keeps a per-`(connection, channel)`
- * last-read marker in {@link ConnectionState.lastReadMarkers}; this port
- * promotes that marker to a per-`(account, channel)` record so it survives
- * reconnects and is shared across an account's connections.
- *
- * Mirrors the {@link MessageStore} / {@link AccountStore} 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; the in-memory
- * reference implementation ({@link InMemoryReadMarkerStore}) ships here.
- *
- * Account and channel keys are both case-folded (rfc1459) so lookups are
- * case-insensitive, matching the rest of the server's comparison semantics.
- */
-export interface ReadMarkerStore {
-  /**
-   * Returns the stored last-read msgid for `(account, channel)`, or
-   * `undefined` when no marker has been recorded.
-   */
-  get(account: string, channel: string): string | undefined;
-  /**
-   * Records (or replaces) the last-read msgid for `(account, channel)`.
-   * Callers MUST only move the marker forward (towards newer messages);
-   * the store itself does not order msgids, it stores the latest value set.
-   */
-  set(account: string, channel: string, msgid: string): void;
-  /**
-   * Enumerates every recorded marker for `account`. Used at identify time to
-   * seed a fresh connection's {@link ConnectionState.lastReadMarkers} so a
-   * reconnect restores the user's read position across all their channels.
-   */
-  forAccount(account: string): ReadonlyArray<ReadMarkerEntry>;
-}
-
-/**
- * Reference in-memory {@link ReadMarkerStore} backed by a
- * `foldedAccount → (foldedChannel → msgid)` nested map.
- *
- * Used by the local CLI, integration tests, and any deployment that has not
- * bound a distributed backend. Cloud adapters replace this with a D1 /
- * DynamoDB-backed implementation against the same surface.
- *
- * Both keys are folded via {@link caseFold} (`rfc1459`) so lookups are
- * case-insensitive; the returned {@link ReadMarkerEntry.channel} carries the
- * folded spelling and {@link ReadMarkerEntry.account} the canonical name
- * passed to {@link ReadMarkerStore.forAccount}.
- */
-export class InMemoryReadMarkerStore implements ReadMarkerStore {
-  private readonly byAccount = new Map<string, Map<string, string>>();
-
-  get(account: string, channel: string): string | undefined {
-    return this.byAccount.get(folded(account))?.get(folded(channel));
-  }
-
-  set(account: string, channel: string, msgid: string): void {
-    const acct = folded(account);
-    let chanMap = this.byAccount.get(acct);
-    if (chanMap === undefined) {
-      chanMap = new Map<string, string>();
-      this.byAccount.set(acct, chanMap);
-    }
-    chanMap.set(folded(channel), msgid);
-  }
-
-  forAccount(account: string): ReadonlyArray<ReadMarkerEntry> {
-    const chanMap = this.byAccount.get(folded(account));
-    if (chanMap === undefined) return [];
-    const out: ReadMarkerEntry[] = [];
-    for (const [channel, msgid] of chanMap) {
-      out.push({ account, channel, msgid });
-    }
-    return out;
-  }
-}
+// ============================================================================
+// Away-status persistence (IRCv3 draft/pre-away)
+// ============================================================================
 
-/** rfc1459 case-fold used for both account and channel keys. */
+/** rfc1459 case-fold used for account, nick, and channel keys. */
 function folded(value: string): string {
   return caseFold('rfc1459', value);
 }
 
-// ============================================================================
-// Away-status persistence (IRCv3 draft/pre-away)
-// ============================================================================
-
 /**
  * Persistence port for IRCv3 `draft/pre-away`.
  *
@@ -694,7 +656,7 @@ function folded(value: string): string {
  * port promotes that reason to a per-`account` record so it survives
  * reconnects and is shared across an account's connections.
  *
- * Mirrors the {@link ReadMarkerStore} pattern: the port is
+ * Mirrors the {@link ServicesStore} read-marker methods: 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; the in-memory
@@ -752,6 +714,1613 @@ export class InMemoryAwayStore implements AwayStore {
   }
 }
 
+// ============================================================================
+// IRC services persistence (NickServ / ChanServ / HostServ / MemoServ)
+// ============================================================================
+
+/**
+ * NickServ enforcement policy for a registered nick.
+ *
+ * Mirrors the Atheme/Anope `SET ENFORCE` modes. The default per registered
+ * account is {@link NickEnforcePolicy.None}; the NickServ reducer flips the
+ * policy via {@link ServicesStore.setNickEnforce} on `SET ENFORCE <mode>`.
+ *
+ *   - `none`  — unidentified use of the nick is permitted; NickServ merely
+ *                sends a notice.
+ *   - `ghost` — unidentified use is permitted for a grace period, then the
+ *                connection is force-disconnected by the `EnforceNick`
+ *                effect.
+ *   - `kill`  — unidentified use is refused immediately (force-disconnect
+ *                with no grace).
+ */
+export type NickEnforcePolicy = 'none' | 'ghost' | 'kill';
+
+/**
+ * One NickServ registration record, created by `NickServ REGISTER` and
+ * stored against a {@link ServicesStore}.
+ *
+ * `nick` is the canonical / display spelling captured at registration;
+ * `account` is the SASL PLAIN username (equal to `nick` until nick grouping
+ * lands). Lookups against the store are case-insensitive (rfc1459-folded);
+ * the returned `nick` / `account` preserve the original spelling so the
+ * wire renders the user's preferred casing.
+ */
+export interface RegisteredNick {
+  /** Display spelling stored at registration. */
+  nick: string;
+  /** Account name (SASL PLAIN username). Equal to `nick` until grouping. */
+  account: string;
+  /** Email captured at registration. */
+  email: string;
+  /** Epoch-ms the registration was recorded (from the injected Clock). */
+  createdAt: number;
+  /** Per-account nick-enforcement policy. */
+  enforce: NickEnforcePolicy;
+}
+
+/**
+ * Persisted topic snapshot for a channel with KEEPTOPIC enabled. Round-trips
+ * across the channel becoming empty: the TOPIC reducer writes here on every
+ * change, and the JOIN reducer consults it on the first join after the
+ * channel becomes empty so the topic is restored.
+ */
+export interface PersistedTopic {
+  /** Topic text (may be empty after a clear). */
+  text: string;
+  /** Setter hostmask captured at the last topic change. */
+  setter: string;
+  /** Epoch-ms the topic was last changed. */
+  setAt: number;
+}
+
+/**
+ * One ChanServ registration record, created by `ChanServ REGISTER`.
+ *
+ * `founder` is the account name that ran REGISTER (transferable via
+ * `SET FOUNDER`). `mlock` is the stored mode-lock modestring (empty when
+ * no lock is set); `restricted` toggles the channel's `+R` mode;
+ * `keepTopic` toggles topic persistence across empty-recreate;
+ * `topic` carries the last known topic snapshot when `keepTopic` is on.
+ */
+export interface RegisteredChannel {
+  /** Display spelling of the channel name stored at registration. */
+  channel: string;
+  /** Founder account (the account that ran REGISTER, or a transfer target). */
+  founder: string;
+  /** Epoch-ms the registration was recorded (from the injected Clock). */
+  createdAt: number;
+  /** Stored mode-lock modestring (empty when no lock is set). */
+  mlock: string;
+  /** Whether SET RESTRICTED is on (block join/PRIVMSG from unidentified). */
+  restricted: boolean;
+  /** Whether SET KEEPTOPIC is on (persist topic across empty-recreate). */
+  keepTopic: boolean;
+  /** Last known topic snapshot; present only while `keepTopic` is on. */
+  topic?: PersistedTopic;
+}
+
+/**
+ * Numeric ChanServ access level for an account on a channel. The numeric
+ * mapping follows the Atheme/Anope convention so the existing `SOP` /
+ * `AOP` / `VOP` / `HOP` shorthand maps cleanly:
+ *
+ *   - `0`  — no entry (returned by {@link ServicesStore.getChannelAccess}
+ *            for unknown pairs).
+ *   - `≤0` — treated as "remove" by {@link ServicesStore.setChannelAccess}.
+ *   - `>0` — a stored access level.
+ */
+export type ChannelAccessLevel = number;
+
+/**
+ * Named ChanServ level thresholds a founder may redefine via `LEVELS SET`.
+ * The threshold is the numeric access level required for ChanServ to apply
+ * the matching channel prefix automatically on JOIN (or, for non-`AUTO*`
+ * ops reserved for future tickets, the level required to invoke a command).
+ *
+ * The three values below are the only thresholds the JOIN auto-prefix hook
+ * consults; {@link ServicesStore.getChannelLevel} returns `undefined` for
+ * unset ops so callers fall back to {@link DEFAULT_CHANNEL_LEVELS}.
+ */
+export type ChannelLevelOp = 'AUTOOP' | 'AUTOHALFOP' | 'AUTOVOICE';
+
+/**
+ * Outcome of {@link ServicesStore.registerNick} and
+ * {@link ServicesStore.verifyNick}: either the canonical account name on
+ * success, or a human-readable reason for the failure.
+ */
+export type ServicesAuthResult = { ok: true; account: string } | { ok: false; reason: string };
+
+/**
+ * Outcome of {@link ServicesStore.registerChannel}: either the founder
+ * account on success, or a human-readable reason for the failure.
+ */
+export type ChannelRegisterResult = { ok: true; founder: string } | { ok: false; reason: string };
+
+/**
+ * One queued MemoServ memo, recorded against the recipient's account and
+ * delivered on the recipient's next identify / SASL login.
+ */
+export interface MemoEntry {
+  /** Monotonic memo id assigned by the store. */
+  id: number;
+  /** Sender account. */
+  from: string;
+  /** Recipient account (the `to` lookup key). */
+  to: string;
+  /** Memo body (single IRC-safe line; multi-line memos join with `\n`). */
+  body: string;
+  /** Epoch-ms the memo was recorded. */
+  sentAt: number;
+  /** Whether the recipient has marked the memo read. */
+  read: boolean;
+}
+
+/** Input shape for {@link ServicesStore.recordMemo}; the store assigns id + read. */
+export type MemoInput = Omit<MemoEntry, 'id' | 'read'>;
+
+/**
+ * One OperServ AKILL record: a network-wide ban mask plus the reason the
+ * oper recorded when adding it. Lookups against the store are
+ * case-insensitive on the mask via {@link matchAkill}; `mask` preserves
+ * the original spelling so the `AKILL LIST` reducer renders the oper's
+ * input verbatim.
+ */
+export interface AkillEntry {
+  /** Ban mask (`nick!user@host` with `*` / `?` wildcards). */
+  mask: string;
+  /** Oper-supplied reason captured when the AKILL was added. */
+  reason: string;
+  /** Epoch-ms the AKILL was recorded (from the injected Clock). */
+  createdAt: number;
+}
+
+/**
+ * One OperServ JUPE record: a blocked nick / server name plus the reason
+ * the oper recorded when adding it. The NICK reducer rejects a jupe'd
+ * nick with `432 ERR_ERRONEUSNICKNAME`. `name` preserves the original
+ * spelling; lookups are case-insensitive (rfc1459-folded).
+ */
+export interface JupeEntry {
+  /** Display spelling of the blocked nick / server name. */
+  name: string;
+  /** Oper-supplied reason captured when the JUPE was added. */
+  reason: string;
+  /** Epoch-ms the JUPE was recorded (from the injected Clock). */
+  createdAt: number;
+}
+
+/**
+ * Persistence port for the integrated IRC services (NickServ, ChanServ,
+ * HostServ, MemoServ) plus the per-account read-marker persistence for
+ * IRCv3 `draft/read-marker`.
+ *
+ * The services reducers ship in-process (no pseudo-server, no S2S); this
+ * port is the single persistence seam those reducers consult. Mirrors the
+ * {@link AccountStore} / {@link MessageStore} pattern: the port is
+ * **synchronous** (reducers must stay pure and free of IO) and is injected
+ * via {@link Ctx}. Adapters that need async storage (D1, DynamoDB)
+ * pre-load the relevant slice into a synchronously-readable store; the
+ * in-memory reference implementation ({@link InMemoryServicesStore}) ships
+ * alongside the port.
+ *
+ * All nick / account / channel keys are case-folded (rfc1459) so lookups
+ * are case-insensitive, matching the rest of the server's comparison
+ * semantics advertised via `005 RPL_ISUPPORT CASEMAPPING=rfc1459`. The
+ * read-marker methods ({@link ServicesStore.getLastReadMarker} /
+ * {@link ServicesStore.setLastReadMarker} / {@link ServicesStore.listReadMarkers})
+ * fold the previously standalone read-marker port into this store; the
+ * per-account away-reason port ({@link AwayStore}) stays independent until
+ * a follow-up folds it in too.
+ *
+ * Persistent adapter backends (D1 / DynamoDB) ship separately; the surface
+ * here is the minimum primitives the services reducers build on.
+ */
+export interface ServicesStore {
+  // ----- NickServ -----
+
+  /**
+   * Registers `nick` against a new SASL account. Returns `{ ok: true }`
+   * with the canonical account name on success; `{ ok: false, reason }`
+   * when the nick is already registered (case-insensitive collision).
+   */
+  registerNick(nick: string, password: string, email: string): ServicesAuthResult;
+  /**
+   * Verifies `nick` / `password` against a prior registration. Returns
+   * `{ ok: true, account }` on a match (the canonical spelling), or
+   * `{ ok: false, reason }` when the nick is unknown or the password is
+   * wrong.
+   */
+  verifyNick(nick: string, password: string): ServicesAuthResult;
+  /**
+   * Removes the nick registration. Returns `true` when a registration was
+   * removed, `false` when the nick was not registered.
+   */
+  dropNick(nick: string): boolean;
+  /** `true` iff `nick` has a registration (case-insensitive). */
+  isRegisteredNick(nick: string): boolean;
+  /**
+   * Updates the nick-enforcement policy for `nick`. No-op when the nick is
+   * not registered (the policy stays {@link NickEnforcePolicy.None}).
+   */
+  setNickEnforce(nick: string, policy: NickEnforcePolicy): void;
+  /**
+   * Returns the nick-enforcement policy for `nick`, or
+   * {@link NickEnforcePolicy.None} when the nick is not registered.
+   */
+  getNickEnforce(nick: string): NickEnforcePolicy;
+  /**
+   * Returns the {@link RegisteredNick} record for `nick`, or `undefined`
+   * when the nick is not registered. Used by `NickServ INFO` and the
+   * enforcement hook to read the canonical account bound to a
+   * (case-insensitive) nick.
+   */
+  getNick(nick: string): RegisteredNick | undefined;
+
+  // ----- ChanServ -----
+
+  /**
+   * Registers `channel` with `founder` as the founder account. Returns
+   * `{ ok: true, founder }` on success; `{ ok: false, reason }` when the
+   * channel is already registered (case-insensitive collision).
+   */
+  registerChannel(channel: string, founder: string): ChannelRegisterResult;
+  /**
+   * Removes the channel registration (and its access list). Returns `true`
+   * when a registration was removed, `false` otherwise.
+   */
+  dropChannel(channel: string): boolean;
+  /**
+   * Returns the founder account for `channel`, or `undefined` when the
+   * channel is not registered.
+   */
+  getChannelFounder(channel: string): string | undefined;
+  /**
+   * Records (or replaces) the ChanServ access level for `account` on
+   * `channel`. A level ≤ 0 removes the entry.
+   */
+  setChannelAccess(channel: string, account: string, level: ChannelAccessLevel): void;
+  /**
+   * Returns the ChanServ access level for `account` on `channel`, or `0`
+   * when no entry exists.
+   */
+  getChannelAccess(channel: string, account: string): ChannelAccessLevel;
+  /**
+   * Enumerates every `(account, level)` access entry recorded for
+   * `channel`, oldest-first by insertion. Used by the ChanServ
+   * `ACCESS LIST` reducer to render the roster without leaking the
+   * store's internal map shape.
+   */
+  listChannelAccess(channel: string): ReadonlyArray<{ account: string; level: number }>;
+
+  /**
+   * Returns the founder-redefined threshold for `op` on `channel`, or
+   * `undefined` when no override is stored (the caller falls back to the
+   * default threshold). Used by the JOIN hook to decide whether to grant
+   * the channel prefix that matches `op` (e.g. `AUTOOP` → `@`).
+   */
+  getChannelLevel(channel: string, op: ChannelLevelOp): number | undefined;
+  /**
+   * Records (or replaces) the founder-redefined threshold for `op` on
+   * `channel`. Called by the `LEVELS SET` reducer.
+   */
+  setChannelLevel(channel: string, op: ChannelLevelOp, level: number): void;
+  /**
+   * Returns every founder-redefined threshold for `channel` (oldest-first
+   * by insertion). Used by the `LEVELS LIST` reducer; entries that the
+   * founder never overrode are absent and the caller fills them in with
+   * the defaults.
+   */
+  listChannelLevels(channel: string): ReadonlyArray<{ op: ChannelLevelOp; level: number }>;
+  /**
+   * Drops every founder-redefined threshold for `channel` so the defaults
+   * take effect again. Called by the `LEVELS RESET` reducer and on
+   * {@link dropChannel}.
+   */
+  resetChannelLevels(channel: string): void;
+
+  /**
+   * ChanServ registration-record getters / mutators. Each corresponds to a
+   * ChanServ `SET` subcommand. `setChannel*` calls are no-ops when the
+   * channel is not registered (the reducer pre-validates founder).
+   */
+  /**
+   * Returns the full {@link RegisteredChannel} record for `channel`, or
+   * `undefined` when the channel is not registered.
+   */
+  getChannel(channel: string): RegisteredChannel | undefined;
+  /** Transfers the founder of `channel` to `account` (SET FOUNDER). */
+  setChannelFounder(channel: string, account: string): void;
+  /** Records (or replaces) the MLOCK modestring for `channel`. */
+  setChannelMlock(channel: string, modestring: string): void;
+  /** Returns the MLOCK modestring for `channel`, or `''` when none is set. */
+  getChannelMlock(channel: string): string;
+  /** Toggles the restricted (block unidentified) flag for `channel`. */
+  setChannelRestricted(channel: string, on: boolean): void;
+  /** Toggles the KEEPTOPIC flag for `channel`. */
+  setChannelKeepTopic(channel: string, on: boolean): void;
+  /**
+   * Records (or replaces) the persisted topic snapshot for `channel`. Called
+   * by the TOPIC reducer when KEEPTOPIC is on. Pass `undefined` to clear.
+   */
+  setChannelTopic(channel: string, topic: PersistedTopic | undefined): void;
+  /** Returns the persisted topic snapshot for `channel`, or `undefined`. */
+  getChannelTopic(channel: string): PersistedTopic | undefined;
+
+  // ----- HostServ -----
+
+  /**
+   * Records (or replaces) the vhost for `account`. An empty string clears
+   * any previously-recorded vhost.
+   */
+  setVhost(account: string, vhost: string): void;
+  /** Returns the vhost for `account`, or `undefined` when none is set. */
+  getVhost(account: string): string | undefined;
+
+  /**
+   * Records (or replaces) a **pending** vhost request for `account`. The
+   * request is held until an oper approves it via {@link approveVhost} or
+   * drops it via {@link rejectVhost}; the vhost is NOT activated (no
+   * {@link setVhost} call) while it remains pending.
+   */
+  requestVhost(account: string, vhost: string): void;
+  /**
+   * Returns the pending vhost request for `account`, or `undefined` when
+   * no request is queued.
+   */
+  getPendingVhost(account: string): string | undefined;
+  /**
+   * Enumerates every pending `(account, vhost)` request, oldest-first by
+   * insertion. Used by the HostServ `LIST` (oper-only) reducer.
+   */
+  listPendingVhosts(): ReadonlyArray<{ account: string; vhost: string }>;
+  /**
+   * Approves the pending vhost request for `account`: removes the
+   * pending entry and activates the vhost via {@link setVhost}. Returns
+   * the activated vhost, or `undefined` when no request was pending.
+   */
+  approveVhost(account: string): string | undefined;
+  /**
+   * Rejects (drops) the pending vhost request for `account`. The vhost
+   * is NOT activated. Returns the rejected vhost, or `undefined` when
+   * no request was pending.
+   */
+  rejectVhost(account: string): string | undefined;
+
+  // ----- MemoServ -----
+
+  /**
+   * Records a memo against the recipient's account and returns the
+   * freshly-assigned monotonic id.
+   */
+  recordMemo(memo: MemoInput): number;
+  /**
+   * Returns every memo addressed to `account` (oldest-first), or an empty
+   * array when none are recorded.
+   */
+  listMemos(account: string): ReadonlyArray<MemoEntry>;
+  /**
+   * Marks memo `id` as read for `account`. Returns `true` when the memo
+   * existed (and is now read), `false` otherwise.
+   */
+  markMemoRead(account: string, id: number): boolean;
+  /**
+   * Removes memo `id` for `account`. Returns `true` when a memo was
+   * removed, `false` when the memo did not exist (or belonged to a
+   * different recipient). Called by the MemoServ `DEL` reducer.
+   */
+  deleteMemo(account: string, id: number): boolean;
+
+  // ----- Read-marker (IRCv3 draft/read-marker) -----
+
+  /**
+   * Returns the stored last-read msgid for `(account, channel)`, or
+   * `undefined` when no marker has been recorded. Keys are case-folded
+   * (rfc1459) so lookups are case-insensitive.
+   */
+  getLastReadMarker(account: string, channel: string): string | undefined;
+  /**
+   * Records (or replaces) the last-read msgid for `(account, channel)`.
+   * Callers MUST only move the marker forward (towards newer messages);
+   * the store itself does not order msgids, it stores the latest value set.
+   */
+  setLastReadMarker(account: string, channel: string, msgid: string): void;
+  /**
+   * Enumerates every recorded marker for `account`. Used at identify time
+   * to seed a fresh connection's `lastReadMarkers` so a reconnect restores
+   * the user's read position across all their channels.
+   */
+  listReadMarkers(account: string): ReadonlyArray<ReadMarkerEntry>;
+
+  // ----- OperServ -----
+
+  /**
+   * Records (or replaces) a network-wide ban mask. Subsequent
+   * {@link matchAkill} calls consult it against incoming hostmasks at the
+   * admission boundary and on every PRIVMSG.
+   */
+  addAkill(mask: string, reason: string): void;
+  /**
+   * Removes the AKILL with the matching mask (case-insensitive). Returns
+   * `true` when an entry was removed, `false` otherwise.
+   */
+  removeAkill(mask: string): boolean;
+  /**
+   * Enumerates every recorded AKILL, oldest-first by insertion. Used by
+   * the OperServ `AKILL LIST` reducer to render the roster.
+   */
+  listAkills(): ReadonlyArray<AkillEntry>;
+  /**
+   * Returns the first AKILL whose mask matches `hostmask` (case-insensitive
+   * wildcard comparison), or `undefined` when none match. Called by the
+   * `$connect` / admission path and the per-PRIVMSG enforcement hook so a
+   * connection whose hostmask fits a banned mask is rejected at the gate.
+   */
+  matchAkill(hostmask: string): AkillEntry | undefined;
+
+  /**
+   * Records (or replaces) a JUPE for the given nick / server name. The
+   * NICK reducer consults {@link isJuped} on every NICK change and
+   * returns `432 ERR_ERRONEUSNICKNAME` for a jupe'd target.
+   */
+  addJupe(name: string, reason?: string): void;
+  /**
+   * Removes the JUPE on `name` (case-insensitive). Returns `true` when a
+   * jupe was removed, `false` otherwise.
+   */
+  removeJupe(name: string): boolean;
+  /** `true` iff `name` is currently juped (case-insensitive). */
+  isJuped(name: string): boolean;
+  /**
+   * Returns the {@link JupeEntry} record for `name`, or `undefined` when
+   * no jupe is set. Used by the OperServ `JUPE LIST` reducer and by
+   * logging paths.
+   */
+  getJupe(name: string): JupeEntry | undefined;
+  /** Enumerates every recorded jupe, oldest-first by insertion. */
+  listJupes(): ReadonlyArray<JupeEntry>;
+}
+
+/**
+ * Snapshot row for a NickServ registration, persisted by adapter backends
+ * (D1 / DynamoDB) and round-tripped through {@link ServicesSnapshot}.
+ *
+ * Mirrors {@link RegisteredNick} with the **scrypt-hashed credential**
+ * captured at registration appended. The plaintext password NEVER lives on
+ * this row: `registerNick` runs the password through
+ * {@link hashAccountCredential} (scrypt + random salt) before storing, and
+ * `verifyNick` re-derives via {@link verifyHashedPassword}. A services
+ * backend compromise (D1 export, DynamoDB scan) therefore does not
+ * disclose any NickServ password — the credential is in the same hashed
+ * shape the SASL `AccountStore` already uses, so a NickServ registration
+ * IS a SASL account.
+ *
+ * The credential never leaves the store via
+ * {@link InMemoryServicesStore.getNick} (which returns a defensive copy
+ * without it), but it MUST be present in the snapshot so the
+ * `verifyNick` round-trip keeps working across a reload.
+ */
+export type ServicesNickRow = RegisteredNick & { credential: HashedAccountCredential };
+
+/**
+ * Snapshot row for a ChanServ access entry: `(channel, account, level)`.
+ * `channel` / `account` preserve the display spelling captured at
+ * `setChannelAccess` time; the storage key is the rfc1459-folded form so
+ * case-insensitive lookups survive a reload.
+ */
+export interface ServicesAccessRow {
+  channel: string;
+  account: string;
+  level: ChannelAccessLevel;
+}
+
+/**
+ * Snapshot row for a founder-redefined ChanServ level threshold.
+ */
+export interface ServicesLevelRow {
+  channel: string;
+  op: ChannelLevelOp;
+  level: number;
+}
+
+/**
+ * Snapshot row for a HostServ vhost: `(account, vhost)`.
+ */
+export interface ServicesVhostRow {
+  account: string;
+  vhost: string;
+}
+
+/**
+ * Snapshot row for a pending HostServ vhost request: `(account, vhost)`.
+ * Round-trips through {@link ServicesSnapshot.pendingVhosts} so a request
+ * queued before a deploy survives the reload and stays pending.
+ */
+export interface ServicesPendingVhostRow {
+  account: string;
+  vhost: string;
+}
+
+/**
+ * Serializable snapshot of every services record in the store, used to
+ * hydrate a fresh {@link InMemoryServicesStore} (or a
+ * {@link PersistentServicesStore} cache) from an adapter backend at boot.
+ *
+ * The shape is the union of the per-service row types so a D1 / DynamoDB
+ * loader can produce it directly from a table scan without adapter-specific
+ * translation. Round-trips through {@link InMemoryServicesStore.snapshot}
+ * / the `snapshot` constructor option; the in-memory reference impl is the
+ * source of truth for the canonical layout.
+ */
+export interface ServicesSnapshot {
+  /** NickServ registrations (with scrypt-hashed credential). */
+  nicks: ServicesNickRow[];
+  /** ChanServ channel registrations. */
+  channels: RegisteredChannel[];
+  /** ChanServ `(channel, account, level)` access entries. */
+  access: ServicesAccessRow[];
+  /** ChanServ founder-redefined level thresholds. */
+  levels: ServicesLevelRow[];
+  /** HostServ `(account, vhost)` entries. */
+  vhosts: ServicesVhostRow[];
+  /** HostServ pending `(account, vhost)` requests awaiting oper approval. */
+  pendingVhosts: ServicesPendingVhostRow[];
+  /** MemoServ queued memos. */
+  memos: MemoEntry[];
+  /** Per-`(account, channel)` draft/read-marker entries. */
+  readMarkers: ReadMarkerEntry[];
+  /** OperServ AKILL roster. */
+  akills: AkillEntry[];
+  /** OperServ JUPE roster. */
+  jupes: JupeEntry[];
+}
+
+/**
+ * One write-behind mutation emitted by {@link PersistentServicesStore} on
+ * `flush()`. The discriminated `kind` maps 1:1 to a per-table upsert /
+ * delete so a D1 / DynamoDB backend can dispatch without parsing the row.
+ *
+ * - `upsert*` rows carry the full record so a backend can `INSERT OR
+ *    REPLACE` / `PutItem` without a prior read.
+ * - `delete*` rows carry the minimum key.
+ * - `insertMemo` / `updateMemoRead` / `deleteMemo` keep the memo id stable
+ *   so the in-memory counter and the persisted rows agree.
+ *
+ * No-ops (e.g. `dropNick` on an unregistered nick, `removeAkill` on an
+ * unknown mask) enqueue nothing — the persistent base class only emits a
+ * write when the underlying `InMemoryServicesStore` mutation changed
+ * state.
+ */
+export type ServicesWrite =
+  | { kind: 'upsertNick'; row: ServicesNickRow }
+  | { kind: 'deleteNick'; nick: string }
+  | { kind: 'upsertChannel'; row: RegisteredChannel }
+  | { kind: 'deleteChannel'; channel: string }
+  | { kind: 'upsertChannelAccess'; row: ServicesAccessRow }
+  | { kind: 'deleteChannelAccess'; channel: string; account: string }
+  | { kind: 'upsertChannelLevel'; row: ServicesLevelRow }
+  | { kind: 'resetChannelLevels'; channel: string }
+  | { kind: 'upsertVhost'; row: ServicesVhostRow }
+  | { kind: 'deleteVhost'; account: string }
+  | { kind: 'upsertPendingVhost'; row: ServicesPendingVhostRow }
+  | { kind: 'deletePendingVhost'; account: string }
+  | { kind: 'insertMemo'; row: MemoEntry }
+  | { kind: 'updateMemoRead'; account: string; id: number }
+  | { kind: 'deleteMemo'; account: string; id: number }
+  | { kind: 'upsertReadMarker'; row: ReadMarkerEntry }
+  | { kind: 'upsertAkill'; row: AkillEntry }
+  | { kind: 'deleteAkill'; mask: string }
+  | { kind: 'upsertJupe'; row: JupeEntry }
+  | { kind: 'deleteJupe'; name: string };
+
+/**
+ * Internal stored nick record: {@link ServicesNickRow} (the
+ * {@link RegisteredNick} shape plus the scrypt-hashed credential captured
+ * at registration). The credential never leaves the store via
+ * {@link InMemoryServicesStore.getNick} (which returns a defensive copy
+ * without it).
+ */
+type StoredNick = ServicesNickRow;
+
+/**
+ * Internal stored AKILL record. The public {@link AkillEntry} shape with
+ * the case-folded mask as a separate field so the
+ * {@link InMemoryServicesStore.matchAkill} fast path can short-circuit on
+ * a structural comparison without re-folding per probe.
+ */
+type StoredAkill = AkillEntry & { maskKey: string };
+
+/**
+ * Internal stored JUPE record. The public {@link JupeEntry} shape with
+ * the case-folded name as a separate field so the
+ * {@link InMemoryServicesStore.isJuped} fast path can short-circuit on
+ * a structural comparison without re-folding per probe.
+ */
+type StoredJupe = JupeEntry & { nameKey: string };
+
+/**
+ * Reference in-memory {@link ServicesStore} used by the local CLI,
+ * integration tests, and any deployment that has not bound a distributed
+ * backend.
+ *
+ * Backed by plain `Map`s keyed by rfc1459-folded nick / account / channel.
+ * Password verification uses the same scrypt path as the SASL
+ * {@link HashedAccountStore} ({@link verifyHashedPassword}) so a NickServ
+ * registration IS a SASL account — both stores carry credentials in the
+ * same hashed shape, and SASL PLAIN's services fallback verifies against
+ * a row created by `NickServ REGISTER` without a second registration.
+ * Returned records are defensive copies so callers cannot mutate the
+ * store by editing a returned {@link RegisteredNick} or {@link MemoEntry}.
+ *
+ * Cloud adapters replace this with a D1 / DynamoDB-backed implementation
+ * against the same surface; until then every services reducer runs against
+ * this reference impl.
+ */
+export class InMemoryServicesStore implements ServicesStore {
+  private readonly nicks = new Map<string, StoredNick>();
+  private readonly channels = new Map<string, RegisteredChannel>();
+  private readonly access = new Map<string, Map<string, ChannelAccessLevel>>();
+  private readonly levels = new Map<string, Map<ChannelLevelOp, number>>();
+  private readonly vhosts = new Map<string, string>();
+  /**
+   * Pending HostServ vhost requests, keyed by folded account. Insertion
+   * order is preserved by the underlying `Map` so {@link listPendingVhosts}
+   * renders requests in the order they arrived.
+   */
+  private readonly pendingVhosts = new Map<string, string>();
+  private readonly memosByAccount = new Map<string, MemoEntry[]>();
+  private readonly readMarkersByAccount = new Map<string, Map<string, string>>();
+  /**
+   * AKILL roster, kept in insertion order so the `AKILL LIST` reducer
+   * renders the masks in the order the opers added them. Lookups by mask
+   * consult {@link akillsByKey} for an O(1) existence check.
+   */
+  private readonly akills: StoredAkill[] = [];
+  private readonly akillsByKey = new Map<string, StoredAkill>();
+  /**
+   * JUPE roster, kept in insertion order so the `JUPE LIST` reducer
+   * renders the names in the order the opers added them. Lookups by name
+   * consult {@link jupesByKey} for an O(1) existence check.
+   */
+  private readonly jupes: StoredJupe[] = [];
+  private readonly jupesByKey = new Map<string, StoredJupe>();
+  private readonly clock: Clock;
+  private memoCounter = 0;
+
+  constructor(opts: { clock?: Clock; snapshot?: ServicesSnapshot } = {}) {
+    this.clock = opts.clock ?? SystemClock;
+    if (opts.snapshot !== undefined) this.hydrate(opts.snapshot);
+  }
+
+  /**
+   * Reloads every service record from {@link snap} into the in-memory maps.
+   *
+   * Used by the constructor's `snapshot` option and by
+   * {@link PersistentServicesStore} subclasses (which feed the pre-loaded
+   * adapter snapshot through the same path). Keys are rfc1459-folded so
+   * case-insensitive lookups survive a reload; the {@link StoredAkill} /
+   * {@link StoredJupe} fast-path maps are rebuilt from the public rows.
+   *
+   * The memo counter resumes after the highest reloaded id so the next
+   * `recordMemo` does not collide with a persisted row.
+   */
+  protected hydrate(snap: ServicesSnapshot): void {
+    for (const row of snap.nicks) {
+      this.nicks.set(folded(row.nick), { ...row, credential: { ...row.credential } });
+    }
+    for (const row of snap.channels) {
+      const stored: RegisteredChannel = { ...row };
+      if (row.topic !== undefined) stored.topic = { ...row.topic };
+      this.channels.set(folded(row.channel), stored);
+    }
+    for (const row of snap.access) {
+      let acctMap = this.access.get(folded(row.channel));
+      if (acctMap === undefined) {
+        acctMap = new Map<string, ChannelAccessLevel>();
+        this.access.set(folded(row.channel), acctMap);
+      }
+      acctMap.set(folded(row.account), row.level);
+    }
+    for (const row of snap.levels) {
+      let opMap = this.levels.get(folded(row.channel));
+      if (opMap === undefined) {
+        opMap = new Map<ChannelLevelOp, number>();
+        this.levels.set(folded(row.channel), opMap);
+      }
+      opMap.set(row.op, row.level);
+    }
+    for (const row of snap.vhosts) {
+      this.vhosts.set(folded(row.account), row.vhost);
+    }
+    for (const row of snap.pendingVhosts) {
+      this.pendingVhosts.set(folded(row.account), row.vhost);
+    }
+    for (const memo of snap.memos) {
+      let arr = this.memosByAccount.get(folded(memo.to));
+      if (arr === undefined) {
+        arr = [];
+        this.memosByAccount.set(folded(memo.to), arr);
+      }
+      arr.push({ ...memo });
+      if (memo.id > this.memoCounter) this.memoCounter = memo.id;
+    }
+    for (const row of snap.readMarkers) {
+      let chanMap = this.readMarkersByAccount.get(folded(row.account));
+      if (chanMap === undefined) {
+        chanMap = new Map<string, string>();
+        this.readMarkersByAccount.set(folded(row.account), chanMap);
+      }
+      chanMap.set(folded(row.channel), row.msgid);
+    }
+    for (const row of snap.akills) {
+      const entry: StoredAkill = { ...row, maskKey: folded(row.mask) };
+      this.akills.push(entry);
+      this.akillsByKey.set(entry.maskKey, entry);
+    }
+    for (const row of snap.jupes) {
+      const entry: StoredJupe = { ...row, nameKey: folded(row.name) };
+      this.jupes.push(entry);
+      this.jupesByKey.set(entry.nameKey, entry);
+    }
+  }
+
+  /**
+   * Serializes every service record into a plain snapshot suitable for
+   * adapter persistence (D1 / DynamoDB) or for round-tripping through a
+   * peer {@link InMemoryServicesStore} (see
+   * `persistent-services-store.test.ts`).
+   *
+   * Returned rows are defensive copies so callers cannot mutate the store
+   * by editing the snapshot. The nick rows include the scrypt-hashed
+   * credential — the snapshot is the persistence shape, not a safe public
+   * view (use {@link getNick} for that).
+   */
+  snapshot(): ServicesSnapshot {
+    const nicks: ServicesNickRow[] = [];
+    for (const rec of this.nicks.values()) {
+      nicks.push({ ...rec, credential: { ...rec.credential } });
+    }
+    const channels: RegisteredChannel[] = [];
+    for (const rec of this.channels.values()) {
+      const out: RegisteredChannel = { ...rec };
+      if (rec.topic !== undefined) out.topic = { ...rec.topic };
+      channels.push(out);
+    }
+    const access: ServicesAccessRow[] = [];
+    for (const [chanKey, acctMap] of this.access) {
+      for (const [account, level] of acctMap) {
+        access.push({ channel: chanKey, account, level });
+      }
+    }
+    const levels: ServicesLevelRow[] = [];
+    for (const [chanKey, opMap] of this.levels) {
+      for (const [op, level] of opMap) {
+        levels.push({ channel: chanKey, op, level });
+      }
+    }
+    const vhosts: ServicesVhostRow[] = [];
+    for (const [account, vhost] of this.vhosts) {
+      vhosts.push({ account, vhost });
+    }
+    const pendingVhosts: ServicesPendingVhostRow[] = [];
+    for (const [account, vhost] of this.pendingVhosts) {
+      pendingVhosts.push({ account, vhost });
+    }
+    const memos: MemoEntry[] = [];
+    for (const arr of this.memosByAccount.values()) {
+      for (const memo of arr) memos.push({ ...memo });
+    }
+    const readMarkers: ReadMarkerEntry[] = [];
+    for (const [account, chanMap] of this.readMarkersByAccount) {
+      for (const [channel, msgid] of chanMap) {
+        readMarkers.push({ account, channel, msgid });
+      }
+    }
+    const akills: AkillEntry[] = this.akills.map((e) => ({
+      mask: e.mask,
+      reason: e.reason,
+      createdAt: e.createdAt,
+    }));
+    const jupes: JupeEntry[] = this.jupes.map((e) => ({
+      name: e.name,
+      reason: e.reason,
+      createdAt: e.createdAt,
+    }));
+    return {
+      nicks,
+      channels,
+      access,
+      levels,
+      vhosts,
+      pendingVhosts,
+      memos,
+      readMarkers,
+      akills,
+      jupes,
+    };
+  }
+
+  // ----- NickServ -----
+
+  registerNick(nick: string, password: string, email: string): ServicesAuthResult {
+    const key = folded(nick);
+    if (this.nicks.has(key)) {
+      return { ok: false, reason: 'nick already registered' };
+    }
+    const now = this.clock.now();
+    const credential = hashAccountCredential(nick, password);
+    this.nicks.set(key, {
+      nick,
+      account: nick,
+      email,
+      createdAt: now,
+      enforce: 'none',
+      credential,
+    });
+    return { ok: true, account: nick };
+  }
+
+  verifyNick(nick: string, password: string): ServicesAuthResult {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) {
+      return { ok: false, reason: 'invalid credentials' };
+    }
+    if (!verifyHashedPassword(password, rec.credential)) {
+      return { ok: false, reason: 'invalid credentials' };
+    }
+    return { ok: true, account: rec.account };
+  }
+
+  dropNick(nick: string): boolean {
+    const key = folded(nick);
+    return this.nicks.delete(key);
+  }
+
+  isRegisteredNick(nick: string): boolean {
+    return this.nicks.has(folded(nick));
+  }
+
+  setNickEnforce(nick: string, policy: NickEnforcePolicy): void {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return;
+    rec.enforce = policy;
+  }
+
+  getNickEnforce(nick: string): NickEnforcePolicy {
+    return this.nicks.get(folded(nick))?.enforce ?? 'none';
+  }
+
+  getNick(nick: string): RegisteredNick | undefined {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return undefined;
+    // Defensive copy with the credential stripped so callers cannot mutate
+    // the stored record or read the credential.
+    return {
+      nick: rec.nick,
+      account: rec.account,
+      email: rec.email,
+      createdAt: rec.createdAt,
+      enforce: rec.enforce,
+    };
+  }
+
+  /**
+   * Adopts a pre-hashed SASL account credential as a registered nick.
+   *
+   * This is the unification seam: an account seeded into the SASL
+   * `AccountStore` (the `accounts`/`Accounts` table, populated by the
+   * seed tooling) is treated as a NickServ registration so `INFO`
+   * resolves it, `SET ENFORCE` applies, and NickServ `IDENTIFY` succeeds
+   * with the seeded password. The resulting {@link RegisteredNick} carries
+   * an empty email, the default `'none'` enforcement policy, and
+   * `createdAt = clock.now()`; the supplied {@link HashedAccountCredential}
+   * is stored verbatim so `verifyNick` re-derives via the same scrypt
+   * path as `registerNick`.
+   *
+   * Returns `true` when a new registration was created; `false` when the
+   * nick (case-insensitive) is already registered — the existing record
+   * wins and the supplied credential is NOT overwritten. Idempotent in
+   * the sense that re-ingesting the same credential is a no-op.
+   *
+   * Adapters call this once per cold start, after both the SASL store and
+   * the services store have been loaded, to merge the SASL account set
+   * into the unified services account set.
+   */
+  ingestAccountCredential(credential: HashedAccountCredential): boolean {
+    const key = folded(credential.account);
+    if (this.nicks.has(key)) return false;
+    const account = credential.account;
+    this.nicks.set(key, {
+      nick: account,
+      account,
+      email: '',
+      createdAt: this.clock.now(),
+      enforce: 'none',
+      credential: { ...credential },
+    });
+    return true;
+  }
+
+  /**
+   * Returns the full stored nick row (including the scrypt-hashed
+   * credential), or `undefined` when the nick is not registered. Defensive
+   * copy so the caller cannot mutate the cache by editing the returned
+   * row.
+   *
+   * Used by {@link PersistentServicesStore} to re-persist the full row on
+   * a `setNickEnforce` change (the public {@link getNick} strips the
+   * credential, but the write-behind op needs it so a backend reload
+   * keeps `verifyNick` working). The helper is protected so only the
+   * write-behind subclass reaches for the credential.
+   */
+  protected getStoredNick(nick: string): ServicesNickRow | undefined {
+    const rec = this.nicks.get(folded(nick));
+    return rec === undefined ? undefined : { ...rec, credential: { ...rec.credential } };
+  }
+
+  // ----- ChanServ -----
+
+  registerChannel(channel: string, founder: string): ChannelRegisterResult {
+    const key = folded(channel);
+    if (this.channels.has(key)) {
+      return { ok: false, reason: 'channel already registered' };
+    }
+    this.channels.set(key, {
+      channel,
+      founder,
+      createdAt: this.clock.now(),
+      mlock: '',
+      restricted: false,
+      keepTopic: false,
+    });
+    return { ok: true, founder };
+  }
+
+  dropChannel(channel: string): boolean {
+    const key = folded(channel);
+    this.access.delete(key);
+    this.levels.delete(key);
+    return this.channels.delete(key);
+  }
+
+  getChannelFounder(channel: string): string | undefined {
+    return this.channels.get(folded(channel))?.founder;
+  }
+
+  getChannel(channel: string): RegisteredChannel | undefined {
+    const rec = this.channels.get(folded(channel));
+    if (rec === undefined) return undefined;
+    // Defensive copy with the persisted-topic field copied by value.
+    const out: RegisteredChannel = {
+      channel: rec.channel,
+      founder: rec.founder,
+      createdAt: rec.createdAt,
+      mlock: rec.mlock,
+      restricted: rec.restricted,
+      keepTopic: rec.keepTopic,
+    };
+    if (rec.topic !== undefined) out.topic = { ...rec.topic };
+    return out;
+  }
+
+  setChannelFounder(channel: string, account: string): void {
+    const rec = this.channels.get(folded(channel));
+    if (rec === undefined) return;
+    rec.founder = account;
+  }
+
+  setChannelMlock(channel: string, modestring: string): void {
+    const rec = this.channels.get(folded(channel));
+    if (rec === undefined) return;
+    rec.mlock = modestring;
+  }
+
+  getChannelMlock(channel: string): string {
+    return this.channels.get(folded(channel))?.mlock ?? '';
+  }
+
+  setChannelRestricted(channel: string, on: boolean): void {
+    const rec = this.channels.get(folded(channel));
+    if (rec === undefined) return;
+    rec.restricted = on;
+  }
+
+  setChannelKeepTopic(channel: string, on: boolean): void {
+    const rec = this.channels.get(folded(channel));
+    if (rec === undefined) return;
+    rec.keepTopic = on;
+    // Clearing keepTopic drops the persisted snapshot so a later re-enable
+    // does not restore a stale topic.
+    if (!on && rec.topic !== undefined) {
+      // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+      delete rec.topic;
+    }
+  }
+
+  setChannelTopic(channel: string, topic: PersistedTopic | undefined): void {
+    const rec = this.channels.get(folded(channel));
+    if (rec === undefined) return;
+    if (topic === undefined) {
+      // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+      delete rec.topic;
+      return;
+    }
+    rec.topic = { ...topic };
+  }
+
+  getChannelTopic(channel: string): PersistedTopic | undefined {
+    const rec = this.channels.get(folded(channel));
+    if (rec === undefined || rec.topic === undefined) return undefined;
+    return { ...rec.topic };
+  }
+
+  setChannelAccess(channel: string, account: string, level: ChannelAccessLevel): void {
+    const chanKey = folded(channel);
+    let acctMap = this.access.get(chanKey);
+    if (acctMap === undefined) {
+      acctMap = new Map<string, ChannelAccessLevel>();
+      this.access.set(chanKey, acctMap);
+    }
+    if (level <= 0) {
+      acctMap.delete(folded(account));
+      // Drop the per-channel map when it ends up empty so the store does
+      // not leak empty maps across long-lived deployments.
+      if (acctMap.size === 0) this.access.delete(chanKey);
+      return;
+    }
+    acctMap.set(folded(account), level);
+  }
+
+  getChannelAccess(channel: string, account: string): ChannelAccessLevel {
+    return this.access.get(folded(channel))?.get(folded(account)) ?? 0;
+  }
+
+  listChannelAccess(channel: string): ReadonlyArray<{ account: string; level: number }> {
+    // The reference store does not retain the original spelling of the
+    // account alongside the level (the key is rfc1459-folded). Until a
+    // persistent backend ships with a canonical-spelling column, LIST
+    // renders the folded key verbatim — IRC nicks are case-insensitive
+    // under CASEMAPPING=rfc1459, so the rendered text still resolves to
+    // the same identity.
+    const acctMap = this.access.get(folded(channel));
+    if (acctMap === undefined) return [];
+    const out: { account: string; level: number }[] = [];
+    for (const [account, level] of acctMap) out.push({ account, level });
+    return out;
+  }
+
+  getChannelLevel(channel: string, op: ChannelLevelOp): number | undefined {
+    return this.levels.get(folded(channel))?.get(op);
+  }
+
+  setChannelLevel(channel: string, op: ChannelLevelOp, level: number): void {
+    const chanKey = folded(channel);
+    let opMap = this.levels.get(chanKey);
+    if (opMap === undefined) {
+      opMap = new Map<ChannelLevelOp, number>();
+      this.levels.set(chanKey, opMap);
+    }
+    opMap.set(op, level);
+  }
+
+  listChannelLevels(channel: string): ReadonlyArray<{ op: ChannelLevelOp; level: number }> {
+    const opMap = this.levels.get(folded(channel));
+    if (opMap === undefined) return [];
+    const out: { op: ChannelLevelOp; level: number }[] = [];
+    for (const [op, level] of opMap) out.push({ op, level });
+    return out;
+  }
+
+  resetChannelLevels(channel: string): void {
+    this.levels.delete(folded(channel));
+  }
+
+  // ----- HostServ -----
+
+  setVhost(account: string, vhost: string): void {
+    const key = folded(account);
+    if (vhost === '') {
+      this.vhosts.delete(key);
+      return;
+    }
+    this.vhosts.set(key, vhost);
+  }
+
+  getVhost(account: string): string | undefined {
+    return this.vhosts.get(folded(account));
+  }
+
+  requestVhost(account: string, vhost: string): void {
+    this.pendingVhosts.set(folded(account), vhost);
+  }
+
+  getPendingVhost(account: string): string | undefined {
+    return this.pendingVhosts.get(folded(account));
+  }
+
+  listPendingVhosts(): ReadonlyArray<{ account: string; vhost: string }> {
+    const out: { account: string; vhost: string }[] = [];
+    for (const [account, vhost] of this.pendingVhosts) out.push({ account, vhost });
+    return out;
+  }
+
+  approveVhost(account: string): string | undefined {
+    const key = folded(account);
+    const vhost = this.pendingVhosts.get(key);
+    if (vhost === undefined) return undefined;
+    this.pendingVhosts.delete(key);
+    this.setVhost(account, vhost);
+    return vhost;
+  }
+
+  rejectVhost(account: string): string | undefined {
+    const key = folded(account);
+    const vhost = this.pendingVhosts.get(key);
+    if (vhost === undefined) return undefined;
+    this.pendingVhosts.delete(key);
+    return vhost;
+  }
+
+  // ----- MemoServ -----
+
+  recordMemo(memo: MemoInput): number {
+    const id = ++this.memoCounter;
+    const entry: MemoEntry = { ...memo, id, read: false };
+    const key = folded(memo.to);
+    let arr = this.memosByAccount.get(key);
+    if (arr === undefined) {
+      arr = [];
+      this.memosByAccount.set(key, arr);
+    }
+    arr.push(entry);
+    return id;
+  }
+
+  listMemos(account: string): ReadonlyArray<MemoEntry> {
+    const arr = this.memosByAccount.get(folded(account));
+    if (arr === undefined) return [];
+    // Defensive copy of each entry so callers cannot mutate the stored
+    // memo records (e.g. flipping `read`) by editing the returned array.
+    return arr.map((m) => ({ ...m }));
+  }
+
+  markMemoRead(account: string, id: number): boolean {
+    const arr = this.memosByAccount.get(folded(account));
+    if (arr === undefined) return false;
+    const memo = arr.find((m) => m.id === id);
+    if (memo === undefined) return false;
+    memo.read = true;
+    return true;
+  }
+
+  deleteMemo(account: string, id: number): boolean {
+    const key = folded(account);
+    const arr = this.memosByAccount.get(key);
+    if (arr === undefined) return false;
+    const idx = arr.findIndex((m) => m.id === id);
+    if (idx === -1) return false;
+    arr.splice(idx, 1);
+    if (arr.length === 0) {
+      this.memosByAccount.delete(key);
+    }
+    return true;
+  }
+
+  // ----- Read-marker (IRCv3 draft/read-marker) -----
+
+  getLastReadMarker(account: string, channel: string): string | undefined {
+    return this.readMarkersByAccount.get(folded(account))?.get(folded(channel));
+  }
+
+  setLastReadMarker(account: string, channel: string, msgid: string): void {
+    const acct = folded(account);
+    let chanMap = this.readMarkersByAccount.get(acct);
+    if (chanMap === undefined) {
+      chanMap = new Map<string, string>();
+      this.readMarkersByAccount.set(acct, chanMap);
+    }
+    chanMap.set(folded(channel), msgid);
+  }
+
+  listReadMarkers(account: string): ReadonlyArray<ReadMarkerEntry> {
+    const chanMap = this.readMarkersByAccount.get(folded(account));
+    if (chanMap === undefined) return [];
+    const out: ReadMarkerEntry[] = [];
+    for (const [channel, msgid] of chanMap) {
+      out.push({ account, channel, msgid });
+    }
+    return out;
+  }
+
+  // ----- OperServ -----
+
+  addAkill(mask: string, reason: string): void {
+    const maskKey = folded(mask);
+    const now = this.clock.now();
+    const existing = this.akillsByKey.get(maskKey);
+    if (existing !== undefined) {
+      // Replace-in-place preserves insertion order while updating the
+      // reason + timestamp so a re-add does not silently demote the mask.
+      existing.reason = reason;
+      existing.createdAt = now;
+      existing.mask = mask;
+      return;
+    }
+    const entry: StoredAkill = { mask, reason, createdAt: now, maskKey };
+    this.akills.push(entry);
+    this.akillsByKey.set(maskKey, entry);
+  }
+
+  removeAkill(mask: string): boolean {
+    const maskKey = folded(mask);
+    const existing = this.akillsByKey.get(maskKey);
+    if (existing === undefined) return false;
+    this.akillsByKey.delete(maskKey);
+    // `existing` is guaranteed present in `akills`: every `addAkill` path
+    // that populates `akillsByKey` also pushes to the array (replace-in-place
+    // mutates the shared reference), and the two are mutated in lockstep.
+    this.akills.splice(this.akills.indexOf(existing), 1);
+    return true;
+  }
+
+  listAkills(): ReadonlyArray<AkillEntry> {
+    return this.akills.map((e) => ({ mask: e.mask, reason: e.reason, createdAt: e.createdAt }));
+  }
+
+  matchAkill(hostmask: string): AkillEntry | undefined {
+    for (const entry of this.akills) {
+      if (matchesAkillMask(entry.mask, hostmask)) {
+        // Defensive copy so a caller cannot mutate the stored record by
+        // editing the returned entry.
+        return { mask: entry.mask, reason: entry.reason, createdAt: entry.createdAt };
+      }
+    }
+    return undefined;
+  }
+
+  addJupe(name: string, reason?: string): void {
+    const nameKey = folded(name);
+    const now = this.clock.now();
+    const existing = this.jupesByKey.get(nameKey);
+    if (existing !== undefined) {
+      existing.reason = reason ?? '';
+      existing.createdAt = now;
+      existing.name = name;
+      return;
+    }
+    const entry: StoredJupe = { name, reason: reason ?? '', createdAt: now, nameKey };
+    this.jupes.push(entry);
+    this.jupesByKey.set(nameKey, entry);
+  }
+
+  removeJupe(name: string): boolean {
+    const nameKey = folded(name);
+    const existing = this.jupesByKey.get(nameKey);
+    if (existing === undefined) return false;
+    this.jupesByKey.delete(nameKey);
+    // `existing` is guaranteed present in `jupes`: every `addJupe` path
+    // that populates `jupesByKey` also pushes to the array (replace-in-place
+    // mutates the shared reference), and the two are mutated in lockstep.
+    this.jupes.splice(this.jupes.indexOf(existing), 1);
+    return true;
+  }
+
+  isJuped(name: string): boolean {
+    return this.jupesByKey.has(folded(name));
+  }
+
+  getJupe(name: string): JupeEntry | undefined {
+    const entry = this.jupesByKey.get(folded(name));
+    if (entry === undefined) return undefined;
+    return { name: entry.name, reason: entry.reason, createdAt: entry.createdAt };
+  }
+
+  listJupes(): ReadonlyArray<JupeEntry> {
+    return this.jupes.map((e) => ({ name: e.name, reason: e.reason, createdAt: e.createdAt }));
+  }
+}
+
+/**
+ * Write-behind base class for persistent {@link ServicesStore} backends
+ * (D1, DynamoDB). Subclasses pre-load a {@link ServicesSnapshot} at boot
+ * via the constructor option and implement {@link applyWrites} to drain
+ * queued {@link ServicesWrite} ops into the adapter backend.
+ *
+ * The services port is synchronous (reducers stay free of IO); this base
+ * keeps that contract by mutating the inherited
+ * {@link InMemoryServicesStore} cache synchronously and enqueueing a
+ * matching write-behind op per mutation. The reducer sees the new state
+ * immediately; the backend lags behind until `flush()` is awaited (the
+ * adapter calls `flush()` at the end of each connection turn / invocation).
+ *
+ * No-op mutations (e.g. `dropNick` on an unregistered nick, `removeAkill`
+ * on an unknown mask) enqueue nothing — only mutations that changed the
+ * in-memory cache produce a write. Concurrent `flush()` calls coalesce
+ * into a single {@link applyWrites} invocation so a turn that triggers
+ * many reducers persists one batch, not N.
+ */
+export abstract class PersistentServicesStore extends InMemoryServicesStore {
+  /**
+   * Pending write-behind ops accumulated since the last `flush()`. Drained
+   * in insertion order so a backend that cares about ordering (e.g. an
+   * upsert followed by a delete on the same key) sees the ops in the
+   * order the reducers produced them.
+   */
+  private readonly pending: ServicesWrite[] = [];
+  /**
+   * The in-flight {@link applyWrites} promise, or `undefined` when no
+   * flush is running. Concurrent `flush()` callers receive this same
+   * promise so the backend is asked to persist once, not once per caller.
+   */
+  private inFlight: Promise<void> | undefined = undefined;
+
+  constructor(opts: { clock?: Clock; snapshot?: ServicesSnapshot } = {}) {
+    super(opts);
+  }
+
+  /**
+   * Drains `writes` into the adapter backend. Subclasses translate each
+   * {@link ServicesWrite} into the backend's native upsert / delete
+   * (D1 `INSERT OR REPLACE`, DynamoDB `PutItem` / `DeleteItem`). The
+   * base class never calls this with an empty array.
+   */
+  protected abstract applyWrites(writes: ServicesWrite[]): Promise<void>;
+
+  /**
+   * Appends `write` to the pending queue. Called by every overridden
+   * mutator after the synchronous cache update has landed.
+   */
+  private enqueue(write: ServicesWrite): void {
+    this.pending.push(write);
+  }
+
+  /**
+   * Drains the pending queue into the backend.
+   *
+   * Returns immediately with `Promise.resolve()` when no mutations are
+   * pending and no flush is in flight (the common case on a quiescent
+   * turn). When mutations are pending, drains them into a single
+   * {@link applyWrites} batch and tracks the promise on
+   * {@link inFlight} so concurrent callers coalesce onto the same drain.
+   */
+  flush(): Promise<void> {
+    if (this.inFlight !== undefined) return this.inFlight;
+    if (this.pending.length === 0) return Promise.resolve();
+    const writes = this.pending.splice(0);
+    const p = this.applyWrites(writes);
+    this.inFlight = p;
+    // Clear the slot once the backend settles so a later mutation can
+    // start a fresh drain. `void` — the returned promise is independent
+    // of `p`, which is what callers await.
+    void p.finally(() => {
+      this.inFlight = undefined;
+    });
+    return p;
+  }
+
+  // ----- NickServ -----
+
+  override registerNick(nick: string, password: string, email: string): ServicesAuthResult {
+    const result = super.registerNick(nick, password, email);
+    if (result.ok) {
+      // `result.ok` guarantees the nick is registered, so `getStoredNick`
+      // is defined; re-persist the full row (hashed credential included)
+      // for the upsert.
+      const row = this.getStoredNick(nick) as ServicesNickRow;
+      this.enqueue({ kind: 'upsertNick', row });
+    }
+    return result;
+  }
+
+  override dropNick(nick: string): boolean {
+    const removed = super.dropNick(nick);
+    if (removed) this.enqueue({ kind: 'deleteNick', nick });
+    return removed;
+  }
+
+  override setNickEnforce(nick: string, policy: NickEnforcePolicy): void {
+    if (!this.isRegisteredNick(nick)) return;
+    super.setNickEnforce(nick, policy);
+    // The `isRegisteredNick` guard above guarantees the nick is present, so
+    // `getStoredNick` is defined — read it back to capture the exact stored
+    // row (hashed credential included) for the upsert.
+    const row = this.getStoredNick(nick) as ServicesNickRow;
+    this.enqueue({ kind: 'upsertNick', row });
+  }
+
+  override ingestAccountCredential(credential: HashedAccountCredential): boolean {
+    const created = super.ingestAccountCredential(credential);
+    if (created) {
+      const row = this.getStoredNick(credential.account) as ServicesNickRow | undefined;
+      if (row !== undefined) this.enqueue({ kind: 'upsertNick', row });
+    }
+    return created;
+  }
+
+  // ----- ChanServ -----
+
+  override registerChannel(channel: string, founder: string): ChannelRegisterResult {
+    const result = super.registerChannel(channel, founder);
+    if (result.ok) {
+      // `result.ok` guarantees the channel is registered, so `getChannel`
+      // is defined — read it back to capture the full row super stored.
+      const rec = this.getChannel(channel) as RegisteredChannel;
+      this.enqueue({ kind: 'upsertChannel', row: rec });
+    }
+    return result;
+  }
+
+  override dropChannel(channel: string): boolean {
+    const removed = super.dropChannel(channel);
+    if (removed) this.enqueue({ kind: 'deleteChannel', channel });
+    return removed;
+  }
+
+  override setChannelFounder(channel: string, account: string): void {
+    super.setChannelFounder(channel, account);
+    const rec = this.getChannel(channel);
+    if (rec !== undefined) this.enqueue({ kind: 'upsertChannel', row: rec });
+  }
+
+  override setChannelMlock(channel: string, modestring: string): void {
+    super.setChannelMlock(channel, modestring);
+    const rec = this.getChannel(channel);
+    if (rec !== undefined) this.enqueue({ kind: 'upsertChannel', row: rec });
+  }
+
+  override setChannelRestricted(channel: string, on: boolean): void {
+    super.setChannelRestricted(channel, on);
+    const rec = this.getChannel(channel);
+    if (rec !== undefined) this.enqueue({ kind: 'upsertChannel', row: rec });
+  }
+
+  override setChannelKeepTopic(channel: string, on: boolean): void {
+    super.setChannelKeepTopic(channel, on);
+    const rec = this.getChannel(channel);
+    if (rec !== undefined) this.enqueue({ kind: 'upsertChannel', row: rec });
+  }
+
+  override setChannelTopic(channel: string, topic: PersistedTopic | undefined): void {
+    super.setChannelTopic(channel, topic);
+    const rec = this.getChannel(channel);
+    if (rec !== undefined) this.enqueue({ kind: 'upsertChannel', row: rec });
+  }
+
+  override setChannelAccess(channel: string, account: string, level: ChannelAccessLevel): void {
+    const existed = this.getChannelAccess(channel, account) > 0;
+    super.setChannelAccess(channel, account, level);
+    if (level > 0) {
+      this.enqueue({ kind: 'upsertChannelAccess', row: { channel, account, level } });
+    } else if (existed) {
+      this.enqueue({ kind: 'deleteChannelAccess', channel, account });
+    }
+  }
+
+  override setChannelLevel(channel: string, op: ChannelLevelOp, level: number): void {
+    super.setChannelLevel(channel, op, level);
+    this.enqueue({ kind: 'upsertChannelLevel', row: { channel, op, level } });
+  }
+
+  override resetChannelLevels(channel: string): void {
+    super.resetChannelLevels(channel);
+    this.enqueue({ kind: 'resetChannelLevels', channel });
+  }
+
+  // ----- HostServ -----
+
+  override setVhost(account: string, vhost: string): void {
+    const existed = this.getVhost(account) !== undefined;
+    super.setVhost(account, vhost);
+    if (vhost !== '') {
+      this.enqueue({ kind: 'upsertVhost', row: { account, vhost } });
+    } else if (existed) {
+      this.enqueue({ kind: 'deleteVhost', account });
+    }
+  }
+
+  override requestVhost(account: string, vhost: string): void {
+    super.requestVhost(account, vhost);
+    this.enqueue({ kind: 'upsertPendingVhost', row: { account, vhost } });
+  }
+
+  override approveVhost(account: string): string | undefined {
+    const vhost = super.approveVhost(account);
+    if (vhost !== undefined) {
+      this.enqueue({ kind: 'deletePendingVhost', account });
+      this.enqueue({ kind: 'upsertVhost', row: { account, vhost } });
+    }
+    return vhost;
+  }
+
+  override rejectVhost(account: string): string | undefined {
+    const vhost = super.rejectVhost(account);
+    if (vhost !== undefined) {
+      this.enqueue({ kind: 'deletePendingVhost', account });
+    }
+    return vhost;
+  }
+
+  // ----- MemoServ -----
+
+  override recordMemo(memo: MemoInput): number {
+    const id = super.recordMemo(memo);
+    this.enqueue({ kind: 'insertMemo', row: { ...memo, id, read: false } });
+    return id;
+  }
+
+  override markMemoRead(account: string, id: number): boolean {
+    const marked = super.markMemoRead(account, id);
+    if (marked) this.enqueue({ kind: 'updateMemoRead', account, id });
+    return marked;
+  }
+
+  override deleteMemo(account: string, id: number): boolean {
+    const removed = super.deleteMemo(account, id);
+    if (removed) this.enqueue({ kind: 'deleteMemo', account, id });
+    return removed;
+  }
+
+  // ----- Read-marker (IRCv3 draft/read-marker) -----
+
+  override setLastReadMarker(account: string, channel: string, msgid: string): void {
+    super.setLastReadMarker(account, channel, msgid);
+    this.enqueue({ kind: 'upsertReadMarker', row: { account, channel, msgid } });
+  }
+
+  // ----- OperServ -----
+
+  override addAkill(mask: string, reason: string): void {
+    super.addAkill(mask, reason);
+    // super.addAkill always inserts (or replaces in place), so the entry is
+    // guaranteed present; read it back to capture the exact `createdAt`
+    // super stored (avoids a second `clock.now()` call drifting from the
+    // in-memory value).
+    const row = this.listAkills().find((a) => folded(a.mask) === folded(mask)) as AkillEntry;
+    this.enqueue({ kind: 'upsertAkill', row });
+  }
+
+  override removeAkill(mask: string): boolean {
+    const removed = super.removeAkill(mask);
+    if (removed) this.enqueue({ kind: 'deleteAkill', mask });
+    return removed;
+  }
+
+  override addJupe(name: string, reason?: string): void {
+    super.addJupe(name, reason);
+    const row = this.listJupes().find((j) => folded(j.name) === folded(name)) as JupeEntry;
+    this.enqueue({ kind: 'upsertJupe', row });
+  }
+
+  override removeJupe(name: string): boolean {
+    const removed = super.removeJupe(name);
+    if (removed) this.enqueue({ kind: 'deleteJupe', name });
+    return removed;
+  }
+}
+
+/**
+ * Returns true iff `hostmask` matches the IRC ban mask `mask`. Identical
+ * to the implementation in `privmsg.ts` / `join.ts`; duplicated so the
+ * services layer stays self-contained and the matching rule is testable
+ * in isolation. Comparison is case-insensitive (the `i` regex flag) so a
+ * `*!*@Bad.Example.Net` mask catches `evil!spam@bad.example.net`.
+ */
+function matchesAkillMask(mask: string, hostmask: string): boolean {
+  let pattern = '^';
+  for (const ch of mask) {
+    if (ch === '*') {
+      pattern += '.*';
+    } else if (ch === '?') {
+      pattern += '.';
+    } else if (/[A-Za-z0-9]/.test(ch)) {
+      pattern += ch;
+    } else {
+      pattern += `\\${ch}`;
+    }
+  }
+  pattern += '$';
+  return new RegExp(pattern, 'i').test(hostmask);
+}
+
 // ============================================================================
 // Nick history (WHOWAS)
 // ============================================================================