One intent, two spellings: `visible` (actions) vs `visibleWhen` (fields / sections / userActions) — and the alias guard only covers one direction

[baozhoutao]

Summary

One intent — "show this thing only when the predicate holds" — is spelled two different ways depending on which schema you are authoring, and the guard that catches the wrong spelling only runs in one direction.

• Actions (and action params) declare it as visible / disabled — ActionSchema (ui/action.zod.ts:1131), ActionParamSchema (L383).
• Everything else declares it as visibleWhen / disabledWhen — fields (data/field.zod.ts:814), form sections (ui/view.zod.ts:1757, L1858), page components (ui/page.zod.ts:150), per-option predicates (field.zod.ts:176), and the built-in row CRUD overrides userActions.edit/delete (data/object.zod.ts:1079).

The action schemas already recognise the other spelling and rename it: actionObject() registers visibleWhen → visible, showWhen → visible, disabledWhen → disabled (action.zod.ts:776), and ACTION_PARAM_KEY_ALIASES maps visiblewhen/visibleon/visibility → visible (L74). The comment there states the motive exactly:

ADR-0089 made visibleWhen the canonical predicate on view/page schemas. An author who learned it there would silently lose a param's capability gate here.

The reverse alias does not exist. An author who learns visible on an action and writes it on a field or on userActions.delete gets a bare unknown-key error that never names the key they should have used.

Measured (spec dist on main, ObjectSchema.create)

ACCEPTED  field.visibleWhen                          (canonical)
REJECTED  field.visible
          Unrecognized key(s) on this field: `visible`. Until #4001 closed this shape
          these were dropped silently — …
REJECTED  userActions.delete.visible
          Unrecognized key: "visible"
REJECTED  userActions.delete.disabled
          Unrecognized key: "disabled"

Neither message mentions visibleWhen / disabledWhen. RowCrudActionOverrideSchema is a plain z.object({…}).strict() — it has no aliases / guidance map at all, so it cannot say anything beyond zod's default.

The arms accepted also differ, which matters for any unification:

