Nav gating cannot express "prune when the destination cannot serve" — `enable.apiEnabled` is never consulted by `filterAppForUser`

[huangyiirene]

Split out of #7544 (fixed in #7909) by the domain:metadata seat. #7909 removed the one dead entry; this is the general gap it sat on, and it is a contract-face change ⇒ domain:spec.

Symptom

A Setup/app nav entry whose destination object cannot serve the request is shipped to the client in the /meta payload anyway. The user sees a menu item that, when clicked, cannot work — and today the console renders that failure as a generic empty state, so it reads as "you have no records" rather than "this page cannot work" (that half is an objectui surface — see the companion card linked below).

Root cause — measured on origin/main, twice, independently

filterAppForUser (packages/rest/src/rest-server.ts:2976-3056) is the server-side nav filter. It gates:

• _unpublished (the machine-managed key, ⛔ not hidden)
• app-level and item-level requiredPermissions
• requiresService (ADR-0057 D10)
• empty-group collapse ([console][nav] filterNav never drops a group DECLARED with children: [] — Setup renders an inert 「Approvals」 group on a runtime without plugin-approvals #7380)

Its own docblock names what it does not gate:

NOT gated here: visible (CEL) at any level, and requiresObject — both are still evaluated client-side only. That asymmetry is deliberate and pinned in rest.test.ts.

Nothing in nav filtering consults enable.apiEnabled at all. Two measurements, run separately by the #7544 dev and by the dispatching PM:

Probe	Result
apiEnabled in rest-server.ts	9 occurrences — apiAccessDenialFromEnable (:1665), the enforceApiAccess docblock (:2468-2505), the bulk path (:10128, :10177, :10423)
…of those, inside filterAppForUser (:2976-3056)	0
requiresObject in rest-server.ts	1 — the docblock line at :3011 saying it is not gated there

So requiresObject, the key that looks like the right tool, never reaches the server-side filter.

⭐ Why this is not "just add a gate"

Two independent conditions decide whether a destination can serve, and neither is expressible on a nav entry today:

1. enable.apiEnabled: false → OBJECT_API_DISABLED (404). apiAccessDenialFromEnable (:1658) is a pure function of the object's enable block — it takes no user, no permissions and no context. The denial is identical for every persona, platform admin included.
2. an apiMethods whitelist without the needed operation → OBJECT_API_METHOD_NOT_ALLOWED (405), same pure-function property.

⚠️ A requiredPermissions gate cannot prune either, and this is the load-bearing point: they are independent conditions, so no combination of permissions on the entry prunes an entry whose object is API-disabled. #7544 shipped exactly that combination for a year and it read as correct to reviewers — the in-code comment on the removed entry claimed a non-admin "403s server-side", which implies an admin could list. None could.

⇒ Re-pointing a dead entry at a requiresObject gate would not have pruned it either. Deletion was the only repair available to #7544, not merely the one chosen.

The sibling defect shares this root

The Account app served whole to a member denied every backing object (same QA sweep as #7544) uses requiresObject and still leaves the server with no pruning signal — because requiresObject is the client-only key. Both halves are one missing server-side declaration. Anyone closing this should check whether that sibling closes with it.

Scope — this is a fork, rule it before dispatching

⛔ Do not leave a dev to pick; the readings produce different contract faces:

• (a) Make requiresObject server-side — reuse the existing key, and have filterAppForUser resolve the named object and consult enable. Cheapest to declare, but it changes the meaning of an existing spec key and the docblock says the client-only asymmetry is deliberate and pinned in rest.test.ts — so that pin is a decision to overturn in the open, not a test to update quietly.
• (b) A new declaration (e.g. requiresServableObject / an enable-aware variant) — leaves requiresObject alone, costs a new spec property (ADR-0087 registration required).
• (c) Derive it, declare nothing — type: 'object' entries already name their objectName; the filter could consult enable for every such entry with no new key at all. Smallest contract face; ⚠️ but it is implicit behaviour, and it prunes entries whose authors never asked for pruning.

Whoever dispatches this should rule with a falsifiable premise, or escalate with the menu.

Control — a fix must not over-prune

nav_api_keys → sys_api_key rides the same machinery and has no enable restriction: it must survive any pruning change. packages/platform-objects/src/platform-objects.test.ts (landed in #7909, describe('object entries can actually serve a list (#7544)')) already asserts both directions through the same derivation source the REST gate uses (resolveEffectiveApiMethods / isApiOperationAllowed, #3391) — reuse it rather than writing a second, drifting copy of the gate order.

⚠️ sys_jwks's enable block is ⛔ out of scope. It is API-disabled because its rows are private JWT signing-key material; #7909 pinned that it stays apiEnabled: false / apiMethods: [] / access.default: 'private'. Opening a read path onto it is a credential disclosure, not a fix.

Evidence trail

• Setup › Advanced › Signing Keys (JWKS) is a dead nav entry — sys_jwks is API-disabled and a requiredPermissions gate cannot prune it #7544 — the reported instance (QA run QA run · platform-core (FULL area) · a86db175 · 2026-08-11 · 3 PASS / 1 PARTIAL / 7 FAIL #7514), and the dev report with the full measurement table
• fix(platform-objects): drop the dead Setup › Advanced › Signing Keys (JWKS) nav entry (#7544) #7909 — the removal, and the invariant test that now catches a re-added dead entry
• 跟踪:UI 操作按钮与 apiMethods 白名单一致性契约落地(#3026 设计定稿) #3391 — apiMethods fails CLOSED
• ADR-0057 D10 — requiresService, the existing precedent for a server-side nav gate
• [console][nav] filterNav never drops a group DECLARED with children: [] — Setup renders an inert 「Approvals」 group on a runtime without plugin-approvals #7380 — empty-group collapse

[huangyiirene]

Moved pm:queue → needs-user-decision by the spec seat (session session_0123k4cam2jEAkPmbJeoaY3r), under the standing lane-triage authorization. The card's own scope section forbids leaving the pick to a dev ("⛔ Do not leave a dev to pick"), and each route is a contract action on the manual floor: (a) re-means a published key whose client-only asymmetry is deliberately pinned in rest.test.ts; (b) mints a new authorable key (permanent ADR-0087 vocabulary); (c) adds implicit server-side behavior to a published surface.

Four-lens analysis:

1. Platform long-term coherence — servability is already fully declared on the object (enable.apiEnabled, apiMethods). Routes (a) and (b) declare it a second time on the nav entry, creating a two-source truth that can drift (entry says servable, object says not). Route (c) derives from the single existing source — no vocabulary growth — at the cost of one implicit rule in a filter whose gates are today all declared.
2. Measured business pull — real, measured twice: Setup › Advanced › Signing Keys (JWKS) is a dead nav entry — sys_jwks is API-disabled and a requiredPermissions gate cannot prune it #7544's dead entry shipped for a year and read as correct to reviewers (its in-code comment claimed a fallback that never existed), and the Account-app sibling still has no pruning signal. The pruning has pull; a new opt-in key does not — no author has asked to ship an entry whose destination cannot serve.
3. AI-agent error-resistance — (c) is structurally strongest: the footgun class disappears without asking authors (or AI authors) to remember a key. Its weakness is silence — an author whose object is accidentally API-disabled sees the entry vanish with no signal. If (c) is ruled, it should carry a loud companion: a publish-time diagnostic naming the pruned entry and the enable/apiMethods condition that pruned it (same principle as the authoring-validation-not-persisted: a flat view body is accepted, published and reported valid, then expands to nothing — the write door judges by the wire union, not the strict ViewSchema #7741 ruling: no silent dead rows — and no silent repairs either).
4. Startup scope discipline — (c) declares nothing and maintains nothing new. (b) is a permanent key for a derivable fact — the worst shape. (a) is cheap to type but spends its budget overturning a pinned deliberate decision.

Recommendation: (c) — filterAppForUser consults servability for every type: 'object' entry through the existing #3391 derivation source (resolveEffectiveApiMethods / isApiOperationAllowed — reuse the #7909 invariant test's gate order, not a second copy), plus the publish-time diagnostic above. Controls from the card stand: nav_api_keys → sys_api_key must survive any pruning change; sys_jwks stays apiEnabled: false and ⛔ out of scope. Note (c) leaves requiresObject's client-only pin untouched — no pin needs overturning.

Routing note if ruled (c): the implementation lands in packages/rest (filterAppForUser) ⇒ likely re-route domain:cli for the code, with this seat holding the contract statement (the docblock's "NOT gated here" list changes meaning). Awaiting your ruling — the card dispatches the moment one lands.

---

Generated by Claude Code