cursedbelt-server 1.0.0

package/src/server/ws/hub.ts

@@ -0,0 +1,168 @@
+import type { Server, ServerWebSocket } from 'bun';
+import type { MiddlewareHandler } from 'hono';
+import { ApiError, toErrorEnvelope } from '../errors';
+import { computePresence } from './presence';
+import { joinRoom, ROOM_META_KEY } from './room';
+import type {
+  WsChannel,
+  WsClient,
+  WsData,
+  WsHandshake,
+  WsHub,
+  WsHubOpts,
+  WsMessage,
+} from './types';
+
+const DEFAULT_HEARTBEAT_MS = 30_000;
+const DEFAULT_STALE_MS = 120_000;
+/** Bun's `idleTimeout` ceiling (seconds). */
+const BUN_IDLE_TIMEOUT_MAX_S = 960;
+
+/** Serialize the wire envelope once per fan-out. */
+const encode = (event: string, data: unknown): string => JSON.stringify({ event, data });
+
+/**
+ * The heartbeat sweep, factored out as a pure function so it's testable without faking
+ * timers: ping every live client, close (don't delete — let the `close` handler fire
+ * `onDisconnect` + remove) any unheard-from past `staleMs`. The hub's `setInterval`
+ * calls this with `Date.now()`.
+ */
+export function sweepStaleClients(clients: Iterable<WsClient>, now: number, staleMs: number): void {
+  for (const client of clients) {
+    if (now - client.lastPingAt > staleMs) {
+      client.ws.close(1001, 'stale');
+    } else {
+      client.ws.ping();
+    }
+  }
+}
+
+/**
+ * Build a typed WebSocket hub on Bun's native upgrade. The hub owns the transport —
+ * connection registry, channel routing, heartbeat/stale-cull, and presence-as-a-view;
+ * the registered {@link WsChannel}s own the business logic. Mount {@link WsHub.upgradeHandler}
+ * on the Hono upgrade route(s) and hand {@link WsHub.handlers} to `serveBun`'s `websocket`.
+ *
+ * @example
+ * const hub = createWsHub({ channels: wsChannels, authenticate });
+ * app.get('/ws/:channel', hub.upgradeHandler);
+ * serveBun(app, { port, websocket: hub.handlers });
+ */
+export function createWsHub<T extends Record<string, WsChannel<any>>>(opts: WsHubOpts<T>): WsHub {
+  const clients = new Map<string, WsClient>();
+  const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+  const heartbeatMs = opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+
+  const channelOf = (name: string): WsChannel<any> | undefined => opts.channels[name];
+  const clientFromWs = (ws: ServerWebSocket<WsData>): WsClient | undefined =>
+    clients.get(ws.data.clientId);
+
+  // Our heartbeat is authoritative (it also drives presence), so disable Bun's auto-ping
+  // and let its idle timeout backstop just beyond our stale window.
+  const idleTimeout = Math.min(Math.ceil(staleMs / 1000), BUN_IDLE_TIMEOUT_MAX_S);
+
+  const heartbeat = setInterval(() => {
+    sweepStaleClients(clients.values(), Date.now(), staleMs);
+  }, heartbeatMs);
+  // Don't keep the process alive for the heartbeat alone (server tests, graceful exit).
+  heartbeat.unref?.();
+
+  const upgradeHandler: MiddlewareHandler = async (c) => {
+    const channel = c.req.param('channel') ?? c.req.query('channel') ?? 'default';
+    const room = c.req.query('room') ?? undefined;
+    const handshake: WsHandshake = { headers: c.req.raw.headers, url: c.req.url, channel, room };
+
+    let user: Awaited<ReturnType<typeof opts.authenticate>>;
+    try {
+      user = await opts.authenticate(handshake);
+    } catch {
+      user = null;
+    }
+    if (!user) return c.json(toErrorEnvelope(new ApiError(401, 'Unauthorized')), 401);
+
+    const data: WsData = { clientId: crypto.randomUUID(), user, channel, room };
+    const server = c.env as unknown as Server<WsData>;
+    const upgraded = server.upgrade(c.req.raw, { data });
+    if (!upgraded) return c.text('Upgrade required', 426);
+    // Bun has taken over the socket and sent the 101; this Response is discarded by
+    // Bun.serve. (A real 101 can't be constructed — the Fetch Response ctor forbids 1xx.)
+    return c.body(null, 204);
+  };
+
+  const hub: WsHub = {
+    upgradeHandler,
+    handlers: {
+      idleTimeout,
+      sendPings: false,
+      open(ws) {
+        const { clientId, user, channel, room } = ws.data;
+        const now = Date.now();
+        const client: WsClient = {
+          id: clientId,
+          user,
+          ws,
+          channel,
+          connectedAt: now,
+          lastPingAt: now,
+          meta: {},
+        };
+        if (room) joinRoom(client, room);
+        clients.set(clientId, client);
+        channelOf(channel)?.onConnect?.(client, hub);
+      },
+      message(ws, raw) {
+        const client = clientFromWs(ws);
+        if (!client) return;
+        client.lastPingAt = Date.now();
+        let msg: WsMessage;
+        try {
+          msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString());
+        } catch {
+          return; // ignore malformed frames rather than crash the socket
+        }
+        channelOf(client.channel)?.onMessage(client, msg, hub);
+      },
+      // A pong (reply to our heartbeat ping) proves liveness without an app message.
+      pong(ws) {
+        const client = clientFromWs(ws);
+        if (client) client.lastPingAt = Date.now();
+      },
+      close(ws) {
+        const client = clientFromWs(ws);
+        if (!client) return;
+        channelOf(client.channel)?.onDisconnect?.(client, hub);
+        clients.delete(client.id);
+      },
+    },
+    broadcast(channel, event, data) {
+      const payload = encode(event, data);
+      for (const client of clients.values()) {
+        if (client.channel === channel) client.ws.send(payload);
+      }
+    },
+    broadcastToRoom(channel, roomId, event, data) {
+      const payload = encode(event, data);
+      for (const client of clients.values()) {
+        if (client.channel === channel && client.meta[ROOM_META_KEY] === roomId) {
+          client.ws.send(payload);
+        }
+      }
+    },
+    send(clientId, event, data) {
+      clients.get(clientId)?.ws.send(encode(event, data));
+    },
+    getClients(channel) {
+      const all = [...clients.values()];
+      return channel ? all.filter((client) => client.channel === channel) : all;
+    },
+    getClient: (id) => clients.get(id),
+    getPresence(channel) {
+      return computePresence(clients.values(), channel, channelOf(channel)?.presence ?? false);
+    },
+    close() {
+      clearInterval(heartbeat);
+    },
+  };
+
+  return hub;
+}

