cursedbelt-core 1.0.0

package/src/ctgr/v0compat.ts

@@ -0,0 +1,156 @@
+/*
+ * Legacy (v0) ctgr decoder — kept ONLY for the rollout window so a server running v1
+ * still understands requests from not-yet-updated clients (which send no `_cv`). The
+ * v0 codec was `encode→reverse→swap→base64→swap`: a trivially reversible transform,
+ * never a security mechanism (the real protection is the getOnly JWT claim + the CSRF
+ * guard, both unchanged). Delete this file once all clients ship v1.
+ *
+ * Detect v0 by the ABSENCE of `_cv` (the old client never sent it) — the safest
+ * heuristic, since v1 always sets `_cv=1`. v0 carried the method only in the path
+ * (`/ctgr<XX>`), so the middleware passes the path-derived method in.
+ */
+import { fromBase64 } from './base64url';
+import { extractFiles } from './codec';
+import type { CtgrDecoded, CtgrMethod } from './types';
+
+const decodeBase64Utf8 = (str: string): string => new TextDecoder().decode(fromBase64(str));
+const reverseString = (str: string): string => str.split('').reverse().join('');
+const swapEnds = (str: string): string => {
+  if (str.length < 2) return str;
+  const arr = str.split('');
+  arr[0] = str[str.length - 1];
+  arr[str.length - 1] = str[0];
+  return arr.join('');
+};
+
+/** Reverse the v0 client pipeline (`encode→reverse→swap→encode→swap`) and parse JSON. */
+export function decodeV0Payload(encoded: string): unknown {
+  const json = decodeBase64Utf8(reverseString(swapEnds(decodeBase64Utf8(swapEnds(encoded)))));
+  let body = JSON.parse(json);
+  // The legacy client occasionally double-encoded the body string; unwrap it.
+  if (typeof body === 'string') body = JSON.parse(body);
+  return body;
+}
+
+function toDecoded(body: unknown, method: CtgrMethod): CtgrDecoded {
+  const { body: rest, files } = extractFiles(body);
+  return files ? { method, body: rest, files } : { method, body: rest };
+}
+
+export interface V0ChunkStoreOpts {
+  maxInFlight?: number;
+  /** Hard cap on the joined encoded string length (chars). Default ~80 MB. */
+  maxPayloadChars?: number;
+  ttlMs?: number;
+  now?: () => number;
+}
+
+interface V0Entry {
+  parts: (string | undefined)[];
+  total: number;
+  received: number;
+  chars: number;
+  method: CtgrMethod;
+  updatedAt: number;
+}
+
+/**
+ * Bounded accumulator for v0 requests, mirroring the legacy `unGETifyRoute` (`p` for
+ * a single payload; `cid`/`ci`/`ct`/`p` for chunked). Same `add` contract as the v1
+ * {@link ChunkStore}: `false` for an intermediate chunk, {@link CtgrDecoded} when
+ * complete, `Error` on malformed input.
+ */
+export class V0ChunkStore {
+  private readonly entries = new Map<string, V0Entry>();
+  private readonly maxInFlight: number;
+  private readonly maxPayloadChars: number;
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  constructor(opts: V0ChunkStoreOpts = {}) {
+    this.maxInFlight = opts.maxInFlight ?? 200;
+    this.maxPayloadChars = opts.maxPayloadChars ?? 80 * 1024 * 1024;
+    this.ttlMs = opts.ttlMs ?? 2 * 60 * 1000;
+    this.now = opts.now ?? Date.now;
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  add(params: Record<string, string>, method: CtgrMethod): CtgrDecoded | false | Error {
+    this.evictStale();
+
+    // Single payload (or a body-less converted request: no `p`).
+    if (params.cid === undefined) {
+      if (!params.p) return { method, body: undefined };
+      try {
+        return toDecoded(decodeV0Payload(params.p), method);
+      } catch (err) {
+        return asError(err);
+      }
+    }
+
+    // Chunked payload.
+    const cid = params.cid;
+    const total = Number(params.ct);
+    const index = Number(params.ci);
+    if (
+      !Number.isInteger(total) ||
+      total <= 0 ||
+      !Number.isInteger(index) ||
+      index < 0 ||
+      index >= total
+    ) {
+      return new Error('ctgr v0: invalid chunk metadata');
+    }
+
+    let entry = this.entries.get(cid);
+    if (!entry) {
+      if (this.entries.size >= this.maxInFlight) {
+        return new Error('ctgr v0: too many in-flight payloads');
+      }
+      entry = {
+        parts: new Array(total),
+        total,
+        received: 0,
+        chars: 0,
+        method,
+        updatedAt: this.now(),
+      };
+      this.entries.set(cid, entry);
+    }
+    entry.updatedAt = this.now();
+
+    const piece = params.p ?? '';
+    if (entry.parts[index] === undefined) {
+      entry.parts[index] = piece;
+      entry.received += 1;
+      entry.chars += piece.length;
+      if (entry.chars > this.maxPayloadChars) {
+        this.entries.delete(cid);
+        return new Error('ctgr v0: payload exceeds size cap');
+      }
+    }
+
+    if (entry.received < entry.total) return false;
+
+    this.entries.delete(cid);
+    try {
+      return toDecoded(decodeV0Payload(entry.parts.join('')), method);
+    } catch (err) {
+      return asError(err);
+    }
+  }
+
+  private evictStale(): void {
+    const cutoff = this.now() - this.ttlMs;
+    for (const [cid, entry] of this.entries) {
+      if (entry.updatedAt < cutoff) this.entries.delete(cid);
+    }
+  }
+}
+
+function asError(err: unknown): Error {
+  return err instanceof Error ? err : new Error(String(err));
+}

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/index.ts

@@ -0,0 +1,25 @@
+/**
+ * cursedbelt-core — the framework-agnostic bottom of the cursedbelt split
+ * (task 148, 2026-09-15). Isomorphic domain logic only: no react, no hono,
+ * no DOM requirement at runtime. `cwip` sits below this package;
+ * `cursedbelt-server` and `cursedbelt` (the React design system) sit above it
+ * and share their domain models through it by published version.
+ *
+ * The real surface is the subpath exports (`cursedbelt-core/sharing`,
+ * `cursedbelt-core/master-lock`, …) — this root barrel stays deliberately
+ * tiny because a fat root barrel is what made the pre-split `cursedbelt`
+ * drag 47 dependencies into every consumer.
+ */
+export const VERSION = '1.0.0';
+
+// The two root-level conveniences the pre-split "." barrel actually served:
+// the WCAG readable-foreground picker and the baked marketing-copy contract.
+export { contrastText } from './core/color';
+export {
+	isSiteCopyKey,
+	SITE_COPY_BAKED_ONLY,
+	SITE_COPY_DEFAULTS,
+	SITE_COPY_KEYS,
+	SITE_COPY_MAX_VALUE_LENGTH,
+	type SiteCopyKey,
+} from './core/site/siteCopy';

package/src/leafSubpathsImportNothing.spec.ts

@@ -0,0 +1,287 @@
+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: './ctgr/types',
+    /** Wire-format types + the method⇄abbreviation maps. Trivially isomorphic on purpose. */
+    evaluates: 'METHOD_TO_ABBREV',
+  },
+] as const;
+
+/**
+ * Imports `cwip/error` (a real dependency of this package), so the fixture proving it
+ * CANNOT resolve is the proof the fixture has no packages at all — not an assertion
+ * about `errors.ts` itself.
+ */
+const CONTROL = 'src/shared/errors.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 pre-split copy of this file carried a second half here: "barrels reach no
+ * optional peer statically", bundling each heavy barrel and asserting no OPTIONAL
+ * peer is a static import. cursedbelt-core declares NO optional peers — its whole
+ * dependency surface is cwip + ufuzzy with a zod peer — so that half would measure
+ * an empty set and its own vacuity guard (`OPTIONAL_PEERS.size > 10`) would red.
+ * It lives on in `cursedbelt`, where the optional peers actually are. The day this
+ * package grows an optional peer, copy the half back from there rather than
+ * re-deriving it: the bundling trap notes in its header were paid for.
+ */
+
+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 'cwip' — 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 'cwip");
+  });
+
+  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);
+    });
+  }
+});

