cursedbelt-server 1.0.0

package/package.json

@@ -0,0 +1,234 @@
+{
+	"name": "cursedbelt-server",
+	"version": "1.0.0",
+	"license": "ISC",
+	"type": "module",
+	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
+	"cursed": {
+		"schemaVersion": 1,
+		"app": {
+			"name": "cursedbelt-server",
+			"commands": {
+				"test": "test",
+				"typecheck": "typecheck",
+				"build": "build"
+			}
+		}
+	},
+	"scripts": {
+		"clean": "rm -rf dist",
+		"typecheck": "tsc -p tsconfig.build.json --noEmit",
+		"test": "NODE_ENV=development bun test src",
+		"build": "bun run clean && tsc -p tsconfig.build.json",
+		"paths": "bun ../../tools/check-paths.ts .",
+		"verify": "bun run paths && bun run typecheck && bun run build && bun run test",
+		"prepublishOnly": "bun run verify"
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/server/index.d.ts",
+			"bun": "./src/server/index.ts",
+			"source": "./src/server/index.ts",
+			"import": "./dist/server/index.js"
+		},
+		"./activity": {
+			"types": "./dist/server/activity/index.d.ts",
+			"bun": "./src/server/activity/index.ts",
+			"source": "./src/server/activity/index.ts",
+			"import": "./dist/server/activity/index.js"
+		},
+		"./context": {
+			"types": "./dist/server/context.d.ts",
+			"bun": "./src/server/context.ts",
+			"source": "./src/server/context.ts",
+			"import": "./dist/server/context.js"
+		},
+		"./dropzone": {
+			"types": "./dist/server/dropzone/index.d.ts",
+			"bun": "./src/server/dropzone/index.ts",
+			"source": "./src/server/dropzone/index.ts",
+			"import": "./dist/server/dropzone/index.js"
+		},
+		"./errors": {
+			"types": "./dist/server/errors.d.ts",
+			"bun": "./src/server/errors.ts",
+			"source": "./src/server/errors.ts",
+			"import": "./dist/server/errors.js"
+		},
+		"./guard": {
+			"types": "./dist/server/guard/index.d.ts",
+			"bun": "./src/server/guard/index.ts",
+			"source": "./src/server/guard/index.ts",
+			"import": "./dist/server/guard/index.js"
+		},
+		"./guard/revocations": {
+			"types": "./dist/server/guard/revocationStore.d.ts",
+			"bun": "./src/server/guard/revocationStore.ts",
+			"source": "./src/server/guard/revocationStore.ts",
+			"import": "./dist/server/guard/revocationStore.js"
+		},
+		"./incidents": {
+			"types": "./dist/server/incidents/index.d.ts",
+			"bun": "./src/server/incidents/index.ts",
+			"source": "./src/server/incidents/index.ts",
+			"import": "./dist/server/incidents/index.js"
+		},
+		"./item-crypto": {
+			"types": "./dist/server/auth/vault.d.ts",
+			"bun": "./src/server/auth/vault.ts",
+			"source": "./src/server/auth/vault.ts",
+			"import": "./dist/server/auth/vault.js"
+		},
+		"./jobs": {
+			"types": "./dist/server/jobs/index.d.ts",
+			"bun": "./src/server/jobs/index.ts",
+			"source": "./src/server/jobs/index.ts",
+			"import": "./dist/server/jobs/index.js"
+		},
+		"./login-throttle": {
+			"types": "./dist/server/auth/loginThrottle.d.ts",
+			"bun": "./src/server/auth/loginThrottle.ts",
+			"source": "./src/server/auth/loginThrottle.ts",
+			"import": "./dist/server/auth/loginThrottle.js"
+		},
+		"./master-lock": {
+			"types": "./dist/server/master-lock/index.d.ts",
+			"bun": "./src/server/master-lock/index.ts",
+			"source": "./src/server/master-lock/index.ts",
+			"import": "./dist/server/master-lock/index.js"
+		},
+		"./middleware": {
+			"types": "./dist/server/middleware/index.d.ts",
+			"bun": "./src/server/middleware/index.ts",
+			"source": "./src/server/middleware/index.ts",
+			"import": "./dist/server/middleware/index.js"
+		},
+		"./migration": {
+			"types": "./dist/server/migration/runner.d.ts",
+			"bun": "./src/server/migration/runner.ts",
+			"source": "./src/server/migration/runner.ts",
+			"import": "./dist/server/migration/runner.js"
+		},
+		"./net": {
+			"types": "./dist/server/net/outboundGuard.d.ts",
+			"bun": "./src/server/net/outboundGuard.ts",
+			"source": "./src/server/net/outboundGuard.ts",
+			"import": "./dist/server/net/outboundGuard.js"
+		},
+		"./notifications": {
+			"types": "./dist/server/notifications/index.d.ts",
+			"bun": "./src/server/notifications/index.ts",
+			"source": "./src/server/notifications/index.ts",
+			"import": "./dist/server/notifications/index.js"
+		},
+		"./resume": {
+			"types": "./dist/server/resume/index.d.ts",
+			"bun": "./src/server/resume/index.ts",
+			"source": "./src/server/resume/index.ts",
+			"import": "./dist/server/resume/index.js"
+		},
+		"./retention": {
+			"types": "./dist/server/retention/index.d.ts",
+			"bun": "./src/server/retention/index.ts",
+			"source": "./src/server/retention/index.ts",
+			"import": "./dist/server/retention/index.js"
+		},
+		"./search": {
+			"types": "./dist/server/search/index.d.ts",
+			"bun": "./src/server/search/index.ts",
+			"source": "./src/server/search/index.ts",
+			"import": "./dist/server/search/index.js"
+		},
+		"./sharing": {
+			"types": "./dist/server/sharing/index.d.ts",
+			"bun": "./src/server/sharing/index.ts",
+			"source": "./src/server/sharing/index.ts",
+			"import": "./dist/server/sharing/index.js"
+		},
+		"./sqlite": {
+			"types": "./dist/server/sqlite/index.d.ts",
+			"bun": "./src/server/sqlite/index.ts",
+			"source": "./src/server/sqlite/index.ts",
+			"import": "./dist/server/sqlite/index.js"
+		},
+		"./storage": {
+			"types": "./dist/server/storage/index.d.ts",
+			"bun": "./src/server/storage/index.ts",
+			"source": "./src/server/storage/index.ts",
+			"import": "./dist/server/storage/index.js"
+		},
+		"./storage/types": {
+			"types": "./dist/server/storage/types.d.ts",
+			"bun": "./src/server/storage/types.ts",
+			"source": "./src/server/storage/types.ts",
+			"import": "./dist/server/storage/types.js"
+		},
+		"./sync": {
+			"types": "./dist/server/sync/index.d.ts",
+			"bun": "./src/server/sync/index.ts",
+			"source": "./src/server/sync/index.ts",
+			"import": "./dist/server/sync/index.js"
+		},
+		"./ws": {
+			"types": "./dist/server/ws/index.d.ts",
+			"bun": "./src/server/ws/index.ts",
+			"source": "./src/server/ws/index.ts",
+			"import": "./dist/server/ws/index.js"
+		}
+	},
+	"dependencies": {
+		"cursedbelt-core": "^1.0.0",
+		"cwip": "^3.0.2",
+		"jose": "^6.2.3"
+	},
+	"peerDependencies": {
+		"hono": ">=4",
+		"zod": "^4.4.0",
+		"@node-rs/argon2": "^2.0.2",
+		"kysely": "^0.28.17",
+		"kysely-bun-sqlite": "^0.4.0",
+		"otplib": "^13.4.1",
+		"plainjob": "^0.0.14",
+		"sharp": "^0.35.2"
+	},
+	"peerDependenciesMeta": {
+		"@node-rs/argon2": {
+			"optional": true
+		},
+		"kysely": {
+			"optional": true
+		},
+		"kysely-bun-sqlite": {
+			"optional": true
+		},
+		"otplib": {
+			"optional": true
+		},
+		"plainjob": {
+			"optional": true
+		},
+		"sharp": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.0",
+		"@happy-dom/global-registrator": "^20.10.6",
+		"@node-rs/argon2": "^2.0.2",
+		"@types/bun": "^1.3.14",
+		"@types/node": "^24",
+		"hono": "4.12.28",
+		"kysely": "^0.28.17",
+		"kysely-bun-sqlite": "^0.4.0",
+		"otplib": "^13.4.1",
+		"papaparse": "^5",
+		"plainjob": "^0.0.14",
+		"sharp": "^0.35.2",
+		"typescript": "^6.0.3",
+		"zod": "4.4.3"
+	}
+}

