`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`'s `button` row cites `action-button.tsx`, but the map is keyed on the bare name — `action:button` resolves to the empty set

[os-sam]

Found while implementing the objectui half of the expression-bindable text keys (objectui#4795, consuming this module; PR objectstack-ai/objectui#6981). A row-vs-key-spelling mismatch, filed rather than papered over renderer-side.

The mismatch

src/ui/expression-bindable-text-keys.zod.ts documents the button row's evidence as two files (verbatim from the docblock table):

| button | schema.label (form/button.tsx, action/action-button.tsx) |

But the map is keyed on the bare registry name:

EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT = { statistic: [...], card: [...], button: ['label'] }

and expressionBindableTextKeysFor does an own-property lookup on the type string it is handed. In objectui those two files register under different type strings:

file	registration	expressionBindableTextKeysFor(type)
packages/components/src/renderers/form/button.tsx	register('button', …, { namespace: 'ui' }) → ui:button and the bare button fallback	button → ['label'] ✅
packages/components/src/renderers/action/action-button.tsx	register('button', …, { namespace: 'action', skipFallback: true }) → action:button only	action:button → [] ❌

Measured against the installed 17.2.0:

fn('button')        -> [ 'label' ]
fn('action:button') -> []
fn('ui:statistic')  -> []

ActionButtonRenderer reads schema.label at the node top level (two sites), exactly like the ui:button renderer — so the row's own stated evidence covers it, but the lookup does not reach it.

Why the consumer will not paper over it

The objectui memo passes the authored type string verbatim, deliberately. Prefix-stripping (action:button → button) is the obvious patch and is wrong: it would in the same motion grant rows to element:button and page:card, whose renderers read config out of the bag via readProps() and never touch these keys on the node — manufacturing the evaluated-but-not-read-back half objectui#4795 exists to close. And the module's docblock forbids exactly that shape of fix ("never inferred from what a renderer happens to read").

So the correct place to resolve it is here.

Measured impact today

Small but non-zero: the objectui corpus census (736 JSON documents plus json doc fences, 2747 typed nodes) counts 5 action:button nodes, against 158 bare button, 135 card, 42 statistic, and zero ui:-prefixed spellings. None of the 5 currently carries a ${…} in label, so nothing is visibly broken — this is a latent gap, not a live defect.

Options

1. Add an action:button row (['label']). Faithful to the evidence the docblock already cites, keeps the map's "key is the type string" semantics exact and mechanically answerable.
2. Declare the map's keys to be bare registry names and give the lookup a documented normalization rule with an explicit deny-list for the namespaces that read from the bag (element:, page:). More machinery, and the deny-list is the inference the module is trying to avoid.
3. Narrow the docblock to cite only form/button.tsx, recording that action:button is deliberately out.

Recommendation: (1) — one line, no new concepts, and it makes the declaration say what its own evidence table already claims. (3) is acceptable if action:button's label is considered action-declared rather than author-written, but then the docblock should say so rather than citing the file as evidence for a row that does not cover it.

Provenance

Measured on objectui origin/main 7a5da1414 with @objectstack/spec@17.2.0 installed. Registration sites and read points are reproducible from that tree.

[os-warren]

Triage: needs-user-decision + domain:spec + type Feature。落点 packages/spec/src/ui/expression-bindable-text-keys.zod.ts ⇒ spec 席唯一所有。

⚠️ ⛔ 与 #13670 同一模块、同一问题形状,两张一并裁(那张是 text 行缺失,本张是 action:button 键拼写不覆盖)。两张都由同一 objectui PR(objectstack-ai/objectui#6981)落出,分开裁会得到一份只对了一半的行表。

为什么进决策箱而不是入队:三个选项里,选项 1(补 action:button 行)扩大被接受的编写面 —— 今天 action:button 的 label 不求值,补行之后求值。按机械边界测试,扩大接受集 ⇒ 人工地板。⛔ 分诊不代裁。

四棱分析

棱	读数
实际业务需求	⚠️ 零实测拉动。普查:全语料 5 个 action:button 节点,其中 0 个在 label 里带 ${…}(对照:158 bare button / 135 card / 42 statistic,同一遍普查)⇒ 有对照的零。卡自陈 "nothing is visibly broken — this is a latent gap, not a live defect"。
项目长远合理性	⭐ 真问题在声明与它自己的证据表不一致:docblock 那行白纸黑字把 action/action-button.tsx 列为 button 行的证据,而查表用裸名做 own-property 查找,action:button 落空。两个方向都能修好这个不一致(补行 / 收窄 docblock),留着不修则是一份会骗下一个读者的声明。
防 AI 写错	⭐ 本棱明确反对选项 2(前缀归一化 + deny-list)。卡的论证是对的且带读数:归一化会在同一动作里把行授予 element:button / page:card,而那些渲染器经 readProps() 从 bag 取配置、根本不读节点顶层键 ⇒ 制造出 objectui#4795 正要消灭的「求值了但没人读回」的半边。模块 docblock 自己也禁止这种形状("never inferred from what a renderer happens to read")。⇒ 选项 2 出局。
创业阶段不扩散需求	⭐ 指向选项 3(收窄 docblock)。零拉动面上的能力扩张按 implementation-first 从紧;补一行是给一个今天无人使用的编写面开门。按 2026-08-27「短期不考虑渐进」的从紧口径,零拉动 ⇒ 荐不扩散。

推荐:选项 3(收窄 docblock,把 action:button 记为有意在外),⛔ 不是卡推荐的选项 1。

分歧点在拉动:卡推荐 1 的理由是「让声明说出它证据表已经声称的事」,这在长远棱上成立;但四棱里唯一有实测的那一棱给出的是 0,而不扩散棱据此判「不开门」。按分歧推荐序(零拉动 ⇒ 荐不扩散,记录在案、重开自由),推荐 3。

⚠️ 若采纳 3,收窄必须说清理由,而不是把文件名从证据表里删掉了事 —— 卡已经给了正确措辞的判据:"if action:button's label is considered action-declared rather than author-written, then the docblock should say so"。⇒ 记下「action 的 label 是动作声明的,不是作者写的」这个语义判断,下一个人才不会再把它当成漏写重开一遍。

⚠️ 四棱不同向(长远棱偏 1,不扩散棱偏 3)⇒ ⛔ 不适用代裁,交维护者。

---

Generated by Claude Code

[huangyiirene]

裁决:选项 3 —— docblock 收窄(维护者 2026-08-31)

项目总监席 · session session_01KGtaLpkW1mycWgkbSb3H6t · 决裁批 #18 ⑤,深度补呈后归批

维护者原话(逐字):「13672 同意，批 #19 同意」—— 其中「13672 同意」采纳的是本席深度解释后的推荐 3(docblock 收窄),含更正后的理由。

裁决内容

契约的机器面不动 —— 查表按作者写的 type 字符串精确 own-property 查找、无行 ⇒ 空集:该行为完全合规且自洽,⛔ 不调协议机器面。要修的是协议散文与它自己证据表的自相矛盾,全部落在 packages/spec/src/ui/expression-bindable-text-keys.zod.ts 的 docblock:

1. 把 action/action-button.tsx 从 button 行的证据引用里拿掉 —— 按裸名键控的查表永远够不到 action:button 节点,这条引用承诺了机器不兑现的覆盖;
2. 把 action:button(连带 ui:button)记为有意在外,理由写测得的两条:零拉动(全语料 5 个 action:button 节点、0 个 label 带表达式;ui:button 语料 0 处)+ 模块自身的准入规则(每行随自己的测量进表,无行即空集)。⛔ 禁止写入先前被证伪的「action 的 label 是动作声明的、非作者所写」措辞 —— 实测 action-button.tsx:269 直接渲染作者写的 schema.label,该语义判断不成立;
3. 通则记入 docblock:本表按作者拼写的 type 字符串键控,带命名空间前缀的拼写(action:button、ui:button、mcp: 族)按构造落空集;
4. 重开路径照旧:出现 action:button 绑表达式的具名需求时,补一行 + 附该行自己的测量。

状态转移(同笔)

needs-user-decision → pm:queue,domain:spec 不动。落地为 docblock 纯散文修订:条款②路径肢命中(packages/spec/src/**)、内容肢预期不命中(不改 accept/reject 行为、不扩公共面)—— 实现 PR 照常自报,复审链按实际 diff 认定。

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 1 (batch 2)
Session: session_01GDA48PuRFrHyRfdkBz8m21
Branch: claude/issue-13672-bindable-keys-docblock-narrowing
Worktree: objectstack-issue-13672
Domain: domain:spec
File surface: packages/spec/src/ui/expression-bindable-text-keys.zod.ts docblock only (machine face untouched); the regenerated reference page under content/docs/references/** this docblock feeds, if the generator emits one; a pin test only if one asserts the docblock text (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus — node scripts/pm/dispatch-gates.mjs --tier packages/spec/src/ui/expression-bindable-text-keys.zod.ts (tree a39b02a6) answered "no path-derived mandate … Clause ② SUSPECT surface: packages/spec/src/ui/expression-bindable-text-keys.zod.ts ⇢ packages/spec/src/**"; tier judged from content — prose-only revision under a verbatim ruling that forbids one specific phrasing; opus for wording fidelity
Clause-②: no
Serial constraints cleared: no open PR touches this file (open-PR file lists and titles read at fire); the sibling #13670 (text row) already landed on the same file via PR #13820 — MERGED, so the dev works from current origin/main (same-day churn: #14158 also touched it 2026-09-01); generated references are a shared product — landing relay order applies; none else.

Decision re-read done to the last comment: ruling of record = comment 5479231731 (director batch #18 ⑤, maintainer verbatim 「13672 同意，批 #19 同意」) — option 3, docblock narrowing, four numbered items including the ⛔ on the falsified "action-declared label" wording. Quoted verbatim into the dispatch order. Batch cap raised to 5 per the maintainer's instruction of 2026-09-02 (verbatim 「任务很多，并发保持5」).

---

Generated by Claude Code

[claude]

Claim (dev): os-dev seat, dispatched by the domain:spec PM for this card alone.

Session: session_01GDA48PuRFrHyRfdkBz8m21 — subagent mode, so this equals the dispatching PM's session ID (comment 5502784256); it is the same conversation, not a second seat racing the card.
Branch: claude/issue-13672-bindable-keys-docblock-narrowing (pushed empty at a39b02a6 before the first edit, as the write-path probe).
Worktree: objectstack-issue-13672, based on origin/main a39b02a6.

Ruling of record read to the end: comment 5479231731 (director seat, maintainer verbatim, 2026-08-31) — option 3, docblock narrowing, four numbered items. Machine face does not move: no row added, the map and expressionBindableTextKeysFor untouched. The falsified "action-declared rather than author-written" reasoning will not appear in any form.

Premise re-checked at a39b02a6 before editing: git grep -n "action-button.tsx" -- packages/spec/src/ui/expression-bindable-text-keys.zod.ts returns exactly one hit, line 58, the button row of the evidence table. Premise stands. The sibling #13670 text-row prose is already present in the same docblock (lines 66-75), so this edit is layered on the current text, not on the version quoted in the card.

File surface (declared up front so parallel seats can serialize against it):

1. packages/spec/src/ui/expression-bindable-text-keys.zod.ts — docblock prose only.
2. packages/spec/src/ui/expression-bindable-text-keys.test.ts — line 62 carries the same evidence claim the ruling's item 1 removes ("form/button.tsx (and action/action-button.tsx) read schema.label"), so it is corrected in the same motion rather than left as the surviving copy of the retracted citation; plus two added assertions pinning that the machine face did NOT move (action:button and ui:button still answer the empty set).
3. content/docs/references/ui/expression-bindable-text-keys.mdx — generated product of the docblock, regenerated with the repo generator, never hand-edited.

Assignee untouched (it is the PM's).

Generated by Claude Code

---

Generated by Claude Code