docs(cli): stamp the vitest mock-target census, and name all three mocked workspace packages

[claude]

Fixes #13873

The defect

The server.deps.external COSTS paragraph in packages/cli/vitest.config.ts ends by
telling the next editor that "a package added here later must be re-checked for both"
— mockability and coverage instrumentation. It then supplied that re-check's starting
point as a present-tense census: three mock targets, exactly one of them a workspace
package (@objectstack/cloud-connection).

Re-measured on 55519d5036: eight distinct targets over eleven sites, and
three of them are workspace packages. A reader doing the re-check the sentence asks
for, on the authority of the sentence itself, would conclude that externalising a
workspace package is free of mock conflicts in this package. It is not — externalising
@objectstack/lint or @objectstack/platform-objects/plugin breaks the file that mocks
it, with an error pointing at that test rather than at the config entry that caused it.

Same shape as #12529 on this very file: a document that sends the reader to the right
place and then tells them what they will find, so they do not look.

The re-measured census

Taken on 55519d5036, 2026-08-31. Eleven vi.mock / vi.doMock sites, eight targets:

target	kind	sites
../utils/optional-package.js	relative	3
../../utils/api-client.js	relative	2
../../utils/schema-migrate.js	relative	1
../../utils/secret-reference-union.js	relative	1
node:fs/promises	node builtin	1
@objectstack/cloud-connection	workspace	1
@objectstack/platform-objects/plugin	workspace	1
@objectstack/lint	workspace	1

All three @objectstack/* targets are declared workspace:* in packages/cli/package.json
— verified, not assumed.

The other half of the claim is still true, and the zero is not vacuous

The paragraph also claims packages/cli has no vi.mock of @objectstack/types — the one
package the entry below actually externalises. That half holds, and it was checked with a
positive control rather than accepted: the same instrument does find three @objectstack/*
mock targets, and @objectstack/types is genuinely reachable here — ten test files import it,
across both @objectstack/types and @objectstack/types/node — so the zero is a real zero
and not a zero over an absent dependency.

⚠️ The card's own reproduce command is broken, and that is load-bearing

#13873 published this reproduce command:

git grep -ohE "vi\.(do)?mock\(\s*'[^']+'" -- 'packages/cli/**/*.test.ts' | sort -u

