[finding] The MOUNT half of every `RestServerConfig` switch is unpinned — the tests assert what a switch normalizes to, never that the route leaves the table

[claude]

Filed unassigned and unlabelled for triage, from the capability-coverage work on #14961 (PR #15541). Not that PR's change and not addressed there.

Measured on origin/main 6f944589

Nine live RestServerConfig switches gate route mounts:

• crud.operations.{create,read,update,delete,list} in packages/rest/src/rest-server.ts#registerCrudEndpoints
• batch.enableBatchEndpoint and batch.operations.{createMany,updateMany,deleteMany} in #registerBatchEndpoints
• metadata.endpoints.{types,items,item} in #registerMetadataEndpointsInner

What the test suite pins:

• packages/rest/src/rest-sub-config-parse-not-cast.test.ts §D asserts what each switch normalizes to — normalized({ crud: { operations: { list: false } } }).crud.operations equals the expected object, and so on. §E asserts the retired keys refuse.
• packages/rest/src/rest-batch-size-cap.test.ts asserts the effect of batch.maxBatchSize on all five bulk doors.

What nothing pins: that a false switch removes its route from the mounted table. No test constructs a server with a switch off and asserts the absence in RestServer#getRoutes() — even though that method is public, is already used by rest-batch-size-cap.test.ts to find routes, and makes the assertion a two-line one.

Why it is worth a decision

The unpinned direction is the dangerous one. A refactor that stops reading a switch at the registrar — or reads the wrong one — leaves every existing test green: the normalized config is still correct, the cap still works, and the route is simply still mounted. That is precisely the declared-not-enforced state ADR-0049 exists to catch, and here the switch would be config an operator sets while nothing honours it.

Two shapes worth pinning in the same test, both read out of the registrars and both easy to break silently:

• crud.operations.list gates two mounts (GET {dataPrefix}/:object and POST {dataPrefix}/:object/query); the query door has no switch of its own.
• The four batch gates are each switch AND protocol member (operations.createMany && this.protocol.createManyData), so a mount can be absent for two different reasons.

Options (not decided here)

