cursedbelt 2.7.0 → 3.0.0

package/scripts/verify.ts

@@ -0,0 +1,291 @@
+#!/usr/bin/env bun
+/**
+ * `bun run verify` — every check this repo has, run as a dependency GRAPH instead of a
+ * six-link `&&` chain.
+ *
+ * ## Why this stopped being a chain
+ *
+ * Measured 2026-09-15 on an idle machine, stage by stage, with the chain in place:
+ *
+ *     paths 0.4s · typecheck 22.6s (three tsc projects) · demo:check 7.2s
+ *     · build 13.2s · test 67.6s · e2e 32.2s        →  142.0s end to end
+ *
+ * Five of those are single-threaded `tsc`/scan work that share nothing but the source tree,
+ * and they were queued behind one another on a fourteen-core machine. As a graph the same
+ * stages finish in roughly half the wall clock, and the saving grows with load: this repo's
+ * gate is two thirds of every gate second the generation has ever spent.
+ *
+ * 🔴 NOTHING HERE IS A SMALLER GATE. Every script the chain ran is still run, and
+ * `src/verifyGraph.spec.ts` fails if one is dropped or orphaned. This generation's third
+ * rule is that a repo's gate proves that repo — a gate that got faster by proving less is
+ * not faster, it is gone. There is deliberately no `verify:fast`: one gate, or the fast one
+ * becomes the one everybody runs and the slow one becomes the one nobody does.
+ *
+ * ## The edges, and why these are the only ones
+ *
+ * `build` regenerates `src/styles-static.css` and `src/styles-utilities.css` (its first two
+ * steps), and `stylesStaticMatches.spec.ts` and `stylesUtilitiesMatches.spec.ts` read those
+ * exact files and assert they are current. Run concurrently against a STALE stylesheet, one
+ * process writes the bytes the other is asserting on — a flake that appears only on the
+ * commit that changed a component, which is the worst possible day for it.
+ *
+ * So the generators are their own stage and everything that touches those bytes waits for
+ * it. Once `styles` has run, the same generators inside `build` find their output current
+ * and write nothing (they compare before writing) — which is what makes `build` safe to run
+ * beside `test` and `e2e` rather than in front of them.
+ *
+ * 🔴 `build` is a LEAF, not a prerequisite. No spec under `src` opens `dist/` — checked by
+ * `verifyGraph.spec.ts` rather than asserted here — and the demo resolves every
+ * `cursedbelt/…` specifier to SOURCE through the export map, so nothing in `test` or `e2e`
+ * can see the compiled output at all.
+ *
+ * ## What it prints
+ *
+ * Buffered per stage, never interleaved: six concurrent stages writing to one transcript is
+ * output nobody can read. The cost of buffering is silence, and silence is exactly what
+ * `autopilot/src/proc.ts` exists to prevent — so a heartbeat names what is still running and
+ * for how long. A reader can tell "thinking" from "dead" without knowing anything about the
+ * suite.
+ *
+ * 🔴 A failing stage's output is printed LAST, after the timing table. The runner keeps the
+ * final 4 KB of a gate as the evidence it files against the task (`worker.ts`), so whatever
+ * is at the tail is what a human reads first. The chain got this for free by stopping at the
+ * failure; a graph has to put it there on purpose.
+ */
+import { cpus } from "node:os";
+import { resolve } from "node:path";
+
+export interface Stage {
+	/**
+	 * The `package.json` script this stage runs. 🔴 A script name, never a command line —
+	 * `package.json` stays the one place every command is spelled, so this file cannot drift
+	 * from what `bun run <thing>` does.
+	 */
+	script: string;
+	/** Stages that must be GREEN before this one may start. */
+	needs?: readonly string[];
+	/** Why the edge exists. An edge nobody can explain is an edge nobody can safely remove. */
+	why?: string;
+}
+
+/**
+ * The gate. 🔴 Order in this list means nothing — `needs` is the only thing that sequences
+ * anything, and the scheduler starts whatever is ready.
+ */
+export const STAGES: readonly Stage[] = [
+	{ script: "paths" },
+	{ script: "typecheck:root" },
+	{ script: "typecheck:specs" },
+	{ script: "demo:check" },
+	{ script: "styles" },
+	{
+		script: "build",
+		needs: ["styles"],
+		why: "its first two steps are the same generators; two writers on one stylesheet is a race",
+	},
+	{
+		script: "test",
+		needs: ["styles"],
+		why: "stylesStaticMatches / stylesUtilitiesMatches read those two files and assert they are current",
+	},
+	{
+		script: "e2e",
+		needs: ["styles"],
+		why: "the demo bundle it drives is compiled from the same stylesheets",
+	},
+];
+
+/** The repo root — this file's own directory, one level up. Never a literal. */
+export const ROOT = resolve(import.meta.dir, "..");
+
+/**
+ * How many stages may run at once.
+ *
+ * 🔴 A THIRD of the cores, not all of them, and the reason is that a stage is not a process.
+ * `e2e` alone spawns seven Playwright workers and `build` spawns two `tsc` processes, so a
+ * cap of six stages is already twenty-odd processes. This Mac reached twenty-one concurrent
+ * `bun test` processes once and the machine-wide PreToolUse warning exists because of it.
+ * Parallelism never reduces the total CPU work; over-subscribing only converts it into
+ * thrash, and browser specs degrade worse than anything else under contention.
+ *
+ * An explicit `CURSEDBELT_VERIFY_JOBS` wins, including `1`, which is how a bisect gets the
+ * old serial behaviour back without a second gate script existing.
+ */
+export function jobLimit(env: NodeJS.ProcessEnv = process.env, cpuCount: number = cpus().length): number {
+	const asked = Number(env.CURSEDBELT_VERIFY_JOBS);
+	if (Number.isFinite(asked) && asked >= 1) return Math.floor(asked);
+	return Math.max(2, Math.min(6, Math.floor(cpuCount / 3)));
+}
+
+/**
+ * 🔴 Every stage reachable, and every `needs` naming a stage that exists.
+ *
+ * Both halves matter and they fail in opposite directions: a typo in `needs` would otherwise
+ * make a stage that can NEVER run (the scheduler would idle with work left, and "nothing
+ * failed" is not the same as "everything passed"), while a cycle would deadlock the same way.
+ * Checked before anything is spawned, so a broken graph costs a second rather than a gate.
+ */
+export function graphFault(stages: readonly Stage[] = STAGES): string | null {
+	const names = new Set(stages.map((s) => s.script));
+	if (names.size !== stages.length) return "two stages name the same script";
+	for (const stage of stages) {
+		for (const need of stage.needs ?? []) {
+			if (!names.has(need)) return `\`${stage.script}\` needs \`${need}\`, which is not a stage`;
+		}
+	}
+	// Kahn's algorithm: anything still unresolved when nothing more can be resolved is a cycle.
+	const done = new Set<string>();
+	for (;;) {
+		const ready = stages.filter((s) => !done.has(s.script) && (s.needs ?? []).every((n) => done.has(n)));
+		if (ready.length === 0) break;
+		for (const s of ready) done.add(s.script);
+	}
+	const stuck = stages.filter((s) => !done.has(s.script)).map((s) => s.script);
+	return stuck.length > 0 ? `these stages can never run (a cycle in \`needs\`): ${stuck.join(", ")}` : null;
+}
+
+export interface StageResult {
+	script: string;
+	ok: boolean;
+	ms: number;
+	output: string;
+	/** Not started, because something it needed failed or the run had already gone red. */
+	skipped?: boolean;
+}
+
+function secs(ms: number): string {
+	return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** The table every run ends with, green or red. Pure, so the shape of it is testable. */
+export function timingTable(results: readonly StageResult[], wallMs: number): string {
+	const width = Math.max(10, ...results.map((r) => r.script.length));
+	const cpu = results.reduce((a, r) => a + r.ms, 0);
+	const lines = [`  ${"stage".padEnd(width)}   elapsed  result`];
+	for (const r of [...results].sort((a, b) => b.ms - a.ms)) {
+		const verdict = r.skipped ? "skipped" : r.ok ? "ok" : "FAILED";
+		lines.push(`  ${r.script.padEnd(width)} ${secs(r.ms).padStart(9)}  ${verdict}`);
+	}
+	lines.push(
+		"",
+		`  ${secs(wallMs)} of wall clock; ${secs(cpu)} of stage time. ` +
+			`${cpu > wallMs ? `${(cpu / wallMs).toFixed(1)}× overlap.` : "No overlap — one stage at a time."}`,
+	);
+	return lines.join("\n");
+}
+
+async function runStage(stage: Stage): Promise<StageResult> {
+	const started = Date.now();
+	const child = Bun.spawn([process.execPath, "run", stage.script], {
+		cwd: ROOT,
+		stdout: "pipe",
+		// Merged rather than kept apart: a compiler writes diagnostics to one and progress to
+		// the other, and a reader needs them interleaved the way the stage wrote them.
+		stderr: "pipe",
+	});
+	const [out, err, code] = await Promise.all([
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+		child.exited,
+	]);
+	return { script: stage.script, ok: code === 0, ms: Date.now() - started, output: `${out}${err}` };
+}
+
+/** Bytes of a failing stage's output that reach the tail. Enough for a stack, not a build log. */
+const FAILURE_TAIL = 12_000;
+
+export async function verify(stages: readonly Stage[] = STAGES): Promise<number> {
+	const fault = graphFault(stages);
+	if (fault) {
+		process.stdout.write(`\n🔴 the verify graph is broken: ${fault}\n`);
+		return 2;
+	}
+	const jobs = jobLimit();
+	const startedAt = Date.now();
+	process.stdout.write(`\n▸ verify — ${stages.length} stages, up to ${jobs} at once.\n\n`);
+
+	const results = new Map<string, StageResult>();
+	const running = new Map<string, number>();
+	let red = false;
+
+	// 🔴 Names what is STILL running, never a spinner. The question a reader has at minute
+	// four of a Playwright suite is "which stage, and how long has it been there" — a
+	// progress animation answers neither, and the transcript this lands in is a file.
+	const heartbeat = setInterval(() => {
+		if (running.size === 0) return;
+		const live = [...running.entries()]
+			.map(([script, at]) => `${script} ${secs(Date.now() - at)}`)
+			.sort()
+			.join(" · ");
+		process.stdout.write(`  ⧗ still running: ${live}\n`);
+	}, 30_000);
+	// Never hold the process open on the timer alone.
+	heartbeat.unref?.();
+
+	const inFlight = new Set<Promise<void>>();
+	const start = (stage: Stage): void => {
+		running.set(stage.script, Date.now());
+		process.stdout.write(`  ▶ ${stage.script}\n`);
+		const task = runStage(stage).then((result) => {
+			running.delete(stage.script);
+			results.set(result.script, result);
+			if (!result.ok) red = true;
+			process.stdout.write(`  ${result.ok ? "✔" : "✘"} ${result.script} ${secs(result.ms)}\n`);
+		});
+		inFlight.add(task);
+		void task.finally(() => inFlight.delete(task));
+	};
+
+	for (;;) {
+		// 🔴 Once anything is red, nothing NEW starts — the chain would never have reached it —
+		// but whatever is already running is left to finish. Killing an in-flight stage buys
+		// back seconds that are already spent and throws away a second, independent failure
+		// that would otherwise be in the same report.
+		const ready = red
+			? []
+			: stages.filter(
+					(s) =>
+						!results.has(s.script) &&
+						!running.has(s.script) &&
+						(s.needs ?? []).every((n) => results.get(n)?.ok === true),
+				);
+		while (ready.length > 0 && running.size < jobs) {
+			const next = ready.shift();
+			if (next) start(next);
+		}
+		if (inFlight.size === 0) break;
+		await Promise.race(inFlight);
+	}
+	clearInterval(heartbeat);
+
+	for (const stage of stages) {
+		if (!results.has(stage.script)) {
+			results.set(stage.script, { script: stage.script, ok: false, ms: 0, output: "", skipped: true });
+		}
+	}
+
+	const all = stages.map((s) => results.get(s.script) as StageResult);
+	const failed = all.filter((r) => !r.ok && !r.skipped);
+	const skipped = all.filter((r) => r.skipped);
+	const wall = Date.now() - startedAt;
+
+	process.stdout.write(`\n${timingTable(all, wall)}\n`);
+	if (skipped.length > 0) {
+		process.stdout.write(
+			`\n  ⏭ not run, because the gate was already red: ${skipped.map((r) => r.script).join(", ")}\n`,
+		);
+	}
+	if (failed.length === 0) {
+		process.stdout.write(`\n✅ verify green in ${secs(wall)}.\n`);
+		return 0;
+	}
+	// 🔴 LAST. `worker.ts` files the final 4 KB of this as the evidence against the task.
+	for (const r of failed) {
+		process.stdout.write(`\n\n${"═".repeat(72)}\n🔴 FAILED: bun run ${r.script}  (${secs(r.ms)})\n${"═".repeat(72)}\n`);
+		process.stdout.write(r.output.length > FAILURE_TAIL ? `…\n${r.output.slice(-FAILURE_TAIL)}` : r.output);
+	}
+	process.stdout.write(`\n\n🔴 verify FAILED in ${secs(wall)}: ${failed.map((r) => r.script).join(", ")}\n`);
+	return 1;
+}
+
+if (import.meta.main) process.exit(await verify());

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * A BARREL is what apps actually import, and its whole promise is what it does NOT
+ * pull in. `cursedbelt/react` is imported by all eight apps — 138 import lines across
+ * the fleet, more than every other subpath combined — so one static import of an
+ * OPTIONAL peer inside it means every app must install a package it may never call.
+ *
+ * ## Where this check came from, and why this file is now the half that stayed
+ *
+ * It was written on 2026-09-15 for the SERVER tier, after the same defect landed
+ * twice in two days, one level apart. `apps/collections/src/kit/binaryStore.ts`
+ * needed exactly one thing from the belt:
+ *
+ *     import type { FileTokenClaims } from "cursedbelt/server/storage";   subpath-check:ignore
+ *
+ * A TYPE — TypeScript erases it, so the app should have paid nothing at runtime.
+ * What it actually paid was `error: Cannot find package 'otplib'`, and four unrelated
+ * route suites died. `server/storage`'s index is a barrel; it reached `streamToken.ts`,
+ * which imported the `../auth` INDEX for two jose functions, and that index reaches
+ * `totp.ts` → `otplib`, an optional peer. The app declared `otplib` as a direct
+ * dependency to get its suites back — a one-time-password library installed to satisfy
+ * a claim shape.
+ *
+ * The rule written down after the first occurrence ("never import the
+ * `cursedbelt/server` barrel for one primitive" — subpath-check:ignore, quoting the
+ * pre-split name deliberately) could not catch the second, because
+ * `./server/storage` IS a leaf by that rule's standard and has a barrel of its own. A
+ * rule only a human can apply gets re-broken by the next module that looks like a leaf.
+ * So: a check.
+ *
+ * 🔴 At the 2026-09-15 split (task 148) the server tier moved to `cursedbelt-server`,
+ * and the RUNTIME-FIXTURE half of this spec went with it — the throwaway
+ * `node_modules`, the bun-auto-install trap, the negative control, and the two leaves
+ * it proved (`./storage/types`, `./login-throttle`). Read that copy for those notes;
+ * they were expensive and they are still true over there. This package's exports have
+ * no zero-runtime leaf left to prove — every react subpath evaluates a component on
+ * purpose — so what stays here is the BARREL half, pointed at the one barrel that
+ * matters, with `recharts` standing where `otplib` stood.
+ *
+ * ## Verified failing before it was trusted (2026-09-15, this package)
+ *
+ *   · `import 'recharts';` added to `src/react/index.ts`
+ *       → red: "importing cursedbelt/react statically pulls these OPTIONAL peers … recharts"
+ *   · `import '@ffmpeg/ffmpeg';` added to `src/react/components/Button.tsx` — TWO hops
+ *     out (barrel → components → Button), which a grep of the barrel file cannot see
+ *       → red identically. That is the branch that matters; the direct one is the easy case.
+ *   · 🔴 the first attempt at that second branch put the import in `src/react/charts/index.ts`
+ *     and stayed GREEN — correctly. The barrel does not re-export `charts` at all
+ *     (`./react/charts` is its own subpath precisely so `recharts` stays unpaid), and
+ *     `react-grid-layout` — the package first reached for — is a hard `dependency`, not an
+ *     optional peer, so it is not in scope by construction. A fixture that fails to fail
+ *     is worth writing down: both halves of that mistake would have read as "the check
+ *     works" to anyone who only ran the first branch.
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * The other half, and the one that caught the SECOND edge. A leaf can be clean while the
+ * barrel it was split out of still drags an optional peer, and a barrel is what most apps
+ * import — all eight apps take `cursedbelt/react` whole.
+ *
+ * Measured by bundling the subpath's relative graph with every bare import left external
+ * and reading what remains. The subpaths listed must reach NO optional peer with a STATIC
+ * import: a static one is paid at import time by every consumer, which is the crash the
+ * task above is about; a `await import('sharp')` inside the function that needs it is
+ * exactly the right shape and stays legal here.
+ *
+ * Limitation, stated rather than hidden: the externals are read out of the bundle's import
+ * statements textually, so an import bun emits across several lines would be missed. That
+ * makes this half a floor, not a ceiling — the runtime fixture above is the strict one.
+ */
+const NO_STATIC_OPTIONAL_PEERS = [
+  {
+    subpath: './react',
+    /** Its `streamToken.ts` and (two hops out) `private-media/unlock.ts` both imported the
+     *  `../auth` index for two jose functions, so `otplib` was static in here until 2.6.0. */
+    entry: 'src/react/index.ts',
+  },
+] as const;
+
+const OPTIONAL_PEERS = new Set(
+  Object.entries(
+    (pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> })
+      .peerDependenciesMeta ?? {},
+  )
+    .filter(([, meta]) => meta?.optional === true)
+    .map(([name]) => name),
+);
+
+/** `import x from "pkg"`, `import "pkg"`, `export … from "pkg"` — one line each, as bun emits. */
+const STATIC_SPECIFIER = /^(?:import|export)\s[^\n]*?["']([^"'\n]+)["'];?$|^import\s*["']([^"'\n]+)["'];?$/gm;
+
+/**
+ * 🔴 An OUTDIR, not stdout, and this repo is why (2026-09-15).
+ *
+ * Every barrel worth checking here is a React one, and a React barrel reaches a
+ * `.css` import — so bun emits two files and refuses stdout with *"cannot write
+ * multiple output files without an output directory"*. That is an exit 1 the
+ * `could not bundle` guard below correctly reports, and the temptation is to make
+ * the guard lenient. Do not: a bundle that did not happen must never read as a
+ * barrel that pulls nothing. Give it somewhere to write instead, and scan every
+ * `.js` it emits — a stylesheet cannot import a package, so the CSS output is
+ * irrelevant to the question and only the JS is read.
+ */
+const staticOptionalPeersOf = (entry: string): string[] => {
+  const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-barrel-scan/${entry.replace(/[^a-z0-9]+/gi, '-')}`;
+  const build = Bun.spawnSync(
+    ['bun', 'build', entry, '--target=bun', '--packages=external', '--outdir', outdir],
+    { cwd: REPO, stdout: 'pipe', stderr: 'pipe' },
+  );
+  const emitted = [...new Bun.Glob('**/*.js').scanSync({ cwd: outdir, onlyFiles: true })];
+  const bundle = emitted.map((f) => readFileSync(`${outdir}/${f}`, 'utf8')).join('\n');
+  if (build.exitCode !== 0 || bundle.trim() === '') {
+    throw new Error(
+      `could not bundle ${entry} (exit ${build.exitCode}) — a check that cannot measure is not a passing check:\n${build.stderr.toString()}`,
+    );
+  }
+  const found = new Set<string>();
+  for (const match of bundle.matchAll(STATIC_SPECIFIER)) {
+    const specifier = match[1] ?? match[2];
+    if (specifier === undefined || specifier.startsWith('.')) continue;
+    // `@scope/name/deep` → `@scope/name`, `pkg/deep` → `pkg`.
+    const parts = specifier.split('/');
+    const name = specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+    if (name !== undefined && OPTIONAL_PEERS.has(name)) found.add(name);
+  }
+  return [...found].sort();
+};
+
+
+describe('barrels reach no optional peer statically', () => {
+  it('knows which peers are optional', () => {
+    // Guards the assertions below: an empty set makes every one of them pass vacuously.
+    expect(OPTIONAL_PEERS.size, 'peerDependenciesMeta lists no optional peer').toBeGreaterThan(10);
+    expect(
+      [...OPTIONAL_PEERS],
+      'recharts is the shape this guards: a chart library nobody pays for until they import ./react/charts',
+    ).toContain('recharts');
+  });
+
+  for (const target of NO_STATIC_OPTIONAL_PEERS) {
+    it(`cursedbelt/${target.subpath.slice(2)} costs a consumer no optional peer to import`, () => {
+      expect(
+        staticOptionalPeersOf(target.entry),
+        `importing cursedbelt/${target.subpath.slice(2)} statically pulls these OPTIONAL peers, so every consumer must install them for code it may never call. Either import the leaf module that has what you need instead of a sibling INDEX (that is how 'otplib' got in here twice), or make the dependency lazy: \`const { x } = await import('pkg')\` inside the function that needs it.`,
+      ).toEqual([]);
+    });
+  }
+});

