`RecordHighlightsField` does not declare `readonly`, so the spec silently strips the key the chip gate reads

[xuyushun441-sys]

Split out of #5077 as an out-of-scope finding — filed unassigned, needs a maintainer decision before it can be actioned.

What was measured

While implementing #5077 (objectui PR carries readonly through the record:highlights entry normalization) I checked whether an authored readonly is actually part of the contract. It is not.

packages/spec/src/ui/component.zod.ts:

export const RecordHighlightsField = z.union([
  z.string(),
  z.object({
    name: z.string(),
    label: z.string().optional(),
    icon: z.string().optional(),
    type: z.string().optional(),
  }),
]).describe('Highlight field: bare name, or {name,label?,icon?,type?}');

Four keys. readonly is not among them, and the object is not .strict(), so it is silently stripped. Measured against the installed build:

input   { fields: [ { name: 'supply_share', readonly: true, type: 'number' } ] }
parsed  { "fields": [ { "name": "supply_share", "type": "number" } ], "layout": "horizontal" }

Why this matters today, and more tomorrow

ComponentPropsMap has no consumers outside component.zod.ts and its own test — I grepped. So per-component props are not validated on the live load path right now: PageComponentSchema.properties is z.record(z.string(), z.unknown()) and the bag rides through untouched. That is the only reason the objectui-side fix in #5077 works end to end at all.

That is a fragile place to stand:

• The moment ComponentPropsMap is wired into validation — which is plainly the direction of travel, given protocol 15 flipped FormFieldSchema / FormSectionSchema / PageComponentSchema to .strict() under ADR-0089 D3a precisely so an undeclared key is "a loud parse error instead of a silent strip" — an authored readonly: true becomes either a silent strip or a hard parse error. The silent-strip case is the dangerous one: header chips for hook-maintained columns quietly become editable again, and the corruption in highlightFields cannot declare read-only, so the detail page's header chips let users overwrite hook-maintained columns #5077 returns with no diagnostic anywhere.
• readonly is absent from the block's declared inputs, so it never reaches the generated sdui.manifest.json. An AI author reading the manifest has no way to learn the key exists. Per AGENTS.md #0.1 the renderer reading a key the spec does not declare is exactly the consumer-side tolerance we do not want — it fossilizes a second de-facto contract.

The decision

Should readonly become a declared key on RecordHighlightsField?

Option A — declare it in the spec (readonly: z.boolean().optional()), then declare it in objectui's record:highlights block inputs so it reaches the manifest.

• Long-term soundness: this is the contract-first route. The key is genuinely enforced — objectui's HeaderHighlight gate acts on it — so it satisfies ADR-0049 enforce-or-remove on arrival rather than joining the declared-but-inert backlog. It also survives the .strict() flip instead of being broken by it.
• AI-authoring safety: declared means it appears in the manifest an authoring model reads, and means a typo (readOnly, read_only) fails loudly once the props map is enforced, instead of silently leaving a machine-owned column writable. This is the option that structurally prevents the mistake at authoring time.

Option B — leave the spec alone; objectui keeps reading an undeclared key.

• Long-term cost, stated plainly: a permanent divergence between what the spec says a highlight entry is and what the renderer honours. It works only while per-component props go unvalidated, and it breaks — silently, in the data-corrupting direction — on the day they are validated. It is the "lenient consumer" pattern AGENTS.md #0.1 names.

Option C — do not add a key; have the chips consult the form view's field-level readonly (suggestion 3 on #5077).

• One declaration covering both the dialog and the detail-page surfaces, which is the asymmetry that produced highlightFields cannot declare read-only, so the detail page's header chips let users overwrite hook-maintained columns #5077 in the first place. No new vocabulary. But it is a larger change, it only helps records that have a form view with that field, and it does not give an author a way to lock a chip that has no corresponding form-view field.

