cursedops 0.2.5 → 0.2.6

package/README.md

@@ -13,9 +13,11 @@ bun add cursedops
 | `cursedops/smoke` | the scaffolding of a deployed smoke — the ledger, the fetch, the DNS hint, the exit code — and the one check no app owns: every address of a deployment serving the same built client |
 | `cursedops/serve` | the static tier's four helpers — the path-traversal guard, the MIME table, the hashed-asset test, the crash handlers |
 | `cursedops/api-floor` | the rule that an unmatched `/api/...` is a phrase and never the app shell — the namespace predicates, the trailing-slash normaliser and the default 404 body. No `node:` import, so it mounts inside a Worker |
+| `cursedops/public-surface` | the ratchet on a LIBRARY's public surface — a symbol count per export subpath against a committed baseline that may only fall — and its `public-surface` bin. Not an app's: the one entry here admitted for three published libraries, see below |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
-name, a hostname, a port or a route.
+name, a hostname, a port or a route. `typescript` is an **optional** peer: only
+`cursedops/public-surface` imports it, and nothing else here ever loads it.
 
 ## 🔴 The ceiling, and why this library has one
 
@@ -52,6 +54,22 @@ told ONE NAME is a check about that name; this one is about a property every dep
 with two addresses has. It buys the exception by being pinned to a failure it has
 actually caught — `src/smoke.test.ts` runs it against the genuine 2026-09-12 shell.
 
+🔴 **`public-surface` is the second recorded exception, and the first whose callers are
+not apps.** Rule 1 is met — more than met — but by three LIBRARIES: `cwip`, `cursedbelt`
+and `cursedbelt-server` each carried `scripts/publicSurface.ts` (430, 455 and 476 lines),
+and by 0.2.6 the bodies had already forked, which is what admits it. Measured 2026-09-22:
+`cwip`'s threw on a bare-specifier `export *` where the other two resolved and counted
+it, so the three numbers were not commensurable; and when the ESM-extension fix (task
+269) made `./x.js` the spelling of an internal specifier, `cursedbelt-server`'s and
+`cursedbelt`'s copies each had to be taught `./x.js` → `./x.ts` by hand, separately,
+while `cwip`'s never was. Each library is published on its own and its gate must pass
+from a lone checkout, so neither a `file:` import nor a reach into `$FORGE/tools` could
+share it; a published version could, and this package is already that for the fleet.
+It is a devDependency of each library, so nothing their consumers install changed. On
+adoption all three measured **identical per-subpath counts** to their own copies
+(`cwip` 60 subpaths/2,089 symbols, `cursedbelt` 51/1,837, `cursedbelt-server` 34/992) —
+a consolidation that moves a count has changed the measurement, not the plumbing.
+
 ### What was deliberately left in the apps
 
 The comparison that produced this library found three areas that are genuinely
@@ -245,6 +263,29 @@ input the eight copies refused refused, at the same cost. A symlinked ancestor o
 root cancels out — which is the failure a one-sided `realpath` would have shipped to
 every app on this machine, and is its own test.
 