package/src/buildIsStaged.spec.ts

@@ -10,7 +10,7 @@
  *
  * cursedbelt is a `file:` dependency of every satellite, so that is not a local
  * problem: every consumer in the fleet typechecked as *"Cannot find module
- * cursedbelt/server/activity"*, *"could not resolve cursedbelt/react"*. The cost
+ * cursedbelt-server/activity"*, *"could not resolve cursedbelt/react"*. The cost
  * is not the outage, it is the SHAPE of it — a landing gate goes red with three app
  * typechecks failing and every test passing, which reads exactly like a defect in
  * the reader's own diff. Two agents hunted their own branches for it.
@@ -56,11 +56,19 @@ describe('the build is staged, not destructive-then-verify', () => {
   })
 
   test('the compilers emit into the staging directory', () => {
-    // Both projects carry `"outDir": "dist"` in their tsconfigs; the CLI override is
-    // what redirects them. If one of the two loses `--outDir dist.next` it writes
-    // straight into the live tree and the staging is half-inert.
+    // Every tsc project carries `"outDir": "dist"` in its tsconfig; the CLI override is
+    // what redirects them. If one loses `--outDir dist.next` it writes straight into the
+    // live tree and the staging is half-inert.
+    //
+    // 🔴 Counted against the tsc invocations in the script rather than hard-coded: this
+    // was `toBe(2)` until 2026-09-15, when the split took `tsconfig.build.server.json`
+    // (and its project) to `cursedbelt-server`. A hard-coded 2 would have had to be
+    // hand-edited to 1 — and then again to 2 by whoever adds the next project, which is
+    // exactly the edit somebody makes without re-reading what it means.
+    const tscRuns = build.match(/tsc --project/g) ?? []
     const overrides = build.match(/--outDir dist\.next/g) ?? []
-    expect(overrides.length, 'both tsc projects must emit into dist.next').toBe(2)
+    expect(tscRuns.length, 'the build must run at least one tsc project').toBeGreaterThan(0)
+    expect(overrides.length, 'every tsc project must emit into dist.next').toBe(tscRuns.length)
   })
 
   test('the assets are copied into the staging directory too', () => {

package/src/demoFixture.spec.ts

@@ -12,6 +12,7 @@ import {
 } from '../demo/devServer';
 import { DEMO_TSCONFIG, derivePaths, readDemoTsconfig, renderPathsBlock } from '../demo/generatePaths';
 import pkg from '../package.json';
+import { STAGES } from '../scripts/verify';
 
 /**
  * 🔴 The e2e suite must never be able to sit green while it drives nothing.
@@ -101,7 +102,16 @@ describe('the e2e fixture exists', () => {
 		// Everything above proves the fixture resolves. Only this proves anybody looks:
 		// without it, `e2e` drops back out of the gate and this whole file becomes a
 		// comment about a suite nothing runs.
-		expect(pkg.scripts.verify, '`verify` must end in the e2e suite').toInclude('bun run e2e');
+		//
+		// 🔴 `verify` stopped being an `&&` chain on 2026-09-15 and became a dependency
+		// graph (`scripts/verify.ts`), so "the script mentions e2e" is no longer where the
+		// answer lives. Asking the graph is strictly stronger than asking the string was:
+		// `verifyGraph.spec.ts` additionally pins that every OTHER stage of the old chain
+		// is still in it, which the `toInclude` never checked for any of them.
+		expect(
+			STAGES.map((s) => s.script),
+			'`verify` must still run the e2e suite',
+		).toContain('e2e');
 		expect(pkg.scripts.e2e).toInclude('e2e/playwright.config.ts');
 	});
 });

package/src/index.ts

@@ -1,120 +1,14 @@
 /**
- * 🔴 A change to ANY file in this package is now visible to `deploy:stale` (2026-08-19).
+ * cursedbelt — since 3.0.0 (task 148, 2026-09-15), the React design system and
+ * nothing else. The split put the isomorphic domain logic in `cursedbelt-core`,
+ * the Bun/Hono app tier in `cursedbelt-server`, and the cc SaaS/engine platform
+ * in `cursedbelt-cc`; each is reached by published version, never by path.
  *
- * `cursedbelt` is consumed as a live `file:` dep, so a fix here ships in every consumer's
- * NEXT artifact without moving `cursed-satellites` by one commit — and for months that
- * meant the fleet ledger reported every consumer FRESH while they served the old bundle.
- * Unit 13's media-player fix is the measured case: three apps were redeployed by hand and
- * two were left stale with nothing able to say so.
- *
- * Every artifact now records `belt.commitFull` beside its own sha (`satellite-kit`'s
- * `buildStamp.ts`), and `compareFreshness` reports a consumer whose belt sha is behind
- * this repo's `main` as `belt-behind`. So: land here, run
- * `cd ~/code/active/cursed-satellites && bun run deploy:stale -- --dry-run`, and the
- * consumers are named. You no longer have to remember that they exist.
- *
- * 🔴 And run `bun run build` before you call it done — a consumer's BROWSER bundle
- * resolves this package through `dist`, not through the `bun` condition its server uses.
- * `bun run gate` at the repo root fails when `dist` is older than `src`.
+ * The real surface is `cursedbelt/react` (the barrel), the per-component
+ * subpaths (`cursedbelt/react/charts`, …), and the stylesheet entries
+ * (`cursedbelt/styles.css`, `cursedbelt/theme.css`). This root exists so the
+ * package resolves bare, and stays deliberately empty of re-exports: the
+ * pre-split "." barrel re-exported core helpers, and keeping them here would
+ * have been a compatibility layer wearing a barrel's name.
  */
-// cursedbelt core (framework-agnostic utilities). The React UI kit lives in
-// `cursedbelt/react`; the isomorphic ctgr codec in `cursedbelt/server`.
-export const VERSION = '0.0.0';
-
-// Color helpers — framework-agnostic, pure over hex strings. `contrastText` is the
-// canonical readable-foreground picker (WCAG luminance) shared by both apps.
-export { contrastText } from './core/color';
-// D36 — the marketing-copy contract: the ONE key/default list the static site
-// build bakes, the server validates against, and the admin panel lists. Pure
-// data, so it is safe from every consumer (a bun build script included).
-export {
-  isSiteCopyKey,
-  SITE_COPY_BAKED_ONLY,
-  SITE_COPY_DEFAULTS,
-  SITE_COPY_KEYS,
-  SITE_COPY_MAX_VALUE_LENGTH,
-  type SiteCopyKey,
-} from './core/site/siteCopy';
-// Schema-field descriptor model — the framework-agnostic types/helpers behind
-// `SchemaFields` (React) and cursedshell's `describeSchema`/reflection layer.
-// Despite living under `src/react/`, this module itself has zero React import
-// (its only own import is a type-only `FieldOption`), so it's re-exported here
-// too for React-free consumers (e.g. `cursedshell/contract`). `cursedbelt/react`
-// keeps re-exporting the same symbols for existing consumers.
-export {
-  defaultKindFor,
-  type FieldConstraints,
-  type FieldDescriptor,
-  type FieldKind,
-  type FieldType,
-  type FieldUiHints,
-  humanizeFieldName,
-} from './react/schema-fields/types';
-// The ONE zod → FieldDescriptor walker (and the `.meta()` hint channel it reads).
-// Lives beside the descriptor types it produces so a cursedbelt schema and a
-// cursedshell plugin schema reflect through the same code; cursedshell
-// re-exports these under its own names.
-export { describeSchema, field, UI_META_KEY, uiHintsOf } from './react/schema-fields/describeSchema';
-// CSV codec — typed PapaParse wrapper (parse/stream/serialize). The codec itself
-// lives in cwip (`cwip/csv`, framework-free pure logic per STANDARDS §1/§3);
-// cursedbelt only re-exports it so its public surface is unchanged.
-export {
-  type CsvParseOptions,
-  type CsvParseResult,
-  parseCsv,
-  type StreamCsvOptions,
-  streamCsv,
-  type ToCsvOptions,
-  toCsv,
-} from 'cwip/csv';
-// Client download — the canonical "save this blob" primitive (DOM-only, no-ops off
-// the browser). `base64ToBytes` decodes a base64 payload (e.g. an exported .sqlite
-// snapshot) for it.
-export { base64ToBytes, downloadBlob } from './core/download';
-
-// Color-scheme (light/dark) store (framework-free). `initColorScheme()` applies the
-// saved/OS scheme at app boot; the React toggle/hook are in `cursedbelt/react`.
-export {
-  applyColorSchemeToDocument,
-  COLOR_SCHEME_STORAGE_KEY,
-  type ColorSchemeMode,
-  type ColorSchemeStorage,
-  type ColorSchemeStore,
-  type ColorSchemeStoreOptions,
-  colorSchemeStore,
-  createColorSchemeStore,
-  getColorSchemeMode,
-  getResolvedColorScheme,
-  initColorScheme,
-  type ResolvedColorScheme,
-  setColorSchemeMode,
-  subscribeColorScheme,
-  toggleColorScheme,
-} from './core/colorScheme';
-
-// UI-scale model + store (framework-free). `initUiScale()` applies the saved size at
-// app boot; the React control/hook are in `cursedbelt/react`.
-export {
-  applyUiScaleToDocument,
-  clampUiScale,
-  createUiScaleStore,
-  DEFAULT_UI_SCALE,
-  getUiScale,
-  initUiScale,
-  MAX_UI_SCALE,
-  MIN_UI_SCALE,
-  nearestUiScaleLevel,
-  setUiScale,
-  stepUiScale,
-  subscribeUiScale,
-  UI_SCALE_LEVELS,
-  UI_SCALE_STEP,
-  UI_SCALE_STORAGE_KEY,
-  type UiScaleLevel,
-  type UiScaleLevelId,
-  type UiScaleStorage,
-  type UiScaleStore,
-  type UiScaleStoreOptions,
-  uiScaleStore,
-  uiScaleToFontSize,
-} from './core/uiScale';
+export const VERSION = '3.0.0';

package/src/publicSurface.spec.ts

@@ -44,7 +44,10 @@ describe('public surface', () => {
 	it('has measured a real surface', () => {
 		// Guards the three assertions below: if `exports` were ever read as empty,
 		// every one of them passes vacuously and the ratchet quietly dies.
-		expect(result.surface.counts.size).toBeGreaterThan(50);
+		// 🔴 30, not 50: the 2026-09-15 split took this package from 89 export subpaths to
+		// 45, and a vacuity guard set above the real surface fails for the one reason a
+		// vacuity guard must never fail — the surface being healthy and simply smaller.
+		expect(result.surface.counts.size).toBeGreaterThan(30);
 	});
 
 	it('publishes no export subpath the baseline does not know', () => {

package/src/react/analytics/AnalyticsPanel.tsx

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import { rangeLabel, type RangeWindow } from '../../core/analytics/range';
+import { rangeLabel, type RangeWindow } from 'cursedbelt-core/analytics/range';
 import { ChartTablePanel, type ChartTablePanelProps } from '../components/ChartTablePanel';
 import type { ColDef } from '../components/DataTable/types';
 

package/src/react/analytics/MetricDrilldown.tsx

@@ -2,7 +2,7 @@ import { type ReactNode, useCallback, useState } from 'react';
 import { Modal } from '../components/Modal';
 import type { ColDef } from '../components/DataTable/types';
 import { AnalyticsPanel } from './AnalyticsPanel';
-import type { RangeWindow } from '../../core/analytics/range';
+import type { RangeWindow } from 'cursedbelt-core/analytics/range';
 
 export interface MetricDrilldownProps<TRow extends Record<string, unknown>> {
   open: boolean;