surface	key	false literal	CEL string	{dialect, source}
action / action param	visible	✅ (#5970)	✅	✅
field / section / component / userActions.*	visibleWhen	❌	✅	✅

On userActions.edit/delete the boolean lives on a sibling key (enabled: false), so the same "settled at authoring time" case is spelled differently again.

Why raise it

The asymmetry argument the repo already accepts, applied to itself. From action.zod.ts (#5970, on visible vs disabled before they were unified):

An asymmetry between two keys that mean the same kind of thing is a dialect nursery: it teaches each consumer to keep its own widening … and every one of those is a second de-facto contract (Prime Directive #12).

Two spellings for one intent across neighbouring schemas is the same nursery one level up. Today it costs authors a failed parse and a search; the aliases already carry the admission that authors DO move between these surfaces.

Asks (in order of cost)

1. Symmetry, no behaviour change — give RowCrudActionOverrideSchema (and the field / section / component shapes) the same aliases treatment the action shapes have: visible → visibleWhen, showWhen → visibleWhen, disabled → disabledWhen. Purely a better error; nothing that parses today changes. Note the boolean case on userActions.* should point at enabled, not at visibleWhen, or the hint will just move the confusion.
2. A platform decision on ONE canonical, recorded rather than left implicit. visibleWhen is the majority surface and already ADR-0089's canonical, so converging there (with visible demoted to a registered alias on the action shapes) is the smaller move — but it needs a call on:
   • the boolean arm: ExpressionInputSchema has none, and visible: false is common enough that spec: ActionSchema 的 visible / disabled 统一为 boolean | string(CEL) | {dialect,source}（#4075 step 3 前置，维护者 2026-08-06 已裁决） #5970 added it deliberately. Converging means either widening the target schema or telling authors to switch key;
   • already-published metadata written with visible, and whatever the retirement process (ADR-0087) requires;
   • whether ADR-0089's scope was ever meant to reach the action shapes at all.

Item 1 stands on its own even if item 2 lands as "keep both" — right now the guard protects one direction of a two-way street.

[os-zhuang]

Triage: split, then needs-user-decision + domain:spec for what remains.

Split: ask 1 (alias/guidance symmetry — no behaviour change) is now #7832, queued domain:spec-surface. Verified before splitting that strictObject's aliases table is error-message curation only (packages/spec/src/shared/strict-object.ts — "semantic near-misses edit distance cannot reach"), so ask 1 is byte-identical on acceptance and does not need this card's ruling. This card keeps ask 2: one canonical spelling for the visibility predicate, or deliberately keep both — a public-contract call (domain:spec because any convergence changes acceptance).

Four-lens block (filing requirement):
① Platform long-term coherence — converging on visibleWhen (ADR-0089's canonical) shrinks a two-dialect surface to one; "keep both + aliases" freezes the dialect but stops its growth; status quo grows it (each new schema re-chooses a spelling).
② Measured business pull — authors demonstrably cross surfaces: the action side registered visibleWhen → visible precisely because borrowed spellings arrived (#5970's admission); #7816's measurements show the reverse borrowings die as bare unknown-key errors today.
③ AI-agent error-resistance — one canonical + loud renaming guidance is the hardest to misuse; two spellings with one-directional guidance is the current trap (an AI author trained on the majority surface writes visibleWhen everywhere and only the action shapes rescue it).
④ Startup scope discipline — full convergence costs an ADR-0087 retirement of visible (published metadata exists) plus a boolean-arm decision (ExpressionInputSchema has no false literal); #7832 delivers most of the author-facing value at ~zero contract cost, so the wider move can be deferred without bleeding.

Concrete question for the maintainer: converge on visibleWhen (with visible demoted to a registered alias on action shapes, boolean arm resolved), or record "both are canonical on their own surfaces" and close after #7832? Recommendation from triage: the latter is the cheaper stable state; convergence is only worth it bundled with an ADR-0089 scope clarification.

Dedup: no other open card owns the spelling question; #7832 owns the guidance half; #7456 (objectName inert on embedded actions) is adjacent strictness work, not this.

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

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling — 2026-08-12

裁定:Ask 1 现在做;Ask 2 只记方向,v18 再收敛。

要点:

• Ask 1(批准,进队列):给 RowCrudActionOverrideSchema 及 field / section / component 形状补上与 action 形状对称的 aliases:visible → visibleWhen、showWhen → visibleWhen、disabled → disabledWhen;userActions.* 上的布尔情形按卡内提醒指向 enabled,别把困惑挪个地方。纯报错改善,今天能 parse 的一切不变。
• Ask 2(方向裁定,不动工):canonical 是 visibleWhen(多数面 + ADR-0089 已然方向)。⛔ v17 不做发布面收敛、不动已发布 metadata、不走 ADR-0087 退役 —— 留给 v18 评估。自本裁定起,新 surface 不得再引入 visible 拼法。
• 布尔 arm(visible: false)的去留属于 Ask 2 的 v18 评估范围,现在不裁。

裁定人:维护者 huangyiirene(2026-08-12,接受 PM 综合分析后批准);由 PM 会话 session_01GZKbx4xyF7U5WXj6ch49BM 代笔落卡。转 pm:queue(范围 = Ask 1)。

---

Generated by Claude Code

[hotlong]

Blocked-by: #7887

Finding-grading round: moved pm:queue → pm:blocked. This card's ask 1 requests alias rows (disabled → disabledWhen) on the section/component shapes — but whether those shapes should carry that vocabulary at all is exactly the boundary-vs-gap question now escalated on #7887. Dispatching before that ruling risks building the rejected half. Unblock condition (also recorded on #7887): when #7887 is ruled, return this card to pm:queue — if "boundary", ask 1 narrows to guidance text + the field-arm correction (field.zod.ts:464: fields take readonlyWhen, so the alias target here is wrong for fields too); if "gap", ask 1 proceeds as written.

---

Generated by Claude Code