+## `cursedops/public-surface`
+
+```sh
+# in the library's package.json — `bun run surface` / `bun run surface --prune`
+"surface": "public-surface"            # cwip adds --peers
+```
+
+```ts
+import { run } from "cursedops/public-surface";
+
+const { fresh, grown, stale, peers } = await run({ root: packageDir });   // all four [] when clean
+```
+
+`publicSurface.baseline` at the package root is one `<count>  <subpath>` line per
+export subpath. It fails on a subpath the baseline does not list, on one that GREW, and
+on an entry that shrank or matches nothing — so a deleted module cannot leave an
+allowance behind. `--prune` only ever lowers; new surface is a line added by hand in a
+commit that says why. What a count includes and excludes, and the three measurements
+that each produced a copy of this, are in the header of `src/publicSurface.ts`.
+
+It is a check a library runs on ITSELF. It never asks who imports the library — that
+is cross-repo, and a repo's gate proves that repo.
+
 ## Verifying
 
 ```sh

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cursedops",
-	"version": "0.2.5",
-	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, the scaffolding of a deployed smoke, and the static-serving helpers eight apps copied — the path-traversal guard among them — and the API floor that keeps an unmatched /api/... from ever being answered with the app shell. Mechanism only — no app knows its name from here. Bun, zero dependencies, ships source.",
+	"version": "0.2.6",
+	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, the scaffolding of a deployed smoke, and the static-serving helpers eight apps copied — the path-traversal guard among them — and the API floor that keeps an unmatched /api/... from ever being answered with the app shell — and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
@@ -42,12 +42,29 @@
 			"source": "./src/smoke.ts",
 			"import": "./src/smoke.ts"
 		},
+		"./public-surface": {
+			"types": "./src/publicSurface.ts",
+			"bun": "./src/publicSurface.ts",
+			"source": "./src/publicSurface.ts",
+			"import": "./src/publicSurface.ts"
+		},
 		"./package.json": "./package.json"
 	},
+	"bin": {
+		"public-surface": "./src/publicSurface.ts"
+	},
 	"files": [
 		"src",
 		"!src/**/*.test.ts"
 	],
+	"peerDependencies": {
+		"typescript": ">=5"
+	},
+	"peerDependenciesMeta": {
+		"typescript": {
+			"optional": true
+		}
+	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.14",
 		"@types/bun": "^1.3.14",

package/src/publicSurface.ts

@@ -0,0 +1,568 @@
+#!/usr/bin/env bun
+/**
+ * `cursedops/public-surface` — refuse a library's public surface that grows without a
+ * recorded reason. One measurement, one baseline format, one CLI, for every library
+ * that ratchets its surface.
+ *
+ * ```sh
+ * public-surface [--peers] [--seed] [--prune]     # the `bin`, run from the package root
+ * ```
+ *
+ * ```ts
+ * import { run } from "cursedops/public-surface";
+ * const { fresh, grown, stale, peers } = await run({ root: packageDir, peers: true });
+ * ```
+ *
+ * ## What this exists for
+ *
+ * Three libraries measured the same failure from three ends, and each wrote this file:
+ *
+ *   · `cwip`, 2026-09-13. `cwip@1.1.24` was one entry point and its own description said
+ *     *"Helpful utility functions with no external dependencies"*. Three months and one
+ *     reasonable-looking module at a time later, `4.0.0` published **86 subpaths and
+ *     3,109 exported symbols**, of which every consumer on this machine imported 480 —
+ *     15.4%. 2,629 symbols and nine peer dependencies accumulated inside a green gate.
+ *     Tasks 26/27/28 then deleted ~17,000 lines of it.
+ *   · `cursedbelt`, 2026-09-13, across all 845 consumer files on this machine that
+ *     mention it: `1.0.0` published **108 export subpaths and 3,359 exported symbols**,
+ *     of which every consumer together imported **406 — 12.1%**. `cursedbelt/react`
+ *     alone exposed 1,037 and 178 were used. The owner's own account of how it got
+ *     there is *"worked on over many projects with tons of features changing"*.
+ *   · `cursedbelt-server`, 2026-09-19 — the one of the three with no ceiling at all.
+ *     While it was missing that package went from 30 export subpaths at `4.1.0`
+ *     (`ecab556`) to 34 at `4.10.0` (`0a035b1`); `4.1.0` alone added `./binary-store`
+ *     and `./binary-store/testing`, 26 exported symbols in one commit, and nothing had
+ *     to acknowledge it. Walking every named import of it under `$FORGE/{apps,libs,
+ *     autopilot}` — 202 files — against the symbol sets this file computes: **132 of
+ *     836 distinct exported symbols, 15.8%**; eight of 34 subpaths had no importer.
+ *
+ * The rows each package seeded from, measured by the body that package had then — so
+ * each row is commensurable with that package's later runs and NOT with the other two:
+ *
+ *                                          subpaths   symbols   peers
+ *     cwip 4.0.0                                 86     3,109      13
+ *     cwip seeded 2026-09-13                     57     2,030       6
+ *     cursedbelt 1.0.0, before tasks 32/33      108     4,167      51
+ *     cursedbelt seeded 2026-09-13               85     3,808      47
+ *     cursedbelt-server seeded 2026-09-19        34       991       —
+ *
+ * (cursedbelt counts 4,167 for the tree the task measured at 3,359. The gap is method,
+ * not surface — a `default` export, a destructured `export const {a, b}` and a bare
+ * `export * from 'cwip/layout'` are each counted here and were not there. Two numbers
+ * that do not say what they counted cannot be compared, and only one can be a ratchet.)
+ *
+ * 🔴 **This is NOT a dead-code check, and 12–16% used is not a bug to delete.** A design
+ * system or a server tier is SUPPOSED to ship more than any one app has adopted, and
+ * most of the surface is alive — deleting everything safely deletable from `cursedbelt`
+ * removed 4% of it. What was missing was not restraint, it was an INSTRUMENT: the total
+ * was never measured, so growth was invisible at the only moment anyone could have
+ * judged it. This makes growth visible and deliberate. **Document the WHY; automate the
+ * WHETHER.**
+ *
+ * ## Why one body, and why here
+ *
+ * Until 0.2.6 this was `scripts/publicSurface.ts` in each of the three libraries, and
+ * the third was written knowing it was a third (task 084). The bodies had already
+ * forked — which is the whole argument:
+ *
+ *   · `cursedbelt`'s resolved a bare-specifier `export *`, cached one parse per file and
+ *     read `./scripts/**` entries. `cwip`'s THREW on a bare specifier and had none of the
+ *     rest, so a `cwip` subpath re-exporting a package was a hard error there and a count
+ *     in the other two, and the numbers were not commensurable.
+ *   · On 2026-09-22 the ESM-extension fix (task 269) made `./x.js` the spelling of an
+ *     internal specifier, and `cursedbelt-server`'s and `cursedbelt`'s copies each had
+ *     to be taught `./x.js` → `./x.ts` by hand, separately. `cwip`'s never was.
+ *
+ * Each library is a separately published package whose gate must pass from a lone
+ * checkout, which rules out a `file:` import and a reach into `$FORGE/tools` alike. It
+ * lives in `cursedops` — already a published, Bun-only, source-shipping dependency — as
+ * a devDependency of each library, so nothing a library's consumers install changes.
+ * `typescript` is an OPTIONAL peer here: only this subpath imports it, and every
+ * library that runs it already has it.
+ *
+ * ## The ratchet
+ *
+ * `publicSurface.baseline` at the package root holds a COUNT PER SUBPATH, the same shape
+ * as the generation's `tools/check-paths.baseline`. Four ways to fail, and the last two
+ * are what make it a ratchet rather than a high-water mark:
+ *
+ *   1. a subpath in `exports` that the baseline does not list       → NEW SURFACE
+ *   2. a listed subpath whose symbol count went UP                  → GREW
+ *   3. a listed subpath whose count went DOWN, or that is gone      → run --prune
+ *   4. an entry matching no subpath at all                          → run --prune
+ *
+ * (3) and (4) mean a deleted module cannot leave a stale allowance behind for the next
+ * module to grow into. `--prune` records the burn-down in one deliberate command and
+ * REFUSES to raise anything, so a genuine new export is a line added BY HAND in a commit
+ * that says why. `--seed` exists once per package and refuses over an existing baseline.
+ *
+ * ## 🔴 What it counts, exactly — and what it does not
+ *
+ * Per export subpath in `package.json`, the TypeScript AST of the entry module and every
+ * `export * from` beneath it, transitively, deduped by name:
+ *
+ *   · `export const/let/var/function/class/interface/type/enum/namespace`
+ *   · `export { x }`, `export { x as y }`, `export type { x }`
+ *   · `export * as ns from './m'`  (one symbol: `ns`)
+ *   · `export default` / `export default function Foo` (one symbol: `default`)
+ *   · `export * from './m'`        (transitive; cycles are visited once; `./m.js` names
+ *                                   `./m.ts`, the spelling Node ESM needs in emitted code)
+ *   · `export * from 'some-package'` — RESOLVED and walked. A package's symbols
+ *     re-exported under this package's name are this package's surface. If it resolves
+ *     to something this cannot parse (a `.js` build with no types), the run FAILS rather
+ *     than counting zero.
+ *
+ * Deliberately NOT counted, each because counting it would make the number lie:
+ *
+ *   · non-TS export targets (a stylesheet, a wasm blob) — no symbols. Reported as
+ *     "asset export(s)" so they cannot vanish from the accounting.
+ *   · anything not reachable from an `exports` subpath. Internal modules are not public
+ *     surface; what a barrel re-exports is.
+ *   · `bin` targets. 🔴 They ARE public surface and NOT reachable through `exports` —
+ *     which is why an earlier reachability walk seeded from `exports` alone once
+ *     reported `cursedbelt`'s shipped `cc-verify` CLI as removable. A CLI's interface is
+ *     its argv, not its export list.
+ *   · the SHAPE of the subpaths — each library's `publishShape` spec owns that.
+ *
+ * Entry resolution reads the `bun`, `source`, `types`, `import`, `default` conditions in
+ * that order and takes the first `./src/**` or `./scripts/**` TypeScript file — so it
+ * works on a clean checkout before any `build` has written `dist`.
+ *
+ * ## The peers half (`--peers`, or `peers: true`)
+ *
+ * Opt-in, because a library that already has a declared-deps spec must not grow a
+ * second ratchet that can disagree with it. `cwip` has none, so it asks for this:
+ *
+ *   · every peer is named by a non-test `src` file — as a static/dynamic import, a
+ *     `requirePeer(...)` call, or an `@peer <name>` pragma;
+ *   · every peer range is a registry range — a URL, `file:`, `link:`, `git+` or
+ *     `github:` range is refused.
+ *
+ * Measured 2026-09-13 on `cwip`: FOUR of thirteen peers matched no `from '<peer>'` line,
+ * and `xlsx` was pinned to a raw CDN tarball URL. 🔴 The pragma is why this is not the
+ * shell loop that found those four: THREE of its hits were false — `pg`, `mysql2` and
+ * `mssql` load through a runtime variable (`loadDriver('mysql2/promise')`) and were
+ * already declared with `@peer`. Only `@playwright/test` was orphaned; shipping the
+ * loop's answer would have deleted three live peers. Test files and any `testing/`
+ * directory are excluded from the scan: a `mock.module('mongodb', …)` is not a use.
+ *
+ * ## What this may NOT become
+ *
+ *   · Not a usage check. It must never try to know who imports a library; that is
+ *     cross-repo, and a repo's gate proves that repo.
+ *   · Not a ban on growth. New surface is one hand-added line plus a commit message.
+ *   · Not a second guard. One check, one baseline, entry criteria in this header.
+ */
+import { dirname, join } from "node:path";
+import ts from "typescript";
+import { findPackageRoot } from "./roots.ts";
+
+export type SurfaceOptions = {
+	/** The package directory — the one holding `package.json` and the baseline. */
+	root: string;
+	/** Defaults to `<root>/publicSurface.baseline`. */
+	baseline?: string;
+	/** Also check `peerDependencies` (see "The peers half"). Off by default. */
+	peers?: boolean;
+};
+
+type Pkg = {
+	name?: string;
+	exports?: Record<string, unknown>;
+	peerDependencies?: Record<string, string>;
+	scripts?: Record<string, string>;
+};
+
+export type Surface = {
+	/** subpath (as written in `exports`) → deduped exported symbol count */
+	counts: Map<string, number>;
+	/** subpaths skipped because they resolve to a non-TS asset */
+	assets: string[];
+};
+
+export type Baseline = { header: string[]; counts: Map<string, number> };
+
+export type Failures = { grown: string[]; fresh: string[]; stale: string[]; peers: string[] };
+
+const baselineOf = (options: SurfaceOptions): string => options.baseline ?? join(options.root, "publicSurface.baseline");
+
+const readPkg = async (root: string): Promise<Pkg> => (await Bun.file(join(root, "package.json")).json()) as Pkg;
+
+/**
+ * The command a person types to prune THIS package — the `package.json` script that runs
+ * the `public-surface` bin, so the advice names what the package actually wired.
+ */
+export const pruneCommand = (pkg: Pkg): string => {
+	const script = Object.entries(pkg.scripts ?? {}).find(([, body]) => /\bpublic-surface\b/.test(body));
+	return script ? `bun run ${script[0]} --prune` : "bunx public-surface --prune";
+};
+
+export const defaultHeader = (pkg: Pkg): string[] => [
+	`# Public surface of \`${pkg.name ?? "this package"}\`: one line per export subpath, \`<exported symbols>  <subpath>\`.`,
+	"#",
+	"# A CEILING, not an amnesty. The check fails on a subpath NOT listed here, on a listed",
+	"# subpath that gained a symbol, and on an entry that no longer matches `package.json`",
+	"# exports — so a deleted module cannot leave a stale allowance behind. Surface can only fall.",
+	"#",
+	`# To record a deliberate change:  ${pruneCommand(pkg)}`,
+	"# It refuses to RAISE anything, so new surface is a reviewed diff, never a silent one.",
+	"#",
+	"# What a count includes, what it excludes and why, are in the header of the measurement:",
+	"# cursedops/src/publicSurface.ts. Say nothing here that the entries below already say.",
+];
+
+// ── the measurement ─────────────────────────────────────────────────────────────
+
+const isRelative = (spec: string): boolean => spec.startsWith("./") || spec.startsWith("../");
+const isWalkable = (file: string): boolean => /\.(m|c)?tsx?$/.test(file);
+
+/** `./a/b` from `src/x/y.ts` → the first of `src/a/b.ts(x)`, `src/a/b/index.ts(x)`, … that exists. */
+const resolveRelative = async (fromFile: string, spec: string): Promise<string | null> => {
+	const base = join(dirname(fromFile), spec);
+	// `./x.js` names `./x.ts` — the spelling Node ESM needs in the emitted file (task 269),
+	// which tsc copies verbatim from the source. Tried first so a `.js` never resolves to
+	// itself. This is the line two of the three forked copies each had to gain by hand.
+	const fromJs = /\.js$/.test(base) ? [base.replace(/\.js$/, ".ts"), base.replace(/\.js$/, ".tsx")] : [];
+	const candidates = [...fromJs, `${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`, base];
+	for (const c of candidates) {
+		if (await Bun.file(c).exists()) return c;
+	}
+	return null;
+};
+
+/**
+ * A bare `export * from 'pkg'` — resolved through node resolution so its symbols are
+ * counted rather than silently dropped. Throws when the package resolves to something
+ * with no parseable types, because a zero there would be a lie.
+ */
+const resolveBare = (fromFile: string, spec: string): string => {
+	let resolved: string;
+	try {
+		resolved = Bun.resolveSync(spec, dirname(fromFile));
+	} catch (cause) {
+		throw new Error(
+			`${fromFile}: \`export * from '${spec}'\` re-exports a package that does not resolve, so its ` +
+				"symbols cannot be counted. Install it, or name the symbols — do not let the count lie.",
+			{ cause },
+		);
+	}
+	if (!isWalkable(resolved)) {
+		throw new Error(
+			`${fromFile}: \`export * from '${spec}'\` resolves to ${resolved}, which this measurement cannot ` +
+				"parse. Point it at TypeScript, name the symbols, or teach cursedops/public-surface to read " +
+				"a declaration bundle — do not let the count lie.",
+		);
+	}
+	return resolved;
+};
+
+/** Every name a binding pattern introduces — `export const { a, b: [c] } = …` is three. */
+const bindingNames = (name: ts.BindingName, out: Set<string>): void => {
+	if (ts.isIdentifier(name)) {
+		out.add(name.text);
+		return;
+	}
+	for (const el of name.elements) {
+		if (ts.isBindingElement(el)) bindingNames(el.name, out);
+	}
+};
+
+/**
+ * One measurement's parse cache. Barrels overlap heavily — `cursedbelt-server`'s 991
+ * counted symbols are 836 distinct names because `.` re-exports most leaf barrels — so
+ * every file is parsed once per run, not once per subpath that reaches it.
+ */
+const walker = () => {
+	const parsed = new Map<string, ts.SourceFile>();
+	const sourceOf = async (file: string): Promise<ts.SourceFile> => {
+		const hit = parsed.get(file);
+		if (hit !== undefined) return hit;
+		// 🔴 Bun.file, NOT node:fs — a library's test preload can share one process with
+		// specs that virtualize node:fs, and a readFileSync scan then reads MOCK data and
+		// the measurement passes against files it never opened.
+		const source = ts.createSourceFile(file, await Bun.file(file).text(), ts.ScriptTarget.ES2022, true);
+		parsed.set(file, source);
+		return source;
+	};
+
+	/** Deduped exported names of `file`, following `export * from` chains. */
+	const exportedNames = async (file: string, seen = new Set<string>()): Promise<Set<string>> => {
+		const names = new Set<string>();
+		if (seen.has(file)) return names;
+		seen.add(file);
+
+		const source = await sourceOf(file);
+		const modifiersOf = (node: ts.Node): readonly ts.Modifier[] =>
+			ts.canHaveModifiers(node) ? (ts.getModifiers(node) ?? []) : [];
+
+		for (const st of source.statements) {
+			if (ts.isExportDeclaration(st)) {
+				if (st.exportClause && ts.isNamedExports(st.exportClause)) {
+					for (const el of st.exportClause.elements) names.add(el.name.text);
+				} else if (st.exportClause && ts.isNamespaceExport(st.exportClause)) {
+					names.add(st.exportClause.name.text);
+				} else {
+					const spec = st.moduleSpecifier && ts.isStringLiteral(st.moduleSpecifier) ? st.moduleSpecifier.text : null;
+					if (spec === null) continue;
+					let target: string | null;
+					if (isRelative(spec)) {
+						target = await resolveRelative(file, spec);
+						if (target === null) throw new Error(`${file}: \`export * from '${spec}'\` resolves to nothing.`);
+					} else {
+						target = resolveBare(file, spec);
+					}
+					for (const n of await exportedNames(target, seen)) names.add(n);
+				}
+				continue;
+			}
+			if (ts.isExportAssignment(st)) {
+				names.add("default");
+				continue;
+			}
+			const modifiers = modifiersOf(st);
+			if (!modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+			// `export default function Foo()` is imported as `default`, not as `Foo`.
+			if (modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) {
+				names.add("default");
+				continue;
+			}
+			if (ts.isVariableStatement(st)) {
+				for (const d of st.declarationList.declarations) bindingNames(d.name, names);
+			} else if (
+				(ts.isFunctionDeclaration(st) ||
+					ts.isClassDeclaration(st) ||
+					ts.isInterfaceDeclaration(st) ||
+					ts.isTypeAliasDeclaration(st) ||
+					ts.isEnumDeclaration(st) ||
+					ts.isModuleDeclaration(st)) &&
+				st.name !== undefined
+			) {
+				if (ts.isIdentifier(st.name) || ts.isStringLiteral(st.name)) names.add(st.name.text);
+			}
+		}
+		return names;
+	};
+	return exportedNames;
+};
+
+/** The `./src/**` or `./scripts/**` TypeScript file a subpath resolves to, or null when it is an asset. */
+const entryOf = (root: string, value: unknown): string | null => {
+	if (typeof value === "string")
+		return (value.startsWith("./src/") || value.startsWith("./scripts/")) && isWalkable(value)
+			? join(root, value.slice(2))
+			: null;
+	if (typeof value !== "object" || value === null) return null;
+	// `bun` and `source` point at TypeScript; `types` and `import` may point into `dist`,
+	// which is build output and may not exist. This order is what makes the measurement
+	// work on a clean checkout. Nested conditions (`./testing`) recurse.
+	const record = value as Record<string, unknown>;
+	for (const key of ["bun", "source", "types", "import", "default"]) {
+		if (key in record) {
+			const hit = entryOf(root, record[key]);
+			if (hit !== null) return hit;
+		}
+	}
+	for (const v of Object.values(record)) {
+		const hit = entryOf(root, v);
+		if (hit !== null) return hit;
+	}
+	return null;
+};
+
+/** Measure `pkg.exports` of the package at `root`. */
+export const measureSurface = async (root: string, pkg: { exports?: Record<string, unknown> }): Promise<Surface> => {
+	const exportedNames = walker();
+	const counts = new Map<string, number>();
+	const assets: string[] = [];
+	for (const [subpath, value] of Object.entries(pkg.exports ?? {})) {
+		const entry = entryOf(root, value);
+		if (entry === null) {
+			assets.push(subpath);
+			continue;
+		}
+		counts.set(subpath, (await exportedNames(entry)).size);
+	}
+	return { counts, assets };
+};
+
+// ── peers ───────────────────────────────────────────────────────────────────────
+
+/** Not a use of a peer: a test file, or anything under a `testing/` directory. */
+const SKIP_FOR_PEERS = /(\.(test|spec)\.tsx?$)|((^|\/)testing\/)/;
+
+export const peerProblems = async (root: string, pkg: { peerDependencies?: Record<string, string> }): Promise<string[]> => {
+	const peers = Object.entries(pkg.peerDependencies ?? {});
+	if (peers.length === 0) return [];
+
+	const files = [...new Bun.Glob("**/*.{ts,tsx}").scanSync({ cwd: join(root, "src") })]
+		.map((f) => `src/${f}`)
+		.filter((f) => !SKIP_FOR_PEERS.test(f));
+	const texts = await Promise.all(files.map((f) => Bun.file(join(root, f)).text()));
+	const haystack = texts.join("\n");
+
+	const problems: string[] = [];
+	for (const [name, range] of peers) {
+		const esc = name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+		const spec = `${esc}(?:/[^'"\`]*)?`;
+		const used = new RegExp(
+			`from\\s*['"\`]${spec}['"\`]` + // import x from 'p' / export … from 'p'
+				`|import\\s*\\(\\s*['"\`]${spec}['"\`]` + //  await import('p'), typeof import('p')
+				`|require(?:Peer)?\\s*\\(\\s*['"\`]${spec}['"\`]` + // requirePeer('p', …)
+				`|@peer\\s+${esc}\\b`, // runtime-variable specifier, declared
+		).test(haystack);
+		if (!used) {
+			problems.push(
+				`peerDependencies["${name}"] is imported by no non-test file under src/. ` +
+					"Remove it, or — if it is loaded through a runtime variable — declare it with an " +
+					"`@peer` pragma beside the loader.",
+			);
+		}
+		if (!/^[\d^~<>=*x\s|.-]/i.test(range) || /:|\/\//.test(range)) {
+			problems.push(
+				`peerDependencies["${name}"] = "${range}" is not a registry range. A URL, file:, link: or ` +
+					"git+ range cannot be reproduced by --frozen-lockfile and cannot be deduped by npm.",
+			);
+		}
+	}
+	return problems;
+};
+
+// ── the baseline ────────────────────────────────────────────────────────────────
+
+export const parseBaseline = (text: string, fallbackHeader: string[] = defaultHeader({})): Baseline => {
+	const header = text.split("\n").filter((l) => l.startsWith("#"));
+	const counts = new Map<string, number>();
+	for (const line of text.split("\n")) {
+		if (!line.trim() || line.startsWith("#")) continue;
+		const m = line.match(/^\s*(\d+)\s+(\S.*)$/);
+		if (m?.[2] !== undefined) counts.set(m[2].trim(), Number(m[1]));
+	}
+	return { header: header.length > 0 ? header : fallbackHeader, counts };
+};
+
+export const readBaseline = async (file: string, fallbackHeader?: string[]): Promise<Baseline> => {
+	const f = Bun.file(file);
+	return parseBaseline((await f.exists()) ? await f.text() : "", fallbackHeader);
+};
+
+export const formatBaseline = (header: string[], counts: Map<string, number>): string =>
+	`${[...header, ...[...counts.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([k, n]) => `${n}  ${k}`)].join("\n")}\n`;
+
+export const compare = (surface: Surface, baseline: Baseline): Failures => {
+	const fresh: string[] = [];
+	const grown: string[] = [];
+	for (const [subpath, n] of surface.counts) {
+		const allowed = baseline.counts.get(subpath);
+		if (allowed === undefined) fresh.push(`${subpath}  — NEW subpath, ${n} exported symbol(s)`);
+		else if (n > allowed) grown.push(`${subpath}  — baseline allows ${allowed}, exports ${n} now`);
+	}
+	const stale = [...baseline.counts.entries()]
+		.filter(([subpath, n]) => (surface.counts.get(subpath) ?? 0) < n)
+		.map(([subpath, n]) =>
+			surface.counts.has(subpath)
+				? `${subpath}  — baseline says ${n}, exports ${surface.counts.get(subpath)}`
+				: `${subpath}  — baseline says ${n}, the subpath is gone`,
+		);
+	return { fresh, grown, stale, peers: [] };
+};
+
+/** Measure the package at `options.root` and compare it with its baseline. */
+export const run = async (options: SurfaceOptions): Promise<Failures & { surface: Surface; baseline: Baseline }> => {
+	const pkg = await readPkg(options.root);
+	const surface = await measureSurface(options.root, pkg);
+	const baseline = await readBaseline(baselineOf(options), defaultHeader(pkg));
+	const failures = compare(surface, baseline);
+	if (options.peers) failures.peers = await peerProblems(options.root, pkg);
+	return { ...failures, surface, baseline };
+};
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * The CLI, as a function: prints what the three per-library scripts printed and returns
+ * the exit code — 0 clean (or seeded/pruned), 1 on any failure or refusal.
+ */
+export const main = async (argv: readonly string[], options: SurfaceOptions): Promise<number> => {
+	const BASELINE = baselineOf(options);
+	const ROOT = options.root;
+	const pkg = await readPkg(ROOT);
+	const { fresh, grown, stale, peers, surface, baseline } = await run({ ...options, peers: options.peers || argv.includes("--peers") });
+	const total = [...surface.counts.values()].reduce((a, b) => a + b, 0);
+
+	// `--seed` exists once, to record the surface the ratchet starts from. It REFUSES over
+	// an existing baseline, so re-seeding means deleting the file first — two visible steps
+	// and a whole-file diff, rather than one command that quietly re-baselines whatever grew.
+	if (argv.includes("--seed")) {
+		if (baseline.counts.size > 0) {
+			console.error(`publicSurface --seed refuses: ${BASELINE} already records ${baseline.counts.size} subpath(s).`);
+			console.error("Lower it with --prune. Raising it is a hand edit in a commit that says why.");
+			return 1;
+		}
+		await Bun.write(BASELINE, formatBaseline(baseline.header, surface.counts));
+		console.log(`publicSurface: seeded ${surface.counts.size} subpath(s), ${total} exported symbol(s).`);
+		return 0;
+	}
+
+	if (argv.includes("--prune")) {
+		// 🔴 It may only LOWER. Growth is the thing this exists to make visible; a prune
+		// that could absorb it would be the disable switch.
+		if (fresh.length > 0 || grown.length > 0) {
+			console.error("publicSurface --prune refuses while the surface has GROWN — it may only lower the baseline.\n");
+			for (const v of [...fresh, ...grown]) console.error(`  ${v}`);
+			console.error(
+				"\nTo record deliberate new surface, add the line by hand and say in the commit message why the\npackage needs it — that is the reviewable moment this check exists to create.\n",
+			);
+			return 1;
+		}
+		const lowered = new Map<string, number>();
+		for (const [subpath, n] of baseline.counts) {
+			const now = surface.counts.get(subpath);
+			if (now !== undefined) lowered.set(subpath, Math.min(n, now));
+		}
+		await Bun.write(BASELINE, formatBaseline(baseline.header, lowered));
+		console.log(
+			`publicSurface: baseline pruned to ${lowered.size} subpath(s), ` +
+				`${baseline.counts.size - lowered.size} removed, ${[...lowered.values()].reduce((a, b) => a + b, 0)} symbols.`,
+		);
+		return 0;
+	}
+
+	let bad = false;
+	const report = (label: string, lines: string[], advice: string): void => {
+		if (lines.length === 0) return;
+		bad = true;
+		console.error(`\n${lines.length} ${label}:\n`);
+		for (const l of lines) console.error(`  ${l}`);
+		console.error(`\n${advice}\n`);
+	};
+	report(
+		"export subpath(s) the baseline does not know",
+		fresh,
+		`A new subpath is a permanent public promise. If it is genuinely wanted, add its line to\n${BASELINE} and say why in the commit message.`,
+	);
+	report("subpath(s) that gained exported symbols", grown, "A baseline entry is a ceiling. Raise it by hand, in a commit that says why.");
+	report(
+		"baseline entr(y|ies) that no longer match `exports`",
+		stale,
+		`Surface came off and the ratchet was not tightened. Run:\n  cd ${ROOT} && ${pruneCommand(pkg)}`,
+	);
+	report("peerDependency problem(s)", peers, "A peer nothing imports is a peer nobody can explain.");
+	if (bad) return 1;
+
+	console.log(
+		`publicSurface: ${surface.counts.size} subpath(s), ${total} exported symbol(s), ` +
+			`${surface.assets.length} asset export(s) — none grown.`,
+	);
+	return 0;
+};
+
+if (import.meta.main) {
+	// The package is the one the command was run in — `bun run <script>` starts in the
+	// package root, and a walk up makes a subdirectory work too.
+	const root = findPackageRoot(process.cwd());
+	if (root === null) {
+		console.error(`public-surface: no package.json at or above ${process.cwd()}.`);
+		process.exit(1);
+	}
+	process.exit(await main(process.argv.slice(2), { root }));
+}