Recommendation: A, and it is the same answer on both axes. It is the only option under which the authored declaration and the enforced behaviour are the same fact, which is what makes it safe for AI-written metadata; and it is the only one that does not have a scheduled breakage date. C is worth doing as well, but as a convenience layered on top of a declared key, not instead of one — A is small, and it is what makes the #5077 fix durable rather than incidental.

Note the scope boundary: this is about the page component's RecordHighlightsField. The object's own highlightFields stays a plain string[] — no change proposed there.

Downstream: yinlianghui/hotcrm-heimao#61.

[xuyushun441-sys]

PM 分诊(维护者 2026-08-04 定调:#5077 按 bug 修,不动协议)

• highlightFields cannot declare read-only, so the detail page's header chips let users overwrite hook-maintained columns #5077 的修复不依赖本单:objectui#3356(已合)+ objectui#3355 即可闭环;readonly 今天能生效是因为 SDUI props 路径无解析闸门(SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068)。
• 本单不入队、不排期。它的真实期限是:SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 的 props 校验闸门落地之前必须先落本声明(否则授权的 readonly 被静默剥离,highlightFields cannot declare read-only, so the detail page's header chips let users overwrite hook-maintained columns #5077 的腐蚀零诊断复发)—— 已作为硬前置登记,实施 SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 者必须先做本单(一行 additive:RecordHighlightsField.readonly?: boolean + 块 inputs)。
• Blocked-by 关系:本单 blocks SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 的任何实施 PR。

---

Generated by Claude Code

[os-zhuang]

维护者裁定(2026-08-05,经 spec 车道 PM session_018fxLGQdatPbBUvCgiVxg6D 誊写):选 A。

• RecordHighlightsField 对象成员声明 readonly: z.boolean().optional()(spec 侧),随后 objectui record:highlights block inputs 声明该键使其进入 sdui.manifest.json(objectui 侧,可另 PR)。
• 依据两轴:声明与强制成为同一事实(objectui HeaderHighlight 门真的读它,落地即满足 ADR-0049),且能存活未来 .strict() 翻转;AI 作者可从 manifest 学到该键,拼写错误在闸门接通后响亮失败。
• Option C(chips 读 form view 字段级 readonly)作为后续便利层保留,不并入本单。
• 本裁定同时解锁 SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068(方向 A 已同批裁定,Blocked-by 本单)。

转入队列并即刻派发。

---

Generated by Claude Code

[os-zhuang]

PM 认领(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-05)

• 分支:claude/issue-5176-highlights-readonly
• 工作树:../objectstack-5176-highlights-readonly(基于最新 origin/main)
• 域:domain:spec
• 文件面:packages/spec/src/ui/component.zod.ts(RecordHighlightsField 声明 readonly)+ 配套测试 + 生成物(如有移动,走生成器并逐项解释);objectui record:highlights block inputs 声明为另 PR / 跟进项,不混入本 PR
• 裁定依据:上方维护者裁定选 A
• 与在飞 [spec] 退役 HookContext session.roles —— #4839 双删后零消费方零生产方(ADR-0049) #5050(data/hook.zod.ts)、SYNC_ARCHITECTURE.md 的 L3 Connector 示例不可编译,且写的是 schema 会**拒收**的键名(sourceField / targetField / transform.type: 'custom' / webhook retryPolicy) #5515(SYNC_ARCHITECTURE.md)、44 个 strictUnknownKeyError 直接调用点的别名表在 #5013 闸门覆盖之外(实测干净,但无人看守) #5483(shared 严格性模块)及同批 [决策] readonly 剥离的 strict/reject 模式落在哪一层 —— B(WriteObservabilityOptions)推荐,A/C/D 各有代价(#4903 后续) #5126(contracts/data-engine.ts)文件面互不相交;SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 同文件但已 pm:blocked 等本单
• 派发:os-dev(opus)。若本评论之前存在不同 session 的认领,以先者为准、本认领作废。

---

Generated by Claude Code