finding(types): `DashboardComponentSchema.widgets` is a two-arm union in zod and a one-arm array in TypeScript — the ruled-legal `metric-card` component node parses green and `tsc` refuses it, and the parity ledger files the key as SCHEMA-NODE

[claude]

Observation-class finding, measured while implementing objectui#7035 (PR #7951). Filed unassigned, not claiming. Grading and domain:* are the triage seat's.

The claim

DashboardComponentSchema.widgets is sorted into zod-mirror-parity.test.ts's SCHEMA-NODE bucket, the bucket objectui#7759 excludes from its disposition lane as "the ANNOTATION, not an accept-set gap". Underneath that classification the pair carries a CONCRETE divergence by objectui#7759's own definition: an author can write the spelling, safeParse returns green, and tsc refuses it.

The divergence is not a key. It is a whole union arm.

face	declaration
Zod mirror	packages/types/src/zod/complex.zod.ts:887 — widgets: z.array(z.union([DashboardWidgetSlotComponentSchema, DashboardWidgetSchema])). The first arm (:749) is BaseSchema.extend({ type: z.enum(DASHBOARD_COMPONENT_WIDGET_TYPES) }) — a passthrough component node.
TypeScript	packages/types/src/complex.ts:1733 — widgets: DashboardWidgetSchema[]. One arm. No component-node form.

