[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

[claude]

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

Measured on origin/main 6f944589

MetadataEndpointsConfigSchema.endpoints declares three live switches, and each one's describe() names exactly one route:

key	its declared meaning
types	GET /meta - List all metadata types
items	GET /meta/:type - List items of type
item	GET /meta/:type/:name - Get specific item

packages/rest/src/rest-server.ts#registerMetadataEndpointsInner gates more than that. Counting the if blocks in that method:

• endpoints.types !== false gates 2 mounts — GET {prefix} and GET {prefix}/types (one handler, two paths, deliberately).
• endpoints.items !== false gates 4 mounts — GET {prefix}/:type, and also GET {prefix}/diagnostics (the cross-type spec-validation sweep), GET {prefix}/_drafts, and POST {prefix}/_migrate-stored, which is a write door.
• endpoints.item !== false gates 4 mounts — GET {prefix}/:type/:name, plus /:type/:name/references, /:type/:name/layers and GET {prefix}/book/:name/tree.

Why it is worth a decision

An operator who reads the schema and turns off "list items of type" — a read they may consider chatty or unnecessary — silently unmounts a migration write door and the diagnostics sweep with it. Nothing warns, and nothing in the declared contract says those routes ride that switch. That is the declared-vs-enforced asymmetry ADR-0049 is about, in the direction the ledger does not look: the key is genuinely live, so no liveness census flags it; what drifted is the key's radius versus its own documentation.

Options (not decided here)

1. Document the real radius — extend each describe() to name what it gates. Cheapest; keeps every current behaviour.
2. Give the extra routes their own switches (or move _migrate-stored and diagnostics under a separate key) — the authored key then means what it says. A spec change with a compatibility question.
3. Rule it correct as-is — items is "the item-listing family, broadly" — and record that reading in the schema so the next reader does not re-derive this.

⚠️ Whichever way, note that RestServerConfig is not reachable from any shipped boot path today (filed separately), so the blast radius is currently limited to programmatic embedders.

Where it is already captured

docs/qa/platform-checklist/FOLLOW-UPS.md §10b E1, and as an acceptance clause on the new api-backend.rest-metadata-config-contract item, which requires a run to ENUMERATE each switch's real radius rather than trust the declared one.

---

Generated by Claude Code

[os-zhuang]

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

Anchor read, not guessed. The declaration is packages/spec/src/api/rest-server.zod.ts:346 ⇒ domain:spec. packages/rest is where the radius is observed, not where any of the three options lands.

Re-measured on origin/main f1d7872 (2026-09-05T00:12:29Z), counting the gates myself rather than trusting the card:

rest-server.zod.ts:346   items: z.boolean().default(true).describe('GET /meta/:type - List items of type'),

rest-server.ts:4673   if (metadata.endpoints.types !== false) {
rest-server.ts:4731   if (metadata.endpoints.items !== false) {     ← /diagnostics
rest-server.ts:4851   if (metadata.endpoints.items !== false) {     ← /_drafts
rest-server.ts:4943   if (metadata.endpoints.items !== false) {
rest-server.ts:5021   if (metadata.endpoints.items !== false) {
rest-server.ts:5480   if (metadata.endpoints.item !== false) {

⇒ Exactly four items gates, as filed. And the file's own routing comment at :4631-4632 enumerates the family it is ordering — "whole-store operations (/diagnostics, /_drafts, /_migrate-stored) → the per-type list (/:type)" — i.e. the code already knows these are whole-store operations and not the per-type list, and puts them on the same switch anyway.

Grade — p2

The card names the shape exactly:

An operator who reads the schema and turns off "list items of type" — a read they may consider chatty or unnecessary — silently unmounts a migration write door and the diagnostics sweep with it. Nothing warns, and nothing in the declared contract says those routes ride that switch.

⭐ And the second-order point is the one that makes this worth p2 rather than a doc nit: no census will ever flag it. items is genuinely live, so a liveness sweep is satisfied; what drifted is the key's radius versus its own describe(). ⇒ This is the declared-vs-enforced asymmetry in the direction the ledger structurally does not look. That is a new member of the family this shift has been cataloguing, not another instance of an existing one.

Not p1, and the card supplies the reason itself: ⚠️ RestServerConfig is not reachable from any shipped boot path today (its own card, #15543, routed alongside this one) — os serve fixes it and the dev plugin passes none, so every live crud / metadata / batch key is embedder-only. ⇒ The blast radius today is programmatic embedders, not deployments.

⚠️ But that mitigation is exactly what makes fixing it cheap now and expensive later. The moment a shipped boot path starts authoring RestServerConfig, this becomes an operator-facing trap on a write door. ⇒ Do this while nobody can be broken by it.

Boundary test — option-dependent, and only one is free

1. Document the real radius (extend each describe()) — prose on a contract surface, keeps every behaviour. No floor. ⛔ Cheapest, and honest, but it ratifies "a switch named list items controls a POST migration door."
2. Give the extra routes their own switches (or move _migrate-stored and diagnostics under a separate key) — the authored key then means what it says. ⇒ A spec change with a compatibility question: an embedder who set items: false today gets those routes back tomorrow unless the new keys default off, and defaulting them off is itself a behaviour change in the other direction. Manual floor.
3. Rule it correct as-is — items means "the item-listing family, broadly" — and record that reading in the schema. No floor; but ⛔ it has to be argued, not asserted, because POST /_migrate-stored is not a listing by any reading.

⛔ Triage is not choosing. ⚠️ One observation the chooser should have: types gates 2 mounts and item gates 4, so items is not an outlier — all three keys' radii exceed their describe(). ⇒ Options 1 and 3 must cover all three keys, not just items; a fix scoped to items alone leaves two-thirds of the same defect in place and reads as if the other two were checked and found correct.

⭐ Already captured downstream — read it before writing

docs/qa/platform-checklist/FOLLOW-UPS.md §10b E1, plus an acceptance clause on the new api-backend.rest-metadata-config-contract item, which requires a run to ENUMERATE each switch's real radius rather than trust the declared one. ⇒ That clause is the right instrument and it is already in place; whichever option lands here has to keep it satisfiable. ⛔ Do not close this card in a way that makes that checklist item vacuous.

Sequencing

Read #15543 first (RestServerConfig unreachable from any shipped boot) and #15544 (the MOUNT half of every switch is unpinned — tests assert what a switch normalizes to, never that the route leaves the table). ⭐ #15544 is the pin this card needs: a test asserting the route is actually absent when the switch is off would have made this radius visible from the start, and would catch option 2 getting it wrong. The three were filed within a minute of each other by the same flight and are best read as one cluster — ⛔ but they are three different defects and should stay three cards.

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

---

Generated by Claude Code