fix(qa): teach the authz blind-spot population rule the registerPerItemRoute spelling

The per-item family's later members register through a switch-carrying local
helper instead of a direct `this.routeManager.register(` call. The census rule
knew only the direct spelling, so it read population 73 / reachable 12 against a
recorded 80 / 19 and the Dogfood Regression Gate went red.

Re-recording 73/12 was the wrong repair: those 8 routes are still mounted and
still registered inside `registerMetadataEndpoints`, so the lower number would
have ratified a false population and encoded a 7-route blind spot in the census
named for finding them. The rule now counts both spellings, excluding the
helper's own forwarding call so it is not double-counted: 72 direct + 8
helper-routed = 80, and 11 + 8 = 19 reachable.

Reachability was checked before the count was widened. `registerPerItemRoute`
reads `this.routeManager` at call time and every call site is inside
`registerMetadataEndpointsInner`, which runs under the anonymous-deny
`guardedRouteManager` swap — so the helper hides nothing from the probe. That is
now measured rather than argued: rest-meta-auth.test.ts drives an anonymous
`GET /meta/:type/:name/history` to 401 with the history read never reached.

Both halves of the new rule carry exact positive controls so neither can go
silently to zero.

Also completes the changeset's BREAKING paragraph: `MetadataEndpointsConfigParsed`
gained a required `maintenance: boolean` on the parsed (output) side — an
ADR-0087 D8 compiler-carried narrowing that was implemented but not written down.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno

Author: claude

.changeset/metadata-endpoints-switch-radius-maintenance-key.md

@@ -54,6 +54,18 @@ the mounted route table moves for two of the four keys, in opposite directions:
   mounted **loses those eight**. There is no key that restores them — the per-item face is
   one face by this ruling — so an embedder that wants the writes keeps `item` on and
   closes the surface at `api.enableMetadata` or at the object's own `enable.apiMethods`.