It returns six targets, not the eight in the card's own table. The regex cannot match
vi.doMock( — capital M — so it silently drops all four doMock sites, which are exactly
the two targets missing from its output: ../utils/optional-package.js and
@objectstack/cloud-connection. The second of those is the only workspace package the
stale parenthesis did name.

This is not an artifact of the file moving today. Re-run at f532630d02, the commit the
card was filed on, the command still returns 6 while the card's table says 8 — so the table
was taken by some other means and the published command never reproduced it.

That is the same defect class as the paragraph being fixed, one level up, so the fix records
the correct spelling and the trap alongside the census.

Fix shape chosen: (2), the stamped census — because this file already has that convention

The card offered two shapes: drop the enumeration and give the reader the command, or keep
the census and stamp it with the commit it was taken on.

Shape (2), for three reasons:

1. It is the convention this file already adopted. Checked before writing, as the card
   required: the block PR test(cli): attribute the suite's import term per file, and price the trade #13872 landed 20 minutes before this work carries the stamp in its
   own header — ## THE \import` TERM, ATTRIBUTED PER FILE (pnpm --filter @objectstack/cli test is a ~24-minute serialized run, and on a shared agent container it holds the verify lock for the whole of it #13504) — f532630, 2026-08-31 — and the older suite-cost section carries the same idea inline (ONE STATED COMMIT —
   2f665a1, re-measured 2026-08-26 (packages/cli/vitest.config.ts's suite-cost section is a 2026-08-20 measurement whose population changed under it — and it carries two inconsistent file/test vintages in adjacent sections #12499)). The new census header copies that shape exactly: ## THE MOCK-TARGET CENSUS ([finding] packages/cli/vitest.config.ts says this package has three vi.mock targets — there are eight, and two more are workspace packages the same paragraph tells you to re-check #13873) — 55519d5, 2026-08-31`. No second stamping
   format was invented.
2. Shape (1) alone would have shipped the broken command. "Give the reader the command"
   is only safe once the command is right, and the obvious spelling under-reports by a third
   of the census including a workspace package. The fix therefore carries the corrected
   command inside the stamped section, as the instrument the stamp points at — not as a
   replacement for the census.
3. The rot argument is what the stamp answers. This file's own words from packages/cli/vitest.config.ts's suite-cost section is a 2026-08-20 measurement whose population changed under it — and it carries two inconsistent file/test vintages in adjacent sections #12499: a date
   says when someone looked, a commit says what they looked at, and only the second can be
   re-checked. A stamped census that goes stale still tells the truth about what it was a
   census of.

What #13872's new block contains, and whether it already covered this

It does not. #13872 added 117 lines in two pure insertions: a supersession note near the old
suite-cost header, and a new section attributing the suite's import term per file. It
measures where the import cost sits, refuses "externalise more workspace dist/" as a
speed fix, and restates that widening server.deps.external keeps its #11775 resolution
warrant while having no speed warrant. It never touches the mock-target census — the COSTS
paragraph was only shifted down, not edited. What it did supply is the stamping shape copied
here, and the scope boundary this PR stays inside.

Scope

Comment-only. server.deps.external's contents are unchanged, and nothing here argues that
anything should be externalised — #13504's measurement found no speed warrant, and #11775's
resolution warrant is untouched.

Verification

Comment-only, proven mechanically. git diff -U0 is 45 changed lines, of which 2 are
file headers; the count of changed lines that are not comments is 0, and the detector was
positive-controlled by feeding it an executable line (returns 1). Blob hash moved
f288aee5fde9753d69b8f8116774a2212a16bc0d -> 07d443b7be0dccc6532ef2494d1408dde9f9fd86.
No ablation applies — nothing executable changed.

Suite shape undisturbed (the positive control this change owes, since this file decides
the whole suite's shape):
pnpm --filter @objectstack/cli exec vitest list --filesOnly — exit 0 before and after,
221 files both times, and the sorted lists are byte-identical (diff empty). The full
suite was deliberately not re-run for a comment change; that exclusive-lock cost is precisely
what #13504 measured.

Gates — union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
on the final head e8b3c7cbdf (change set derived by the script itself: 1 path, untracked 0):

union named 19, ran 19, unreconciled 0 (comm -23, exact string comparison)

18 of 19 green by their own verdict lines. One NOT MEASURED, in the gate's own words:

• node scripts/check-test-completeness.mjs — exit 3: "PREREQUISITE NOT MET — this gate
  grades a saved turbo run test log, and no log was named. … Arrived here from the gate
  family scripts/pm/dispatch-gates.mjs derives? That list names this script with NO
  argument, which is this branch. There is no local log to hand it, so the local reading for
  this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."

pnpm check:dual-build-cjs-loads first returned the same class of non-verdict (exit 3,
"PREREQUISITE NOT MET … ⛔ This is NOT a pass: nothing was measured"); it was then given
what it needed — turbo run build over ./packages/*, ./examples/*^... and
./packages/*/*, both exit 0 — and re-run to a real green: "✓ check:dual-build-cjs-loads —
102 published require entry point(s) across 66 package(s) load; 610 emitted CommonJS file(s)
parse."

Also run, beyond the derived union:

• pnpm lint (repo-wide eslint . --no-inline-config, the always-runs tail) — exit 0, 73s.
  Run in full, so no narrowing needs defending.
• pnpm --filter @objectstack/cli typecheck — exit 0, script name echoed (tsc --noEmit),
  so this is not the zero-match false green.
  ⚠️ Reported honestly: that green does not cover the edited file. tsc --listFiles shows
  the program is 1317 files and packages/cli/vitest.config.ts is not among them (0 hits,
  against a control file that returns 1). The measurement that does cover this file is the
  vitest list control above — vitest loads and evaluates this config to resolve it.

Changeset: skip-changeset, measured rather than assumed. npm pack --dry-run --json in
packages/cli ships no vitest.config* and no .test.ts; package.json declares
files: ["dist", "README.md", "CHANGELOG.md"], so this file can never ship whatever the build
state. A comment in a test config publishes nothing.

No skills/** path is touched, so no published-skill line-count budget applies.

Generated by Claude Code

---

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 6193e576d8f243e42d3ce8f15fa91b0763d49aaf → packageMentionDocs.