package/src/lockfileIsTracked.spec.ts

@@ -0,0 +1,50 @@
+/**
+ * 🔴 Rule 2 of this generation: `bun install --frozen-lockfile` must pass on a
+ * CLEAN CHECKOUT — not merely in the tree an agent happens to be sitting in.
+ *
+ * ── What this cost, 2026-09-13 ──────────────────────────────────────────────
+ * `.gitignore` carried a `bun.lock` stanza with a comment explaining it was
+ * temporary: the only lockfile that could exist at the time recorded a
+ * proof-only local pack of `cwip`, and committing that would have reintroduced
+ * the `file:` dependency the package had just removed. The reasoning was sound
+ * and the expiry condition — "until cwip is on the registry" — was real. It was
+ * also written in a comment, which nothing can evaluate. `cwip@3.0.2` went to
+ * the registry and the stanza stayed, so rule 2 was true of every working tree
+ * and false of every fresh clone: exactly the case the rule exists for, and the
+ * one nobody hits until they are the person doing the clone.
+ *
+ * A temporary ignore needs a check that notices when it stopped being true.
+ * This is that check. `git check-ignore` is the whole mechanism, because the
+ * failure is not "the lockfile is missing" — it is "git has been told to throw
+ * it away", which is invisible in a tree that already has one.
+ *
+ * Deliberately NOT `git ls-files bun.lock`: a regenerated lockfile is untracked
+ * until it is staged, and a check that reds on work-in-progress teaches people
+ * to skip it. Ignored-vs-not is the property that actually regresses.
+ */
+import { describe, expect, test } from 'bun:test'
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url))
+
+describe('bun.lock is part of the checkout', () => {
+  test('the lockfile exists', () => {
+    expect(
+      existsSync(new URL('../bun.lock', import.meta.url)),
+      'no bun.lock — regenerate it with `bun install`, or `bun install --frozen-lockfile` cannot pass for anyone cloning this',
+    ).toBe(true)
+  })
+
+  test('git is not told to ignore it', () => {
+    const git = spawnSync('git', ['check-ignore', '-q', 'bun.lock'], { cwd: repoRoot })
+    if (git.error) return // no git on this host: nothing to assert about ignore rules
+
+    // exit 0 = the path IS ignored; 1 = it is not; anything else = git could not tell us.
+    expect(
+      git.status,
+      'bun.lock is gitignored, so a fresh clone has no lockfile and `bun install --frozen-lockfile` cannot pass there. Delete the stanza from .gitignore rather than the assertion.',
+    ).not.toBe(0)
+  })
+})