docs(cli): re-measure the vitest suite-cost section on a stated commit (#12499)

[os-litant]

Fixes#12499

Re-measures the suite-cost section of packages/cli/vitest.config.ts on a
stated commit, and collapses the file's two file/test vintages (135 / 1470 in
one section, 137 / 1498 in the next) into one measured population stated once.
Comment text only.

Extends #12494
(#12460), which tensed these sentences and declared the non-re-measure. This PR
is that re-measure; it does not re-open anything #12494 settled.

Why the old figures could not be re-checked

The section was dated 2026-08-20 and anchored to nothing. Between that date
and 2f665a1af the population it described moved twice over, and none of it was
visible from inside the file:

	2026-08-20	2f665a1af
files / tests	137 / 1498	185 / 2115
spawner files	20	39
wall (--maxWorkers=2)	495.81s	793.31s

A date says when someone looked. A commit says what they looked at, and only
the second can be re-checked — so the header now prints the sha beside the
numbers, and the counts live in exactly one place in the file.

What was measured, and how

One box, 4 cores, warm build, vitest run --maxWorkers=2 per package, vitest
4.1.10 on node 22.22.2 — the 2026-08-20 protocol, re-run. Every run held the
container's shared heavy-verify lock (scripts/pm/os-verify-lock.sh), because
several agents share this box.

Contention actually seen, since a cost measurement taken beside a neighbour's
build is a reading about the box: the --maxWorkers=2 run waited 4m01s behind
a neighbouring agent's @objectstack/cli^... build, then held the lock 13m14s.
The lock serialises locked work only — a neighbour's unlocked gate script
was observed at ~130% CPU partway through, and 1-minute load averaged 4.36
(peak 6.97) across the run.

Results

The one population, stated once

185 files / 2115 tests on 2f665a1af, all passing. Both stale copies
(135 / 1470, 137 / 1498) are gone; the count now appears in exactly one
place in the file, and the Why the service-cache entry section points at it
rather than keeping a second copy.

Concentration — re-measured, and it moved in two directions at once

	2026-08-20	2f665a1af
median file	0.03s	0.05s
files under 2s	105 of 137	129 of 185
top 20 files, share of file wall	87.7%	71.3% (965.3s of 1353.1s)
CLI-spawning files	20	39
their share of the file wall	56.1% (300.1s)	89.4% (1209.8s)
tests they carry	177 of 1498	319 of 2115

⭐ The two shares moved in opposite directions, and that is the finding: the
spawner set nearly doubled, so it now holds almost the whole wall (56.1% ->
89.4%) while the top-20 concentration fell (87.7% -> 71.3%) because the same
kind of cost is spread over more files. Reading either number alone gives the
wrong story. All twenty of the top 20 are spawners.

"File wall" is now defined in the header as the sum of per-module run durations,
which is the same quantity vitest prints as the tests term of its own
Duration line — so the two can be checked against each other instead of
drifting.

All six rows of the cross-package table are one vintage

Refreshing only the cli row would have left the "both normalisers" argument
comparing 2026-08-26 against 2026-08-20, so all six packages were re-run on
2f665a1af, plus a second cli run at --maxWorkers=4 for the worker A/B and
a fresh NODE_COMPILE_CACHE A/B. Nine measured runs in total, all green.

⚠️example-showcase failed 9 of 26 files the first time — Failed to resolve entry for package "@objectstack/connector-rest", i.e. packages outside the
cli closure I had built. A red suite's wall is not a cost measurement, so its
closure was built and it was re-run green (26 files / 364 tests) before entering
the table. In CI this cannot happen: turbo's default test task declares
dependsOn: ["^build"].

Per-spawn floor — absolutes moved, the ratio held

	2026-08-20	2f665a1af
tsx bin/run-dev.js --version	6.5-6.8s	5.45-6.07s
node bin/run.js --version	2.9-3.2s	2.46-2.66s
node -e 0	0.031s	0.025-0.031s
source / built (means of 5 runs each)	2.18x	2.21x

⭐ Exactly the #11707 precedent: the seconds did not reproduce, the ratio did.
The header now says which of its numbers are box-dependent (all the seconds) and
which a reader on another box should expect to reproduce (the ratios).

By entry point, and a trap in reading it

	files	file wall	s/file	tests	s/test
bin/run-dev.js (source)	35	1169.2s	33.4	311	3.8
bin/run.js (built)	4	40.6s	10.1	8	5.1

⛔ That is not a measurement of what the two entries cost — the four built-entry
files are also the smallest here (2.0 tests/file against 8.9) and per test the
ordering reverses. The header says so, and points at the floor table for the
entry cost. Re-deriving 3.3x from this row would have been wrong in the same way
that scaling the old figures by 2.06x would have been.

Instrument controls

⛔ Nothing here reports a zero or an "unchanged" that the instrument was not
first shown capable of contradicting:

• Timer — positive control at known ground truth: a 500ms busy-wait reads
  0.530-0.535s, a 2000ms one reads 2.024-2.032s.
• Timer, negative — node bin/run-NOPE.js --version (an entry that does not
  exist) returns in 0.030s and exit 1: pure timing reads a nonexistent
  command as the best floor on the board. Every floor row was checked for
  exit 0.
• setup 0ms — the reporter was re-run against a deliberate 300ms
  setup file and printed setup 618ms (2 modules), so the zero is a fact about
  the suite, not a blind spot.
• Per-module reporter — validated against a two-file probe with known
  contents (2 files / 3 tests / 617ms wall, one test made to cost 400ms), and
  it reports both extremes in the real run (0.000s and 93.96s).
• Log parser — the same parser was run over the probe log whose true values
  are known before it was pointed at the real ones.
• Spawner classifier — a spelling known absent returns zero, a spelling
  known present returns its lines. ⚠️ Its first pass undercounted by three:
  those files assemble the entry from separate literals
  (join(…, '..', 'bin', 'run-dev.js')), so a slash-joined pattern missed them
  while still returning a plausible number. Prose mentions were excluded the
  other way — one file names the entry four times and explicitly does not spawn
  it. Both traps are now written into the header.
• Comment-only claim — the filter that says this diff touches no code was
  run over c48f9a0e7 (which did change code in this file: 7 lines reported)
  and over 3d8d2f15d (comment-only: silent) before being trusted here.

Scope

packages/cli/vitest.config.ts only, comment text — the emitted config object
is byte-identical. The four dist-consuming test files, the three spawners
#12441 is in flight on, and turbo.json are untouched. skip-changeset:
nothing published changes.

⚠️Reported, not acted on: the header's conclusion has not changed, so
nothing in it was rewritten. tests is still the dominant term by a wider
margin than before (1353.09s against 203.72s import and 25.17s transform), so
"before adding a test block, re-measure: if tests is still the dominant
term, the block is not the lever" still points the right way. Two supporting
figures moved and were restated rather than re-argued — both verdicts stand:

• per-file transform cost is now second-lowest of the six, not lowest
  (spec is below it at 0.036s/file). The claim it supports — the wide
  dependency closure is not what the test files import — is if anything
  stronger, since cli is now second-lowest on import per file too.
• the NODE_COMPILE_CACHE A/B no longer reads as "inside noise": cached
  (5.15/5.16/5.34/5.42s) and uncached (5.46/5.61/5.64/5.71s) do not overlap
  across four samples each. It is still rejected — ~0.3s (~5%) for 42MB, against
  the 3.11s the built entry already saves per spawn.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/cli/vitest.config.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/cli/vitest.config.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 23 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 14b114553c3e7c61672e3d25a1d15036f7561e27 → packageMentionDocs.