8 zod-mirror drifts need a per-key ruling — renderer readings attached (groups B and C of #5927)

[yinlianghui]

Filed by the execution seat that landed #5927 group A (PR #6032, session session_01CSoz9uGhaaSgiq3hshtN7L, branch claude/issue-5927-zod-mirror-group-a-widenings). Unassigned and unlabelled on purpose — triage grades it.

Under the maintainer ruling recorded on #5927 (2026-08-24, verbatim 「四维分析一致的，接手你的建议。」), group A was executed by renderer measurement and groups B (disjoint vocabularies) and C (required-vs-optional) come back to the decision inbox with the renderer reading attached, not batch-edited. This card carries all eight readings. ⛔ Nothing here was edited.

Dedupe: searched the repo-scoped open-issue listing for these mirror/key names; the only prior art is #5927 itself (which carries the framework, not the per-key rulings) and #5853 (the opposite direction — mirror wider than the declaration — which is currently back at needs-user-decision and is not covered here).

Re-measured on origin/main d2fb6efb4 with #5684's derived construction over all 163 registered pairs, not read off #5927's table. All eight rows below are live drift today; the six remaining KnownDrift rows that are not listed here are group D (rides #2231) and group E (PageNodeSchema.pageType, sanctioned divergence).

The method, and the counter-probe that makes a null reading trustworthy

"The renderer implements it" is a claim about running code. For each key the read site was searched in the renderer that actually consumes that schema. Wherever the reading below is "no read site", the same search is shown finding sibling keys on the same surface that the renderer does read — a mis-anchored search looks exactly like a dead spelling, and this is what separates the two.

Group B — disjoint vocabularies

B1. form.zod.ts#FormSchema.mode — TS disabled | read | edit vs mirror create | edit | view

Reading: neither vocabulary has a read site on this surface. The ui:form renderer (packages/components/src/renderers/form/form.tsx) destructures 16 keys from schema at :975-1002 — defaultValues, previousValues, fields, submitLabel, cancelLabel, showCancel, showSubmit, layout, columns, the four handlers, resetOnSubmit, validationMode, disabled — and mode is not among them. grep 'schema\.mode' over the whole file returns 0.

Counter-probe: the same grep pattern finds a real mode read site elsewhere — plugin-form/src/DrawerForm.tsx:257,367,391,399,492,494 reads schema.mode === 'create' / 'edit' / 'view'. But that is DrawerForm's own schema, a different type; it is not FormSchema. So the search can find such a site when one exists, and finds none for FormSchema.mode.

Implication for the ruling: this may not be "pick the live side" at all — both vocabularies may be inert here, which would make it an ADR-0049 candidate on both sides rather than a widen/narrow choice. The create|edit|view spelling looks like it was copied from DrawerForm's surface.

B2. navigation.zod.ts#HeaderBarSchema.variant — TS default | bordered | floating vs mirror default | bordered | transparent

Reading: no read site for either vocabulary. packages/components/src/renderers/navigation/header-bar.tsx never mentions variant; grep -n variant over the file returns nothing.

Counter-probe, same method on the same file: grep -o 'schema\.[a-zA-Z]*' finds schema.crumbs (:68), schema.search (:80), schema.actions (:95), schema.rightContent (:98). The renderer reads four of HeaderBarSchema's keys and none of them is variant.

Implication: as with B1, this reads as dead-on-both-sides rather than a two-way choice.

B3. complex.zod.ts#FilterFieldSchema.operators — TS carries is_empty / is_not_empty, mirror carries is_null / is_not_null

Reading: both spellings are live in the codebase, but at different layers, and neither is read through this schema.

• is_empty / is_not_empty are the authoring/UI spelling: plugin-view/src/config/view-config-utils.ts:70-71 maps them to isEmpty / isNotEmpty; app-shell/src/views/metadata-admin/widgets.tsx:2056 does the same.
• is_null / is_not_null are the query-AST spelling: core/src/query/query-ast.ts:149,177, core/src/utils/filter-converter.ts:141,145, permissions/src/evaluator.ts:154.
• core/src/utils/filter-converter.ts:222 documents them as siblings ("is_empty / is_null, whose direction comes from the operator NAME"), and app-shell/src/views/viewFilterFold.ts:88 lists all four together.
• But the ui:filter-builder renderer never reads operators. packages/components/src/renderers/complex/filter-builder.tsx is 89 lines and reads exactly schema.fields, schema.label, schema.name, schema.value, schema.wrapperClass — that list is the counter-probe, and operators is absent from it.

Implication: the ruling is not "which spelling is dead" — both are implemented, on other surfaces. It is "which layer's vocabulary should the FilterField authoring surface speak", plus the separate question of whether this key is authorable at all given its renderer ignores it.

B4. data-display.zod.ts#DataTableSchema.rowActions — TS boolean vs mirror any[]

Reading: the renderer implements the boolean and never reads array elements. packages/components/src/renderers/complex/data-table.tsx — rowActions = false default (:708), {rowActions && ( (:1935, :2319), (rowActions ? 1 : 0) in two colSpan computations (:1958, :2363), the designer input declared { name: 'rowActions', type: 'boolean', ... } (:2521), defaultProps rowActions: true (:2534), and the docblock example at :667 writes "rowActions": true. Nothing indexes into it.

Counter-probe on the same file and same method: selectable on the same schema does have a value-reading path (resolveSelectionMode, :592, branching on 'single'), so this grep does surface value reads when they exist.

Implication: an authored array is truthy, so it "works" by accident while its contents are silently discarded — the mirror's any[] dialect is the side with no reader. Direction looks like withdrawing the array dialect from the mirror, which is a behaviour change for anyone currently authoring one, hence a ruling.

B5. form.zod.ts#CalendarSchema.defaultValue / .value — TS Date | Date[] vs mirror string | Date

Reading: the TS side matches the underlying control; the mirror's string limb does not. packages/components/src/renderers/form/calendar.tsx:17 is the whole read: selected={(schema.value || schema.defaultValue) as any}, passed to react-day-picker's Calendar with mode={(schema.mode || "single") as any} (:15). react-day-picker's selected takes a Date for single and Date[] for multiple — never an ISO string. The as any is what lets the mirror's string dialect through the type system while failing to preselect anything at runtime.

Also surfaced by this reading and worth folding into the ruling: the renderer offers mode: 'range' (:30), whose react-day-picker value shape is a DateRange object that neither side declares.

B6. complex.zod.ts#ChatbotSchema.body — TS SchemaNode | SchemaNode[] (inherited slot) vs mirror Record<string, unknown> ("additional API body params")

Reading: the two sides are not two dialects of one key — the mirror has taken a name the base schema owns, for a meaning the declaration already spells differently.

• The TS side is not ChatbotSchema's own key: ChatbotSchema extends BaseSchema, and BaseSchema.body is SchemaNode | SchemaNode[] (packages/types/src/base.ts:189) — the rendered-slot key. It is implemented broadly as such: renderChildren(schema.body) in renderers/overlay/tooltip.tsx:31, renderers/data-display/badge.tsx:32, renderers/data-display/alert.tsx:22, renderers/navigation/sidebar.tsx:43,59,79,89,112.
• The API-params meaning already has its own declared key: ChatbotSchema.requestBody?: Record<string, unknown> (packages/types/src/complex.ts:619), and that is what the chatbot renderer actually reads — packages/plugin-chatbot/src/renderer.tsx:87,305,438 all pass body: schema.requestBody into the request. renderer.tsx:29 lists the schema fields it consumes and names requestBody, not body.
• No read of schema.body under the API-params meaning exists anywhere.

Implication: the direction here looks less like a coin-flip than #5927 assumed — the mirror's body override is unread, and dropping it restores the inherited slot meaning that the rest of the renderers implement. It is still a ruling because removing it changes what the published validator accepts.

Group C — the mirror REQUIRES a key the declaration marks optional

Both rows read the same way, and both readings point at the mirror as the stale side: the renderer implements the absent case in running code.

C1. form.zod.ts#ComboboxSchema.options

TS declares options?: ComboboxOption[] (packages/types/src/form.ts:1298); the mirror requires it. packages/components/src/renderers/form/combobox.tsx:25 reads options={schema.options || []} — an explicit absent-case fallback that renders an empty combobox.

C2. form.zod.ts#CommandSchema.groups

TS declares groups?: CommandGroup[] (packages/types/src/form.ts:1373); the mirror requires it. packages/components/src/renderers/form/command.tsx:31 reads schema.groups?.map(...) — optional chaining, again the absent case handled deliberately.

So { "type": "combobox" } type-checks, renders, and is refused at parse time. Making these two .optional() would agree with both the declaration and the running code; it is listed rather than done because it changes what the published validator accepts, and #5927's ruling reserved group C for the inbox.

Where these are recorded now

packages/types/src/__tests__/zod-mirror-parity.test.ts, KnownDrift. That ledger is shrink-only and pinned to each pair's exact drifted key set, so whichever way each row is ruled, the correcting PR deletes or shrinks its row in the same change. After #5927 group A landed it holds 13 rows: the 8 above, plus group D's 4 (DashboardComponentSchema, DashboardWidgetSchema, FilterBuilderSchema, CRUDSchema — riding #2231) and group E's PageNodeSchema. Note FilterBuilderSchema.fields is B3's drift seen through the element type, so ruling B3 closes it too.

Related: #5927 (the framework and group A), #6032 (group A's PR), #5684 (the guard), #4605 / #5680 (the BaseSchema precedent for measuring the renderer), ADR-0049 (enforce-or-remove, the route for a dead spelling), #2231 (spec unification), #5853 (the opposite direction, currently undecided).

---

Generated by Claude Code

[os-zhuang]

分诊(session session_01LrqnyLhY3kYBBRird4peBT,2026-08-24):入决策箱(needs-user-decision + domain:ui)—— 去向由 #5927 裁决原文预定(B/C 两组「come back to the decision inbox with the renderer reading attached」),本卡即该回箱载体,8 条渲染器读数已附卡面。四棱卡面块如下(逐键读数以卡面正文为准,此处不复述)。

os-decision-facets

一句话问题:8 个「TS 声明」与「运行时校验器」各说各话的键,每个要一条「往哪边收敛」的裁决 —— 改哪边都会改变已发布校验器接受什么,所以按 #5927 的裁决逐键人工裁,不批量编辑。

选项 × 真实代价(按读数分三簇):

• 双边皆死簇(B1 FormSchema.mode、B2 HeaderBarSchema.variant):两套词表在该表面都无读点 —— 真正的选择不是「选哪边」而是「两边都撤(ADR-0049 enforce-or-remove)还是留着」。撤 = 公开面收缩,响亮;留 = 继续声明一个运行时不兑现的键。
• 镜子侧死簇(B4 rowActions 数组方言、B5 Calendar 的 string 方言、B6 ChatbotSchema.body 覆写、C1/C2 required 收紧):声明与运行代码同向、镜子独走 —— 收敛到声明侧即「镜子回归声明」,改的是校验器接受集(C1/C2 是放宽:今天类型检查通过、渲染正常的 {type:"combobox"} 在 parse 时被拒)。
• 分层词表簇(B3 FilterFieldSchema.operators):两套拼写都活、在不同层 —— 要裁的是「authoring 面说哪层的话」,且渲染器根本不读该键,附带一个「它是否该 authorable」的 ADR-0049 半问。

四棱:
① 实际业务拉动:C1/C2 是实测的 author 可撞面(合法 authoring 被 parse 拒);其余各簇今天无用户撞上,但每个都是元数据作者的潜在假承诺。
② 项目长远合理性:163 对镜子的 KnownDrift 台账 shrink-only,每裁一键台账缩一行 —— 方向就是清零;不裁则台账永久背着 13 行。
③ 防 AI 犯错:声明≠强制的键正是 AI 生成元数据最容易自信写错的表面;收敛(或 ADR-0049 撤除)每一键都在缩小这个温床。C1/C2 反向提醒:收紧 required 会让 AI 既有产出当场变红 —— 变红是对的,但要在 changeset 里说清。
④ 创业阶段不扩散:全部 8 键都是收敛/删减方向,无新增能力面;双边皆死簇走撤除是净减法。

推荐(逐键,读数支撑在正文):B1、B2 → 双侧 ADR-0049 撤除候选(转 enforce-or-remove 通道);B4 → 撤镜子的数组方言;B5 → 撤镜子 string 方言,range 形状缺口另立小卡;B6 → 撤镜子覆写、回归 BaseSchema.body 槽语义(API 义已有 requestBody);C1、C2 → 镜子改 .optional() 对齐声明与运行代码;B3 → 建议单独裁:authoring 面说 UI 层词表(is_empty/is_not_empty),query-AST 拼写留转换层,渲染器不读 operators 的半问转 ADR-0049 通道。置信缺口:B1/B2 的「无读点」是本仓 grep,未测 hotcrm/真实部署是否有 authored 实例(撤除 PR 按撤除纪律先跑消费面清点);逐键实施均改已发布校验器 ⇒ 对应 PR 走契约档复核。

低摩擦裁决格式:回「按推荐」即可整批落地;或逐键「B3 改 X」式点名覆盖,未点名的按推荐走。

---

Generated by Claude Code

[os-steve]

Maintainer ruling (2026-08-25, in-session batch adjudication, batch 2; verbatim: 「其他同意」 — the whole per-key table accepted as recommended). Ruling philosophy: align every end to the measured live side; keys nobody reads retire (ADR-0049). Per key:

key	ruled disposition
B1 FormSchema.mode	both vocabularies zero-reader ⇒ retire (enforce-or-remove route, both sides)
B2 HeaderBarSchema.variant	zero-reader ⇒ retire
B3 FilterFieldSchema.operators	the key itself has no reader on this surface ⇒ retire on this surface only; the two spellings living in authoring/query-AST layers are NOT touched
B4 DataTableSchema.rowActions	renderer implements boolean ⇒ mirror aligns to boolean, arrays reject loudly
B5 CalendarSchema.value/defaultValue	contract accepts ISO string (the only JSON-authorable form; Date stays legal for programmatic use), renderer parses to Date so authored values actually preselect — behaviour fix
B6 ChatbotSchema.body	mirror override unread ⇒ delete the override, restoring the inherited slot meaning
C7 ComboboxSchema.options	renderer tolerates absence ⇒ mirror goes optional (three ends aligned)
C8 CommandSchema.groups	same ⇒ optional

Claim-time obligations ruled with it: re-run the zero-reader greps (B1/B2/B3/B6) against current main before editing — the verdicts above ride the card's measurements and stale-premise discipline applies; retirements follow the recorded retirement route (tombstone/prescription per house pattern), not bare deletion.

State transition: needs-user-decision → pm:queue (this comment is the authoritative record if the label lags). Lane domain:ui, one claim, per-key commits. Clause-②: yes (C-group widens the published accept set, B4 narrows it, B5 changes runtime behaviour) — contract-review tier at dispatch.

---

Generated by Claude Code