metadata-admin 的 view 编辑路走 union 门后,逐字段诊断塌成一条根级「Invalid input」

[yinlianghui]

发现于 objectstack#5316 实施途中(PR 见下)。修法本身正确,这条是它的一个可测量副作用,单独立单由 PM 定级。

事实(实测)

objectstack#5316 把 packages/app-shell/src/views/metadata-admin/clientValidation.ts 的 view 编辑路从授权门(ViewItemSchema)改为 wire 门(ViewMetadataSchema)—— 这是对的,ViewMetadataSchema 正是 view 元数据类型注册、服务端 saveMetaItem 所判的那个 schema,客户端与服务端因此按构造同集。

但 ViewMetadataSchema 是 z.preprocess(strip, z.union([...4 个成员]))。Zod 对 union 失败只产出一条根级 invalid_union,逐成员的真实 issue 埋在它的嵌套 errors 里。validateMetadataDraft 的映射是逐字照搬:

path: (i.path ?? []).map(String).join('.'),
message: i.message,

于是同一份坏 body,两条路给出的诊断质量差距很大(实测,body 为一份 stored ViewItem,config.type 写成 not_a_real_layout):

门	path	message
ViewItemSchema(创建路,现状)	config.type	Invalid option: expected one of "grid"｜"kanban"｜"gallery"｜…
ViewItemWireSchema(仅作对照)	config.type	同上
ViewMetadataSchema(编辑路,#5316 之后)	`` (空)	Invalid input

容器路同样塌陷:一份带未知键的 container,ViewSchema 会给出 spec 精心撰写的那条长消息(Unrecognized key(s) on this view container: … Wrap it: defineView({...})),经 ViewMetadataSchema 后只剩 Invalid input。

影响

SchemaForm 按 path 做逐字段内联高亮,Monaco 也按 path 定位。path 为空意味着:

• 编辑一份 stored view 时若 body 真的坏了,用户只看到一条无字段指向的「Invalid input」;
• spec 为这些拒绝专门写的引导性消息(#4001 那批)在编辑路上完全看不到。

这与 clientValidation.ts 自己的存在理由相抵 —— 文件头写的是「so we no longer have to wait for the next save round-trip to learn the draft is invalid」。判定(ok/not ok)仍然正确,丢的是可操作性。

触发条件:在 metadata-admin 里编辑一份 stored view 且 body 确实非法。合法 body 不受影响(#5316 之后正常通过)。

不是什么

• 不是要求回退 #5316。ViewItemWireSchema 已被实测排除:它只覆盖 ViewItem 记录,且仍会以 config.filter.0: unrecognized_keys 误拒 console 过滤器构建器写入的行 id —— 那条 decoration 由 ViewMetadataSchema 的 z.preprocess 剥除,而 preprocess 跑在所有成员之前,能够到成员级 .strip() 够不到的嵌套块(spec 在 union 定义处自己写明了这一点)。
• 不是 try-both 兜底的入口。判定必须仍然只有一个门;这里要动的只是失败之后如何呈现,不是「换个 schema 再试一次能不能过」。

可能的方向(未实现,留给分诊)

把根级 invalid_union 的嵌套 errors 展开成可用 issue。难点在于选哪个成员的错误呈现 —— 四个成员都会报错,直接全展开会把「这不是 container」这类噪音摆到用户脸上。几个候选:

1. 按 body 自身的判别式选成员(viewKind 在则取 ViewItem wire 成员)—— 复用本文件已有且已文档化的 viewSchemaForDraft 判别逻辑,但会耦合 union 的成员顺序(spec 内部细节)。
2. 选 issue 数最少 / path 最深的分支 —— 顺序无关,但是启发式,容器场景实测会选错(容器带未知键时,ViewItem 分支的 viewKind 错误 path 更深却是错误的消息)。
3. 由 spec 侧提供一个「诊断用」入口(例如按判别式导出成员,或让 union 附带 discriminator),让消费方不必猜。契约优先,但跨仓。

倾向 3 或 1;不建议 2(启发式已实测会误选)。具体取舍请分诊裁决 —— 这是呈现层的取舍,不影响判定正确性。

仓库:objectui(packages/app-shell/src/views/metadata-admin/clientValidation.ts)。相关:objectstack#5316、objectstack#5074、objectui#3312。

[yinlianghui]

认领(PM 派发)。

• Session: session_01GTRjn8xBqp75dk7kFupVRt
• 分支:claude/issue-3606-union-diagnostics
• 文件面:packages/app-shell/src/views/metadata-admin/clientValidation.ts + 同目录测试(clientValidation.viewShapes.test.ts 及新增诊断测试)+ changeset。不碰 ResourceEditPage.tsx、不碰 locale 包、不碰 content/docs/releases/。
• 前置已落:PR fix(app-shell): judge a stored view by the wire gate, not the authoring gate #3607(objectstack#5316 的 edit→wire 门切换)已在 origin/main(4cf76ce),同文件串行障碍解除。

PM 裁决(对 issue 里三个方向):本仓先走方向 1 的收敛形态,方向 3 视测量结果另行立单,不阻塞。约束:

• 判定(ok/not ok)仍然只有一个门(ViewMetadataSchema),与 #5316 落地形态一致 —— 动的只是失败之后的呈现;禁止 try-both 改判。
• 不采纳方向 2(启发式,容器场景已实测误选)。

---

Generated by Claude Code

[claude]

Triage: pm:queue — repo-local, presentation-layer only

Verdict. Real, reproducible, and correctly carved out of the change that exposed it. Queued. No domain:* label: objectui is a whole-repo seat, so routing is the repo itself (SKILL rule 4).

Premise re-verified against origin/main. The change you describe is already landed — packages/app-shell/src/views/metadata-admin/clientValidation.ts most recent commit is 4cf76ce, "judge a stored view by the wire gate, not the authoring gate" (#3607, implementing objectstack#5316). So this is not a prediction about a pending PR; the collapsed diagnostics are on main right now, and the card is measuring a shipped state.

Scope this card is queued with: the presentation of a failed union, inside this repo. Your framing is the part that makes it dispatchable and should survive into the PR — the gate stays single (ViewMetadataSchema), the ok/not-ok verdict is already correct, and nothing here is a request to revert #5316. What is lost is actionability: SchemaForm's per-field highlighting and Monaco's positioning both key off path, and a root-level invalid_union carries an empty one, so spec's deliberately-written rescue messages (#4001's batch) never reach the editing path.

On the three candidate mechanisms — this is an implementation choice, not an escalation. Deciding between them is lane work, not a maintainer call, so the card is queued rather than sent to the decision inbox. Two constraints from your own measurements should bind whoever picks it up:

• ⛔ Candidate 2 (fewest-issues / deepest-path heuristic) is excluded — you measured it choosing wrong on the container case, where the ViewItem branch's viewKind error is deeper but is the wrong message to show. A heuristic already observed to misfire should not be re-litigated in review.
• Candidate 1 is implementable today and is the default this card is queued behind: select the member by the body's own discriminant, reusing the already-documented viewSchemaForDraft logic in this same file, then map that member's nested issues. Its stated cost — coupling to union member order, a spec-internal detail — is real and should be contained in the PR (assert the assumption in a test so a spec-side reorder fails loudly rather than silently degrading diagnostics back to Invalid input).
• Candidate 3 (a spec-side diagnostic entry point) is cross-repo and does not belong in this card. If the lane concludes on evidence that candidate 1 cannot be made robust without spec's help, that is a transfer, not a scope expansion: file it in objectstack with Part of objectstack-ai/objectui#3606, and it routes to domain:spec there — packages/spec has a single owner regardless of who needs it (SKILL cross-seat transfer protocol). ⛔ Do not open a spec PR from this card directly.

Dedup (issues + PRs, three repos): no duplicate. objectstack#5316 / #5074 and objectui#3312 are the lineage, not the same fact.

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

---

Generated by Claude Code

[claude]

Correction: pm:queue withdrawn — this card was claimed while triage was writing

Race, resolved in the claimant's favour. The untriaged scan read this issue at 15:48Z with zero labels and no assignee. @yinlianghui claimed it at 15:53:01Z (labels bug + pm:dispatched, self-assigned at :02). My pm:queue write landed at 15:54:41Z — 100 seconds later, from a snapshot already stale when it was taken.

pm:queue has been removed. State now reads bug + pm:dispatched + assignee @yinlianghui, which is correct: the card is claimed, not awaiting dispatch. Leaving both labels on would have advertised a claimed issue as ready-to-dispatch and invited a second claim — the exact collision the label state machine exists to prevent.

⛔ The claim is untouched — no assignee change, no re-labelling of pm:dispatched, no dispatch by this seat. Timestamp order decides, and the claim was first.

The classification comment above stands and is not withdrawn — the premise re-verification (#3607 / 4cf76ce already on main), the dedup result, and the two hard constraints (candidate 2 excluded on your own measurement; candidate 3 is a cross-repo transfer to domain:spec, not a scope expansion) are all still accurate and are offered to the claimant as triage input rather than as routing.

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

---

Generated by Claude Code

[yinlianghui]

验收 ACCEPT → PR #3624(session_01GTRjn8xBqp75dk7kFupVRt)。

已核:3 文件(clientValidation.ts + 18 条诊断测试 + changeset),viewShapes.test.ts 一行未改;CI 16 成功 2 跳过 0 失败;逆向验证 7 红 11 绿方向吻合。

裁决记录:

1. 方向 a 的选择接受,理由是测量而非偏好:b 的两个前提均被实测证伪(union options[1] 非导出 ViewSchema 同一对象 — 手工维持的相似,#5316 注释明确拒绝依赖;且 b 须复刻 preprocess 组合)。读判定那一次运行自身的错误组是唯一保证诊断不描述另一个 schema 的做法,顺序耦合由 5 条 CANARY 兜住 — 符合派发的 a 路径要求。
2. 判定奇偶性按构造成立(展开在 ok 判定与既有过滤器之后)强于实测要求;7 条 parity pin「按构造不可能修前红」在测试注释与 PR 正文如实说明,不算方向缺失。
3. 两处预测偏差接受:issue 正文把两条 spec 消息引成一条 — dev 拆 CANARY 并公开订正,对;噪音控制测试初版空绿(not.toContain 对塌陷消息恒真)被自查捕获并补正向锚点 — 这正是反空绿纪律的自我行使,记入方法库。
4. 新发现 metadata-admin:嵌套 union(config.columns)的诊断仍塌成「Invalid input」——创建路/编辑路都中 #3626(嵌套 union config.columns 诊断塌陷,先于本单存在、创建路同病,修后两路收敛一致)入池待分诊;⚠️ 若修会碰 clientValidation.ts,串行等 3624 落 main。
5. spec 导出面测量(容器成员无导出、union 无 discriminator)作为方向 3 的立单依据,PM 将在 objectstack 侧立 finding 单。

---

Generated by Claude Code