package/src/server/ws/index.ts

@@ -0,0 +1,20 @@
+// cursedbelt-server WS hub — Bun-native upgrade, typed channel registry, heartbeat,
+// presence-as-a-view, and the push-only event-bus subset. Pairs with the partysocket
+// client in `cursedbelt/client`.
+export { createEventBus } from './eventBus';
+export { createWsHub } from './hub';
+export { computePresence } from './presence';
+export { joinRoom, leaveRoom, ROOM_META_KEY, roomOf } from './room';
+export type {
+  EventBus,
+  EventBusData,
+  PresenceEntry,
+  PresenceState,
+  WsChannel,
+  WsClient,
+  WsData,
+  WsHandshake,
+  WsHub,
+  WsHubOpts,
+  WsMessage,
+} from './types';

package/src/server/ws/presence.spec.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from 'bun:test';
+import type { AuthUser } from '../auth/types';
+import { computePresence } from './presence';
+import type { WsClient } from './types';
+
+const user = (id: string): AuthUser => ({ id, roles: [], getOnly: false, sessionId: `s-${id}` });
+const client = (id: string, channel: string, connectedAt: number): WsClient =>
+  ({ id, user: user(id), channel, connectedAt, meta: {} }) as unknown as WsClient;
+
+describe('computePresence', () => {
+  test('returns one row per client on the channel when enabled', () => {
+    const clients = [client('a', 'chat', 100), client('b', 'chat', 200), client('c', 'game', 300)];
+    expect(computePresence(clients, 'chat', true)).toEqual([
+      { userId: 'a', connectedAt: 100 },
+      { userId: 'b', connectedAt: 200 },
+    ]);
+  });
+
+  test('returns empty when presence is not enabled for the channel', () => {
+    const clients = [client('a', 'chat', 100)];
+    expect(computePresence(clients, 'chat', false)).toEqual([]);
+  });
+
+  test('returns empty for a channel with no clients', () => {
+    expect(computePresence([], 'chat', true)).toEqual([]);
+  });
+});

