finding(types): 28 zod-mirror keys are declared `z.function()`, which NO JSON document can satisfy — 14 in-repo corpus files author them and are silently invalid

[yinlianghui]

Filed unassigned by the domain:ui execution seat while measuring objectui#5392 (session session_01CSoz9uGhaaSgiq3hshtN7L). Out of scope for that card, which is a measurement of zod→JSON Schema fidelity; this is a separate defect its instrument surfaced.

Dedupe search run before filing: #5250 (BaseSchema.passthrough() accepts undeclared keys) is the opposite direction and does not cover this; #5927 / #5853 / #6058 are the mirror-vs-TypeScript-declaration drift family, which is a different axis — this is mirror-vs-JSON-authorability. No existing card names z.function().

What was measured

@object-ui/types is the protocol layer for a JSON-authored UI vocabulary. Its zod mirrors declare 28 distinct keys as z.function():

cell custom onCancel onCardAdd onCardClick onCardMove onChange onClick
onCollapsedChange onColumnAdd onColumnsReorder onComplete onConfirm onDismiss
onError onExpandChange onOpenChange onPageChange onRowDelete onRowEdit
onSelectChange onSelectionChange onSendMessage onSlideChange onSubmit
onValueChange onViewChange validate

Command (run in packages/types/src/zod/):

grep -hoE "^\s*[A-Za-z]+: z\.function\(" *.ts | sed 's/[[:space:]]*//;s/: z.function($//' | sort -u

60 call sites across 9 files (grep -oF 'z.function(' *.ts | wc -l → 60; grep -lF → base, complex, data-display, disclosure, feedback, form, layout, navigation, overlay).

No JSON value satisfies z.function() — measured, with a positive control in the same run:

null -> REJECT {} -> REJECT
1 -> REJECT [] -> REJECT
"x" -> REJECT true -> REJECT
a real function -> accept <- control: the instrument can say "accept"

Why it matters: 14 in-repo corpus files author these keys and fail

Validating every root-type JSON file in the repo against AnyComponentSchema.safeParse finds 14 files that are rejected today, all for this reason. Example, examples/schema-catalog/src/schemas/components-feedback-toast/destructive.json:

{"type":"button","label":"Destructive Toast","variant":"destructive",
 "onClick":{"action":"toast","variant":"destructive","title":"Error","description":"Something went wrong."}}

ButtonSchema.safeParse -> false
issue: { code: "invalid_type", expected: "function", path: ["onClick"],
 message: "Invalid input: expected function, received object" }

The file is authoring onClick as a declarative action object, which is the only thing JSON can express. The mirror asks for a JS function. The affected files are the components-feedback-toast/ and components-feedback-sonner/ catalogs.

And they are invisible

All 14 sit in objectui#5127's structure-key-less set — they carry no body/children/className/… at the root, so objectui check never judges them. They are invalid and unreported, which is why this has stood.

The question this needs ruled

Two directions, and this is a contract question rather than a mechanical fix:

