cursedbelt-core 1.0.0

package/src/namedSubpathsResolve.spec.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * Every `cursedbelt/<subpath>` this repo NAMES must be one it actually exports
+ * (2026-09-13).
+ *
+ * Removing the 23 subpaths nothing referenced left 19 sentences in `src` and
+ * `docs` still advertising them — `cursedbelt/ctgr`, `cursedbelt/server/media`,
+ * `cursedbelt/tokens` and friends, each one a copy-pasteable import that now
+ * throws ERR_PACKAGE_PATH_NOT_EXPORTED. Nothing could see them, because a
+ * subpath named in prose is invisible to `tsc` (it is a comment), invisible to
+ * Biome (it is a string), and invisible to `check-paths.ts` (it is not a
+ * filesystem path). The only reason those 19 were found is that one agent
+ * grepped for them by hand while deleting the exports.
+ *
+ * That is the drift this file exists to make impossible: the manifest and the
+ * prose describing it can no longer disagree without something going red.
+ *
+ * 🔴 Bun.Glob + Bun.file, NOT node:fs — this package's test preload virtualizes
+ * node:fs, so a readdirSync/readFileSync scan reads MOCK data and passes against
+ * files it never opened. Same trap as publishShape.spec.ts; see its header.
+ *
+ * Escape hatch: a line that must name a removed subpath (a changelog entry, a
+ * migration note) carries `subpath-check:ignore` and is skipped.
+ */
+const ROOTS = ['src', 'scripts', 'docs'] as const;
+
+const BINARY = /\.(png|jpe?g|gif|webp|avif|ico|mp4|webm|mp3|wav|pdf|zip|gz|woff2?|ttf|otf|eot|wasm)$/i;
+
+const IGNORE = 'subpath-check:ignore';
+
+/**
+ * `cursedbelt/<subpath>` wherever it appears — code, comment or markdown. The
+ * trailing class stops `cursedbelt/react` from matching inside
+ * `cursedbelt/react/timeline`, so a removed deep subpath cannot hide behind a
+ * live shallow one.
+ *
+ * The leading `(?<![\w/.-])` is what separates an IMPORT SPECIFIER from a REPO
+ * PATH: `packages/cursedbelt/src/...` and `../cursedbelt/scripts/...` name files
+ * on disk (check-paths.ts' job), not subpaths, and flagging them would make this
+ * gate unpassable and therefore useless.
+ */
+// Parameterized on pkg.name since the 2026-09-15 split: in THIS repo a bare
+// `cursedbelt/...` mention names the react package's surface, not ours, and
+// only `cursedbelt-core/...` mentions are checkable against our own manifest.
+const NAMED = new RegExp(String.raw`(?<![\w/.-])${pkg.name}(\/[a-z0-9][a-z0-9._/-]*[a-z0-9])`, 'gi');
+
+/** First segment is a directory in THIS repo ⇒ the mention is a file path. */
+const REPO_DIRS = /^\/(src|scripts|dist|docs|e2e|demo|node_modules|releases)(\/|$)/;
+
+/**
+ * Ends in a file extension ⇒ a file path, not a subpath — except the three CSS
+ * entries, which genuinely ARE exports (`cursedbelt/styles.css`).
+ */
+const FILE_EXT = /\.(?!css$)[a-z0-9]+$/i;
+
+const exported = new Set(Object.keys(pkg.exports).map((k) => k.replace(/^\./, '')));
+
+// This file and the task/report prose quoting the removal are allowed to name them.
+const SELF = 'namedSubpathsResolve.spec.ts';
+
+type Offence = { file: string; line: number; subpath: string; text: string };
+
+let cache: Promise<Offence[]> | undefined;
+const offences = (): Promise<Offence[]> => {
+	cache ??= (async () => {
+		const repo = `${import.meta.dir}/..`;
+		const found: Offence[] = [];
+		for (const root of ROOTS) {
+			const dir = `${repo}/${root}`;
+			for (const rel of new Bun.Glob('**/*').scanSync({ cwd: dir, onlyFiles: true })) {
+				if (BINARY.test(rel) || rel.endsWith(SELF)) continue;
+				const text = await Bun.file(`${dir}/${rel}`).text();
+				const lines = text.split('\n');
+				for (let i = 0; i < lines.length; i++) {
+					const line = lines[i] ?? '';
+					if (line.includes(IGNORE)) continue;
+					for (const m of line.matchAll(NAMED)) {
+						const subpath = m[1] ?? '';
+						if (exported.has(subpath)) continue;
+						if (REPO_DIRS.test(subpath) || FILE_EXT.test(subpath)) continue;
+						found.push({ file: `${root}/${rel}`, line: i + 1, subpath, text: line.trim() });
+					}
+				}
+			}
+		}
+		return found;
+	})();
+	return cache;
+};
+
+describe('subpaths named in this repo resolve', () => {
+	it('has scanned a real source tree', async () => {
+		// Guards the whole file: if the glob or the fs mock ever returns nothing,
+		// the assertion below passes vacuously and the gate quietly dies.
+		const repo = `${import.meta.dir}/..`;
+		let seen = 0;
+		for (const root of ROOTS) {
+			for (const _ of new Bun.Glob('**/*').scanSync({ cwd: `${repo}/${root}`, onlyFiles: true })) seen++;
+		}
+		expect(seen).toBeGreaterThan(100);
+	});
+
+	it('knows what the manifest exports', () => {
+		// If `exports` is ever read wrong, every offence below silently becomes one.
+		expect(exported.has('')).toBe(true); // the "." root entry
+		expect(exported.has('/master-lock')).toBe(true);
+		expect(exported.has('/react')).toBe(false); // the react tier stayed in `cursedbelt` at the 2026-09-15 split
+	});
+
+	it('names no subpath package.json does not export', async () => {
+		const dead = await offences();
+		expect(
+			dead,
+			`these name a cursedbelt subpath that is not in package.json exports — a consumer who\n` +
+				`copies one gets ERR_PACKAGE_PATH_NOT_EXPORTED. Point at the surviving subpath, or at\n` +
+				`the repo path, or mark the line \`${IGNORE}\`:\n` +
+				dead.map((d) => `  ${d.file}:${d.line}  cursedbelt${d.subpath}\n      ${d.text}`).join('\n'),
+		).toEqual([]);
+	});
+});