package/src/server/ws/presence.ts

@@ -0,0 +1,26 @@
+import type { PresenceState, WsClient } from './types';
+
+/**
+ * Presence is a *view* over the live client map, not a tracked structure — there is no
+ * `PresenceTracker` class to keep in sync. The hub's `getPresence(channel)` delegates
+ * here; a channel that wants to push presence does
+ * `hub.broadcast('chat', 'presence', hub.getPresence('chat'))` from its lifecycle hooks.
+ */
+
+/** The presence snapshot for `channel`: one `{ userId, connectedAt }` row per live
+ * client on that channel, or empty when the channel doesn't opt into presence.
+ * Pure (no timers, no state) so it's trivially testable. */
+export function computePresence(
+  clients: Iterable<WsClient>,
+  channel: string,
+  presenceEnabled: boolean,
+): PresenceState {
+  if (!presenceEnabled) return [];
+  const rows: PresenceState = [];
+  for (const client of clients) {
+    if (client.channel === channel) {
+      rows.push({ userId: client.user.id, connectedAt: client.connectedAt });
+    }
+  }
+  return rows;
+}

package/src/server/ws/room.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from 'bun:test';
+import { joinRoom, leaveRoom, ROOM_META_KEY, roomOf } from './room';
+import type { WsClient } from './types';
+
+const client = (): WsClient => ({ id: 'c', meta: {} }) as unknown as WsClient;
+
+describe('room helpers', () => {
+  test('joinRoom sets the room meta under ROOM_META_KEY; roomOf reads it', () => {
+    const c = client();
+    expect(roomOf(c)).toBeUndefined();
+    joinRoom(c, 'lobby');
+    expect(c.meta[ROOM_META_KEY]).toBe('lobby');
+    expect(roomOf(c)).toBe('lobby');
+  });
+
+  test('joinRoom replaces the current room', () => {
+    const c = client();
+    joinRoom(c, 'a');
+    joinRoom(c, 'b');
+    expect(roomOf(c)).toBe('b');
+  });
+
+  test('leaveRoom clears membership', () => {
+    const c = client();
+    joinRoom(c, 'a');
+    leaveRoom(c);
+    expect(roomOf(c)).toBeUndefined();
+    expect(c.meta[ROOM_META_KEY]).toBeUndefined();
+  });
+
+  test('roomOf ignores a non-string meta value', () => {
+    const c = client();
+    c.meta[ROOM_META_KEY] = 42;
+    expect(roomOf(c)).toBeUndefined();
+  });
+});

package/src/server/ws/room.ts

@@ -0,0 +1,29 @@
+import type { WsClient } from './types';
+
+/**
+ * Rooms are not a separate stateful abstraction — they are a typed convention over
+ * {@link WsClient.meta}. A channel puts a client in a room with {@link joinRoom}; the
+ * hub's `broadcastToRoom` matches on the same key. This replaces the old `wsRoom.ts` /
+ * `reconnectableRoom.ts` classes: the hub owns connections + fan-out, the channel owns
+ * membership + any history buffer.
+ */
+
+/** The {@link WsClient.meta} key a client's current room id lives under. The hub's
+ * `broadcastToRoom` reads the same key — keep them in lockstep. */
+export const ROOM_META_KEY = 'roomId';
+
+/** Put `client` in `roomId` (replaces any current room). */
+export function joinRoom(client: WsClient, roomId: string): void {
+  client.meta[ROOM_META_KEY] = roomId;
+}
+
+/** Remove `client` from its room (a subsequent room broadcast won't reach it). */
+export function leaveRoom(client: WsClient): void {
+  delete client.meta[ROOM_META_KEY];
+}
+
+/** The client's current room id, or undefined if it isn't in one. */
+export function roomOf(client: WsClient): string | undefined {
+  const room = client.meta[ROOM_META_KEY];
+  return typeof room === 'string' ? room : undefined;
+}

package/src/server/ws/types.ts

