docs(rest): the mirrored makeRes() census states a property, not a list of three

[claude]

Fixes #15584

The mirrored-fixture census in packages/rest/src/http-response-test-builder.ts named three files. The card reports a fourth, inside rest.test.ts. That fourth instance is real and is confirmed below — but appending it would have replaced one false roster with another.

Measured against the roster's own stated property — a local any-typed fixture that mirrors status / json onto res.statusCode / res.body, asserted on instead of the spies — the real population is 76 of this package's 187 test files.

The roster was not short by one. It was short by 73, and it was independently wrong about one of the three names it did carry.

What was measured

At a5eccf925, over packages/rest/src/*.test.ts:

read	result
names the roster carried	3
files matching the roster's stated property	76 of 187
of those 76, helper literally spelled makeRes	30
control — files that DO define a makeRes and are correctly excluded	18
rest.test.ts in the census (the card's fourth instance)	yes
the three named files, all genuinely in the census	yes — correct entries, just 73 short
analytics-dataset-dimension-gate.test.ts contains the string makeRes	no — its fixture is spelled mockRes

One command, and it is now in the docblock so a reader re-derives instead of trusting a sentence:

grep -lE 'expect\([A-Za-z_$][A-Za-z0-9_$]*\.(statusCode|body)\b' \
  packages/rest/src/*.test.ts | xargs grep -l 'statusCode = ' | wc -l

Extracted verbatim out of the committed file and run, it prints 76.

Both errors have one cause. The population was enumerated by HELPER NAME, and the helper name is the one thing about this shape that varies — only 30 of the 76 spell it makeRes; the rest spell it mockRes or inline it. That is also why the roster's own third name failed its own stated property. A hand-list keyed on the one varying attribute can only go stale silently, so a fourth name would have inherited the defect rather than repaired it.

The census had TWO carriers, not one

The same three-name list was mirrored in packages/rest/test-typecheck-debt.json's _note. That field is authored and check:test-typecheck --update preserves it verbatim (the gate's own #12624 pin asserts exactly that), so regeneration would never have corrected it. Fixing only the docblock would have left the identical false roster in place one file away. Corrected in the same edit.

What this PR deliberately does NOT do

⛔ No assertion is converted, and the unchecked route.handler call is left unchecked. The fence from #14356's triage applies unchanged: a mirror does not satisfy IHttpResponse, and a mirror keeps only the LAST status where mock.calls keeps every one, so swapping in the builder would change what the tests assert rather than change the fixture. That is a decision per assertion, and it stays its own card. Confirmed still true here: invoke() in rest.test.ts carries that file's only route.handler call whose enclosing binding is untyped.

⛔ No new CI gate. A ratchet over 76 files, with the conversion decision still open, would be a gate with no permitted repair. What replaces the hand-list is the property, the derivation command and a non-zero control — not a new red.

Reader-facing half

rest.test.ts gets a pointer comment at the mirrored fixture. The card's argument is that this is the instance a reader of that file is likeliest to assume is already covered because the rest of the file now is; the comment says it is a mirror, points at the census, and names the untyped call site. That file usefully holds one fixture of each kind — the makeRes under describe('export handler') captures status in a closure and is correctly outside the census — which is the concrete reason to state a property rather than a filename.

Verification

Comment-only: every changed line in the two .ts files is a comment line (git diff | grep -v '^[+-]\s*\(\*\|//\)' is empty), and the only non-.ts change is one authored JSON prose string.

• pnpm --filter '@objectstack/rest^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/rest exec vitest run — Test Files 187 passed (187) · Tests 3182 passed (3182), VERDICT command-exit 0
• pnpm --filter @objectstack/rest typecheck — VERDICT command-exit 0; check:test-typecheck: OK — 0 file(s) / 0 error(s) / 0 pinned signature(s), and its self-test confirms the run "preserves an authored _note verbatim"
• Gate families derived with node scripts/pm/dispatch-gates.mjs --commands with no paths — asserted against the script's own Reconciliation total of 47; the separate Artifact rosters block of 39 run alongside it

Scope narrowed and declared: turbo ls --affected names 19 packages, because packages/rest is a dependency of many. The change cannot reach any of them: src/index.ts is untouched, http-response-test-builder.ts is not imported by the bundle entry (tsup entry is src/index.ts), and a comment-only edit emits nothing. Local verification is therefore scoped to packages/rest; CI runs the full affected set.

Changeset

skip-changeset. packages/rest publishes ["dist","README.md","CHANGELOG.md"]. Two of the three changed files are test-layer and never reach dist (the builder is not imported by src/index.ts; the other is a .test.ts), the third is not in the published list at all, and the whole diff is comments. Nothing published changes, so there is no user-visible change to describe.

验收备注

• noted, not filed — the same mirrored-fixture idiom is the package's de facto default (76 of 187 test files). That is a fact about the conversion card's size, not a defect of its own, and it is now derivable instead of guessed.
• noted, not filed — a standing mechanical gate over this population is possible but was deliberately not added here: with the conversion decision still open it would be a permanently-red ratchet with no permitted repair. It belongs with the conversion card, which can set a shrink-only target the same day it converts the first fixture.
• #15416 holds packages/rest/src/rest-server.ts under a hard serial. This PR does not touch that file; the census surface and its do not intersect.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 2 changed file(s) yielded no anchor (packages/rest/src/http-response-test-builder.ts, packages/rest/test-typecheck-debt.json), 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

• 2 changed file(s) yielded no anchor (packages/rest/src/http-response-test-builder.ts, packages/rest/test-typecheck-debt.json) — 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 — 13 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 3335bd35eaf47a5b2aed9120e217dafd242ff7e1 → packageMentionDocs.