finding(react): a key authored under the `props` envelope never reaches a renderer that reads `schema` — measured as a silent empty `data-table` next to a working `properties` twin

[claude]

Found while implementing #6665 (the non-array node-level data diagnostic). Measured on that
card's merge-base but outside its fence, so filed separately.

The fact

#6665's four-leg re-measurement was run on 5967be095 through the real SchemaRenderer
inside a SchemaRendererProvider holding { customers: [ 2 records ] }, identical columns
in every leg, reading tbody td. Leg 2 is this card:

node	rendered body
{ "type": "data-table", "data": "${data.customers}", ... }	No results found (that is #6665)
{ "type": "data-table", "props": { "data": "${data.customers}" }, ... }	No results found
{ "type": "data-table", "properties": { "data": "${data.customers}" }, ... }	the two rows
{ "type": "data-table", "data": [ 2 literal records ], ... }	the two rows

The interesting pair is legs 2 and 3: the SAME key, the SAME value, one envelope apart, and
only properties puts rows on screen.

The mechanism

SchemaRenderer HOISTS properties.* onto the node (minus HOIST_PROTECTED_KEYS), which is
why leg 3 works — the hoisted data is a real array by the time DataTableRenderer
destructures it. props is not hoisted; it is spread as React props on the created element.
DataTableRenderer is declared as ({ schema }) and reads nothing else, so a key written
under props never reaches it.

That is not specific to data-table. It applies to EVERY renderer that reads only schema —
which is the normal shape for the component renderers, as distinct from the element:* family
whose readProps() merges { ...schema.props, ...schema.properties }. So the same key
spelled props is honoured in one renderer family and silently dropped in the other.

props is documented as the annotated legacy alias for the config bag, and the 2026-08-18
ruling recorded on #5123 settled precedence between the two bags (properties wins on both
channels). Neither says the alias is INERT for component renderers, which is what the
measurement above shows.

Why it is not #6665

#6665 was fenced to node-level data, and its diagnostic is deliberately silent here: with
the key under props, node-level data is genuinely absent, so there is nothing for a
data-table-level predicate to honestly say. That silence is pinned by a test in that PR
(does NOT reach into the props envelope) rather than left to be rediscovered. Widening that
predicate to reach into props would patch one component against a repo-wide shape.

What a taker would need to decide first

Whether this is a defect or the declared design. Both readings are available today:

• Defect — an author writes a key the docs call a supported alias, every gate accepts it
  (BaseSchema is .passthrough() with [key: string]: any), and the result is a silent
  drop with a correct-looking header, the same success-receipt shape data-table accepts a bind and silently renders its header over an empty body #6575 and data-table: a ${...} expression authored in node-level data is not evaluated and renders an empty body silently #6665 exist to
  remove.
• Design — props is the React-prop channel, component renderers read schema, and the
  alias was only ever meant for the readProps() family.

If it is a defect, the arms are the familiar three: hoist props like properties (a
behaviour change on published components, so a ruling), diagnose it at the SchemaRenderer
tier (no behaviour change, one place, covers every renderer), or refuse it at parse (blocked
on the .passthrough() ceiling, #5155 / #6269).

Refs: #6665 (where it was measured) - #6575 (the diagnostic precedent) - #5123 (the two-bag
precedence ruling) - #4795 (the properties authoring-channel contract question) - #5155 /
#6269 (the .passthrough() ceiling).

---

Generated by Claude Code

[huangyiirene]

分诊：入决策箱 + 四棱块

定级：needs-user-decision · domain:ui · priority:p1 · type Bug。卡面自己写明「a taker would need to decide first: whether this is a defect or the declared design」，且若判缺陷，其中一条手臂是已发布组件的行为变更 ⇒ 命中人工地板。

<!-- os-decision-facets -->

一句话问题：props 是文档承认的 config bag 别名，BaseSchema 是 .passthrough() 所以每道门禁都收，但对只读 schema 的组件渲染器家族它完全不生效 —— 键被静默丢弃，表头照常渲染。先要裁的是：这是缺陷，还是既定设计。

这不是推演：卡面 leg 2 与 leg 3 同键、同值、只差一层信封，properties 出两行、props 出 No results found。

第一层裁决 × 真实客户可感成本

	判定	代价
设计	props 是 React prop 通道，只有 element:* 家族的 readProps() 合并两个 bag	零代码。但文档必须改口 —— 否则「支持的别名」这句承诺继续骗人
缺陷	别名应当在两个家族都生效	⇒ 进第二层，三条手臂

若判缺陷，三条手臂