@@ -0,0 +1,134 @@
+import type { ServerWebSocket, WebSocketHandler } from 'bun';
+import type { MiddlewareHandler } from 'hono';
+import type { AuthUser } from '../auth/types';
+
+/**
+ * Shared types for the cursedbelt WebSocket hub.
+ *
+ * cursedbelt owns the *transport* — connection lifecycle, channel routing,
+ * heartbeat/stale-cull, presence-as-a-view, and an injected `authenticate`
+ * callback. The *channels* (what each message means, the per-feature game/chat
+ * state) stay app-business; an app registers its channels into the hub and
+ * consumes the broadcast helpers. ru's push-only variant is {@link EventBus}.
+ *
+ * Built on Bun's native WS upgrade (`Server.upgrade` + `Bun.serve { websocket }`),
+ * surfaced through Hono via {@link WsHub.upgradeHandler}. No `ws`-lib, no adapter.
+ */
+
+/** The JSON envelope every frame uses, both directions: `{ event, data }`. The hub
+ * emits this from {@link WsHub.broadcast}/`send`; channels receive the parsed inbound
+ * envelope as their `onMessage` payload. `T` narrows `data` for a typed channel. */
+export interface WsMessage<T = unknown> {
+  event: string;
+  data: T;
+}
+
+/** What the hub stashes on the Bun `ServerWebSocket.data` at upgrade time so `open`
+ * can register the client without a second handshake round-trip (see the gotcha in
+ * the task spec). `room` is the optional `?room=` query param — a named room within
+ * the channel, applied to {@link WsClient.meta} on connect. */
+export interface WsData {
+  clientId: string;
+  user: AuthUser;
+  channel: string;
+  room?: string;
+}
+
+/** The minimal view of the WS handshake handed to {@link WsHubOpts.authenticate}. The
+ * app reads its auth cookie off `headers` and verifies it (cursedbelt never reads the
+ * cookie itself — auth *model* is app business). */
+export interface WsHandshake {
+  headers: Headers;
+  url: string;
+  channel: string;
+  room?: string;
+}
+
+/** A live connection. `meta` is the per-channel scratch bag (room membership via the
+ * `room.ts` helpers, game seat, typing flag, …) — the hub never interprets it beyond
+ * {@link WsHub.broadcastToRoom}'s room match. `lastPingAt` is "last time we heard from
+ * this client" (an inbound message OR a pong); the heartbeat culls on it. */
+export interface WsClient {
+  id: string;
+  user: AuthUser;
+  ws: ServerWebSocket<WsData>;
+  channel: string;
+  connectedAt: number;
+  lastPingAt: number;
+  meta: Record<string, unknown>;
+}
+
+/** A business channel registered into the hub. The hub routes inbound frames to
+ * `onMessage` by {@link WsClient.channel} and fires the lifecycle hooks; everything
+ * the handler *does* (broadcast shape, game state, history) is app business. */
+export interface WsChannel<TMsg = WsMessage> {
+  name: string;
+  /** Fired after the client is registered (room meta already applied). */
+  onConnect?(client: WsClient, hub: WsHub): void;
+  /** Fired once per inbound frame (the parsed `{ event, data }` envelope). */
+  onMessage(client: WsClient, msg: TMsg, hub: WsHub): void;
+  /** Fired when the socket closes (explicit, stale-culled, or peer-dropped). */
+  onDisconnect?(client: WsClient, hub: WsHub): void;
+  /** Whether this channel contributes to {@link WsHub.getPresence}. Default: false. */
+  presence?: boolean;
+}
+
+/** A presence row — the public, business-safe view of a connected client. */
+export interface PresenceEntry {
+  userId: string;
+  connectedAt: number;
+}
+
+/** The presence snapshot for a channel: one row per live, presence-enabled client. */
+export type PresenceState = PresenceEntry[];
+
+export interface WsHubOpts<TChannelMap extends Record<string, WsChannel<any>>> {
+  /** The business channel registry, keyed by channel name (the `?channel=`/`:channel`
+   * the client connects to). */
+  channels: TChannelMap;
+  /** Cookie→user verification for the handshake. Return `null` to reject the upgrade
+   * with a 401 (an HTTP 401, not a WS close). */
+  authenticate(handshake: WsHandshake): Promise<AuthUser | null>;
+  /** How often the heartbeat pings live clients + sweeps stale ones. Default 30_000. */
+  heartbeatIntervalMs?: number;
+  /** A client unheard-from for longer than this is culled. Default 120_000 (2 min). */
+  staleMs?: number;
+}
+
+export interface WsHub {
+  /** The Bun `websocket` config — pass straight to `serveBun(app, { websocket: hub.handlers })`.
+   * `message` is required by Bun; `open`/`close`/`pong` drive lifecycle + liveness. */
+  handlers: WebSocketHandler<WsData>;
+  /** Mount on the Hono upgrade route(s): `app.get('/ws/:channel', hub.upgradeHandler)`.
+   * Authenticates, then calls `Server.upgrade` (Bun-native). */
+  upgradeHandler: MiddlewareHandler;
+  /** Send `{ event, data }` to every client on `channel`. */
+  broadcast(channel: string, event: string, data: unknown): void;
+  /** Send `{ event, data }` to every client on `channel` whose room (meta) is `roomId`. */
+  broadcastToRoom(channel: string, roomId: string, event: string, data: unknown): void;
+  /** Send `{ event, data }` to one client by id (no-op if gone). */
+  send(clientId: string, event: string, data: unknown): void;
+  /** Live clients, optionally filtered to one channel. */
+  getClients(channel?: string): WsClient[];
+  /** One client by id, or undefined. */
+  getClient(clientId: string): WsClient | undefined;
+  /** The presence snapshot for a presence-enabled channel (empty otherwise). */
+  getPresence(channel: string): PresenceState;
+  /** Stop the heartbeat timer (call on shutdown / in tests to avoid a leaked interval). */
+  close(): void;
+}
+
+/** ru's push-only subset: broadcast-to-all, no auth, no inbound routing. One bus,
+ * mounted once; ru's task queue / caSync / Forge workers call `broadcast`. */
+export interface EventBus {
+  /** Bun `websocket` config. `message` is a documented no-op (push-only). */
+  handlers: WebSocketHandler<EventBusData>;
+  upgradeHandler: MiddlewareHandler;
+  /** Push `{ event, data }` to every connected client. */
+  broadcast(event: string, data: unknown): void;
+  /** Number of connected clients. */
+  clientCount(): number;
+}
+
+/** The event bus carries no per-socket data (no auth, no channel). */
+export type EventBusData = Record<never, never>;