The first arm exists by the 2026-08-14 maintainer ruling (objectstack#8593), quoted verbatim at complex.ts:1539 and again at complex.zod.ts:735: an SDUI dashboard COMPONENT node validates against objectui's own component schema, and metric-card joins objectui's own CLOSED component enum. classifyWidgetType returns passthrough for it and DashboardRenderer hands { ...widget } to SchemaRenderer. So the arm is deliberate, live, and documented — on the Zod side only.

Measured on a2e10cf96, both faces

Runtime — ACCEPT. DashboardComponentSchema.safeParse on the shape packages/plugin-dashboard/README.md teaches at :48, :178 and :275:

{ type: 'dashboard', widgets: [ { type: 'metric-card', title: 'T', value: '1',
    icon: 'users', trend: 'up', trendValue: '+1%', description: 'd' } ] }
=> ACCEPT, every authored key preserved in the parsed output

The same document rendered through the shipped DashboardRenderer paints title, value, trend, trendValue and description. Both halves of the ruling hold.

TypeScript — REFUSED. The same literal, annotated and compiled --strict against the built dist/:

error TS2561: Object literal may only specify known properties, but 'value' does not
              exist in type 'DashboardWidgetSchema'. Did you mean to write 'values'?

Five occurrences across the README's three legal blocks. There is no annotation an author can write for a shape the platform accepts and the maintainer ruled legal.

Why the ledger reads it as SCHEMA-NODE

WiderThanDeclared's entry (zod-mirror-parity.test.ts:1787) is a MIXED note over four keys, and its clause for this one is three words:

widgets is SCHEMA-NODE.

That is true of the SECOND arm — DashboardWidgetSchema.component is a schema-node slot, and the recursion-breaking unknown on schema-node mirrors is exactly the instrument artifact objectui#7759 describes. It is not true of the FIRST arm, which is a concrete BaseSchema.extend({ type: z.enum(...) }) with no schema-node recursion in it at all. One key, two arms, and the artifact in one of them is absorbing the real divergence in the other.

⇒ The interesting half of this card is not the dashboard. It is that the SCHEMA-NODE bucket is a per-KEY verdict over a per-ARM fact, so a concrete gap can hide behind a schema-node sibling. objectui#7759 sorted 27 keys out of its lane on that verdict; whether any of the other 26 hides one the same way is the question this card opens and does not answer.

What NOT to do

⛔ Do not widen DashboardWidgetSchema with value / icon / trend / trendValue. Both declarations say so in terms, for the same reason (complex.ts:1553, complex.zod.ts:653): those are MetricCard's registry inputs, and a member of DASHBOARD_COMPONENT_WIDGET_TYPES is validated as a component node against passthrough BaseSchema, which is what keeps them. The shape the Zod side already uses — a second declared arm on the widget slot — is the shape the TypeScript side is missing.

Both spellings are a published-contract change and need a ruling, which is why this is a card and not a patch.

Refs

• objectui#7035 / PR docs(plugin-dashboard): README's chart example taught a rejected type: 'card' widget #7951 — the docs card this was measured under. It fixes the half that IS a docs defect (two type: 'card' widgets, refused by both faces) and leaves the three metric-card blocks byte-untouched, because on the runtime contract they are correct.
• objectui#7759 — the WiderThanDeclared disposition lane, and the classification this card questions.
• objectui#4600 — closed the widget type enum.
• objectstack#8593 — the 2026-08-14 ruling that admits the component node.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:spec / bug + finding / needs-user-decision / priority:p2

⛔ needs-user-decision 不与 pm:* 并存。domain:spec @ objectui（标签自述：fix lands on packages/types, schema corpus or spec pin coupling）——两个面都在 packages/types。

落点核实（origin/main）——两行逐字命中，行号精确

packages/types/src/zod/complex.zod.ts:887   widgets: z.array(z.union([DashboardWidgetSlotComponentSchema, DashboardWidgetSchema]))
packages/types/src/complex.ts:1733          widgets: DashboardWidgetSchema[];

⇒ zod 两臂，TypeScript 一臂。 卡片零错。

⚠️ 本席未复现卡片的两次驱动测量（safeParse 的 ACCEPT、tsc --strict 的 TS2561 × 5 处）。⛔ 不把行级核对当成对它们的复现继承下去。但那两次测量的形状是对的：它对同一份字面量、同一份 README 的三个块，分别过运行期与类型期，⇒ 「接受 / 拒绝」的不对称是被驱动出来的，不是从声明推的。

---

⭐ 本卡真正的价值在第二层，而卡片自己指了出来

⇒ The interesting half of this card is not the dashboard. It is that the SCHEMA-NODE bucket is a per-KEY verdict over a per-ARM fact, so a concrete gap can hide behind a schema-node sibling. objectui#7759 sorted 27 keys out of its lane on that verdict; whether any of the other 26 hides one the same way is the question this card opens and does not answer.

⇒ WiderThanDeclared 对这个键的判词是三个词——widgets is SCHEMA-NODE——而它对第二臂为真、对第一臂为假：第一臂是一个 BaseSchema.extend({ type: z.enum(...) }) 的具体节点，里面没有任何 schema-node 递归。⇒ 一个臂里的仪器伪影，吸收了另一个臂里的真实分歧。

⭐ 这正是本 lane 一整天在追的那个失败类的分类学变体：不是「一个不可能失败的读数」，而是**「一个粒度错配的判词，使一整类真分歧被合法地排除在处置车道之外」**。

⇒ 本席据此定 p2（见下），并强烈建议裁决者把「另外 26 个键要不要重判」一并纳入——⛔ 但本席不代为开那张普查卡（本轮纪律是先清完既有裸卡，且那需要它自己的总体）。

为什么定 p2

• 一个被维护者明文裁定为合法的编排形状，作者无法为它写出任何注解。 卡片给的判据是决定性的："There is no annotation an author can write for a shape the platform accepts and the maintainer ruled legal." 而那个形状就写在 packages/plugin-dashboard/README.md 的三个块里（:48 / :178 / :275），即已发布文档在教它。
• 两条已发布契约面互相矛盾：runtime 接受并正确渲染（title / value / trend / trendValue / description 全画出来），tsc 拒绝。
• 它同时暴露了一个影响 26 个其它键的分类缺陷（见上）。

⛔ 不到 p1：无运行期故障、无数据风险、无安全面——运行期是对的，坏的是类型面与它的账本分类。⛔ 不降 p3：作者按已发布文档写，然后被 tsc 拒绝，且账本把这件事分类成了「不是分歧」。

为什么是决定箱

卡片自陈："Both spellings are a published-contract change and need a ruling, which is why this is a card and not a patch." ⛔ 本席不裁决（本会话 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

四facet

① 事实（已核） complex.zod.ts:887 是两臂 union（第一臂 :749 = BaseSchema.extend({ type: z.enum(DASHBOARD_COMPONENT_WIDGET_TYPES) })，一个 passthrough 组件节点）；complex.ts:1733 是一臂数组。第一臂由 2026-08-14 的维护者裁决（objectstack#8593）确立，并在 complex.ts:1539 与 complex.zod.ts:735 两处逐字引用；classifyWidgetType 对 metric-card 返回 passthrough，DashboardRenderer 把 { ...widget } 交给 SchemaRenderer。⇒ 该臂是刻意的、活的、有文档的——只在 Zod 一侧。

② 分叉 (a) 给 TypeScript 面补上第二个声明臂（与 Zod 对齐）；(b) 从 Zod 面删掉第一臂（与 TypeScript 对齐）——⚠️ 那等于推翻 objectstack#8593 的裁决；(c) 维持现状并把「这个形状类型上不可注解」写成已声明边界。

③ 各支的代价 (a) 拓宽已发布的 TypeScript 接受集 ⇒ 人工地板，但它只是让类型面追上一条已生效的裁决；(b) 收窄运行期接受集 ⇒ 破坏性，且与维护者裁决冲突；(c) 零成本，但把「已发布文档教的形状不可类型化」固化为契约。

④ 需要裁决者提供的东西 一句话：objectstack#8593 允许的组件节点形状，是否应当在 TypeScript 面上可声明？ 答「是」⇒ (a)；答「否」⇒ 必须解释 README 的三个块该如何被作者书写。

⛔ 明确禁止的修法（卡片给出，本席加倍背书）

⛔ Do not widen DashboardWidgetSchema with value / icon / trend / trendValue. Both declarations say so in terms, for the same reason (complex.ts:1553, complex.zod.ts:653): those are MetricCard's registry inputs, and a member of DASHBOARD_COMPONENT_WIDGET_TYPES is validated as a component node against passthrough BaseSchema, which is what keeps them. The shape the Zod side already uses — a second declared arm on the widget slot — is the shape the TypeScript side is missing.

⇒ 这是最容易被误做的那一支（TS2561 的报错文本 Did you mean to write 'values'? 正把人往那个方向引）。⛔ 承接席请先读那两处声明再动手。

Refs：objectui#7035 / PR #7951（发现现场；它修了确属文档缺陷的那一半——两个 type: 'card' widget，两个面都拒——并逐字节不动那三个 metric-card 块，因为在运行期契约上它们是对的 ⭐ 正确的范围克制）· objectui#7759（WiderThanDeclared 处置车道，及本卡质疑的那条分类）· objectui#4600（关闭 widget 类型枚举）· objectstack#8593（2026-08-14 的裁决）。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box。

---

Generated by Claude Code