package/src/noPathDeps.spec.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * Rule 1 of `~/code` (2026-09-12): share by published version, never by path.
+ *
+ * `file:`, `link:`, `workspace:*` and a directory-valued `overrides` entry each
+ * defeat `bun install --frozen-lockfile`, and a `file:` install is served from a
+ * cache keyed on the VERSION STRING — so re-packing the same version silently
+ * ships stale bytes straight through `bun install --force`. That is the defect
+ * that made a `cursed-satellites` change cost twenty minutes; this is the line
+ * that stops it coming back one convenient shortcut at a time.
+ */
+const PATHY = /^(file:|link:|workspace:|portal:)/;
+
+describe('no path dependencies', () => {
+	for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'overrides'] as const) {
+		it(`${field} names no path-valued spec`, () => {
+			const block = (pkg as Record<string, unknown>)[field] as Record<string, string> | undefined;
+			const bad = Object.entries(block ?? {}).filter(([, v]) => typeof v === 'string' && PATHY.test(v));
+			expect(bad, `share by published version, never by path:\n  ${bad.map(([k, v]) => `${k} = ${v}`).join('\n  ')}`).toEqual([]);
+		});
+	}
+});

package/src/publishShape.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * What this exists for (2026-09-12).
+ *
+ * Two ways this package can publish something that installs clean and does not
+ * work, both found the hard way while extracting it from the monorepo:
+ *
+ * 1. `exports` resolves the `bun` and `source` conditions to `./src/*.ts`, but
+ *    `files` shipped only `dist`. Every consumer runs bun, so every subpath
+ *    resolved to a path that was not in the tarball. Invisible under a `file:`
+ *    link, because the whole directory was there.
+ *
+ * 2. A `tsc` run with no tsconfig falls back to defaults and emits `.js`/`.d.ts`
+ *    NEXT TO the sources. Those get packed, and a consumer's bun condition then
+ *    loads the stale `.js` instead of the `.ts` — a second module instance, so
+ *    every module-level singleton silently doubles.
+ *
+ * Both are one assertion each, and both fail loudly at `bun test` rather than at
+ * a consumer's runtime three repos away.
+ */
+// 🔴 Bun.Glob, NOT node:fs: this package's own test preload virtualizes node:fs
+// (`[cwip/testing] System mocks enabled`), so readdirSync here returns MOCK data
+// and the assertion below passes against a directory it never read. Cost an hour
+// to find; the scan must not go through a mocked module.
+const emittedInSrc = (): string[] => {
+	const all = new Set([...new Bun.Glob('**/*').scanSync({ cwd: import.meta.dir })]);
+	// A hand-written ambient declaration (css.d.ts) has no .ts sibling and is
+	// legitimate; an EMITTED one always sits next to the source it came from.
+	return [...all].filter((f) => {
+		if (f.endsWith('.js') || f.endsWith('.js.map')) return true;
+		if (!f.endsWith('.d.ts')) return false;
+		return all.has(`${f.slice(0, -5)}.ts`) || all.has(`${f.slice(0, -5)}.tsx`);
+	});
+};
+
+describe('publish shape', () => {
+	it('ships every directory its exports resolve into', () => {
+		const files = (pkg as { files?: string[] }).files ?? [];
+		const roots = new Set<string>();
+		for (const entry of Object.values((pkg as { exports: Record<string, unknown> }).exports)) {
+			if (typeof entry !== 'object' || entry === null) continue;
+			for (const target of Object.values(entry as Record<string, string>)) {
+				if (typeof target === 'string' && target.startsWith('./')) {
+					const top = target.slice(2).split('/')[0];
+					if (top !== undefined) roots.add(top);
+				}
+			}
+		}
+		for (const root of roots) {
+			expect(
+				files.some((f) => f === root || f.startsWith(`${root}/`)),
+				`exports resolve into "${root}/" but package.json files does not ship it`,
+			).toBe(true);
+		}
+	});
+
+	it('has no compiled output sitting in src', () => {
+		const emitted = emittedInSrc();
+		expect(emitted, `tsc emitted into src instead of dist:\n  ${emitted.slice(0, 10).join('\n  ')}`).toEqual([]);
+	});
+
+	it('declares bin paths npm will actually keep', () => {
+		// npm rejects a "./"-prefixed bin value, calls the NAME invalid, and drops
+		// the entry — with a warning, not an error. The package publishes fine and
+		// installs with no CLI at all. Invisible under a file: link, where the bin
+		// is linked from the source manifest before npm ever normalises it.
+		const bin = (pkg as { bin?: Record<string, string> }).bin ?? {};
+		const prefixed = Object.entries(bin).filter(([, v]) => v.startsWith('./'));
+		expect(
+			prefixed,
+			`npm drops "./"-prefixed bin entries on publish:\n  ${prefixed.map(([k, v]) => `${k} = ${v}`).join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('lists "types" first in every conditional export', () => {
+		// Condition order is significant and "types" must win, or tsc resolves the
+		// `bun`/`source` condition and typechecks our shipped .ts instead of the
+		// .d.ts. A consumer then inherits type errors from OUR optional peers —
+		// cursedbelt could not typecheck against cwip because `unpdf`, an optional
+		// peer it does not install, was reachable through cwip/src.
+		const wrong = Object.entries((pkg as { exports: Record<string, unknown> }).exports)
+			.filter(([, e]) => typeof e === 'object' && e !== null && 'types' in e)
+			.filter(([, e]) => Object.keys(e as object)[0] !== 'types')
+			.map(([k]) => k);
+		expect(wrong, `"types" must be the first condition:\n  ${wrong.join('\n  ')}`).toEqual([]);
+	});
+});

package/src/shared/errors.ts

@@ -0,0 +1,153 @@
+/**
+ * The canonical server error class + error/validation envelope for the whole
+ * monorepo — cursedbelt apps AND cursedshell plugins.
+ *
+ * Every API failure — thrown deep in a handler, surfaced by middleware, or raised
+ * by a plugin service — is shaped into ONE wire contract, the **rich** envelope
+ * defined once in cwip (`cwip/error`):
+ *
+ *   { "error": { "name", "message", "code?", "status?", "category?", "context?",
+ *       "isOperational", "timestamp" }, "correlationId?": "…" }
+ *
+ * Clients parse exactly this shape, so there is no per-route error drift — and no
+ * drift between a cwip-based server (which already emits it via `cwip/server`'s
+ * `errorHandler`) and a cursedshell one. The extra fields are additive:
+ * a client that only reads `message`/`code`/`context` keeps working unchanged.
+ *
+ * `ApiError` is the ergonomic throwable: `throw new ApiError(404, 'not found')`.
+ * It is a thin subclass of cwip's `AppError` with the status-first constructor
+ * shape every plugin already uses, so a single `getSummary()`/`toErrorEnvelope`
+ * produces the rich body. The `errorEnvelope` Hono `onError` handler
+ * (cursedbelt-server) turns it (and any other thrown value) into the envelope +
+ * the right HTTP status; {@link ApiError.fromEnvelope} rebuilds one on the CLIENT
+ * from a parsed error body.
+ *
+ * This module is **framework-free** (no Hono, no DOM, no server deps — it imports
+ * only cwip's framework-free `cwip/error` and a type-only `zod` for the validation
+ * builder), so it is safe to import from browser bundles and from cursedshell's
+ * plugin-pure layer via the `cursedbelt-core/errors` subpath. Server code reaches the
+ * same symbols through `cursedbelt-server` (which re-exports this module).
+ */
+import {
+  AppError,
+  type AppErrorSummary,
+  type ErrorEnvelope,
+  isAppError,
+  type ToErrorEnvelopeOptions,
+  toErrorEnvelope,
+} from 'cwip/error';
+import type { ZodError } from 'zod';
+
+// ── Re-export the ONE canonical envelope + formatter (defined in cwip) ────────
+//    So `cursedbelt-core/errors` and `cwip/error` speak the exact same wire contract.
+export { AppError, type AppErrorSummary, type ErrorEnvelope, isAppError, type ToErrorEnvelopeOptions, toErrorEnvelope };
+
+// ── Throwable ────────────────────────────────────────────────────────────────
+
+export interface ApiErrorOptions {
+  /** Stable machine code carried into the envelope. */
+  code?: string;
+  /** Structured detail carried into the envelope (e.g. `{ issues }`). */
+  context?: Record<string, unknown>;
+  /** Underlying cause, preserved for server-side logging (never serialized). */
+  cause?: unknown;
+}
+
+/**
+ * A throwable HTTP error carrying its status + canonical-envelope fields. A thin,
+ * status-first subclass of cwip's {@link AppError} — `new ApiError(404, 'nope',
+ * { code, context })` is the ergonomic form every handler/middleware/plugin
+ * service uses; the inherited `getSummary()` yields the rich `AppErrorSummary` so
+ * `toErrorEnvelope` maps it to the response with no extra work. On the client,
+ * {@link ApiError.fromEnvelope} rebuilds it from a parsed error body so callers
+ * can branch on `.status`/`.code`/`.context`.
+ */
+export class ApiError extends AppError {
+  /**
+   * Always set — narrows the base's optional `status` (an `ApiError` is defined
+   * by its HTTP status). The value is assigned by `AppError`'s constructor from
+   * the `status` we pass through; `declare` just re-types it without re-emitting
+   * the field (so the base's assignment isn't shadowed under class-field semantics).
+   */
+  declare readonly status: number;
+
+  constructor(status: number, message: string, options: ApiErrorOptions = {}) {
+    super(message, {
+      status,
+      code: options.code,
+      context: options.context,
+      cause: options.cause,
+    });
+    // `AppError` sets `this.name = new.target.name` → 'ApiError' already.
+  }
+
+  /**
+   * Rebuild an `ApiError` from a parsed error envelope's `error` object — the
+   * client half of the contract (e.g. `createServiceClient`'s response parser).
+   * Reads only `message`/`code`/`context`, so it works against both the rich
+   * envelope and any legacy minimal body. Missing/absent envelope falls back to a
+   * status-derived message.
+   */
+  static fromEnvelope(status: number, envelope?: Partial<AppErrorSummary>): ApiError {
+    return new ApiError(status, envelope?.message ?? `Request failed with status ${status}`, {
+      code: envelope?.code,
+      context: envelope?.context,
+    });
+  }
+}
+
+/** Type guard for {@link ApiError} (the status-first server throwable). */
+export const isApiError = (value: unknown): value is ApiError => value instanceof ApiError;
+
+// ── Validation envelope (the ONE shape both zValidator and the cursedshell ────
+//    service-router emit; mirrors Zod's own `issue.path`) ─────────────────────
+
+/**
+ * One field-level validation error on the wire. `path` is the dotted Zod path to
+ * the offending field (`''` for a top-level/whole-body issue) — it mirrors
+ * `z.ZodIssue.path`, so server code maps 1:1 and clients read a stable name.
+ */
+export interface ValidationIssue {
+  /** Dotted path to the offending field (`''` for a top-level issue). */
+  path: string;
+  /** Human-readable, zod-authored message. */
+  message: string;
+}
+
+/**
+ * The canonical machine code carried in a validation envelope's `error.code`, so a
+ * client can branch on it without string-matching the (localizable) message.
+ */
+export const VALIDATION_ERROR_CODE = 'validation';
+
+/** The HTTP status every validation failure maps to (both emitters respond 400). */
+export const VALIDATION_STATUS = 400;
+
+/** The default client-facing message when validation fails. */
+const DEFAULT_VALIDATION_MESSAGE = 'Validation failed';
+
+/** Map a {@link https://zod.dev | zod} error's issues to the wire {@link ValidationIssue}s. */
+export function toValidationIssues(error: ZodError): ValidationIssue[] {
+  return error.issues.map((issue) => ({
+    path: issue.path.map((segment) => String(segment)).join('.'),
+    message: issue.message,
+  }));
+}
+
+/**
+ * Build the canonical validation envelope from a zod error (or pre-mapped issues).
+ * It constructs an {@link ApiError} (status {@link VALIDATION_STATUS}, code
+ * {@link VALIDATION_ERROR_CODE}, `context.issues`) and runs it through the shared
+ * {@link toErrorEnvelope}, so a validation failure is shaped identically to every
+ * other error on the wire — `{ error: { …, code: 'validation', status: 400,
+ * context: { issues } } }`. This is the single builder — both cursedbelt's
+ * `zValidator` middleware and cursedshell's `buildServiceRouter` call it, so a
+ * client parses validation failures identically no matter which layer emitted them.
+ */
+export function validationEnvelope(
+  errorOrIssues: ZodError | ValidationIssue[],
+  message: string = DEFAULT_VALIDATION_MESSAGE,
+): ErrorEnvelope {
+  const issues = Array.isArray(errorOrIssues) ? errorOrIssues : toValidationIssues(errorOrIssues);
+  return toErrorEnvelope(new ApiError(VALIDATION_STATUS, message, { code: VALIDATION_ERROR_CODE, context: { issues } }));
+}

package/src/skippedTestsAreAnswered.spec.ts

@@ -0,0 +1,221 @@
+/**
+ * 🔴 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('the walker reads a real tree — a scan that visits nothing proves nothing', () => {
+    // This package split out of cursedbelt with ZERO skip sites (2026-09-15), so
+    // detector liveness cannot come from finding one in the tree. The fixture
+    // assertions above prove the DETECTOR; this proves the WALK: it must visit
+    // the same order of spec files the suite runs, or the scan is reading a
+    // wrong directory and every green above is about nothing.
+    const specs = [...readdirSync(SRC, { recursive: true })].filter((e) => /\.spec\.tsx?$/.test(String(e)));
+    expect(specs.length).toBeGreaterThan(20);
+  });
+});