• Narrow the declaration — if a JSON author can never supply a function, z.function() is declared != enforceable on a JSON surface and the keys should be removed or demoted to a runtime-only (non-authorable) face under ADR-0049 enforce-or-remove.
• Widen the mirror to the declarative form — if onClick: {action: …} is the intended authored spelling (which the corpus and the renderer's own action plumbing suggest), the mirror should declare that shape, and the 14 corpus files become valid.

⛔ Not fixed here — picking one changes a published contract. Filed for triage.

Related: #5250, #5927, #5853, #6058, #5127, #5392.

[os-zhuang]

Triage: needs-user-decision + domain:ui(落点 @object-ui/types zod mirror,objectui 发布库契约)。立卡人已正确停手 —— 两个方向都改已发布契约,人工地板。查重结论照准:与 #5927/#5853/#6058(mirror↔TS 声明漂移轴)不同轴,本卡是 mirror↔JSON 可作者性轴;#5250 是反方向。姊妹卡:#6132(文档 action props 无声明槽位)同属 action-prop 契约族,裁决时宜同场对读。

四维分析(决策输入,非裁决)

实际业务需求 —— JSON authoring 是本平台的核心面,而 28 个键今天对 JSON 作者是结构性不可满足:仓内 14 个 corpus 文件实际作者了 onClick: {action: …} 声明式动作对象并在 safeParse 下全数被拒(且因 #5127 结构键盲区而不可见)。真实用法存在、真实被拒 —— 这不是投机性能力面。

项目长远合理性 —— contract-first:mirror 应当声明运行时真正接受并兑现的形状。z.function() 在 JSON 协议层等于「声明了一个任何文档都写不出的键」,declared ≠ authorable,两个方向(收窄退役 / 拓宽到声明式形状)都比现状诚实。但拓宽必须逐键对准运行时:凡 renderer 的 action 管线并不消费声明式对象的键,拓宽即是「声明一个运行时不兑现的能力」。

防 AI 写代码/元数据犯错 —— 现状是最坏形态:AI 作者照 corpus 学会 onClick: {action: …},schema 静默拒绝、门禁又看不见(#5127 盲区),错误既不响也不可修。严格声明真实形状(或响亮移除)任一方向都消除这个温床;维持现状是唯一不可接受项。

创业阶段不扩散需求 —— 不新造能力:声明式 action 对象已是 corpus 与 renderer 管线的既有用法,收敛的是「声明与现实的差距」,不是扩面。28 键一刀切拓宽才是扩散 —— 应以实测消费为界。

四棱块

• 业务:14 corpus 文件实测被拒,真实用法 > 投机面 → 指向「按实测收敛」
• 长远:declared=enforced,mirror 对准运行时真实接受形状 → 指向「按实测收敛」
• 防错:现状 = 静默拒绝 + 门禁盲区双重掩盖,任一方向皆优于维持 → 指向「按实测收敛」
• 聚焦:不新造能力,以 renderer 实测消费为界拆两半 → 指向「按实测收敛」

推荐(四棱同向,但改已发布契约 = 人工地板,恒交维护者):先量后裁的逐键收敛 —— 对 28 键逐键实测 renderer action 管线是否消费声明式对象:① 有消费的键,mirror 拓宽为声明式 ActionConfig 形状(14 corpus 文件随之转合法);② 零消费的键,按 ADR-0049 enforce-or-remove 退役或降级为 runtime-only 非作者面。测量卡先行、裁决后分两腿实施;与 #6132 的槽位裁决同场对读避免两次裁同族。

---

Generated by Claude Code

[os-steve]

维护者提问(2026-08-25 批次回批,逐字):「6124 服务端协议中 hook 函数被保存成json时转换过，前端是否要类似的思路。」—— 本卡暂留决策箱,以下是对服务端机制的实测对照与细化提案(读数取 objectstack origin/main)。

服务端实际怎么做(两件套 + 一条边界):

1. Hook 体:函数从不进 JSON,进的是「声明式信封」(packages/spec/src/data/hook-body.zod.ts):JSON 面是 strict 的结构化对象 {language: 'expression'|'js', source: <字符串>, capabilities, timeoutMs},运行时用 new AsyncFunction('ctx', source) 在带能力令牌的沙箱里再水化。校验器声明的是可序列化形,不是 z.function()。
2. Flow functions:双面 union + build 期降级(packages/spec/src/automation/flow-function.zod.ts:220-232):FlowFunctionEntrySchema = z.union([z.function(), 声明记录, 字符串 ref, 降级记录]) —— 程序面(defineStack 里的真函数)合法,但 objectstack build 在 parse 前把每个内联 callable 降级成字符串 ref,真函数乘 sibling ESM 模块、加载时再挂回。一个 schema 同时诚实声明「作者写的形」和「构建产物形」。
3. 纯运行时契约面保留 z.function()(driver.zod.ts/data-engine.zod.ts):那些 schema 描述的是从不作为 JSON 作者化的运行时接口 —— z.function() 在那里是对的。本卡的病根恰是一个 schema 同时伺候两个面。

前端要不要同思路?—— 要,且比服务端更省:前端已有闭合的声明式词汇(ActionDef),不需要发明 source-string 信封。 细化提案(原推荐 2+1 的服务端对齐版):

• A(推荐):28 键逐键测渲染器消费面 ——
  • 有声明式消费(渲染器吃 {"action":…} 对象形)⇒ 镜像改 z.union([z.function(), ActionDefSchema])(照 FlowFunctionEntrySchema 先例:函数臂伺候程序面/React 回调,对象臂伺候 JSON 作者;JSON 文档永远走对象臂);14 个语料文件随之转绿或修正;
  • 无声明式消费 ⇒ 退出 JSON 镜像(runtime-only face,ADR-0049)—— 照 driver.zod.ts 先例。
• 边界纪律(rider 测量,命中则另立小卡):若 objectui 存在任何「schema → JSON 序列化」出口(designer 保存等),函数值在出口必须响亮拒绝或降级为声明式形 —— JSON.stringify 对函数值是静默丢弃,正是本仓最忌的形状;服务端的 lowerCallables 即此步的先例。
• B(否决理由存档):纯 function-only(全 28 键保持 z.function())= 校验器继续对 JSON 作者撒谎;纯对象-only(删函数臂)= 程序面/React 用法失去声明。

一致性核对:#6182(handler 表达式方言)已出箱,其裁决若与本案相交,claim 时先读、以后者不推翻前者为准。
置信缺口:28 键逐键消费面未测(语料只证明 toast/sonner 一角);ActionDef 联合形的确切边界(是否含字符串命名 handler ref,对齐 flow 的 ref 臂)待测量后定。

低摩擦裁决:回「A」即按上式入队(Clause-②,契约复审档);「A,但 …」照常。

---

Generated by Claude Code

[os-steve]

Maintainer ruling (2026-08-25, batch adjudication close-out; verbatim: 「6124 同意 A」): Option A — the server-pattern alignment as refined in the previous comment.

Ruled execution shape:

1. Per-key measurement across all 28 z.function() keys: does the renderer consume a declarative object form for this key?
2. Consumed ⇒ mirror becomes z.union([z.function(), <closed ActionDef shape>]) — the function arm serves the programmatic/React face, the object arm serves JSON authors (the FlowFunctionEntrySchema precedent, objectstack flow-function.zod.ts); the exact ActionDef union boundary (including whether a string-named handler ref arm belongs, mirroring flow's ref arm) is fixed by the measurements.
3. Not consumed ⇒ the key leaves the JSON mirror (runtime-only face, ADR-0049 — the driver.zod.ts precedent).
4. The 14 silently-invalid corpus files go green (or get corrected) in the same PR — that flip is the proof the contract now tells authors the truth.
5. Rider measurement: if any schema→JSON serialization door exists in objectui (designer save etc.), function values must be loudly refused or lowered at that door (JSON.stringify drops functions silently — the server's lowerCallables is the precedent); a hit files its own follow-up card, not a rider fix.
6. Consistency check at claim: read [Decision] Is an authored handler EXPRESSION a supported dialect? 56 mirrors say function, 11 say string, and both appear in files that mirror the other #6182's landed ruling first; the later ruling must not silently overturn the earlier one — conflict = fork back to triage.

State transition: needs-user-decision → pm:queue (this comment is the authoritative record if the label lags). Lane domain:ui. Clause-②: yes (published-validator accept-set change) — contract-review tier at dispatch. Size M (28-key measurement + union edits + corpus verification).

---

Generated by Claude Code

[os-steve]

Scope extension (triage, same-day ruling #6182-A, maintainer verbatim 「同意」): the 11 z.string() handler-expression mirrors measured in #6182 (rg -n 'on[A-Z][A-Za-z]*:\s*z\.(function|string|any)' packages/types/src/zod/ — the string rows, e.g. onClick/onInstall/onPreview/onSave/onCancel/onBack/onViewChange/onChange) join this card's per-key sweep with the SAME ruled treatment as the 28 z.function() keys: renderer consumes a declarative object form ⇒ union arm; otherwise runtime-only retirement. The expression-string dialect is not a supported authoring form (it is measurably dropped at runtime, #4453). The 3 z.any() rows from the same census get the same per-key walk while you are in the files. #6182 is pm:blocked on this card and closes on its landing.

---

Generated by Claude Code