package/src/declaredDepsAreImported.spec.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * Every declared dependency must be reachable from an import (2026-09-13).
+ *
+ * `dependencies` is not advice — a consumer installs all of it to render one
+ * button. `peerDependencies` is a promise that installing the peer lights a
+ * feature up. Both rot silently: a component gets deleted, its package stays
+ * declared, and nothing anywhere reds. At the time this was written the manifest
+ * carried three runtime deps and five optional peers that no file imported.
+ *
+ * 🔴 The reason this matches an IMPORT SPECIFIER and scans EVERY file type,
+ * rather than grepping .ts for the bare name:
+ *
+ *  - A .ts-only grep says `tw-animate-css` is dead. It is not — it is pulled in
+ *    from CSS (`@import` in src/styles.css), and deleting it would have shipped
+ *    a package whose stylesheet cannot resolve. That is the exact mistake this
+ *    session made on its first pass.
+ *  - A bare-name grep says everything is alive, because names like `diff` and
+ *    `marked` appear in prose in hundreds of files. A gate that cannot fail is
+ *    not a gate.
+ *
+ * devDependencies are deliberately NOT checked: several are installed only so
+ * this repo can typecheck and test an OPTIONAL peer's integration, so "nothing
+ * imports it by name" is the expected state there, not a defect.
+ */
+const ROOTS = ['src', 'scripts'] as const;
+
+// Reading a font or a screenshot as text costs time and can never match.
+const BINARY = /\.(png|jpe?g|gif|webp|avif|ico|mp4|webm|mp3|wav|pdf|zip|gz|woff2?|ttf|otf|eot|wasm)$/i;
+
+/**
+ * `from 'x'` · `import 'x/y.css'` · `import('x')` · `require('x')` · `@import "x"`,
+ * with or without a subpath. Anchored on the specifier quote so a name mentioned
+ * in prose or in a comment does not count as a use.
+ */
+const RE_SPECIAL = /[.*+?^${}()|[\]\\]/g;
+
+const importsPackage = (name: string): RegExp =>
+	new RegExp(`(?:from|import|require|@import)\\s*\\(?\\s*['"]${name.replace(RE_SPECIAL, '\\$&')}(?:/[^'"]*)?['"]`);
+
+// 🔴 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.
+let cache: Promise<string[]> | undefined;
+const sources = (): Promise<string[]> => {
+	cache ??= (async () => {
+		const repo = `${import.meta.dir}/..`;
+		const texts: string[] = [];
+		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)) continue;
+				texts.push(await Bun.file(`${dir}/${rel}`).text());
+			}
+		}
+		return texts;
+	})();
+	return cache;
+};
+
+const unimported = async (block: Record<string, string> | undefined): Promise<string[]> => {
+	const texts = await sources();
+	return Object.keys(block ?? {}).filter((name) => {
+		const re = importsPackage(name);
+		return !texts.some((t) => re.test(t));
+	});
+};
+
+describe('declared dependencies are imported', () => {
+	it('has scanned a real source tree', async () => {
+		// Guards the whole file: if the glob or the fs mock ever returns nothing,
+		// every assertion below passes vacuously and the gate quietly dies.
+		expect((await sources()).length).toBeGreaterThan(100);
+	});
+
+	for (const field of ['dependencies', 'peerDependencies'] as const) {
+		it(`${field} names nothing the code never imports`, async () => {
+			const dead = await unimported((pkg as Record<string, unknown>)[field] as Record<string, string>);
+			expect(
+				dead,
+				`declared in ${field} but imported nowhere in ${ROOTS.join('/')} — import it or drop it:\n  ${dead.join('\n  ')}`,
+			).toEqual([]);
+		});
+	}
+});

