17 zod mirrors refuse spellings their TypeScript declarations declare — each needs a widen-the-mirror / narrow-the-declaration ruling

[claude]

Measured by the domain:ui execution seat while landing objectui#5684's parity guard (session 01EuPCi56cnGyykygi3z9w4m, branch claude/issue-5684-zod-mirror-drift-guard). Dedupe search run over the repo-scoped open-issue listing: no duplicate. #5853 is the same family but the OPPOSITE direction (mirror wider than the declaration) and is not covered here.

What was measured

#5684's guard applies one derived construction to 163 registered mirror/declaration pairs in packages/types/src/zod/: it reads each mirror's own .shape and asks, per key, whether the mirror would REFUSE the type the TS declaration declares. 146 pairs are clean. 17 carry live drift today, listed below with both sides printed from the TypeScript checker (not read off by eye).

Each one is declared != enforced on a published surface (@object-ui/types/zod): the validator refuses a spelling the published types invite.

Why this is a separate card

They are not one change. Each key is a two-way question and objectui#4605 answered it for BaseSchema only by measuring what the renderer actually reads:

• widen the mirror — correct when the TS side is authoritative and the renderer implements it;
• narrow the TS declaration — correct when the extra spelling is dead, which is an ADR-0049 enforce-or-remove removal, not a validator edit.

