serverless-ircd 0.7.0 → 0.8.0

package/packages/cf-adapter/src/d1-services-store.ts

@@ -0,0 +1,703 @@
+/**
+ * D1-backed {@link PersistentServicesStore} for the Cloudflare adapter.
+ *
+ * Shares the `ACCOUNTS_DB` D1 binding from the SASL account store and
+ * lays out one table per services section so the whole
+ * {@link ServicesSnapshot} round-trips across a deploy:
+ *
+ *   - `nickserv_accounts`  — NickServ registrations (scrypt-hashed
+ *     credential: never plaintext; the unified account record so a
+ *     NickServ registration IS a SASL account).
+ *   - `chanserv_channels`  — ChanServ channel registrations (+ topic).
+ *   - `chanserv_access`    — ChanServ `(account, level)` access entries.
+ *   - `chanserv_levels`    — founder-redefined ChanServ level thresholds.
+ *   - `hostserv_vhosts`          — HostServ `(account, vhost)` entries.
+ *   - `hostserv_pending_vhosts`   — HostServ pending `(account, vhost)`
+ *     requests awaiting oper approval.
+ *   - `memoserv_memos`     — MemoServ queued memos (globally-unique id).
+ *   - `read_markers`       — per-`(account, channel)` draft/read-marker.
+ *   - `operserv_akills`    — OperServ AKILL roster.
+ *   - `operserv_jupes`     — OperServ JUPE roster.
+ *
+ * Boot path: {@link loadD1ServicesStore} scans every table into a
+ * {@link ServicesSnapshot} (tolerating a fresh deploy where the tables do
+ * not exist yet) and hands it to a `D1ServicesStore`. The store mutates
+ * the inherited in-memory cache synchronously and enqueues one
+ * {@link ServicesWrite} per mutation; `flush()` drains the queue into a
+ * single `db.batch([...])` round-trip.
+ *
+ * Case-insensitive lookups: every PK column is the rfc1459-folded key
+ * (`*_key`) so a re-registration of `Alice` overwrites `alice`. Display
+ * spelling is preserved in a separate column so the wire renders the
+ * user's preferred casing after a reload.
+ */
+
+import {
+  type AkillEntry,
+  type ChannelAccessLevel,
+  type ChannelLevelOp,
+  type Clock,
+  type JupeEntry,
+  type MemoEntry,
+  type NickEnforcePolicy,
+  type PersistedTopic,
+  PersistentServicesStore,
+  type RegisteredChannel,
+  type ServicesAccessRow,
+  type ServicesLevelRow,
+  type ServicesNickRow,
+  type ServicesPendingVhostRow,
+  type ServicesSnapshot,
+  type ServicesVhostRow,
+  type ServicesWrite,
+  SystemClock,
+  caseFold,
+} from '@serverless-ircd/irc-core';
+
+/** rfc1459 case-fold used for every storage key. */
+function fold(value: string): string {
+  return caseFold('rfc1459', value);
+}
+
+/**
+ * Minimal query surface shared by {@link D1Database} and
+ * {@link D1DatabaseSession}. The service loaders accept either so the
+ * snapshot hydrate can run through a session (for read-from-primary
+ * consistency) without the write path (`applyWrites`, which always targets
+ * the primary) caring which it is.
+ */
+interface D1QueryClient {
+  prepare(query: string): D1PreparedStatement;
+  batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
+}
+
+/**
+ * DDL for the ten services tables, in dependency-free order. Exported so
+ * the seed tool, the provisioning docs, and the test `beforeEach` reference
+ * one schema definition. Each statement is `IF NOT EXISTS` so re-running
+ * the list on a warm deploy is a no-op.
+ */
+export const CREATE_NICKSERV_ACCOUNTS_SQL =
+  'CREATE TABLE IF NOT EXISTS nickserv_accounts (nick_key TEXT PRIMARY KEY, nick TEXT NOT NULL, account TEXT NOT NULL, email TEXT NOT NULL, created_at INTEGER NOT NULL, enforce TEXT NOT NULL, algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)';
+
+export const CREATE_SERVICES_TABLES_SQL: readonly string[] = [
+  CREATE_NICKSERV_ACCOUNTS_SQL,
+  'CREATE TABLE IF NOT EXISTS chanserv_channels (channel_key TEXT PRIMARY KEY, channel TEXT NOT NULL, founder TEXT NOT NULL, created_at INTEGER NOT NULL, mlock TEXT NOT NULL, restricted INTEGER NOT NULL, keep_topic INTEGER NOT NULL, topic_text TEXT, topic_setter TEXT, topic_set_at INTEGER)',
+  'CREATE TABLE IF NOT EXISTS chanserv_access (channel_key TEXT NOT NULL, account_key TEXT NOT NULL, channel TEXT NOT NULL, account TEXT NOT NULL, level INTEGER NOT NULL, PRIMARY KEY (channel_key, account_key))',
+  'CREATE TABLE IF NOT EXISTS chanserv_levels (channel_key TEXT NOT NULL, op TEXT NOT NULL, channel TEXT NOT NULL, level INTEGER NOT NULL, PRIMARY KEY (channel_key, op))',
+  'CREATE TABLE IF NOT EXISTS hostserv_vhosts (account_key TEXT PRIMARY KEY, account TEXT NOT NULL, vhost TEXT NOT NULL)',
+  'CREATE TABLE IF NOT EXISTS hostserv_pending_vhosts (account_key TEXT PRIMARY KEY, account TEXT NOT NULL, vhost TEXT NOT NULL)',
+  'CREATE TABLE IF NOT EXISTS memoserv_memos (id INTEGER PRIMARY KEY, from_account TEXT NOT NULL, to_account TEXT NOT NULL, body TEXT NOT NULL, sent_at INTEGER NOT NULL, read INTEGER NOT NULL)',
+  'CREATE TABLE IF NOT EXISTS read_markers (account_key TEXT NOT NULL, channel_key TEXT NOT NULL, account TEXT NOT NULL, channel TEXT NOT NULL, msgid TEXT NOT NULL, PRIMARY KEY (account_key, channel_key))',
+  'CREATE TABLE IF NOT EXISTS operserv_akills (mask_key TEXT PRIMARY KEY, mask TEXT NOT NULL, reason TEXT NOT NULL, created_at INTEGER NOT NULL)',
+  'CREATE TABLE IF NOT EXISTS operserv_jupes (name_key TEXT PRIMARY KEY, name TEXT NOT NULL, reason TEXT NOT NULL, created_at INTEGER NOT NULL)',
+];
+
+/**
+ * D1-backed persistent services store. Extends the shared
+ * {@link PersistentServicesStore} write-behind base; the cache is hydrated
+ * from the snapshot loaded by {@link loadD1ServicesStore} at construction.
+ *
+ * `applyWrites` translates each {@link ServicesWrite} into one (or more)
+ * prepared statements and runs them in a single `db.batch()` round-trip
+ * per `flush()`.
+ */
+export class D1ServicesStore extends PersistentServicesStore {
+  private readonly db: D1Database;
+
+  constructor(opts: { db: D1Database; clock?: Clock; snapshot?: ServicesSnapshot }) {
+    const superOpts: { clock?: Clock; snapshot?: ServicesSnapshot } = {};
+    if (opts.clock !== undefined) superOpts.clock = opts.clock;
+    if (opts.snapshot !== undefined) superOpts.snapshot = opts.snapshot;
+    super(superOpts);
+    this.db = opts.db;
+  }
+
+  protected async applyWrites(writes: ServicesWrite[]): Promise<void> {
+    const stmts: D1PreparedStatement[] = [];
+    for (const w of writes) {
+      for (const stmt of this.statementsFor(w)) stmts.push(stmt);
+    }
+    // The base class never calls applyWrites with an empty queue, and every
+    // ServicesWrite maps to ≥1 statement, so `stmts` is non-empty here.
+    await this.db.batch(stmts);
+  }
+
+  /**
+   * Maps a single {@link ServicesWrite} to its prepared statement(s).
+   * `deleteChannel` fans out into three deletes (channel + access +
+   * levels) so the backend wipes the channel's whole subtree in one
+   * batch.
+   */
+  private statementsFor(w: ServicesWrite): D1PreparedStatement[] {
+    switch (w.kind) {
+      case 'upsertNick': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO nickserv_accounts (nick_key, nick, account, email, created_at, enforce, algorithm, salt, hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+            )
+            .bind(
+              fold(r.nick),
+              r.nick,
+              r.account,
+              r.email,
+              r.createdAt,
+              r.enforce,
+              r.credential.algorithm,
+              r.credential.salt,
+              r.credential.hash,
+            ),
+        ];
+      }
+      case 'deleteNick':
+        return [
+          this.db.prepare('DELETE FROM nickserv_accounts WHERE nick_key = ?').bind(fold(w.nick)),
+        ];
+      case 'upsertChannel': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO chanserv_channels (channel_key, channel, founder, created_at, mlock, restricted, keep_topic, topic_text, topic_setter, topic_set_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+            )
+            .bind(
+              fold(r.channel),
+              r.channel,
+              r.founder,
+              r.createdAt,
+              r.mlock,
+              r.restricted ? 1 : 0,
+              r.keepTopic ? 1 : 0,
+              r.topic?.text ?? null,
+              r.topic?.setter ?? null,
+              r.topic?.setAt ?? null,
+            ),
+        ];
+      }
+      case 'deleteChannel':
+        return [
+          this.db
+            .prepare('DELETE FROM chanserv_channels WHERE channel_key = ?')
+            .bind(fold(w.channel)),
+          this.db
+            .prepare('DELETE FROM chanserv_access WHERE channel_key = ?')
+            .bind(fold(w.channel)),
+          this.db
+            .prepare('DELETE FROM chanserv_levels WHERE channel_key = ?')
+            .bind(fold(w.channel)),
+        ];
+      case 'upsertChannelAccess': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO chanserv_access (channel_key, account_key, channel, account, level) VALUES (?, ?, ?, ?, ?)',
+            )
+            .bind(fold(r.channel), fold(r.account), r.channel, r.account, r.level),
+        ];
+      }
+      case 'deleteChannelAccess':
+        return [
+          this.db
+            .prepare('DELETE FROM chanserv_access WHERE channel_key = ? AND account_key = ?')
+            .bind(fold(w.channel), fold(w.account)),
+        ];
+      case 'upsertChannelLevel': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO chanserv_levels (channel_key, op, channel, level) VALUES (?, ?, ?, ?)',
+            )
+            .bind(fold(r.channel), r.op, r.channel, r.level),
+        ];
+      }
+      case 'resetChannelLevels':
+        return [
+          this.db
+            .prepare('DELETE FROM chanserv_levels WHERE channel_key = ?')
+            .bind(fold(w.channel)),
+        ];
+      case 'upsertVhost': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO hostserv_vhosts (account_key, account, vhost) VALUES (?, ?, ?)',
+            )
+            .bind(fold(r.account), r.account, r.vhost),
+        ];
+      }
+      case 'deleteVhost':
+        return [
+          this.db
+            .prepare('DELETE FROM hostserv_vhosts WHERE account_key = ?')
+            .bind(fold(w.account)),
+        ];
+      case 'upsertPendingVhost': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO hostserv_pending_vhosts (account_key, account, vhost) VALUES (?, ?, ?)',
+            )
+            .bind(fold(r.account), r.account, r.vhost),
+        ];
+      }
+      case 'deletePendingVhost':
+        return [
+          this.db
+            .prepare('DELETE FROM hostserv_pending_vhosts WHERE account_key = ?')
+            .bind(fold(w.account)),
+        ];
+      case 'insertMemo': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO memoserv_memos (id, from_account, to_account, body, sent_at, read) VALUES (?, ?, ?, ?, ?, ?)',
+            )
+            .bind(r.id, r.from, r.to, r.body, r.sentAt, 0),
+        ];
+      }
+      case 'updateMemoRead':
+        return [this.db.prepare('UPDATE memoserv_memos SET read = 1 WHERE id = ?').bind(w.id)];
+      case 'deleteMemo':
+        return [this.db.prepare('DELETE FROM memoserv_memos WHERE id = ?').bind(w.id)];
+      case 'upsertReadMarker': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO read_markers (account_key, channel_key, account, channel, msgid) VALUES (?, ?, ?, ?, ?)',
+            )
+            .bind(fold(r.account), fold(r.channel), r.account, r.channel, r.msgid),
+        ];
+      }
+      case 'upsertAkill': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO operserv_akills (mask_key, mask, reason, created_at) VALUES (?, ?, ?, ?)',
+            )
+            .bind(fold(r.mask), r.mask, r.reason, r.createdAt),
+        ];
+      }
+      case 'deleteAkill':
+        return [
+          this.db.prepare('DELETE FROM operserv_akills WHERE mask_key = ?').bind(fold(w.mask)),
+        ];
+      case 'upsertJupe': {
+        const r = w.row;
+        return [
+          this.db
+            .prepare(
+              'INSERT OR REPLACE INTO operserv_jupes (name_key, name, reason, created_at) VALUES (?, ?, ?, ?)',
+            )
+            .bind(fold(r.name), r.name, r.reason, r.createdAt),
+        ];
+      }
+      case 'deleteJupe':
+        return [
+          this.db.prepare('DELETE FROM operserv_jupes WHERE name_key = ?').bind(fold(w.name)),
+        ];
+    }
+  }
+}
+
+/**
+ * Scans every services table into a {@link ServicesSnapshot}, tolerating a
+ * fresh deploy where the tables do not exist yet (each `SELECT` that
+ * throws is treated as an empty section). Returns the empty snapshot when
+ * the binding is present but unprovisioned so the caller can still mutate
+ * + flush. Callers should run {@link ensureServicesTables} first to
+ * self-provision the schema; this loader stays defensive regardless.
+ */
+async function loadSnapshot(db: D1QueryClient): Promise<ServicesSnapshot> {
+  const [
+    nicks,
+    channels,
+    access,
+    levels,
+    vhosts,
+    pendingVhosts,
+    memos,
+    readMarkers,
+    akills,
+    jupes,
+  ] = await Promise.all([
+    loadNicks(db),
+    loadChannels(db),
+    loadAccess(db),
+    loadLevels(db),
+    loadVhosts(db),
+    loadPendingVhosts(db),
+    loadMemos(db),
+    loadReadMarkers(db),
+    loadAkills(db),
+    loadJupes(db),
+  ]);
+  return {
+    nicks,
+    channels,
+    access,
+    levels,
+    vhosts,
+    pendingVhosts,
+    memos,
+    readMarkers,
+    akills,
+    jupes,
+  };
+}
+
+async function loadNicks(db: D1QueryClient): Promise<ServicesNickRow[]> {
+  const rows = await safeSelect<{
+    nick: unknown;
+    account: unknown;
+    email: unknown;
+    created_at: unknown;
+    enforce: unknown;
+    algorithm: unknown;
+    salt: unknown;
+    hash: unknown;
+  }>(
+    db,
+    'SELECT nick, account, email, created_at, enforce, algorithm, salt, hash FROM nickserv_accounts',
+  );
+  const out: ServicesNickRow[] = [];
+  for (const r of rows) {
+    if (
+      typeof r.nick !== 'string' ||
+      typeof r.account !== 'string' ||
+      typeof r.email !== 'string' ||
+      typeof r.created_at !== 'number' ||
+      typeof r.enforce !== 'string' ||
+      typeof r.algorithm !== 'string' ||
+      typeof r.salt !== 'string' ||
+      typeof r.hash !== 'string'
+    ) {
+      continue;
+    }
+    out.push({
+      nick: r.nick,
+      account: r.account,
+      email: r.email,
+      createdAt: r.created_at,
+      enforce: r.enforce as NickEnforcePolicy,
+      credential: {
+        account: r.account,
+        algorithm: 'scrypt',
+        salt: r.salt,
+        hash: r.hash,
+      },
+    });
+  }
+  return out;
+}
+
+async function loadChannels(db: D1QueryClient): Promise<RegisteredChannel[]> {
+  const rows = await safeSelect<{
+    channel: unknown;
+    founder: unknown;
+    created_at: unknown;
+    mlock: unknown;
+    restricted: unknown;
+    keep_topic: unknown;
+    topic_text: unknown;
+    topic_setter: unknown;
+    topic_set_at: unknown;
+  }>(
+    db,
+    'SELECT channel, founder, created_at, mlock, restricted, keep_topic, topic_text, topic_setter, topic_set_at FROM chanserv_channels',
+  );
+  const out: RegisteredChannel[] = [];
+  for (const r of rows) {
+    if (
+      typeof r.channel !== 'string' ||
+      typeof r.founder !== 'string' ||
+      typeof r.created_at !== 'number' ||
+      typeof r.mlock !== 'string' ||
+      typeof r.restricted !== 'number' ||
+      typeof r.keep_topic !== 'number'
+    ) {
+      continue;
+    }
+    const channel: RegisteredChannel = {
+      channel: r.channel,
+      founder: r.founder,
+      createdAt: r.created_at,
+      mlock: r.mlock,
+      restricted: r.restricted !== 0,
+      keepTopic: r.keep_topic !== 0,
+    };
+    if (
+      typeof r.topic_text === 'string' &&
+      typeof r.topic_setter === 'string' &&
+      typeof r.topic_set_at === 'number'
+    ) {
+      const topic: PersistedTopic = {
+        text: r.topic_text,
+        setter: r.topic_setter,
+        setAt: r.topic_set_at,
+      };
+      channel.topic = topic;
+    }
+    out.push(channel);
+  }
+  return out;
+}
+
+async function loadAccess(db: D1QueryClient): Promise<ServicesAccessRow[]> {
+  const rows = await safeSelect<{ channel: unknown; account: unknown; level: unknown }>(
+    db,
+    'SELECT channel, account, level FROM chanserv_access',
+  );
+  const out: ServicesAccessRow[] = [];
+  for (const r of rows) {
+    if (
+      typeof r.channel !== 'string' ||
+      typeof r.account !== 'string' ||
+      typeof r.level !== 'number'
+    )
+      continue;
+    out.push({ channel: r.channel, account: r.account, level: r.level as ChannelAccessLevel });
+  }
+  return out;
+}
+
+async function loadLevels(db: D1QueryClient): Promise<ServicesLevelRow[]> {
+  const rows = await safeSelect<{ channel: unknown; op: unknown; level: unknown }>(
+    db,
+    'SELECT channel, op, level FROM chanserv_levels',
+  );
+  const out: ServicesLevelRow[] = [];
+  for (const r of rows) {
+    if (typeof r.channel !== 'string' || typeof r.op !== 'string' || typeof r.level !== 'number')
+      continue;
+    out.push({ channel: r.channel, op: r.op as ChannelLevelOp, level: r.level });
+  }
+  return out;
+}
+
+async function loadVhosts(db: D1QueryClient): Promise<ServicesVhostRow[]> {
+  const rows = await safeSelect<{ account: unknown; vhost: unknown }>(
+    db,
+    'SELECT account, vhost FROM hostserv_vhosts',
+  );
+  const out: ServicesVhostRow[] = [];
+  for (const r of rows) {
+    if (typeof r.account !== 'string' || typeof r.vhost !== 'string') continue;
+    out.push({ account: r.account, vhost: r.vhost });
+  }
+  return out;
+}
+
+async function loadPendingVhosts(db: D1QueryClient): Promise<ServicesPendingVhostRow[]> {
+  const rows = await safeSelect<{ account: unknown; vhost: unknown }>(
+    db,
+    'SELECT account, vhost FROM hostserv_pending_vhosts',
+  );
+  const out: ServicesPendingVhostRow[] = [];
+  for (const r of rows) {
+    if (typeof r.account !== 'string' || typeof r.vhost !== 'string') continue;
+    out.push({ account: r.account, vhost: r.vhost });
+  }
+  return out;
+}
+
+async function loadMemos(db: D1QueryClient): Promise<MemoEntry[]> {
+  const rows = await safeSelect<{
+    id: unknown;
+    from_account: unknown;
+    to_account: unknown;
+    body: unknown;
+    sent_at: unknown;
+    read: unknown;
+  }>(db, 'SELECT id, from_account, to_account, body, sent_at, read FROM memoserv_memos');
+  const out: MemoEntry[] = [];
+  for (const r of rows) {
+    if (
+      typeof r.id !== 'number' ||
+      typeof r.from_account !== 'string' ||
+      typeof r.to_account !== 'string' ||
+      typeof r.body !== 'string' ||
+      typeof r.sent_at !== 'number' ||
+      typeof r.read !== 'number'
+    ) {
+      continue;
+    }
+    out.push({
+      id: r.id,
+      from: r.from_account,
+      to: r.to_account,
+      body: r.body,
+      sentAt: r.sent_at,
+      read: r.read !== 0,
+    });
+  }
+  return out;
+}
+
+async function loadReadMarkers(
+  db: D1QueryClient,
+): Promise<{ account: string; channel: string; msgid: string }[]> {
+  const rows = await safeSelect<{ account: unknown; channel: unknown; msgid: unknown }>(
+    db,
+    'SELECT account, channel, msgid FROM read_markers',
+  );
+  const out: { account: string; channel: string; msgid: string }[] = [];
+  for (const r of rows) {
+    if (
+      typeof r.account !== 'string' ||
+      typeof r.channel !== 'string' ||
+      typeof r.msgid !== 'string'
+    )
+      continue;
+    out.push({ account: r.account, channel: r.channel, msgid: r.msgid });
+  }
+  return out;
+}
+
+async function loadAkills(db: D1QueryClient): Promise<AkillEntry[]> {
+  const rows = await safeSelect<{ mask: unknown; reason: unknown; created_at: unknown }>(
+    db,
+    'SELECT mask, reason, created_at FROM operserv_akills',
+  );
+  const out: AkillEntry[] = [];
+  for (const r of rows) {
+    if (
+      typeof r.mask !== 'string' ||
+      typeof r.reason !== 'string' ||
+      typeof r.created_at !== 'number'
+    )
+      continue;
+    out.push({ mask: r.mask, reason: r.reason, createdAt: r.created_at });
+  }
+  return out;
+}
+
+async function loadJupes(db: D1QueryClient): Promise<JupeEntry[]> {
+  const rows = await safeSelect<{ name: unknown; reason: unknown; created_at: unknown }>(
+    db,
+    'SELECT name, reason, created_at FROM operserv_jupes',
+  );
+  const out: JupeEntry[] = [];
+  for (const r of rows) {
+    if (
+      typeof r.name !== 'string' ||
+      typeof r.reason !== 'string' ||
+      typeof r.created_at !== 'number'
+    )
+      continue;
+    out.push({ name: r.name, reason: r.reason, createdAt: r.created_at });
+  }
+  return out;
+}
+
+/**
+ * Runs `sql` against `db` and returns `result.results`, or `[]` when the
+ * table does not exist yet (fresh deploy) or the binding is unreachable.
+ * Silent-skip mirrors the DynamoDB loader: a missing table is treated as
+ * an empty section rather than a fatal boot error.
+ */
+async function safeSelect<R>(db: D1QueryClient, sql: string): Promise<R[]> {
+  try {
+    const result = await db.prepare(sql).all<R>();
+    return result.results;
+  } catch (err) {
+    // A missing table on a fresh deploy legitimately yields no rows, but a
+    // real D1 error (transient unavailability, a lagging replica, a schema
+    // drift) would otherwise be masked as "empty section" — bricking
+    // NickServ for the whole connection (the snapshot is cached for life).
+    // Surface it so the failure shows up in `wrangler tail`.
+    console.error('[d1-services-store] snapshot read failed', { sql, error: String(err) });
+    return [];
+  }
+}
+
+/**
+ * Loads the full services snapshot from D1 and returns a hydrated
+ * {@link D1ServicesStore}. Returns `undefined` only when the D1 binding is
+ * absent (services not configured) — an empty binding still returns a
+ * working store so reducers can register state and persist it on the next
+ * `flush()`.
+ *
+ * @param db    The D1 binding (`undefined` when D1 is not configured).
+ * @param clock Optional injected clock (tests pass a {@link FakeClock};
+ *   production leaves it at {@link SystemClock}).
+ */
+/**
+ * Idempotently creates the ten services tables so a fresh deploy
+ * self-provisions on first load without a manual DDL step. Every statement
+ * is `CREATE TABLE IF NOT EXISTS`, so a warm deploy re-runs the batch as a
+ * cheap no-op. Without this, `loadD1ServicesStore` loads an empty snapshot
+ * (the `SELECT`s hit `safeSelect`'s table-missing branch) and the first
+ * `flush()` throws on the missing table — registrations would appear to
+ * succeed (the NOTICE is emitted before flush) yet never persist, so a
+ * reconnecting client finds nothing in D1.
+ *
+ * Runs as one `db.batch()` round-trip (one D1 call per cold start / DO).
+ */
+async function ensureServicesTables(db: D1QueryClient): Promise<void> {
+  await db.batch(CREATE_SERVICES_TABLES_SQL.map((sql) => db.prepare(sql)));
+  await migrateServicesSchema(db);
+}
+
+/**
+ * One-time schema migration for the `algorithm/salt/hash` unification
+ * (commit cfa5a3c). `CREATE TABLE IF NOT EXISTS` does NOT add columns to
+ * an existing table, so a D1 first provisioned by an older deploy keeps
+ * the original `nickserv_accounts (... enforce, password)` schema. Every
+ * current SELECT/INSERT references `algorithm`, so reads throw
+ * "no such column: algorithm" (masked by `safeSelect` as an empty
+ * snapshot) and writes throw inside `flush()` (after the success NOTICE).
+ *
+ * Detection: `PRAGMA table_info`. If `nickserv_accounts` lacks
+ * `algorithm`, it is the pre-unification schema. Those rows stored a
+ * non-scrypt `password` the current `verifyNick` cannot validate, so the
+ * table is dropped and recreated with the current schema (data loss is
+ * intentional and limited to already-unusable credentials). Idempotent:
+ * once the new schema is in place, `algorithm` is present and this is a
+ * no-op.
+ */
+async function migrateServicesSchema(db: D1QueryClient): Promise<void> {
+  const nickservInfo = await db
+    .prepare('PRAGMA table_info(nickserv_accounts)')
+    .all<{ name: string }>();
+  const nickservCols = new Set(nickservInfo.results.map((r) => r.name));
+  if (nickservCols.has('algorithm')) return;
+  // Old schema detected (has `password`, lacks `algorithm`). The table is
+  // guaranteed to exist (ensureServicesTables just ran CREATE IF NOT
+  // EXISTS); recreate it with the current schema.
+  await db.batch([
+    db.prepare('DROP TABLE nickserv_accounts'),
+    db.prepare(CREATE_NICKSERV_ACCOUNTS_SQL),
+  ]);
+}
+
+export async function loadD1ServicesStore(
+  db: D1Database | undefined,
+  clock: Clock = SystemClock,
+): Promise<D1ServicesStore | undefined> {
+  if (db === undefined) return undefined;
+  // Read services state from the D1 PRIMARY. When read replication is
+  // enabled on the database, D1 may otherwise serve these SELECTs from a
+  // replica that is "arbitrarily out of date" (Cloudflare D1 consistency
+  // docs). A freshly-connecting client would then hydrate an empty/stale
+  // snapshot and cache it for the connection's whole life
+  // (`servicesResolved` guard in ConnectionDO) — so a NickServ IDENTIFY
+  // reports "not registered" even though the row exists in the primary.
+  // `first-primary` forces the first query to the primary; sequential
+  // consistency within the session keeps the rest of the load in sync.
+  // Writes (flush → `this.db.batch`) always target the primary regardless,
+  // so the store still holds the raw `db` for `applyWrites`.
+  // Safe per Cloudflare docs even when read replication is disabled.
+  const session = db.withSession('first-primary');
+  await ensureServicesTables(session);
+  const snapshot = await loadSnapshot(session);
+  return new D1ServicesStore({ db, clock, snapshot });
+}