capability-declaration-lifecycle: no shipped resource enforces a package capability server-side (no REST action-invoke route on this build)

[huangyiirene]

Symptom

No shipped resource enforces a package capability server-side. The three showcase actions carrying requiredPermissions have no REST execution route on this build: /api/v1/actions/<n>, /api/v1/action/<n>, /api/v1/objects/<o>/actions/<n>, and /api/v1/data/<o>/actions/<n> all 404, and rest-route-ledger.ts registers no action-invoke route. So the requiredPermissions gate for these actions is client-side only; there is no server surface on which to exercise the grant/deny contrast.

The three-way grant/deny/regrant resolves by name, but only demonstrable with a platform capability (manage_metadata). The remainder of the item passes: declaration → sys_capability seeding is exact (both documented fallbacks — humanize(name) label, generated description); platform-capability hijack is refused (a package declaring manage_users gets a WARN, skippedPlatform:1, the platform row unchanged — though the refusal is a WARN and boot proceeds); malformed declarations abort boot at Zod parse before any sys_capability write, so #5961 does not hold.

Root cause

Located by the run at packages/rest/src/rest-route-ledger.ts: the ledger's data-actions family registers clone/import/export routes but no action-invoke route for declared object/record actions. Confirmed on origin/main — the data-actions block lists only clone / import / import-jobs / export, no …/actions/<name> invoke route.

Related prior art (closed, different framing): #3923 reported Action.requiredPermissions as client-side fail-open in Console for type:'api' actions on 17.0.0-rc.0, and noted the server-side actionPermissionError covers only the platform ql.executeAction / MCP paths. This card records the coverage gap as observed on build 92f26f7: for the shipped showcase actions there is no REST invoke route at all, so capability-declaration-lifecycle clause 1 can only be exercised against a platform capability.

Reproduction

1. Stock showcase boot; enumerate the REST route ledger and probe the four action-invoke shapes above for a showcase action declaring requiredPermissions → all 404.
2. Confirm the grant/deny/regrant contrast is only demonstrable via a platform capability (manage_metadata).

Suggested fix

Either ship a server-side action-invoke route that enforces requiredPermissions for package-declared actions (so the gate is not client-side only), or record explicitly that package capability enforcement is not yet a server surface and adjust the checklist item's expectation. Route owner: packages/rest route ledger unless the action-invoke owner is located elsewhere.

Source

Extracted from the QA run #7637 (framework 92f26f7, console 09987b680).

[claude]

Dual-label resolution (queue+finding): reclassified needs-user-decision (both pm:queue and finding stripped; domain:cli stays as routing). The card's own fork is a public-API surface ruling: ship a REST action-invoke route that enforces package requiredPermissions server-side, or record that package capability enforcement is deliberately not a REST surface. Verified on origin/main @ 6a9dec6: packages/rest/src/rest-route-ledger.ts:221-230 registers only clone / import / import-jobs / export in the data-actions family — no action-invoke route, as filed. Prior art #3923 (closed completed) fixed the console-side UI gating only and did not rule on a server invoke surface, so this is not an already-made decision. Fail-closed today (all four probe shapes 404), so not a target:v17 blocker on the four-class test.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling — 2026-08-12

裁定:记录口径,不建路由。

要点:

• 口径记录:包能力(package capability)的服务端强制点是 ql.executeAction / MCP 路径的 actionPermissionError;本构建的 REST 没有 action-invoke 面(四种拼法 404、ledger 无此路由),所以「REST 上的 requiredPermissions 强制」不是缺陷,是不存在的面。把这段口径写进 checklist 该条目的预期(measure 真实存在的面:平台路径的 grant/deny/regrant),并在 rest-route-ledger.ts 的 data-actions 块注释里说明 invoke 路由是有意缺席。
• ⛔ 现在不上 REST action-invoke 路由:没有实测需求为它背书。记录在案:当它因真实需求上线时,requiredPermissions 的服务端强制是 day-one 要求,不是 follow-up —— 否则就是 Action.requiredPermissions 在 Console 端形同虚设：会话不下发 systemPermissions + 客户端 fail-open（17.0.0-rc.0） #3923 报过的 client-side fail-open 复活。
• 顺带确认卡内旁枝:平台能力劫持拒绝(WARN + skippedPlatform)与 boot 期 Zod 硬拒都按预期,不动。

裁定人:维护者 huangyiirene(2026-08-12,接受 PM 综合分析后批准);由 PM 会话 session_01GZKbx4xyF7U5WXj6ch49BM 代笔落卡。转 pm:queue(注释 + checklist 口径卡,小)。

---

Generated by Claude Code