feat(spec): every metadata.endpoints.* switch gates exactly the face its name states, and the whole-store operations get their own key maintenance

[huangyiirene]

Fixes #15542
Part of #15854

Implements the maintainer ruling recorded on #15542 (comment 5557095147, director seat, batch #53): an endpoints.* switch gates exactly the face its name states, reads and writes alike. Both halves land here because they are one re-partition of one surface — #15854 is this card's converse mismatch, one switch over.

⛔ Draft on purpose, and it must stay that way. Clause-② is yes; claude-fable-5-1 was exhausted platform-wide when this was dispatched, so construction ran at claude-opus-5 under the quota-exhaustion exemption. Review does not take that exemption. Do not flip ready and do not enqueue until an at-tier needs:contract-review PASS exists.

The defect, in both directions at once

RestServerConfig.metadata.endpoints declared three switches, each describe() naming exactly one route, and each gated a different set:

key	it said	it did
types	GET /meta	2 mounts — GET /meta and GET /meta/types, one handler, two paths (deliberate)
items	GET /meta/:type	4 — the per-type list plus GET /meta/diagnostics, GET /meta/_drafts and the POST /meta/_migrate-stored write door
item	GET /meta/:type/:name	4 reads — and NOT its own PUT / DELETE, nor the history family, which answered to api.enableMetadata alone

So an operator who switched off a listing read they considered chatty silently unmounted a migration write door; and an operator who closed the per-item surface left its writes mounted. Neither is a liveness defect — all three keys were genuinely read — which is why no ADR-0049 census could flag either: what drifted was each key's radius against its own documentation, the axis the ledger structurally cannot see.

The code's own routing comment already separated "whole-store operations (/diagnostics, /_drafts, /_migrate-stored)" from "the per-type list (/:type)". The taxonomy was ahead of the switch surface. This makes the switches equal to it.

What lands

key	mounts it gates now (default prefix /meta)
types	GET /meta, GET /meta/types — unchanged
items	GET /meta/:type — and nothing else
item	GET / PUT / DELETE /meta/:type/:name, /references, /layers, /history, /audit, /diff, /published, /publish, /rollback, GET /meta/book/:name/tree — 12
maintenance	new, default true — GET /meta/diagnostics, GET /meta/_drafts, POST /meta/_migrate-stored — 3

