`normalizeListViewSchema` manufactures `userActions.group` / `hideFields` / `rowColor` — three keys `ListViewSchema` refuses BY NAME, so the fold's own output fails the view save gate

[os-support-ai]

Filed unassigned as an out-of-scope finding while implementing #5398 (the plugin-list half of the userActions collision, PR #5434). Not fixed there — different defect class, different packages.

The defect

Three of the toolbar toggles ListView honours are unauthorable through the spec, and the runtime fold produces them anyway.

packages/core/src/utils/normalize-list-view.ts folds legacy bare show* flags into the canonical userActions block through SHOW_FLAG_TO_USER_ACTION:

showSearch: 'search', showSort: 'sort', showFilters: 'filter',
showDensity: 'rowHeight',
showGroup: 'group', showHideFields: 'hideFields', showColor: 'rowColor',

The first four land on keys the spec declares. The last three do not exist in UserActionsConfigSchema, whose vocabulary is sort, search, filter, refresh, rowHeight, addRecordForm, editInline, buttons.

packages/plugin-list/src/ListView.tsx (toolbarFlags) reads all three regardless:

showGroup: ua?.group !== false,
showHideFields: ua?.hideFields === true,
showColor: ua?.rowColor === true,

Measured — @objectstack/spec@17.0.0, on this repo's main

Each fixture is otherwise legal and produces exactly one issue, so this is a KEY verdict, not a malformed document:

probe	result
ListViewSchema.safeParse(… userActions:{group:true})	success: false, unrecognized_keys: ["group"], 1 issue
ListViewSchema.safeParse(… userActions:{hideFields:true})	success: false, unrecognized_keys: ["hideFields"], 1 issue
ListViewSchema.safeParse(… userActions:{rowColor:true})	success: false, unrecognized_keys: ["rowColor"], 1 issue
ListViewSchema.safeParse(… userActions:{sort:true}) — control	success: true
UserActionsConfigSchema.safeParse({group:true})	success: false, unrecognized_keys: ["group"] (same for the other two)

The control is what makes the three refusals mean "this key", not "this schema refuses everything".

Why it matters

The two halves point opposite ways, and each direction is its own problem:

1. The fold emits a document its own save gate refuses. A stored legacy view carrying showGroup: false comes out of normalizeListViewSchema as userActions: { group: false } — which ListViewSchema rejects by name. Anything that normalizes then validates (or normalizes then persists through a validating path) hits a refusal on a key the runtime itself just wrote. app-shell's ObjectView runs exactly this fold on both halves of every list view it renders.
2. Three real toolbar affordances have no authorable spelling. Grouping, column visibility and row coloring are honoured by ListView and cannot be declared in a spec-valid view document at all — the only way to reach them is the legacy show* flags, which the fold exists to retire.

Both readings converge on a coordination question rather than a local patch: either the spec's UserActionsConfigSchema gains the three keys (the fold and the renderer are then declared = enforced), or the three toggles are retired from the fold and the renderer under ADR-0049 enforce-or-remove. That is a maintainer decision, not a dev one — hence no pm:queue and no assignee.

Reproduce

node --input-type=module -e "
import { ListViewSchema, UserActionsConfigSchema } from '@objectstack/spec/ui';
const uk = r => (r.error?.issues ?? []).filter(i => i.code === 'unrecognized_keys').flatMap(i => i.keys ?? []);
for (const k of ['group','hideFields','rowColor']) {
 const r = ListViewSchema.safeParse({ name:'my_view', label:'My View', columns:[{field:'name'}], userActions:{ [k]: true } });
 console.log(k, r.success, uk(r), (r.error?.issues??[]).length);
}
console.log('control sort', ListViewSchema.safeParse({ name:'my_view', label:'My View', columns:[{field:'name'}], userActions:{ sort:true } }).success);
"

Related: #5398 / #5434 (the userActions view/object name collision — a different defect on the same key), #5240 / #5426 (the plugin-grid half), #2231 (@object-ui/types zod vs @objectstack/spec/ui ListViewSchema drift — an adjacent pair, not this one), #4337 (the legacy list-view vocabulary the fold accepts has no declared type).

---

Generated by Claude Code

[os-zhuang]

Triage: needs-user-decision(契约形状之争 —— 两个方向都动 @objectstack/spec 公开面,人工地板),type Bug。决策分析(中文,按标准块):

一句话问题:列表视图工具栏的三个真实能力(分组 / 列显隐 / 行着色)在规范里写不出来,而运行时的兼容折叠还会自己造出这三个被规范点名拒收的键 —— 折叠的输出过不了它自己的保存门。

选项 × 真实代价:

选项	做什么	客户可感知代价
A	规范收编:UserActionsConfigSchema 增加 group / hideFields / rowColor 三键(declared = enforced)	公开契约 +3 键的永久维护义务;换来作者(含 AI)能声明三个今天已真实存在的开关
B	退役:折叠不再产出三键,渲染器摘除三个开关(ADR-0049 enforce-or-remove)	三个真实工具栏能力从产品消失;存量用旧 show* 标志的视图行为可感知变化(分组按钮不见了)
C	折叠止血:只产出规范认可的键,丢弃三个 legacy 标志并告警;渲染器保留对旧 show* 的直读	两套拼写继续共存 —— 恰是折叠存在要退役的状态,永久延续

业务直译:A = 把已经卖给用户的功能补进说明书;B = 把说明书之外的功能下架;C = 说明书和实际各说各话再拖一版。

长远:A 收敛「声明即强制」;B 收敛面但以砍活能力为代价;C 延续双拼写,是三者中最差的长期形态。
业务:分组/列显隐/行着色是列表产品的常规预期能力,今天用户经 legacy 标志真实可用 —— 只是无法用规范拼写声明;砍掉(B)是用户可感知的倒退。
防AI错:现状最危险 —— 运行时自己产出会被保存门按名拒收的文档(实测三键各 1 issue,control 键通过);A 后 declared=enforced 闭合;B 则需全仓清扫防 AI 从旧例复制。
创业:+3 键是小扩面,但对应已实现、渲染器已尊重的真实能力,不是投机声明面;B 是净删除但删的是活功能。

推荐:A;回退 B。置信缺口(本分析看不见什么):存量 app/模板里 show* 三标志的真实使用量未测;Studio 视图设计器是否已为这三个开关提供授权 UI 未测 —— 若两者皆零,B 的代价大幅缩小。
回一个字母即可;「A,但只收 group」= 按键裁剪的 A。

裁后执行(你不用管):A ⇒ objectstack spec 车道立契约卡(条款②,契约复审档),objectui 折叠/渲染测试随 pin 对齐;B ⇒ objectui 退役卡 + legacy 清扫;C 不建议,不派。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded (2026-08-22, decision-inbox digest with the skills seat, session_01ApyDuQY2fkunMCqXiqvBhR)

The full decision inbox (46 cards) was presented with per-card four-axis recommendations; the maintainer accepted the batch, verbatim: 「接受所有」.

Ruled: Option A — the spec adopts the three keys. UserActionsConfigSchema gains group, hideFields, and rowColor, so the three toolbar affordances ListView already honours become authorable in a spec-valid document and the fold's output passes the save gate (declared = enforced closes). Per the triage execution note, this routes as an objectstack spec-lane contract card (clause ②, contract-review tier), with objectui's fold/renderer tests aligning on the pin. Option B (retiring three live product capabilities) and Option C (permanent double-spelling) are not taken.

State: needs-user-decision removed → pm:queue (ready for dispatch).

---

Generated by Claude Code