package/src/leafSubpathsImportNothing.spec.ts

@@ -0,0 +1,358 @@
+import { describe, expect, it } from 'bun:test';
+import { readdirSync, rmSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * A LEAF subpath's whole promise is what it does NOT pull in. Nothing in this repo
+ * measured that until now (2026-09-15), so the promise was kept by hand — and it was
+ * broken twice in two days, in the same shape, one level apart.
+ *
+ * ## The measurement this exists because of
+ *
+ * `apps/collections/src/kit/binaryStore.ts` needed exactly one thing from here:
+ *
+ *     import type { FileTokenClaims } from "cursedbelt/server/storage";
+ *
+ * A TYPE — TypeScript erases it, so the app should have paid nothing at runtime. What it
+ * actually paid was:
+ *
+ *     error: Cannot find package 'otplib' from
+ *       …/node_modules/cursedbelt/src/server/auth/totp.ts
+ *
+ * …and four unrelated route suites died before anything was measured. `server/storage`'s
+ * index is a barrel; the barrel reached `streamToken.ts`, which imported the `../auth`
+ * INDEX for two jose functions, and that index reaches `totp.ts` → `otplib`, an optional
+ * peer. (`sessionStore.ts` takes its Kysely db as a TYPE, so the `kysely` half of the same
+ * trap arrives through the `./server` barrel's `db/kysely.ts` instead — measured, not
+ * assumed: bundling `./server/storage` externals before this change listed `otplib` and
+ * `hono/cookie`, never `kysely`.) The app declared `otplib` as a direct dependency to get
+ * its route suites back — a one-time-password library installed to satisfy a claim shape.
+ *
+ * That is the exact shape 2.5.1 shipped `./server/login-throttle` to fix, one level
+ * deeper, and the rule written down after it ("never import the `cursedbelt/server`
+ * barrel for one primitive") could not catch it, because `./server/storage` IS a leaf by
+ * that rule's standard and has a barrel of its own. A rule that only a human can apply
+ * gets re-broken by the next module that looks like a leaf. So: a check.
+ *
+ * ## What it does
+ *
+ * Assembles a throwaway consumer under `$TMPDIR` — a `node_modules/cursedbelt` holding
+ * this package's REAL package.json (so the real `exports` map is what resolves) and
+ * nothing else but the leaf source files themselves — then spawns bun in it and imports
+ * each leaf by its PUBLIC specifier. No peers are installed, no other file of this package
+ * is even on disk, so any import that survives transpilation fails the import and this
+ * spec with it. `import type` is erased and costs nothing, which is the whole point:
+ * `verbatimModuleSyntax` is on, so a type import that is not written `import type` is
+ * already a typecheck error, and source and `dist` therefore carry the same module graph.
+ *
+ * ## 🔴 The trap that makes the naive version of this check a lie
+ *
+ * Bun AUTO-INSTALLS a missing bare import out of `~/.bun/install/cache` when the walk up
+ * from the importing file finds NO `node_modules` at all. Measured while building this, in
+ * a scratch directory holding two files and nothing else: `import { authenticator } from
+ * 'otplib'` resolved — from
+ * `~/.bun/install/cache/otplib@13.5.0@@@1/dist/index.js` — and the only error was a missing
+ * named export. An "empty fixture" therefore proves NOTHING about what a leaf drags: every
+ * peer in the cache answers.
+ *
+ * Two things hold the line, and the second is the one that matters:
+ *
+ *  1. `bunfig.toml` with `[install] auto = "disable"` in the fixture root. Note what this
+ *     is and is not: with a `node_modules/` present (as here) bun does not auto-install
+ *     anyway — removing the line and re-running left the negative control failing exactly
+ *     as before. It is the second lock, for the day this fixture is refactored into one
+ *     that has no `node_modules` and the trap silently comes back.
+ *  2. The NEGATIVE CONTROL: a file importing `otplib` and nothing else is copied in beside
+ *     the leaves, and this spec fails if importing it SUCCEEDS. Whatever makes peers
+ *     resolvable — auto-install, a `node_modules` above the scratch root, a future bun
+ *     default — the control sees it and reds, instead of letting every assertion below
+ *     pass vacuously.
+ *
+ * ## 🔴 Verified failing, 2026-09-15, before it was trusted — every branch
+ *
+ *   · `import 'otplib'` added to `src/server/storage/types.ts`
+ *       → "cursedbelt/server/storage/types must import nothing at runtime … Cannot find
+ *          package 'otplib' imported from …/node_modules/cursedbelt/src/server/storage/types.ts"
+ *   · the same, but `import { createStreamTokenService } from './streamToken'` — a
+ *     relative import of a module inside this package
+ *       → red too: "Cannot find module './streamToken'". A leaf may not reach sideways
+ *         either, which is why ONLY the leaf files are copied into the fixture.
+ *   · `./server/storage/types` re-pointed at `src/server/storage/index.ts`, the barrel it
+ *     was split out of
+ *       → red: "Cannot find module './videoDerivativeKeys'". A barrel cannot pass this.
+ *   · the negative control re-pointed at `loginThrottle.ts`, which imports nothing, so the
+ *     fixture stopped demonstrating that peers are unreachable
+ *       → red on the control itself: "the fixture resolved 'otplib' … Every assertion below
+ *         is vacuous until that is fixed". The vacuity guard fires.
+ *   · `src/server/private-media/unlock.ts` put back to `import … from '../auth'` — the
+ *     second, two-hop edge, which grep for `../auth` inside `src/server/storage` cannot see
+ *       → red: "importing cursedbelt/server/storage statically pulls these OPTIONAL peers
+ *         … + otplib". This is the branch that found that edge in the first place.
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * Every subpath that promises to cost a consumer NOTHING at runtime. A leaf earns its
+ * place here by being the answer to "I want one type / one primitive out of a module
+ * whose index is heavy" — the entry names the runtime symbol proving the module really
+ * evaluated, so an accidentally-empty module can never pass this vacuously.
+ *
+ * The file is read from `exports`, never hard-coded: re-target the subpath and the check
+ * follows it to the new file rather than going quietly green against the old one.
+ */
+const LEAVES = [
+  {
+    subpath: './storage/types',
+    /** Claim/config shapes + the keyspace helpers. apps/collections wants `FileTokenClaims`. */
+    evaluates: 'fsSourceKey',
+  },
+  {
+    subpath: './login-throttle',
+    /** The failed-login backoff. Every app with a login door; shipped as 2.5.1. */
+    evaluates: 'createLoginThrottle',
+  },
+] as const;
+
+/**
+ * Imports `otplib` and nothing else, so its failure message is unambiguous. It is the
+ * proof that the fixture has no peers — not an assertion about `totp.ts` itself.
+ */
+const CONTROL = 'src/server/auth/totp.ts';
+
+type Outcome = { ok: true; keys: string[] } | { ok: false; error: string };
+
+const exportsMap = pkg.exports as Record<string, { bun?: string } | string>;
+
+/** `./src/server/storage/types.ts` → `src/server/storage/types.ts`. */
+const sourceOf = (subpath: string): string => {
+  const entry = exportsMap[subpath];
+  const bun = typeof entry === 'object' && entry !== null ? entry.bun : undefined;
+  if (typeof bun !== 'string') {
+    throw new Error(`package.json exports has no \`bun\` target for "${subpath}"`);
+  }
+  return bun.replace(/^\.\//, '');
+};
+
+/**
+ * 🔴 The fixture must sit OUTSIDE this repo, and where it lands is not a detail.
+ *
+ * `scripts/testTmpRoot.ts` redirects `$TMPDIR` per process, and when `$FORGE_STATE`
+ * is unset — a bare checkout with no generation around it — its fallback is
+ * deliberately repo-local: `<repo>/.agent.noindex/tmp/<pid>`. For every other suite
+ * that is exactly right. For this one it is fatal: bun resolves a bare import by
+ * walking node_modules UP to the filesystem root, so a fixture under the repo finds
+ * `<repo>/node_modules/otplib` and every peer this check exists to prove unreachable
+ * becomes reachable.
+ *
+ * Measured 2026-09-15: with `$FORGE_STATE` set the negative control failed correctly;
+ * with it unset the SAME control resolved `otplib` out of this repo's own
+ * `node_modules` and the guard fired — *"the fixture resolved 'otplib' … Every
+ * assertion below is vacuous until that is fixed"*. So `bun run verify` was green
+ * under the runner and red in a plain shell, for a reason that has nothing to do with
+ * the code under test. The control did its job; the fixture's address was the bug.
+ *
+ * Resolution here is therefore explicit rather than inherited. The redirected root is
+ * used when it lies outside the repo (the normal case — the runner always sets
+ * `$FORGE_STATE`, and the preload's sweep then cleans up after a killed run). When it
+ * does not, this hops to `$HOME`, which `resolveTestTmpRoot` refuses for the general
+ * default and which this check genuinely requires: an isolated root is the whole
+ * measurement. Stale siblings are swept by mtime, the same way the preload does it,
+ * so the hop cannot accumulate.
+ */
+const REPO_PREFIX = `${REPO.replace(/\/$/, '')}/`;
+
+const fixtureRoot = (): string => {
+  const redirected = process.env.TMPDIR;
+  if (redirected !== undefined && !`${redirected}/`.startsWith(REPO_PREFIX)) {
+    return `${redirected}/leaf-subpath-fixture`;
+  }
+  const home = process.env.HOME?.trim();
+  if (home === undefined || home === '') {
+    throw new Error(
+      'no isolated root available for the leaf fixture ($TMPDIR is inside this repo and $HOME is unset) — ' +
+        'a check that cannot isolate itself is not a passing check',
+    );
+  }
+  const outside = `${home}/.${pkg.name}-leaf-fixture.noindex`;
+  try {
+    const cutoff = Date.now() - 6 * 60 * 60 * 1000;
+    for (const entry of readdirSync(outside)) {
+      const path = `${outside}/${entry}`;
+      try {
+        if (statSync(path).mtimeMs < cutoff) rmSync(path, { recursive: true, force: true });
+      } catch {
+        // racing another run's sweep is fine — whoever wins, it goes
+      }
+    }
+  } catch {
+    // no root yet: Bun.write creates it below
+  }
+  return `${outside}/${process.pid}/leaf-subpath-fixture`;
+};
+
+const run = async (): Promise<Record<string, Outcome>> => {
+  const root = fixtureRoot();
+  const pkgDir = `${root}/node_modules/${pkg.name}`;
+
+  // The second lock against bun's auto-install (see the header). The negative control is the
+  // first one, and the one that would catch this line being wrong.
+  await Bun.write(`${root}/bunfig.toml`, '[install]\nauto = "disable"\n');
+  // The REAL manifest: the export map under test, resolved exactly as a consumer resolves it.
+  await Bun.write(`${pkgDir}/package.json`, Bun.file(`${REPO}/package.json`));
+
+  const targets: Array<{ name: string; specifier: string }> = [];
+  for (const leaf of LEAVES) {
+    const source = sourceOf(leaf.subpath);
+    // 🔴 Bun.file/Bun.write, NOT node:fs — this repo's test preload virtualizes node:fs, so a
+    // copy made through it can land in a mock the spawned child cannot see. Same trap as
+    // publishShape.spec.ts.
+    await Bun.write(`${pkgDir}/${source}`, Bun.file(`${REPO}/${source}`));
+    targets.push({ name: leaf.subpath, specifier: `${pkg.name}/${leaf.subpath.slice(2)}` });
+  }
+  await Bun.write(`${pkgDir}/${CONTROL}`, Bun.file(`${REPO}/${CONTROL}`));
+  // By PATH, not by subpath: the control is deliberately not exported, and an
+  // ERR_PACKAGE_PATH_NOT_EXPORTED would prove nothing about peer resolution.
+  targets.push({ name: 'control', specifier: `./node_modules/${pkg.name}/${CONTROL}` });
+
+  await Bun.write(
+    `${root}/entry.ts`,
+    `const targets = ${JSON.stringify(targets)};
+const out = {};
+for (const t of targets) {
+  try {
+    const mod = await import(t.specifier);
+    out[t.name] = { ok: true, keys: Object.keys(mod) };
+  } catch (error) {
+    out[t.name] = { ok: false, error: String((error && error.message) || error) };
+  }
+}
+console.log(JSON.stringify(out));
+`,
+  );
+
+  const child = Bun.spawnSync(['bun', 'run', 'entry.ts'], {
+    cwd: root,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const stdout = child.stdout.toString().trim();
+  if (child.exitCode !== 0 || stdout === '') {
+    throw new Error(
+      `the fixture could not run at all (exit ${child.exitCode}) — that is a broken check, not a passing one:\n${child.stderr.toString()}`,
+    );
+  }
+  return JSON.parse(stdout) as Record<string, Outcome>;
+};
+
+/**
+ * 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 — `music`, `family` and `roms` all take `cursedbelt/server/storage` 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: './storage',
+    /** 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/server/storage/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;
+
+const staticOptionalPeersOf = (entry: string): string[] => {
+  const build = Bun.spawnSync(
+    ['bun', 'build', entry, '--target=bun', '--packages=external'],
+    { cwd: REPO, stdout: 'pipe', stderr: 'pipe' },
+  );
+  const bundle = build.stdout.toString();
+  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();
+};
+
+const outcomes = await run();
+
+describe('leaf subpaths import nothing at runtime', () => {
+  it('has a fixture with no peers installed (negative control)', () => {
+    const control = outcomes.control;
+    expect(control, 'the control never ran — the fixture is not measuring anything').toBeDefined();
+    expect(
+      control?.ok === false,
+      `the fixture resolved 'otplib' — bun auto-installed it out of ~/.bun/install/cache, or a node_modules above the fixture answered. Every assertion below is vacuous until that is fixed; do not delete this test to make it pass.`,
+    ).toBe(true);
+    expect(
+      control?.ok === false ? control.error : '',
+      'the control failed for the wrong reason — it must fail on the missing PACKAGE',
+    ).toContain("Cannot find package 'otplib'");
+  });
+
+  for (const leaf of LEAVES) {
+    it(`${pkg.name}/${leaf.subpath.slice(2)} imports clean`, () => {
+      const outcome = outcomes[leaf.subpath];
+      expect(outcome, `${leaf.subpath} was never imported by the fixture`).toBeDefined();
+      expect(
+        outcome?.ok === true ? '' : outcome?.ok === false ? outcome.error : 'missing',
+        `${pkg.name}/${leaf.subpath.slice(2)} must import NOTHING at runtime — that is the entire reason the subpath exists. Move whatever it now reaches behind \`import type\`, or split the leaf again; do not add the dependency to a consumer.`,
+      ).toBe('');
+      // Non-vacuity: a module that resolved but exported nothing would otherwise pass.
+      expect(
+        outcome?.ok === true ? outcome.keys : [],
+        `${leaf.subpath} resolved but does not export ${leaf.evaluates} — the check is pointing at the wrong file`,
+      ).toContain(leaf.evaluates);
+    });
+  }
+});
+
+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(3);
+    expect([...OPTIONAL_PEERS], 'otplib is the peer this whole spec was written for').toContain(
+      'otplib',
+    );
+  });
+
+  for (const target of NO_STATIC_OPTIONAL_PEERS) {
+    it(`${pkg.name}/${target.subpath.slice(2)} costs a consumer no optional peer to import`, () => {
+      expect(
+        staticOptionalPeersOf(target.entry),
+        `importing ${pkg.name}/${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([]);
+    });
+  }
+});