• packages/spec/src/api/rest-server.zod.ts — the new key, and all four describe() strings rewritten to enumerate what they gate. The radius is the contract now, not a sample of it.
• packages/rest/src/rest-server.ts — the three whole-store gates read maintenance; the per-item family's later members (PUT, DELETE, history, audit, publish, rollback, diff, published) go through a new local registerPerItemRoute, which carries the same endpoints.item switch.
• packages/rest/src/rest-config-mount-table.pin.test.ts — the [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 #15544 mount-absent pins re-stated on the new radii, not deleted (ruling item 5). Each key keeps a row asserting the exact set of routes that leaves when it is false, in both directions, each with its presence twin. The §0 exhaustiveness count moves 19 → 20 with the new switch.
• packages/spec/liveness/metadata_endpoints.json — a maintenance row, and radius notes on items / item recording that the move was ruled rather than drifted.
• packages/spec/src/migrations/entries/semantic/18.metadata-endpoints-switch-radius-repartitioned.ts — the ADR-0087 D3 prescription (see below).
• docs/qa/platform-checklist/ — see below; the acceptance clause is kept and re-pointed, never retired.

Why registerPerItemRoute is a call and not one more if block

Two reasons, neither cosmetic. (1) No single brace pair contains exactly the right set: the later members of the per-item face are spread over ~1200 lines with GET /meta/object/:name/state/:field — deliberately not part of that face — sitting among them. (2) A gate that travels with its registration cannot be inherited or shed by moving a route past a brace, which is precisely how this switch came to gate four reads and none of its own writes. It reads this.routeManager at call time, deliberately: registerMetadataEndpoints swaps in the anonymous-deny wrapping registrar for the duration of the method, so a captured reference would register past that gate.

A secondary benefit is diff hygiene on a busy cross-lane file: wrapping those eight registrations in if blocks would have re-indented ~1200 lines of rest-server.ts for no behavioural gain.

One route deliberately left alone

GET /meta/object/:name/state/:field — the object FSM read, addressed by object name rather than by :type/:name — is in no per-family switch and still answers to api.enableMetadata alone. The ruling's enumeration does not name it, so moving it under a switch would be a fresh decision, not a tidy-up. It is called out in the registrar docblock and in the pin table so the next reader does not read its absence as an oversight.

BREAKING — priced and accepted (ruling item 6)

For a programmatic embedder that authors RestServerConfig.metadata.endpoints, the mounted table moves for two keys, in opposite directions:

• items: false removes one route instead of four. An embedder relying on it to close the whole-store family regains all three routes, the write door among them, unless it also sets maintenance: false. One line restores the old table: endpoints: { items: false, maintenance: false }.
• item: false removes twelve instead of four. An embedder relying on it to close only the per-item reads loses PUT, DELETE and the history family too. No key restores them — the per-item face is one face by this ruling.

Measured blast radius today is zero: RestServerConfig is reachable from no shipped boot path (#15543 — os serve fixes the config and the dev plugin passes none), so the affected population is programmatic embedders only. That is exactly why it lands now rather than after a boot path starts authoring it.

ADR-0087 disposition: a D3 semantic migration is REGISTERED; no D2 conversion. The changeset carries adr-0087: registered metadata-endpoints-switch-radius-repartitioned and check-adr-0087-registration accepts it as new in this diff. There is nothing for the conversion layer to convert — no key is renamed, removed or retyped, and a RestServerConfig is plugin TS configuration, never a stack collection member and never a sys_metadata row (the RestServerConfig.openApi31 precedent, #4579), so no rehydration seam sees it. But an embedder is owed a prescription, because both channels that would otherwise reach them are blind here: every key is an optional boolean, so { items: false } still compiles and still parses and simply mounts a different table. A D2 conversion could not decide the question either — rewriting { items: false } to { items: false, maintenance: false } preserves the old mounts but presumes an intent the author never expressed, and leaving it alone re-mounts a write door. That judgment is delegated, which is exactly what D3 is for.

The checklist item is kept satisfiable, not made vacuous (ruling item 7)

docs/qa/platform-checklist/areas/api-backend.json → api-backend.rest-metadata-config-contract is at revision 2. Its acceptance clause still requires a run to ENUMERATE each switch's real radius from a route-table diff rather than trust the describe(); what changed is the expected sets, plus a fourth maintenance step and the both-directions rule (a switch that grows a route is as much a FAIL as one that loses one). Left stale it would not have gone vacuous — it would have produced a false FAIL against the new radii, which is worse. FOLLOW-UPS.md §10b E1 records the ruling and points at revision 2; §10b E3's "nineteen gates pinned" is refreshed to twenty.

Declared scope increments (for the PM)

Three paths outside the claim's declared file surface, all named here rather than folded in silently:

1. docs/qa/platform-checklist/** — required by ruling item 7, as above. Not optional: the alternative is a checklist item that fails against the tree it is meant to measure.
2. packages/spec/liveness/metadata_endpoints.json — a new declared key needs its ADR-0049 ledger row, and items / item carry radius notes that were measured statements about the old gates.
3. packages/spec/src/migrations/entries/semantic/ + the generated registry.ts — check-adr-0087-registration refuses a **BREAKING** changeset with no disposition marker, and not-required (no-migration-prescription) is unavailable to a body that (correctly) prescribes one. Registering was the honest answer, not a wider scope.

Plus content/docs/permissions/system-context.mdx, which is line-anchored into rest-server.ts and was re-anchored mechanically by check-system-context-census --fix (10 anchors, no prose change).

One bounded in-place fix in the same docblock this card rewrites: MetadataEndpointsConfigSchema's @example advertised endpoints: { types, objects, fields } — two keys the schema has never declared. It is the same declared-versus-real class the card is about, sitting three lines above the block being changed, and it now shows the four real keys.

Verification

All figures measured on this branch at 484601894, the final commit.

Tests — bash scripts/pm/os-verify-lock.sh -c "pnpm --filter @objectstack/spec --filter @objectstack/rest run test", VERDICT command-exit 0:

packages/spec test:  Test Files  482 passed (482)   Tests  13102 passed (13102)
packages/rest test:  Test Files  186 passed (186)   Tests   3169 passed  (3169)

pnpm --filter … run typecheck for both: VERDICT command-exit 0 (check:test-typecheck reports the test layer at 0 files / 0 errors for @objectstack/rest).

Reverse verification — the pin can actually fail. With the implementation committed, the _migrate-stored gate was mutated back to endpoints.items and the pin re-run:

PRE  maintenance-gates=3   items-gates=1        (on-disk anchor counts, before)
POST maintenance-gates=2   items-gates=2        (after — the mutation really landed)
MUTATED hash=fa4e02a4… (was 4d20c874…)
Tests  2 failed | 22 passed (24)                ABLATION vitest exit=1
RESTORE: hash=4d20c874… head=4d20c874… — git diff HEAD empty

Direction observed, stated rather than assumed: two rows reddened, not one — metadata.endpoints.items grew a route and metadata.endpoints.maintenance lost one. That is the set-difference-in-both-directions property the pin is built on, demonstrated rather than asserted. The mutation is proved on disk by the anchor counts and the blob hash before the run is read, and the restore by git hash-object matching the HEAD blob with git diff HEAD empty.

Cross-package type check — the declaration really was rebuilt. A probe compiled against @objectstack/spec's rebuilt dist/*.d.ts from inside packages/rest:

leg A (no `maintenance`): exit=2
  src/__dts-probe.ts(3,14): error TS2741: Property 'maintenance' is missing in type
  '{ types: true; items: true; item: true; }' but required in type
  '{ types: boolean; items: boolean; item: boolean; maintenance: boolean; schema?: undefined; }'
leg B (control, with it):  exit=0, 0 probe errors

So the green typecheck above read a fresh declaration, not a cache. The probe file was removed and the removal verified. NormalizedRestServerConfig is module-private to rest-server.ts and MetadataEndpointsConfigParsed has no in-repo consumer, so no downstream package sees the widened parsed shape.

Gates — node scripts/pm/dispatch-gates.mjs --commands derived 102 families from this diff; all 102 were run and reconciled:

✓ dispatch-gates --ran: 102 derived famil(ies) accounted for — 102 run, 0 NOT-MEASURED.

Three of them first returned PREREQUISITE NOT MET (check:skill-examples, check:dual-build-cjs-loads, check:type-check-debt) because they read built output; the workspace was built (turbo run build --filter='./packages/*' --filter='./packages/*/*', 71 tasks successful) and all three then returned 0. check-adr-0087-registration prints 1 declared-breaking changeset(s), each carrying an ADR-0087 disposition … registered metadata-endpoints-switch-radius-repartitioned (new here). pnpm --filter @objectstack/spec check:generated prints ✓ All 15 generated artifacts are up to date after gen:docs and gen:liveness-counts.

Lint — no narrowing was needed: the repo-wide authority ran whole. pnpm lint (eslint . --no-inline-config) EXIT=0 in 58s, re-run on the final tree.

Collision check, read as instructed: scripts/check-single-claim-paths.mjs declares exactly one single-writer path, .objectui-sha. packages/rest/src/rest-server.ts is deliberately not on that list (the header's measurement rejects merely-hot files), so that gate can give no signal here — it passes, and its pass is not a clearance. The zero-quota substitute: git ls-remote --heads origin (1182 heads) matches no branch naming rest-server, metadata-endpoint, 15854, 15544 or 15851.

Known fleet CI defect, not this PR's: if Test Core (1/6) shows cancelled at a 30-minute timeout while the aggregate Test Core reports success, that is #16173 (amplifier #16157). ⛔ Do not re-run it, do not raise the timeout, do not touch scripts/test-shard-timings.json.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/rest, @objectstack/spec, touching 20 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/spec/liveness/metadata_endpoints.json, packages/spec/liveness/state-counts.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

25 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 618f70d74d934c09fa58f1eaa8493e95e4f847e9.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/spec/liveness/metadata_endpoints.json, packages/spec/liveness/state-counts.md) — pages documenting those are invisible to this run
• 5 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 132 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 618f70d74d934c09fa58f1eaa8493e95e4f847e9 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 1f9711a77b62e13046d37f42600d82cb9cd76de3 — the merge of head 484601894bd5b090426b435a14a0010707fc7ec3 into base 618f70d74d934c09fa58f1eaa8493e95e4f847e9, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1f9711a77b62e13046d37f42600d82cb9cd76de3 && git checkout 1f9711a77b62e13046d37f42600d82cb9cd76de3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 618f70d74d934c09fa58f1eaa8493e95e4f847e9 484601894bd5b090426b435a14a0010707fc7ec3 && git checkout -B drift-repro 618f70d74d934c09fa58f1eaa8493e95e4f847e9 && git merge --no-ff 484601894bd5b090426b435a14a0010707fc7ec3

node scripts/docs-audit/affected-docs.mjs --json 618f70d74d934c09fa58f1eaa8493e95e4f847e9

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 618f70d74d934c09fa58f1eaa8493e95e4f847e9 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-zhuang]

Contract review (clause ②) — PASS on content · NOT LANDABLE (red CI, real, this PR's) — PR #16243 at head 48460189 (Fixes #15542 · Part of #15854)

Reviewed by the director seat at tier (claude-fable-5-1, session session_01TezFG8ZMrNH6n5VTNpPpdH), 2026-09-06 08:40Z, on the domain:spec seat's hand-off (5557947706). The construction ran under the quota exemption; this is the at-tier review the PR body says it must not land without.

Clause ② answer: yes on both limbs, as declared, and it implements the maintainer's ruling on #15542 (5557095147, 2 + A: every endpoints.* switch gates exactly the face its name states) whole.

• Limb 1: MetadataEndpointsConfigSchema.endpoints gains maintenance (.default(true)), so the published RestServerConfig type and @objectstack/rest's parsed shape widen by one key; all four describe() strings now enumerate their mounts.
• Limb 2: the mounted route table moves for two keys in opposite directions — items: false removes 1 route instead of 4, item: false removes 12 instead of 4 — which is BREAKING for a programmatic embedder, priced correctly (no shipped boot path constructs the config, [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) and dispositioned under ADR-0087 as a registered D3 semantic migration (18.metadata-endpoints-switch-radius-repartitioned), the right layer since no key is renamed or retyped and a D2 conversion would have to guess an author's intent across a write door. Launch-window form is met: minor on @objectstack/spec + @objectstack/rest, **BREAKING** banner, <!-- adr-0087: registered … -->.

Content, read on the diff: the three whole-store gates read maintenance; items gates the one mount; the later per-item members go through registerPerItemRoute, which reads this.routeManager at call time (correct — registerMetadataEndpoints swaps in the anonymous-deny registrar for the method's duration). The #15544 pins are re-stated on the new radii (19 → 20 rows, both directions, GET /meta/object/:name/state/:field deliberately outside every per-family switch and named as such). The @example correction is in scope by class. Changeset, ledger row, liveness notes and checklist revision 2 are the ruling's items 5–7.

Why it cannot land — Dogfood Regression Gate (3/3) is a real failure this PR causes, and it is a finding, not a count to bump

FAIL  test/authz-probe-blind-spot.test.ts > packages/rest/src/rest-server.ts — population, reach and blind spot are unchanged
AssertionError: expected 73 to be 80
FAIL  … — every positive control is still present in THAT file
AssertionError: control "this.routeManager.register(" moved in packages/rest/src/rest-server.ts: expected 73 to be 80

That pin (#13260) holds the authz-conformance census equal to what authz-conformance.test.ts's discover() can reach, and its population for rest-server.ts is the count of this.routeManager.register( sites: 80 on main, 73 here, because eight registrations now go through registerPerItemRoute and the helper contributes one. ⚠️ If discover() reaches routes by that spelling, the eight per-item routes (PUT, DELETE, /history, /audit, /publish, /rollback, /diff, /published) have just left the authz-conformance probe's reach — a blind-spot increase on the metadata write face, which is the opposite of what this card is for. The remedy is therefore not 80 → 73 in the census: either make discover() (and the census derivation) see through registerPerItemRoute, or register through a spelling the scanner recognises, then re-derive population / reachable / blindSpot and re-state the row with the new controls. The pin file's own header says a moved reading is re-read by whoever moved it; that is this round. Test Core (1/6) on this head also shows the #16173 timeout kill — not this PR's, and it still has to be green on the head that lands.

needs:contract-review comes off PR + card #15542 now (review done at this head). Routed to the domain:spec seat (session_01T6HeZvT9wdSJD1ZxJb5Eno) for the patch round; the new head is re-hung on both carriers and the dogfood/census delta is re-read at tier — the rest of the content is not re-reviewed unless it moves.

---

Generated by Claude Code