+- **The exported type `MetadataEndpointsConfigParsed` narrows: `endpoints` gains a
+  REQUIRED member `maintenance: boolean`.** `maintenance` is `z.boolean().default(true)`,
+  so it is optional on the way *in* and always present on the way *out* — and
+  `MetadataEndpointsConfigParsed` is `z.infer<typeof MetadataEndpointsConfigSchema>`, the
+  OUTPUT side. Any code that builds one of these objects by hand — a test fixture, a
+  helper returning the parsed shape, a `satisfies MetadataEndpointsConfigParsed` literal —
+  stops compiling with `TS2741: Property 'maintenance' is missing`. This one IS
+  compiler-carried (the ADR-0087 D8 class), which is the good case: the break is loud, it
+  lands at build time, and no runtime behaviour depends on the author noticing a
+  changelog. Add `maintenance: true` to restore the previous mounts, or `false` to keep
+  the whole-store family closed. In-repo consumers of the type: none — the narrowing was
+  measured against a probe compiled from the rebuilt declaration, not assumed.
 
 Priced and accepted rather than deferred: `RestServerConfig` is reachable from **no
 shipped boot path** today (`os serve` fixes the config and the dev plugin passes none,
@@ -70,10 +82,14 @@ convert: a `RestServerConfig` is plugin TS configuration, never a stack collecti
 and never a `sys_metadata` row (the `RestServerConfig.openApi31` precedent, #4579), so no
 rehydration seam sees it. What changes is a mounted route table at construction time.
 
-Nor is it compiler-carried: every key is an optional boolean, so `{ items: false }`
-still compiles and still parses and simply mounts a different table. The two channels
-that would otherwise reach a consumer are both blind, which is precisely the residue
-D3 exists for — the prescription is registered as
+Nor is the RADIUS change compiler-carried on the AUTHORED side — and that is the half a
+D3 is owed for. Every authored key is an optional boolean, so `{ items: false }` still
+compiles and still parses and simply mounts a different table: the author is told
+nothing. (The parsed-type narrowing in the third BREAKING bullet above *is*
+compiler-carried, but it catches only code that hand-builds the OUTPUT type — it cannot
+reach the embedder who authored `{ items: false }` and now silently gets three routes
+back.) So for the change that actually moves the route table, both channels that would
+otherwise reach a consumer are blind, which is precisely the residue D3 exists for — the prescription is registered as
 `metadata-endpoints-switch-radius-repartitioned` so `objectstack migrate meta` hands
 it to an upgrading embedder instead of leaving it as prose in a changelog.
 

packages/qa/dogfood/test/authz-probe-blind-spot.census.ts

@@ -77,7 +77,12 @@
 //
 // `rest-server.ts` is pinned below at its STATIC reading: 80 `routeManager`
 // call sites, 17 registrars, 19 sites inside the one mintable registrar, 61
-// outside. A RUNTIME census — construct `RestServer` against a recording
+// outside. ⭐ [#15542] Those 80 are counted across TWO spellings since the
+// per-item family gained a switch-carrying helper — 72 direct
+// `this.routeManager.register(` sites plus 8 `registerPerItemRoute(` calls, the
+// helper's own forwarding call excluded so it is not counted twice. The total
+// did not move; the rule had to learn the second spelling to keep reading it.
+// A RUNTIME census — construct `RestServer` against a recording
 // `RouteManager` and a protocol implementing every optional capability, then
 // call each registrar — reads 85 / 17 / 19 / 66 instead. Both are correct and
 // the delta is fully explained: `registerApprovalsEndpoints` builds 12 routes
@@ -312,7 +317,47 @@ export const PROBE_FILE_CENSUS: readonly ProbeFileReading[] = [
     population: 80,
     reachable: 19,
     blindSpot: 61,
-    populationRule: '`this.routeManager.register(` call sites; reachable = those inside registerMetadataEndpoints',
+    populationRule:
+      'route registration sites — `this.routeManager.register(` call sites, LESS the one inside ' +
+      '`registerPerItemRoute` (the shared forwarder, not a route), PLUS `registerPerItemRoute(` call sites; ' +
+      'reachable = those inside registerMetadataEndpoints',
+    // [#15542 / #15854] ⭐ THE POPULATION RULE LEARNED A SECOND SPELLING, and
+    // the numbers it produces did NOT move: 80 / 19 / 61, exactly as before.
+    //
+    // WHAT MOVED IN THE SOURCE. The per-item family's later members (`PUT`,
+    // `DELETE`, `/history`, `/audit`, `/diff`, `/published`, `/publish`,
+    // `/rollback`) stopped being direct `this.routeManager.register(` call
+    // sites and became `registerPerItemRoute(` calls — a local helper carrying
+    // the `endpoints.item` switch. Net -7 on the old one-spelling reading: 8
+    // sites left that spelling and the helper's own forwarding call added 1
+    // back. So the old rule read population 73 / reachable 12.
+    //
+    // ⛔ 73 / 12 WAS NOT RE-RECORDED, and the reason is this file's whole
+    // purpose. Those 8 routes are still mounted and still registered exactly
+    // where they were; only the spelling of the call changed. Writing 73 down
+    // would have ratified a population 7 short of the real one and encoded a
+    // 7-route hole in the very blind-spot count this census exists to keep
+    // honest — the failure it is named for, committed by its own record.
+    //
+    // ⚠️ REACHABILITY WAS CHECKED BEFORE THE COUNT WAS WIDENED, because if the
+    // helper HID those routes from the probe the repair would belong in
+    // `rest-server.ts` and not here. It does not. `registerPerItemRoute` reads
+    // `this.routeManager` at CALL time and every one of its 8 call sites is
+    // lexically inside `registerMetadataEndpointsInner`, which
+    // `registerMetadataEndpoints` runs with `this.routeManager` swapped to the
+    // anonymous-deny `guardedRouteManager` and restored in a `finally`. So a
+    // helper-routed registration goes through the identical wrapping the 11
+    // remaining direct sites in that registrar do, and the umbrella key
+    // `meta:rest-server.ts:registerMetadataEndpoints` covers it unchanged.
+    // Pinned at runtime rather than argued from source:
+    // `packages/rest/src/rest-meta-auth.test.ts` drives an anonymous
+    // `GET {meta}/:type/:name/history` — a helper-routed route — to 401.
+    //
+    // The decomposition, so the two halves stay legible: 72 direct route
+    // registrations + 8 helper-routed = 80 population; 11 + 8 = 19 reachable.
+    // `this.routeManager.register(` reads 73 because the helper's forwarder is
+    // one of them, and it is sliced out before counting.
+    //
     // [#13214] `enforceAuth` 61 -> 64. ⛔ RE-ANCHORED, not relaxed: the control
     // exists to prove this census is still reading the file it thinks it is, and
     // a rising `enforceAuth` is precisely what the 2026-08-30 ruling on #13214
@@ -329,7 +374,21 @@ export const PROBE_FILE_CENSUS: readonly ProbeFileReading[] = [
     // 80, `reachable` 19, `private register*Endpoints(` 17 and
     // `this.routeManager.register(` 80 are all unchanged — #13214 added no route
     // and no registrar. `blindSpot` therefore stays 61 as well.
-    controls: { 'private register*Endpoints(': 17, 'this.routeManager.register(': 80, enforceAuth: 64 },
+    // ⚠️ That last figure is the reading AS OF #13214 and is left as written:
+    // the control is 73 today for the spelling reason recorded above, and the
+    // population it feeds is still 80. Do not "correct" the paragraph — it is a
+    // dated measurement, not a live claim.
+    controls: {
+      'private register*Endpoints(': 17,
+      'this.routeManager.register(': 73,
+      // Both halves of the new rule carry their own control, so neither can go
+      // silently to zero: a helper deleted and its routes inlined back would
+      // still read population 80, and only these two controls would notice the
+      // shape moved and force this provenance to be re-read.
+      'registerPerItemRoute(': 8,
+      'const registerPerItemRoute =': 1,
+      enforceAuth: 64,
+    },
     note:
       'The single non-tripwire probe names ONE registrar of 17. The other 16 can never mint a key: ' +
       'registerCrudEndpoints, registerApprovalsEndpoints, registerDataActionEndpoints, registerReportsEndpoints, ' +
@@ -560,21 +619,57 @@ export function deriveProbeFileCensus(): {
   }
 
   // ── rest-server.ts ──────────────────────────────────────────────────────
+  //
+  // [#15542 / #15854] TWO SPELLINGS, ONE POPULATION. A route registration in
+  // this file is EITHER a direct `this.routeManager.register(` call site OR a
+  // `registerPerItemRoute(` call — the local helper the per-item family's later
+  // members go through, which carries the `endpoints.item` switch and forwards
+  // to `this.routeManager.register(entry)`. Both are registrations; counting
+  // only the first spelling reads 7 short.
+  //
+  // ⛔ The helper's OWN forwarding call is NOT a registration site — it is the
+  // one shared mechanism 8 sites go through — so its body is sliced out before
+  // counting. Counting it would double-count every helper-routed route.
   {
     const src = read('packages/rest/src/rest-server.ts');
     const registrarRe = /^\s*private\s+register[A-Za-z]*Endpoints\s*\(/gm;
     const mountRe = /this\.routeManager\.register\(/g;
+    // Matches the CALL sites only. The declaration reads
+    // `const registerPerItemRoute = (` and the docblock mentions read
+    // `{@link registerPerItemRoute}` — in neither is the name followed by `(`.
+    const helperCallRe = /registerPerItemRoute\(/g;
+    const helperDeclRe = /const\s+registerPerItemRoute\s*=/;
+
+    /**
+     * Registration sites in one haystack: direct call sites, LESS the helper's
+     * own forwarding call, PLUS the helper's call sites.
+     *
+     * ⛔ Fail-loud, like the ledger marker slice above: a helper declaration
+     * that moves out of this shape slices to '' and nothing is subtracted, so
+     * the reading comes out ONE HIGH (81 / 20) and this census goes RED. It
+     * never silently shrinks — a quietly narrower rule is the failure mode the
+     * whole file is built against.
+     */
+    const sites = (hay: string): number => {
+      const at = hay.search(helperDeclRe);
+      const stop = at < 0 ? -1 : hay.indexOf('\n        };', at);
+      const forwarder = at < 0 || stop < 0 ? '' : hay.slice(at, stop);
+      return occurrences(hay, mountRe) - occurrences(forwarder, mountRe) + occurrences(hay, helperCallRe);
+    };
+
     // Slice the mintable registrar's body: from its declaration to the next one.
     const decls = [...src.matchAll(registrarRe)].map((m) => ({ at: m.index ?? 0, text: m[0] }));
     const metaIdx = decls.findIndex((d) => d.text.includes('registerMetadataEndpoints'));
     const start = decls[metaIdx]?.at ?? 0;
     const end = decls[metaIdx + 1]?.at ?? src.length;
     files.set('packages/rest/src/rest-server.ts', {
-      population: occurrences(src, mountRe),
-      reachable: occurrences(src.slice(start, end), /this\.routeManager\.register\(/g),
+      population: sites(src),
+      reachable: sites(src.slice(start, end)),
       controls: {
         'private register*Endpoints(': occurrences(src, /private\s+register[A-Za-z]*Endpoints\s*\(/g),
         'this.routeManager.register(': occurrences(src, /this\.routeManager\.register\(/g),
+        'registerPerItemRoute(': occurrences(src, /registerPerItemRoute\(/g),
+        'const registerPerItemRoute =': occurrences(src, /const\s+registerPerItemRoute\s*=/g),
         enforceAuth: occurrences(src, /enforceAuth/g),
       },
     });

packages/rest/src/rest-meta-auth.test.ts

@@ -67,6 +67,41 @@ describe('RestServer metadata routes — anonymous-deny gate (#3963)', () => {
         expect(protocol.getMetaItems).toHaveBeenCalled();
     });
 
+    // [#15542 / #15854] The per-item family's later members register through
+    // `registerPerItemRoute` rather than by a direct `this.routeManager.register(`
+    // call. That helper reads `this.routeManager` at CALL time, so it registers
+    // through the same `guardedRouteManager` swap the direct sites do — but that
+    // is a source argument, and the gate is worth a MEASUREMENT. Without this
+    // case the whole helper-routed half of the surface (`PUT`, `DELETE`,
+    // `/history`, `/audit`, `/diff`, `/published`, `/publish`, `/rollback`) had
+    // no test proving it is still anonymously denied, and a future refactor that
+    // captured `this.routeManager` at definition time would register all eight
+    // past the gate with every existing test still green.
+    //
+    // It is also what licenses `authz-probe-blind-spot.census.ts` counting those
+    // 8 as REACHABLE by `meta:rest-server.ts:registerMetadataEndpoints`.
+    it('401s an anonymous helper-routed per-item route — the gate travels with `registerPerItemRoute` (#15542)', async () => {
+        const protocol: any = { historyMetaItem: vi.fn().mockResolvedValue({ events: [] }) };
+        const rest = new RestServer(makeServer() as any, protocol, {} as any);
+        rest.registerRoutes();
+        const route = rest
+            .getRoutes()
+            .find((r) => r.method === 'GET' && /\/meta\/:type\/:name\/history$/.test(r.path));
+        if (!route) throw new Error('GET /meta/:type/:name/history route not registered');
+
+        const { res, state } = makeRes();
+        await (route.handler as (req: any, res: any) => Promise<void>)(
+            { method: 'GET', params: { type: 'object', name: 'sys_metadata' }, query: {}, headers: {} },
+            res,
+        );
+
+        expect(state.status).toBe(401);
+        expect(state.body?.error).toBe('UNAUTHENTICATED');
+        // Short-circuited BEFORE the history read — the per-org event log did
+        // not leak, which is the same property the direct sites are pinned for.
+        expect(protocol.historyMetaItem).not.toHaveBeenCalled();
+    });
+
     it('still 401s an anonymous /meta/object — the opt-out is retired (#3963)', async () => {
         // `api.requireAuth: false` used to serve object schemas anonymously. The
         // opt-out is gone: object metadata is never public. (Only the book/doc