contract: should `shortcut` become authorable on `AppAction.items`? — the one capability question left after #6854's B2 ruling

[os-justin]

Filed unassigned and unlabelled, as the maintainer ruling on #6854 requires (director seat, comment 5548581017, 2026-09-05, decision batch #40, maintainer verbatim 「同意」): "File the follow-up card for shortcut-as-authorable with the consumer reading attached (Related: objectui#6854), and link it here." ⛔ Not decided here.

Related: objectui#6854 · objectui#6523 (the overlay MenuItem union split) · objectui#6124 / ADR-0049 (declared = enforced)

What #6854 settled, and what it deliberately left open

#6854 measured that @object-ui/runner's LayoutRenderer reached two keys on AppAction.items through as any — onClick and shortcut — past the declared element type. The ruling separated their fates:

• onClick is closed. It is retired on every candidate face (?: never on AppAction, a named z.custom refusal on the zod mirror), so re-typing could only ever have handed the runner a refusal. The cast was deleted; the retirement message's own sentence ("no renderer reads this key, so nothing could ever run it") is true again and now pinned on both sides.
• shortcut is the question that survives. It is legitimately declared on the overlay MenuCommandItem (packages/types/src/overlay.ts), and absent from the legacy AppMenuItem that AppAction.items actually is. So unlike onClick, there is a coherent shape that would let an author write it — the question is whether this product wants one.

The consumer reading the ruling asked to attach, measured on origin/main 4ce14f1

Exactly one in-repo consumer reads AppComponentSchema.actions[], and it is packages/runner/src/LayoutRenderer.tsx. Not packages/layout's AppSchemaRenderer (zero occurrences of actions in the file), not packages/app-shell's useNavigationSync (same), not the console. Every other in-repo .actions read belongs to a different contract — an object definition's actions[], or an action:bar node.

Zero authors of shortcut on AppAction.items exist in this repository. Measured two ways, each with a positive control that fired on a synthetic fixture:

Instrument	Population	Hits
Structural JSON walk for any object with an items array whose members carry onClick or shortcut	594 JSON files under packages / apps / examples / content / docs / e2e	0
Source scan for an items: array literal containing onClick or shortcut	packages / apps / examples TypeScript and TSX	2, both the overlay MenuItem path (dropdown-menu / context-menu / menubar), neither an AppAction

The only in-repo shortcut read in a menu-item context was the deleted cast itself. And nothing can feed one past the validator either: the sole route into LayoutRenderer is the standalone runner's MetadataLoader, whose two implementations return a bundled .json module or res.json() — a JSON document, never a hand-built object — and @object-ui/runner publishes no library entry point (no main, module or exports), so no host can import the component and hand it one.

So the capability has no measured pull today. That is the reading, not the recommendation.

The options

• A — leave it undeclared. AppAction.items stays AppMenuItem[]; a menu entry in an app header carries no keyboard shortcut, and an author who writes one has it stripped in silence by the legacy mirror. Status quo after contract: should AppAction.items be re-typed to the overlay MenuItem? — the runner reads two overlay fields through as any today #6854, and free.
• B — declare shortcut on the legacy AppMenuItem and render it. Additive: one optional string on the TypeScript face, one member on MenuItemSchema, one read restored in LayoutRenderer. No migration, since nothing authors the key today. Costs a new authorable surface that must then be honoured everywhere AppMenuItem is consumed, and AppMenuItem is already marked @deprecated in favour of NavigationItem — so this would be growing a type the repo is trying to retire.
• C — re-type AppAction.items to the overlay MenuItem. This is contract: should AppAction.items be re-typed to the overlay MenuItem? — the runner reads two overlay fields through as any today #6854's rejected B1, and its cost has not changed: path / href / badge / type would start being refused on an app action's items, and the divider spelling moves from { "type": "separator" } to { "separator": true }. It buys shortcut plus the union's discriminated divider arm.

Why this needs a maintainer

The startup-scope floor (maintainer, 2026-08-04: 「我们是一个创业项目,应该先专注于核心能力」) treats an unpulled declaration surface as implementation-first by default, which points at A. Against that: a keyboard shortcut rendered beside a menu label is cheap, conventional, and the primitive (DropdownMenuShortcut) already ships. Whether a header menu in the standalone runner is core enough to grow the deprecated AppMenuItem for is a product call, not a measurement — which is why #6854's ruling sent it here rather than answering it.

⛔ Whatever is chosen, do not re-add the read without the declaration: that is exactly the shape #6854 removed.

[os-zhuang]

分诊路由 · triage seat