package/src/skippedTestsAreAnswered.spec.ts

@@ -0,0 +1,215 @@
+/**
+ * 🔴 NO COMMENT, NO SKIP — and the doc that answers "what were they for" must stay true.
+ *
+ * ## What this cost, 2026-09-13
+ *
+ * `bun run verify` reported **5,132 pass / 82 skip / 0 fail**. Nobody could say what the 82
+ * were. Each had been written because something mattered and each had stopped running for a
+ * reason that was, by then, invisible: the gate condition was in the code
+ * (`describe.skipIf(!URL_)`), but *why that variable is unset on every host we own* was in
+ * nobody's head. A suite that carries a number like that quietly is a suite whose green means
+ * less than it says.
+ *
+ * Answering it took 16m 5s of agent time — the figure the runner's ledger recorded for the task,
+ * not an estimate — spent booting a throwaway Postgres, locating a binary-server checkout, and
+ * running each gated suite by hand to learn whether it still passes. All 82 turned out to be
+ * healthy, environment-gated proofs. That is the good outcome, and it is exactly why the next
+ * person must not have to re-derive it: the cost was never the fixing, it was the *finding
+ * out*.
+ *
+ * ## So this is a check, not a paragraph
+ *
+ * Two assertions, both of which fail the moment the record stops matching the code:
+ *
+ *  1. **Every skip site in `src` carries its reason in the comment directly above it.** A new
+ *     `describe.skipIf` with no comment is a red gate, at the moment it is written, by the
+ *     person who knows the answer — which is the only moment the answer is cheap.
+ *  2. **`docs/skipped-tests.md` names exactly the files that have one.** A skip that is
+ *     deleted or added without updating the record reds too, so the doc cannot rot into the
+ *     confident-but-wrong state that makes a doc worse than nothing.
+ *
+ * It deliberately does NOT assert a skip COUNT. The counts move with the host — ffmpeg
+ * installed or not, `CC_PG_URL` set or not — and a check that reds because someone installed
+ * `sharp` teaches people to delete the check.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SRC = fileURLToPath(new URL('.', import.meta.url));
+const REPO = path.resolve(SRC, '..');
+const SELF = 'src/skippedTestsAreAnswered.spec.ts';
+const DOC = 'docs/skipped-tests.md';
+
+/**
+ * A skip site: `describe.skip`, `.todo`, `.failing`, `.skipIf`, `.todoIf` on any of bun's three
+ * entry points, plus the jasmine-era `xit(` / `xdescribe(`.
+ *
+ * Anchored on the entry point so that ordinary identifiers containing "skip" — `skipDirs`,
+ * `skipToken`, `skipKdfReadinessGate`, all of which live in this package — are not sites.
+ */
+const SKIP_SITE = /\b(?:describe|it|test)\s*\.\s*(?:skip|todo|failing|skipIf|todoIf)\b|\bx(?:it|describe)\s*\(/;
+
+/** A comment line, in either style, as it appears immediately above a skip site. */
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*)/;
+
+export interface SkipSite {
+  /** 1-indexed, so a failure message is clickable. */
+  readonly line: number;
+  readonly text: string;
+  /** The contiguous comment block directly above, with no blank line between it and the site. */
+  readonly reason: string;
+}
+
+/**
+ * Every skip site in one file's source, each carrying whatever comment sits directly above it.
+ *
+ * "Directly above" is strict on purpose: a blank line between the comment and the site ends the
+ * block. The failure this guards against is a skip drifting away from the explanation that was
+ * once next to it, and a blank line is exactly how that drift starts.
+ */
+export const findSkipSites = (source: string): SkipSite[] => {
+  const lines = source.split('\n');
+  const sites: SkipSite[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const text = lines[i] as string;
+    if (!SKIP_SITE.test(text)) continue;
+    const above: string[] = [];
+    for (let j = i - 1; j >= 0; j -= 1) {
+      const prev = lines[j] as string;
+      if (!COMMENT_LINE.test(prev)) break;
+      above.unshift(prev);
+    }
+    sites.push({ line: i + 1, text: text.trim(), reason: above.join('\n') });
+  }
+  return sites;
+};
+
+/** A reason has to be ABOUT the skip. Any comment at all would pass otherwise. */
+export const isAnswered = (site: SkipSite): boolean => /skip/i.test(site.reason);
+
+/** Every `src` file that contains at least one skip site, repo-relative and sorted. */
+const scanSrc = (): Map<string, SkipSite[]> => {
+  const found = new Map<string, SkipSite[]>();
+  for (const entry of readdirSync(SRC, { recursive: true })) {
+    const name = String(entry);
+    if (!/\.tsx?$/.test(name)) continue;
+    const rel = `src/${name.split(path.sep).join('/')}`;
+    if (rel === SELF) continue; // the checker names the patterns it bans, so it cannot scan itself
+    const sites = findSkipSites(readFileSync(path.join(SRC, name), 'utf8'));
+    if (sites.length > 0) found.set(rel, sites);
+  }
+  return new Map([...found].sort(([a], [b]) => a.localeCompare(b)));
+};
+
+/**
+ * The suites `docs/skipped-tests.md` claims to cover.
+ *
+ * Only backticked paths in a TABLE ROW count, so the prose above and below the table stays free
+ * to mention any file it likes — including this one.
+ */
+const documentedSuites = async (): Promise<Set<string>> => {
+  const doc = await Bun.file(path.join(REPO, DOC)).text();
+  const rows = doc.split('\n').filter((l) => l.trimStart().startsWith('|'));
+  const named = new Set<string>();
+  for (const row of rows) for (const m of row.matchAll(/`(src\/[^`]+\.tsx?)`/g)) named.add(m[1] as string);
+  return named;
+};
+
+describe('every skip in src answers for itself', () => {
+  test('each skip site carries its reason in the comment directly above it', () => {
+    const unanswered: string[] = [];
+    for (const [file, sites] of scanSrc())
+      for (const site of sites) if (!isAnswered(site)) unanswered.push(`${file}:${site.line}  ${site.text}`);
+
+    expect(
+      unanswered,
+      `A skipped test with no stated reason is a question nobody can answer later — answering the 82 already here\n` +
+        `cost a task of its own on 2026-09-13 (16m 5s, per the runner's ledger). Put one line directly above the\n` +
+        `skip saying what it is WAITING FOR (a service, a fixture, a\n` +
+        `browser, a decision), mentioning the word "skip", and add a row to ${DOC}. If it passes today, unskip it\n` +
+        `instead. Never delete a test to make the number fall.\n\nUnanswered:\n  ${unanswered.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});
+
+describe(`${DOC} matches the suite`, () => {
+  test('it names every file that carries a skip', async () => {
+    const documented = await documentedSuites();
+    const missing = [...scanSrc().keys()].filter((f) => !documented.has(f));
+    expect(
+      missing,
+      `These files gained a skip that ${DOC} does not mention. Add a table row: what it waits for, how to run it,\n` +
+        `and when it was last seen green.\n\n  ${missing.join('\n  ')}`,
+    ).toEqual([]);
+  });
+
+  test('it names no file that has stopped carrying one', async () => {
+    const live = scanSrc();
+    const stale = [...(await documentedSuites())].filter((f) => !live.has(f));
+    expect(
+      stale,
+      `${DOC} still lists these as skipped, but they no longer contain a skip site. Good news — delete the rows\n` +
+        `(and move the count) so the record stops claiming something that is no longer true.\n\n  ${stale.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});
+
+/**
+ * The detector's own failure path. A gate nobody has seen RED is a gate nobody knows works, and
+ * this one's whole value is that it fires on the day a skip is introduced.
+ */
+describe('the detector itself', () => {
+  test('an uncommented skip is a finding', () => {
+    const sites = findSkipSites(["describe.skipIf(!URL_)('x', () => {", '});'].join('\n'));
+    expect(sites).toHaveLength(1);
+    expect(isAnswered(sites[0] as SkipSite)).toBe(false);
+  });
+
+  test('a skip whose comment explains the skip is not', () => {
+    const sites = findSkipSites(
+      ['// SKIPPED unless CC_PG_URL names a real Postgres.', "describe.skipIf(!URL_)('x', () => {", '});'].join('\n'),
+    );
+    expect(isAnswered(sites[0] as SkipSite)).toBe(true);
+  });
+
+  test('a comment about something else does NOT answer for the skip', () => {
+    const sites = findSkipSites(
+      ['// posterOnly is the memory-constrained-host path.', "describe.skipIf(!ffmpeg)('x', () => {", '});'].join('\n'),
+    );
+    expect(isAnswered(sites[0] as SkipSite)).toBe(false);
+  });
+
+  test('a blank line between the comment and the skip breaks the block', () => {
+    const sites = findSkipSites(
+      ['// SKIPPED unless CC_PG_URL is set.', '', "describe.skipIf(!URL_)('x', () => {", '});'].join('\n'),
+    );
+    expect(sites[0]?.reason).toBe('');
+    expect(isAnswered(sites[0] as SkipSite)).toBe(false);
+  });
+
+  test('a JSDoc block above the skip counts as the reason', () => {
+    const sites = findSkipSites(
+      ['/**', ' * SKIPPED until the browser harness exists.', ' */', "it.skip('x', () => {});"].join('\n'),
+    );
+    expect(isAnswered(sites[0] as SkipSite)).toBe(true);
+  });
+
+  test('it finds the other spellings too', () => {
+    expect(findSkipSites("it.todo('later');")).toHaveLength(1);
+    expect(findSkipSites("test.failing('known bad');")).toHaveLength(1);
+    expect(findSkipSites("xit('old style', () => {});")).toHaveLength(1);
+    expect(findSkipSites("xdescribe('old style', () => {});")).toHaveLength(1);
+  });
+
+  test('an identifier that merely contains "skip" is not a skip site', () => {
+    expect(findSkipSites('const skip = new Set(opts.skipDirs ?? []);')).toEqual([]);
+    expect(findSkipSites('if (options.skipKdfReadinessGate !== true) assertArgon2idReady();')).toEqual([]);
+    expect(findSkipSites('const q = useQuery({ queryKey: k, initialPageParam: skipToken });')).toEqual([]);
+  });
+
+  test('this package has skip sites to find — a detector that finds nothing proves nothing', () => {
+    expect(scanSrc().size).toBeGreaterThan(0);
+  });
+});