• A — 把 props 提升到与 properties 同权（hoist）。⚠️ 已发布组件的行为变更：今天靠 props 传真 React prop 的宿主，会突然看到这些键被 hoist 到 node 上。且 props 与 properties 同现时,alias 优先级按「读法」相反 —— 配置袋读到 properties,React prop 读到 props #5123 已裁过两 bag 的优先级，动这里必须与那条裁决对齐。
• B — 在 SchemaRenderer 层诊断。零行为变更、一个地方、覆盖所有渲染器。⭐ 与 data-table accepts a bind and silently renders its header over an empty body #6575 / data-table: a ${...} expression authored in node-level data is not evaluated and renders an empty body silently #6665 同形，这条路本仓已经走通两次。
• C — parse 层拒绝。⛔ 今天做不到：受 .passthrough() 天花板阻挡（finding(types): BaseSchema's [key: string]: any leaves every component schema open, so a "declare the surface" fix can never reject a misspelled TOP-LEVEL key #5155 / finding(types): ObjectViewSchema's table and form slots declare ZERO properties — the same Omit-under-index-signature collapse as #6151, in property position #6269）。

四棱
① 长远合理性：同一拼写在一半渲染器家族生效、另一半静默失效 —— 二义性长期必然继续咬人。B 不消除二义性但让它可见；A 消除二义性但动已发布行为。
② 业务拉动：实测的作者体验是「写了文档承认的别名 → 空表格 + 正确表头」。⚠️ 但今天有没有真实客户正踩着，没数过（见置信缺口）。
③ 防 AI 犯错 —— 分水岭。⭐ 这是标准的成功回执形状：无报错、无警告、表头看起来完全正确。AI 作者从 element:* 的例子学到「props 可用」，搬到组件渲染器上就静默失效，而且每一道门禁都会放行。B 用最小代价把静默失效变成可见失败。
④ 不扩散：B 是一处诊断，净加法极小；A 需清点宿主；C 被天花板挡住。

推荐：⛔ 本席不裁「缺陷 or 设计」这一层 —— 它是契约语义问题。若判缺陷，推荐 B：零行为变更 + 两次同形先例已验证这条路。A 留到 props 别名整体退役时一起做，不要单独动。

⭐ 置信缺口

没有人数过今天有多少 authored 节点把键写在 props 下。 本仓 fixture / schema-catalog、hotcrm、以及第三方 authored 元数据都没清点过。这个数字直接改变裁决：

• 若为 0 ⇒「设计 + 改文档」就够，连 B 都可能是过度反应；
• 若不为 0 ⇒ 每一个都是今天正在静默失效的页面，优先级要上调，且 B 的诊断得能回溯已有内容。

⇒ 建议裁前先在本仓与 hotcrm 跑一次 authored props 节点清点 —— 成本低，且它可能直接决定答案。

低摩擦裁决格式：回「设计 + 改文档」/「缺陷 → B」/「缺陷 → A」/「先清点」。

裁后执行段：判设计 ⇒ 转 pm:queue，落点 content/docs/**（domain:ui），只改文档措辞。缺陷 → B ⇒ 转 pm:queue，落点 packages/react 的 SchemaRenderer 层。缺陷 → A ⇒ ⛔ 必须先与 #5123 的两 bag 优先级裁决对齐，并清点依赖 props 传真 React prop 的宿主，再走契约档复核。先清点 ⇒ 留决策箱，数字回帖后再裁。

---

Generated by Claude Code

[os-elon]

⚖️ RULED — 2026-08-29, maintainer, live director session batch #2 (session session_016SG9S6V15MqeAgkehDcTwk), verbatim: 「同意」 — adopting option 2 (SchemaRenderer-tier diagnostic): when a component-renderer node (outside the element:* readProps() family) carries a props config bag, SchemaRenderer emits a loud diagnostic naming the node and pointing at properties — one seam, every renderer family covered, zero behaviour change. ⛔ Not option 1: hoisting would weld the legacy alias in as a permanent second spelling — the opposite of this repo's alias-retirement direction (the timeScale precedent). Option 3 stays blocked on the .passthrough() ceiling (#5155/#6269).

Precondition fixed at ruling: census before diagnostic level — measure component-level props usage across the in-repo corpus first; if usage is wide the diagnostic's level/dedup is tuned so it informs rather than floods, and the census lands in the PR as evidence. Pins both directions: props bag on a component-renderer node ⇒ diagnostic fires; element:* node or a plain properties node ⇒ silent.

Ruled here; execution routes through the normal dispatch lanes (this seat adjudicates only — maintainer seat-boundary instruction of the same session). Card returns to the queue as ruled work.

---

Generated by Claude Code