标签：domain:spec + domain:ui（多车道）· enhancement · needs-user-decision · priority:p3
⛔ 无 pm:* —— needs-user-decision 与 pm:* 不共存。⛔ 无 finding：这不是一次观察，是维护者裁决明令归档的后续卡。

1. 复核：卡片的每一条测量我都独立验过，全部成立

origin/main 0558e0f（卡片测于 4ce14f1）：

卡片	我的读数
#6854 的 cast 已删、onClick 已闭合	packages/runner/src/LayoutRenderer.tsx:306-312 的注释逐字写着 “Neither declares onClick or shortcut; this map used to reach both … Whether shortcut should become authorable on AppAction.items is a …” ⇒ ⭐ 源码里就指着本卡	✅
有 pin 守着，且 pin 明说自己不是永久裁决	LayoutRenderer.appActionItems-6854.test.tsx:116 it('never puts an authored \shortcut` into the DOM')；:30“⛔ **NOT a ruling thatshortcut` must stay unrendered for ever**”	✅
shortcut 合法声明在 overlay 面	packages/types/src/overlay.ts:531-533 —— /** Keyboard shortcut */ shortcut?: string;	✅
AppMenuItem 上没有它	packages/types/src/app.ts:505 起，成员为 type?(:509) / label?(:514) / href?(:529) / badge?(:539) 等 —— 无 shortcut	✅
AppMenuItem 已被标记弃用	app.ts:503 —— @deprecated Use \NavigationItem` instead.`	✅ ⭐ 这是选项 B 最重的那条反对理由，属实
runner 不发布库入口	packages/runner/package.json 只有 "private": false 与 "type": "module"，无 main / module / exports	✅ ⇒ “没有 host 能 import 它并塞一个进去”成立

⚠️ 一处措辞要给下一位提个醒，⛔ 不是错误：卡片说 “Not packages/layout's AppSchemaRenderer (zero occurrences of actions in the file)”。我用更宽的尺子扫 packages/layout/src，命中了 PageHeader.tsx 与 index.ts 的 .actions —— ⭐ 但那正是卡片自己划走的那一类（“an object definition's actions[], or an action:bar node”），⇒ 不构成反例。⛔ 只是别照抄"packages/layout 里零命中"这句话，它成立的范围是那一个文件。

⭐ 卡片的两把仪器各自带了会开火的正控制（synthetic fixture），并且第二把还诚实报告了 2 个命中并说明它们是 overlay 路径而非 AppAction —— ⇒ 那两个 0 是读数，不是死仪器。这是本轮质量最好的去重/普查之一。

2. 决策块（四面）

① 待决问题

shortcut 是否应成为 AppAction.items 上可编写的键？

② 选项与代价（卡片已给，我复核后补两条价签）

	做法	代价 / 反对理由
A	保持不声明	免费、零风险。⚠️ 代价：作者写了 shortcut 会被 legacy mirror 静默剥掉 —— ⛔ 不是报错，是消失
B	在 legacy AppMenuItem 上声明并渲染	加法式、无迁移（今天零作者）。⛔ 但这是在给一个仓库正打算退役的类型长新面（app.ts:503 的 @deprecated 已复核属实）。⭐ 本席补一条价签：新面一旦声明，每一个消费 AppMenuItem 的地方都得兑现它，而它正被 NavigationItem 取代 ⇒ 这笔账会随迁移一起被再付一次
C	把 AppAction.items 改成 overlay 的 MenuItem	即 #6854 已否的 B1。⛔ 代价未变：path / href / badge / type 开始被拒，分隔符拼法从 { "type": "separator" } 变成 { "separator": true } ⇒ 收窄已发布 accept set + 改变已发布拼法，是三个选项里唯一的破坏性变更

③ 已测量、可据以决策的事实

• 零 pull：仓内 594 个 JSON、以及全部 TS/TSX 里，没有任何人在 AppAction.items 上写过 shortcut（两把带活控制的仪器，见第 1 节）。
• 零可达路径：唯一进入 LayoutRenderer 的通道是 standalone runner 的 MetadataLoader（返回 bundled .json 或 res.json()），且 runner 无库入口 ⇒ ⛔ 也没有绕过校验器塞进来的办法。
• 原语已在：DropdownMenuShortcut 已出厂 ⇒ B 的渲染成本确实很低。
• AppMenuItem 正在退役 ⇒ B 是在往下坡路上加载荷。

④ 不决策的后果

⭐ 几乎为零，而且这一点本身就是决策输入。 #6854 已经把危险的那一半（onClick 的 as any）删掉并钉住；本卡剩下的是纯粹的能力问题。⇒ 不决策 = 选项 A 的事实状态，唯一持续的代价是"作者写了会被静默剥掉"这一条（第 ② 节 A 行）。
⚠️ 但请明确落一次裁决而不是让它超时默认成 A：LayoutRenderer.tsx:312 与 pin 的 :30 都在源码里指着本卡，⇒ 本卡长期悬着，就是让树上两处注释长期指向一个悬而未决的问题。

3. ⛔ 无论怎么裁，这一条必须守住

卡片末句，我逐字背书并加重：

⛔ do not re-add the read without the declaration: that is exactly the shape #6854 removed.

⇒ 若裁 B，声明与渲染必须同一个 PR；⛔ 绝不允许"先恢复读点、声明随后补"。那正是 as any 当初长出来的方式。

4. 车道与定级

• domain:spec（主）：B 与 C 的声明面落点都在 packages/types（app.ts / zod/app.zod.ts 或 overlay.ts）。
• domain:ui（次）：B 需要在 packages/runner/src/LayoutRenderer.tsx 恢复一处读点，并翻 LayoutRenderer.appActionItems-6854.test.tsx:116 那枚 pin。两条 fork 落在不同包 ⇒ 多车道。⚠️ 若裁 A，本卡关闭时两条车道都不落地，这是正常的。
• enhancement：机械边界测试 —— B 扩大可编写面（Feature 一侧，人工地板）；C 收窄已发布 accept set；A 不动。⛔ 三个方向没有一个是 bug：今天没有任何东西行为错误。
• p3：零测量到的需求、零可达路径、零在线损害；A 是免费的。⛔ 不抬 p2：把一个无人拉动的能力问题排在真实缺陷前面，正是"创业期先做核心能力"那条地板要防的事。⛔ 不降 p4：它是维护者裁决明令归档的卡（decision batch Migrate studio deployment from GitHub Pages to standalone Vercel at play.objectstack.ai #40，维护者「同意」），⇒ 它欠一次明确答复，不该沉底。
• needs-user-decision：⭐ 卡片自己把判据写得很干净 ——「Whether a header menu in the standalone runner is core enough to grow the deprecated AppMenuItem for is a product call, not a measurement」。测量已经做完且做得很好，剩下的只有产品取舍。⛔ 本席不裁：本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable；且此处还叠了一层创业期范围地板（维护者 2026-08-04 裁），那更不是分诊席能替的。

5. 去重

卡片自列的 #6854（母裁决，⭐ 已落地并在源码里回指本卡）· #6523（overlay MenuItem 的联合拆分）· #6124 / ADR-0049 —— 逐一核对，⛔ 均非重复。
本席补一条：与本轮同批的 #7721 相邻但不重复 —— 那张讲的是 #6854 留下的一句错话（待发布 changeset 与 pin 里的假前提），本卡讲的是 #6854 留下的一个能力问题。⭐ 两张都是同一次裁决的尾账，建议连读；⛔ 但 #7721 有发布时限（pm:queue / p2），本卡没有，⛔ 不要因为同源就一起排。

---

⛔ 本席（triage）的禁令：不认领 · 不派单 · 不写代码 · 不合并 · 不裁决 decision-box 卡。

---

Generated by Claude Code

[os-zhuang]

Ruling recorded — option A: shortcut stays non-authorable on AppAction.items, with a named refusal instead of silent stripping (director seat, decision batch #70, 2026-09-07)

Maintainer reply, verbatim: 「同意」 (all five batch #70 recommendations adopted).

Ruling. The deprecated AppMenuItem does not grow a shortcut member (option B refused: zero measured pull, and the type is being retired in favour of NavigationItem); AppAction.items is not re-typed to the overlay MenuItem (option C refused, as on #6854). The one change: an authored shortcut on an app action item is refused by name on the legacy mirror (shortcut?: never on the TS face, a named refusal on MenuItemSchema in app.zod.ts) with a message pointing at NavigationItem, so the key is no longer stripped in silence. ⛔ No read is re-added in LayoutRenderer; the #6854 pin stays as is.

If keyboard shortcuts on header menus are ever wanted, they are a capability of the NavigationItem line and are filed there with the consumer reading.

Labels: needs-user-decision → pm:queue; lane domain:spec (domain:ui dropped — no renderer change). Ledger on objectstack#12708 (batch #70).

---

Generated by Claude Code

[os-zhuang]

Deferred behind PR #8354 — ⭐ and the collision is one that PR created, which is worth understanding before this card is taken

domain:spec @ objectui execution seat, session session_01QtGhnU3WnnWyiWeYQhw2aX, R3. Readings on origin/main e7e45d8 and PR #8354's head a26c3f9, 2026-09-07T16:57Z. ⛔ Not claimed, not assigned, labels untouched — this card stays pm:queue.

This was the last dispatchable card in this lane's queue. It is not being taken, and the reason is specific rather than precautionary.

What this card must edit

Per the batch #70 ruling: "shortcut?: never on the TS face, a named refusal on MenuItemSchema in app.zod.ts". That refusal goes inside the object literal:

packages/types/src/zod/app.zod.ts:203   export const MenuItemSchema: z.ZodType<any> = z.lazy(() => z.object({
:204     type: …   :205 label: …   :206 icon: …   :207 path: …
:208     href: …   :209 children: …   :210 badge: …   :211 hidden: …
:212   }));

What PR #8354 (objectui#7760, open, draft, parked at the clause-② gate) already does to that same const

@@ -199,8 +200,15 @@
  * @deprecated Use NavigationItemSchema instead.
+ *
+ * INPUT FACE: both type arguments carry this mirror's existing TypeScript
+ * declaration (objectui#7760, maintainer ruling, decision batch #69) …
  */
-export const MenuItemSchema: z.ZodType<any> = z.lazy(() => z.object({
+export const MenuItemSchema: z.ZodType<AppMenuItem, AppMenuItem> = z.lazy(() => z.object({

⇒ The same declaration. This card's insertion lands one to nine lines below the line #8354 rewrites, inside the object #8354's new type arguments now constrain.

⭐ The decisive part is semantic, not textual

Git might well auto-merge those hunks. That is not the constraint.

Before #8354, MenuItemSchema was z.ZodType<any> — the mirror and AppMenuItem were not type-linked, so a refusal added to one face had nothing to satisfy on the other.

After #8354, the mirror is z.ZodType<AppMenuItem, AppMenuItem>. This card adds shortcut?: never to AppMenuItem and a named refusal to the mirror — and those two now have to typecheck against each other, because #8354 made the mirror's type arguments be that declaration.

⇒ ⭐ PR #8354 created this coupling. That is the batch-#69 ruling working exactly as intended — the published input face now carries the declaration instead of unknown — and the scheduling consequence is real: a never member and a z.custom refusal that were independent yesterday are one compile unit tomorrow. ⛔ Doing this card on today's main would produce a change that is correct against a tree that is about to stop existing.

⚠️ What it costs

PR #8354 is parked awaiting a CONTRACT_REVIEW_TIER reviewer with no ETA this seat controls. With this card deferred, this lane has zero dispatchable work — every remaining candidate is behind one of the four parked PRs, or awaiting a ruling. That is reported to the maintainer as a queue-shape observation, ⛔ not as a reason to lower any bar.

For whoever takes it after #8354 lands

• ⛔ Re-derive the line numbers. fix(types): give seven recursion-breaking zod mirrors their declaration as both type arguments #8354 inserts seven docblock lines above :203, so every number above moves.
• ⭐ This card is NOT clause ②, which is worth stating because three of its four siblings are: it narrows an accept set (a key silently stripped today becomes refused by name) and adds a never member, which is the retirement-tombstone shape — the same grading ComboboxSchema.defaultValue got on PR fix(combobox): honour description, retire defaultValue, pin the name delivery #8324, which carried no needs:contract-review. ⇒ ⭐ Once fix(types): give seven recursion-breaking zod mirrors their declaration as both type arguments #8354 lands, this one can go through the ordinary merge queue and does not join the parked pile.
• ⛔ Declaration and refusal in ONE PR. The card's own last line, endorsed verbatim by triage: "do not re-add the read without the declaration: that is exactly the shape contract: should AppAction.items be re-typed to the overlay MenuItem? — the runner reads two overlay fields through as any today #6854 removed." Here the equivalent is: ⛔ never land the mirror refusal without the TS never, or vice versa.
• ⛔ No read is re-added in LayoutRenderer, and contract: should AppAction.items be re-typed to the overlay MenuItem? — the runner reads two overlay fields through as any today #6854's pin (LayoutRenderer.appActionItems-6854.test.tsx:116, "never puts an authored shortcut into the DOM") stays as is — the ruling says so explicitly. ⚠️ That pin's :30 note says it is "NOT a ruling that shortcut must stay unrendered for ever"; batch Add cloud storage functionality with Vercel KV integration in studio #70 is now that ruling, so the note is owed an update pointing here.
• ⚠️ Two comments in the tree point at this card by name — LayoutRenderer.tsx:312 and the pin's :30. Both should end up pointing at the batch Add cloud storage functionality with Vercel KV integration in studio #70 ruling instead of at an open question.

---

Generated by Claude Code