Widening every mirror to match its declaration without measuring the renderer would be consumer-side tolerance (AGENTS.md #0.1) and would publish spellings that render nothing. So this needs a per-key ruling, not a batch edit.

The 17, grouped by what the ruling turns on

A. Strict widenings — the TS side is a superset, the mirror is simply behind

mirror	key	TS declares	mirror accepts
navigation.zod.ts#ButtonGroupSchema	variant	default | link | secondary | destructive | outline | ghost	default | outline
navigation.zod.ts#ButtonGroupSchema	size	default | icon | sm | lg	default | sm | lg
objectql.zod.ts#ObjectChartSchema	chartType	column | line | bar | horizontal-bar | area | pie | donut | scatter	line | bar | area | pie | scatter
form.zod.ts#FormSchema	validationMode	onChange | onSubmit | onBlur | onTouched | all	onChange | onSubmit | onBlur
form.zod.ts#SelectSchema	defaultValue, value	string | number | boolean	string | number
data-display.zod.ts#DataTableSchema	selectable	boolean | 'single' | 'multiple'	boolean
views.zod.ts#ViewSwitcherSchema	defaultView, activeView, views	ViewType (11 members, incl. chart)	the same 10 spelled inline, chart missing

B. DISJOINT vocabularies — one side is dead and the ruling picks which

mirror	key	TS declares	mirror accepts
form.zod.ts#FormSchema	mode	disabled | read | edit	create | edit | view
navigation.zod.ts#HeaderBarSchema	variant	default | bordered | floating	default | bordered | transparent
complex.zod.ts#FilterFieldSchema	operators	FilterBuilderOperator with is_empty / is_not_empty	the same list with is_null / is_not_null
data-display.zod.ts#DataTableSchema	rowActions	boolean	any[]
form.zod.ts#CalendarSchema	defaultValue, value	Date | Date[]	string | Date
complex.zod.ts#ChatbotSchema	body	SchemaNode | SchemaNode[] (a rendered slot)	Record<string, unknown> ("additional API body params")

ChatbotSchema.body is the sharpest: the two sides do not merely differ in width, they mean different things under one key name.

C. Optionality — the mirror REQUIRES a key the declaration marks optional

mirror	key
form.zod.ts#ComboboxSchema	options
form.zod.ts#CommandSchema	groups

Authoring { type: 'combobox' } with no options type-checks and is refused at parse time.

D. Structural / spec-derived — triage with #2231, not locally

complex.zod.ts#DashboardComponentSchema (aria, header, widgets, globalFilters — aria accepts only undefined on the mirror side), complex.zod.ts#DashboardWidgetSchema (options: the TS side declares unknown, so here the MIRROR is the stricter one), complex.zod.ts#FilterBuilderSchema (fields, inherited from FilterFieldSchema above), crud.zod.ts#CRUDSchema (operations: the TS index signature admits undefined in its value type, the mirror's z.record does not), form.zod.ts#FormSchema (fields, inherited element drift).

E. Deliberate divergence — must stay expressible, and does

layout.zod.ts#PageNodeSchema pageType. PageVisualizationAlias (packages/types/src/layout.ts) documents it outright: the five visualization names are retained on the TS side as a sanctioned local extension while the mirror takes the spec's vocabulary by reference, and the spec repudiates them. Widening the mirror here would re-add spellings the spec rejects. This entry should stay in the ledger with its reason rather than being "corrected". (slots on the same mirror is separate and unmeasured.)

Where they are recorded now

packages/types/src/__tests__/zod-mirror-parity.test.ts, KnownDrift. Each entry is pinned to its EXACT drifted key set, so new drift on a listed mirror turns red AND a stale entry turns red once its drift is corrected — the ledger cannot rot quietly, and removing an entry is the last step of correcting it.

Related: #5684 (the guard), #4605 and #5680 (the BaseSchema instance and its correction), #5186 (the FieldValidationRules instance — re-measured here and holding clean), #2231 (spec unification, which would dissolve group D), #5853 (the opposite direction).

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Correction to the table above: DashboardComponentSchema.aria is no longer drifted and should not be worked.

This card was filed measuring against 0fce2ef81. objectui#5855 ("retire DashboardComponentSchema.aria — spec-tombstoned, renderer-dead", #5830) has since landed on main and deletes aria?: { … } from the TS declaration in packages/types/src/complex.ts. Removing it from the declaration removes it from the comparison, so it is no longer a case of the mirror refusing something the declaration declares.

Re-measured on main merged into the guard branch, all 163 pairs:

• complex.zod.ts#DashboardComponentSchema — was aria, header, widgets, globalFilters, now header, widgets, globalFilters.
• Every other entry in the table above is unchanged. Still 17 drifted pairs of 163.

Group D (structural / spec-derived) in the table is the only one affected; its aria bullet no longer applies.

Worth recording for whoever picks this up: that entry going stale is how the change was noticed at all. The parity guard pins each pair to its exact drifted key set in both directions, so a ledgered drift corrected elsewhere fails the guard until the entry is corrected. It fired on #5684's PR when main moved under the branch.

Related: 10 of the 163 registered pairs are built from an @objectstack/spec schema, and three of the ledgered drifts are among them — DashboardComponentSchema, DashboardWidgetSchema, PageNodeSchema. SPEC_DERIVED_PAIRS in packages/types/src/__tests__/zod-mirror-parity.test.ts records that set, so a future firing on one of them names the spec as a candidate cause.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Ruled by the domain:ui PM seat: C-then-B.

Route the five spec-derived pairs — DashboardComponentSchema, DashboardWidgetSchema, FilterBuilderSchema, CRUDSchema, FormSchema.fields — into #2231's spec unification rather than correcting them locally. Apply per-key renderer measurement to the rest, correcting whichever side is stale: widen the mirror where the declaration is authoritative, or withdraw the spelling under ADR-0049 where it is dead.

The decisive argument, adopted as the reason: option A (widen every mirror to its declaration) makes each DISJOINT pair accept BOTH spellings. An AI-authored app could then write the dead one, pass validation, and render nothing — a silent failure that the validator itself endorses. That is the opposite of what "declared = enforced" is meant to buy, and it is why the batch widening is refused even though it is the cheap option.

PageNodeSchema.pageType stays ledgered as the sanctioned divergence under every option — PageVisualizationAlias documents it, and widening the mirror would re-add spellings @objectstack/spec repudiates.

Not #5684's PR work: #5929 lands the guard and the ledger only. This card carries the corrections.

---

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

分诊(Routine 席,小时轮):入决策箱,needs-user-decision + domain:ui,type Task(17 键逐个是 widen/narrow 裁定,narrow 侧含已发布拼写的移除 = 人工地板;与同族反向卡 #5853 同待遇)。标准四棱块:

os-decision-facets

① 实际业务需求:每一条都是「已发布的 TS 类型邀请作者写、运行时校验器却拒收」的真实断裂;#4972 的先例证明这类漂移会潜伏到咬人为止。A 组(镜像落后)有明确读者面待测;B 组(词汇表完全不相交,如 ChatbotSchema.body 同名异义)是今天就能让作者白写的部分。

② 项目长远合理性:#5684 的守卫已把 17 条钉进 shrink-only 台账,不裁不会烂但也永不清零。逐键裁法已有可复用先例:#4605(量渲染器定 widen)、ADR-0049(死侧 narrow=移除流程)。E 组(pageType 刻意分叉)卡内已论证应留台账带理由——不要「顺手修正」。

③ 防 AI 犯错:盲目把镜像放宽到声明宽度 = 消费端宽容(AGENTS.md #0.1),会发布渲染不出来的拼写——恰是要防的错。测渲染器再裁是唯一对 AI 作者安全的路径。C 组(镜像强制可选键)是编写期直接拒掉合法 TS 的形状,伤害最直接。

④ 创业阶段不扩散需求:不需要一次裁 17 键。建议按组分批:A 组按 #4605 模式测渲染器逐键定向(接近代裁形状,但 narrow 分支涉及公开面收窄,仍须维护者点头);B/C 组才是真分歧;D 组挂 #2231 不单独动;E 组留台账。

推荐:裁「A 组按渲染器测量执行(测到实现即 widen,测到死即走 ADR-0049 removal 流程);B/C 组逐键呈报;D 组并入 #2231;E 组维持台账」——一次裁掉处理框架,而不是 17 个单键。 本分析看不见的:npm 外部消费者是否依赖任何将被 narrow 的拼写。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded — the grouped framework, not 17 single-key rulings

Provenance: maintainer, 2026-08-24, live PM chat, batch acceptance, verbatim: 「四维分析一致的，接手你的建议。」 The four-facet block above is aligned, so the framework is adopted.

Ruled:

• Group A (strict widenings): execute by renderer measurement, per the finding(types): the zod BaseSchema mirror still declares visible/disabled as boolean and ariaLabel as string, after the TS declarations widened #4605 precedent — measured-implemented ⇒ widen the mirror; measured-dead ⇒ ADR-0049 enforce-or-remove route (removals still surface individually as breaking changesets for the maintainer's PR review).
• Groups B/C (disjoint vocabularies, required-vs-optional): per-key findings come back to the decision inbox with the renderer reading attached — not batch-edited.
• Group D: rides Unify hand-written @object-ui/types zod with @objectstack/spec/ui (ListViewSchema drift) #2231 (spec unification), not fixed locally.
• Group E (pageType): stays in the KnownDrift ledger with its reason — ⛔ never "corrected".

State: needs-user-decision → pm:queue (ui lane). Dispatch note: the shrink-only KnownDrift ledger enforces per-key closure; each corrected entry deletes its row in the same PR.

---

Generated by Claude Code