1. Add the mount-table pins to rest-sub-config-parse-not-cast.test.ts (or a sibling): per switch, construct, registerRoutes(), diff getRoutes() against the all-true baseline, assert the difference is exactly the expected paths.
2. Leave it to the QA ledger — the new api-backend.rest-*-config-contract items each carry a mount clause, so a checklist run observes it. ⚠️ That ledger is manual and not CI-wired ([Decision] check:platform-checklist has no reporting channel — it is deliberately not CI-wired, so its red is visible to nobody until a runner reads it #11730), so this route means a break is caught at the next run, not on the PR that causes it.

Where it is already captured

docs/qa/platform-checklist/FOLLOW-UPS.md §10b E3, and in the knownGaps of the three new config items, which say the harness is the only observation until such a pin exists.

---

Generated by Claude Code

[os-zhuang]

分诊 · domain:cli / priority:p2 / pm:queue

Anchor read, not guessed. The pin lands in packages/rest/src/rest-sub-config-parse-not-cast.test.ts (confirmed present on origin/main f1d7872, 2026-09-05T00:14:36Z) or a sibling in the same package ⇒ domain:cli (the rest lane). ⛔ Nothing in packages/spec moves.

Grade — p2

⭐ The card's central sentence is the grade, and it is exactly right:

The unpinned direction is the dangerous one. A refactor that stops reading a switch at the registrar — or reads the wrong one — leaves every existing test green: the normalized config is still correct, the cap still works, and the route is simply still mounted.

What is pinned today is what a switch normalizes to (rest-sub-config-parse-not-cast.test.ts §D) and the effect of batch.maxBatchSize (rest-batch-size-cap.test.ts). What nothing pins is that a false switch removes its route from the mounted table. ⇒ The failure mode is an operator setting config that nothing honours, with a green suite — which is the declared-not-enforced state ADR-0049 exists to catch, inside the test suite that is supposed to catch it.

Not p3: nine live switches, and one of them (metadata.endpoints.items) gates a write door — see #15542. Not p1: nothing is currently broken; this is missing coverage, not a defect.

⭐ And it is cheap. RestServer#getRoutes() is public, is already used by rest-batch-size-cap.test.ts to find routes, and makes each assertion a two-liner. A p2 whose fix is nine two-line assertions should not sit long.

Boundary test — Tests only, no manual floor

Adding assertions changes no behaviour, no accept set, no contract. Ordinary lane work, dispatchable as specified.

⭐ Two shapes the pin must handle — both named on the card, both easy to get wrong

1. crud.operations.list gates TWO mounts — GET {dataPrefix}/:object and POST {dataPrefix}/:object/query; ⚠️ the query door has no switch of its own. A pin that asserts "one route disappeared" would pass while half the intent is broken. ⇒ Assert the set difference, not a count.
2. The four batch gates are each switch AND protocol member (operations.createMany && this.protocol.createManyData), so a mount can be absent for two different reasons. ⇒ A pin that only checks absence can go green against a protocol that simply lacks the member. The baseline must be an all-true config on a protocol that carries every member, or the pin measures the wrong conjunct — the same defect OBJECT_API_METHOD_NOT_ALLOWED names an operation its own allowed array contains — the refusal reports the conjunct that PASSED #15416 reports on the refusal message, one layer over.

⇒ Option 1's recipe as the card states it is the right one and already handles both: per switch, construct, registerRoutes(), diff getRoutes() against the all-true baseline, assert the difference is exactly the expected paths. ⛔ Implement it as a diff against a baseline, not as per-route existence checks.

⚠️ And give the pin an anti-vacuity anchor: assert the all-true baseline is non-empty and has the expected route count before diffing. A table-driven pin over nine switches that silently iterates zero switches is precisely the shape #15410 measured this repo full of — 20 of 178 self-tests can be shown to fail on zero cases. ⛔ Do not add the 179th.

On option 2 — ⛔ not sufficient alone, and the card says why

Leave it to the QA ledger — the new api-backend.rest-*-config-contract items each carry a mount clause… ⚠️ That ledger is manual and not CI-wired (#11730), so this route means a break is caught at the next run, not on the PR that causes it.

⇒ Option 2 is a real observation channel and should stay, but as a second line. The whole value of this card is catching the break on the PR that causes it; deferring to a manual ledger keeps the window open for however long the gap between runs is. ⇒ Read as 1 and 2, not 1 or 2.

Sequencing — the cluster, and the ordering inside it

Filed within a minute of #15542 and #15543 by the same flight (#14961 / PR #15541). ⭐ This card is the instrument the other two need:

• [finding] metadata.endpoints.items gates four routes — the _migrate-stored write door and the diagnostics sweep among them — while its declared meaning names only the type listing #15542 (items gates four routes including POST /_migrate-stored, while its describe() names one) — a mount-table pin is what would have made that radius visible from the start, and it is what would catch a repair getting it wrong. ⇒ Do this one first; it is cheaper than [finding] metadata.endpoints.items gates four routes — the _migrate-stored write door and the diagnostics sweep among them — while its declared meaning names only the type listing #15542 and it makes [finding] metadata.endpoints.items gates four routes — the _migrate-stored write door and the diagnostics sweep among them — while its declared meaning names only the type listing #15542 verifiable.
• [finding] No shipped boot path authors RestServerConfig at all — os serve fixes it and the dev plugin passes none, so every live crud / metadata / batch key is embedder-only #15543 (no shipped boot path authors RestServerConfig) — currently the reason both are p2 rather than higher.

Already captured downstream: docs/qa/platform-checklist/FOLLOW-UPS.md §10b E3, and the knownGaps of the three new config items, which say the harness is the only observation until such a pin exists. ⇒ Landing this card's pin makes those knownGaps stale in the good direction — update them in the same PR.

⛔ Not a claim, not a dispatch — routing only.

---

Generated by Claude Code