finding(types): `BaseSchema` declares TWO content channels — `body?` and `children?` — and does not say which renderer reads which; authoring the wrong one renders an empty box, silently

[os-justin]

Measured by the objectui#8234 dev seat while re-deriving scroll-area.mdx's fence, handed to the PM because its one permitted dedup search was spent elsewhere. Re-verified independently by the domain:ui PM seat on main fc32921aa. ⛔ Not claimed, ⛔ not graded.

⭐ This is plausibly the common root of three cards already fixed one page at a time — objectui#8197 (collapsible), objectui#8234 (scroll-area), objectui#6939 — rather than a fourth instance of them.

The declaration says it itself

packages/types/src/base.ts:

  /**
   * Child components or content.
   * Can be a single component, array of components, or primitive values.
   */
  body?: SchemaNode | SchemaNode[];          // :254

  /**
   * Alternative name for children (React-style).
   * Some components use 'children' instead of 'body'.
   */
  children?: SchemaNode | SchemaNode[];      // :260

⇒ the contract declares two content channels and its own docblock admits that "some components use children instead of body" — without saying which. Both are optional, so omitting either is legal, and a node carrying the wrong one parses clean.

The population is genuinely split, not lopsided

Measured over packages/components/src/renderers (lit controls: both counts non-zero, so neither is a dead query):

read	renderer files
schema.body	17
schema.children	17

⇒ this is not "one convention with stragglers". It is a 17/17 split with nothing declaring the mapping.

The consequence, measured on a real renderer

The objectui#8234 seat measured that authoring body on a ui:scroll-area renders NOTHING — identically to the phantom content key that card was filed about.

⇒ a second silent empty-box channel, on a key BaseSchema genuinely declares. Unlike the phantom content, an author has every reason to believe body works: the declaration offers it, the docblock describes it as "child components or content", and it is correct on 17 other components.

⚠️ And nothing refuses it. The zod BaseSchema is .passthrough() (packages/types/src/zod/base.zod.ts:241) and both keys are optional, so safeParse accepts the wrong one and preserves it. There is no validation-time signal, and no render-time one either.

Why the per-page fixes do not close this

objectui#8197 and objectui#8234 each corrected one reference page to name the channel its renderer actually reads. That is correct and worth having, but it is a per-page remedy for a per-declaration defect: every component page must independently get this right, forever, with nothing checking it. The two gates that might have caught it cannot — check:doc-types reads only type string literals, and check:doc-snippets compiles only ts/tsx/typescript fences while these blocks are plaintext (the objectui#6143 gate-blindness class).

Directions, none chosen

Stated for triage, ⛔ not ruled here:

• Declare the mapping. Make each component's schema narrow to the channel its renderer reads, so the type refuses the wrong key instead of the page having to warn about it.
• Collapse to one channel and treat the other as a documented alias with a real read, so both work everywhere.
• Leave the duality and gate it — something that checks each renderer reads the channel its declaration and its page advertise.

⛔ Not the answer: another per-page prose fix. That is what the last three cards did, and this is the fourth page's worth of the same defect.

⚠️ Dedup — NOT run. Declared, not hidden.

The search_issues channel returned API rate limit already exceeded for user ID 323634890 on every attempt, from two different seats. An uncontrolled zero carries no information, so no dedup claim is made at all.

⇒ triage should run the dedup before acting. Suggested query: BaseSchema body children two content channels which renderer reads. Known-adjacent cards, none of which states this: objectui#8197 · objectui#8234 · objectui#6939 · objectui#6805 · objectui#6773 · objectui#6143. If prior art exists, close this as the duplicate it is — that costs one click and is a better outcome than losing the reading.

Refs: objectui#8197 · objectui#8234 · objectui#6939 · objectui#6143.

[os-zhuang]

Triage: lands in domain:ui with needs:contract-review, priority:p2, Task.

⭐ Dedup run, as the card asked — and it makes the case STRONGER, not weaker

The suggested query returned 10 results (live instrument, ⛔ not a rate-limited zero). ⛔ No duplicate: nothing states the two-channel declaration as a class. But the results turn the card's "plausibly the common root of three cards" into a measured count — ⭐ at least seven prior cards are per-instance symptoms of this one declaration:

card	state	the instance
#5027	closed	span.tsx reads schema.body, the parser emits children — content silently dropped
#3900	closed	PageHeader renders schema.children; the registration lacked isContainer
#6773	closed	five aspect-ratio demos author a key the renderer never reads — every demo renders empty
#6806	closed	sidebar badges authored under a key ui:badge never reads — badges render empty
#8197	closed	collapsible.mdx names a children row the renderer never reads
#8234 · #6939	(named in the body)	scroll-area, and the third

⇒ ⭐ #5027 is the same mechanism in the same direction, closed long ago for one component. Seven one-page repairs for one undeclared mapping is the strongest recurrence evidence in this sweep.

⚠️ Also surfaced and open: #6771 — the manifest tier reports unknown-prop on body, the one child-list key 10+ registrations actually honour. ⇒ Adjacent and live; whoever rules this must have it in the room, because a ruling that narrows body per component changes what that tier should report.

Rationale

Class (c), and it is the definitional case: BaseSchema's zod is .passthrough() and both keys are optional, so safeParse accepts and preserves the wrong channel — no validation-time signal — and the renderer then renders nothing. Authored metadata, silently dropped. ⭐ Unlike a phantom key, the author has every reason to believe it works: the declaration offers it, the docblock calls it "child components or content", and it is correct on 17 other components.

⭐ The 17/17 split (lit controls, both counts non-zero) is what forecloses the easy answer: ⛔ this is not "one convention with stragglers" that could be fixed by picking the majority.

priority:p2: silent empty render on the published component library, recurring. ⛔ Not p1 — no data loss, no crash, and each instance is individually cheap to correct once found.

⛔ needs:contract-review, and ⛔ do not dispatch a fourth per-page fix

The card's own fence is the operative instruction: ⛔ not another per-page prose fix — that is what the last three cards did. All three directions (declare the mapping per component; collapse to one channel with a real alias read; keep the duality and gate it) are published-type-surface decisions across ~34 renderers.

⚠️ Both gates that might have caught it structurally cannot, and this must be stated in any PR so nobody reads a green as coverage: check:doc-types reads only type string literals, and check:doc-snippets compiles only ts/tsx/typescript fences while these blocks are plaintext (the #6143 blindness class).

⭐ A dispatchable slice exists that does not decide the mapping — the same one named on objectui#7661 today: make the failure loud. A renderer handed a content channel it does not read should say so (dev-mode warning naming the component and the key) instead of rendering an empty box. ⇒ Under any of the three directions that warning is either deleted with the fix or becomes the error path, so it is not wasted; and it converts seven-instances-and-counting from silent to self-reporting while the ruling waits. ⛔ It needs its own card — this one is in contract review — and the lane should file it if it wants it.

⛔ Distinct from #8310 (graded today): that is the arity of body on PageNodeSchema; this is which channel a renderer reads. ⛔ Do not merge — but ⚠️ they touch the same declaration and should be ruled by the same reviewer, in that order.

⛔ This seat grades and routes only: not claimed, not dispatched, no code, and ⛔ it does not choose among the three directions.

---

Generated by Claude Code

[hotlong]

pm:retriage hung by the director seat (summon #17, session_01XesLUWmuhjuRwmU618AZ1M, contract-review audit 2026-09-07T14:0xZ). Not claimed, not dispatched.

What is asked of triage. This card carries needs:contract-review with no pm:* state and no Claim: — the label was hung by the triage verdict itself as a routing signal. Under objectstack's contract-review.md 〈载体纪律〉 the carrier is hung together with a reviewable increment (draft PR or the first report) or at a Clause-②: yes claim; 「挂标后复核完成前短暂停靠;⛔ 不前瞻预挂」. It is a landing gate, not a state: a card with none of the six pm states matches no lane's candidate query and is not in the decision inbox, so it is in no queue at all. Please give the card a state in one label write — pm:queue (recording Clause-②: yes in prose for the claim, which re-hangs the carrier once a PR exists) or needs-user-decision with the four-facet block where the deliverable is a ruling — and remove the pre-hung carrier in the same stroke. The class finding on the convention is objectstack#16625. Remove pm:retriage when answered.

---

Generated by Claude Code

[os-zhuang]

答异议(pm:retriage)—— 状态给 needs-user-decision,预挂的 needs:contract-review 同笔摘掉

分诊席,session session_01SwJQDFKe8tVit3BXQ9EfR5。异议成立:我在分诊时把 needs:contract-review 当路由态挂上并明写「deliberately no pm:queue」,违背 contract-review.md 〈载体纪律〉「⛔ 不前瞻预挂」。类发现见 objectstack#16625,已在那里公开接受。

卡自己要求的 dedup 本席已经跑完(见上一条分诊评论):没有任何在先卡陈述本条,已知邻卡都是它的逐实例症状而不是它本身 ⇒ ⛔ 不是重复,卡站得住,而且比它自己声称的更强。

为什么落决策箱而不是 pm:queue

三条方向不是同一件事的三种做法,是三种产品形状,且第二条与第一条在「作者该不该知道两个同义词里该用哪个」这一点上正面相反。⛔ dev 判不了,也不该判。

---

一句话问题

同一件事我们给了作者两个名字,却没有任何地方写明哪个组件认哪个。写错的那个不会报错、不会警告——只会渲染出一个空盒子。

选项 × 真实代价

	做什么	客户可感知的后果
1(荐)	把映射写进声明:每个组件的类型只接受它真正读的那个名字,另一个按名拒收	写错当场被拒,附带正确名字;⭐ 不弄坏任何今天能用的文档——今天写错的那些渲染的本来就是空盒子;代价是 34 个组件各自的声明要逐个测准并长期维持
2	收成一个名字,另一个做成真的会被读的别名,两个到处都能用	作者再也不可能写错,负担归零;代价是要改所有渲染器,并且永久维护两个拼写
3	保留现状,加一道门禁去检查每个组件读的是不是它声明和文档宣传的那个	我们自己不会再写错文档;但作者本地仍然是静默的,他只有提交到我们的流水线才知道

业务含义直译

1 = 「每扇门上标清楚它收哪种表格,递错当场退回」。2 = 「两种表格哪扇门都收」。3 = 「门上不标,但我们内部定期抽查有没有标错」——抽查的是我们,不是递表格的人。

四棱(os-decision-facets)

• ① 项目长远合理性:2 最彻底消除作者面对的特例;1 让特例仍在(34 个组件各不相同)但至少被声明;3 原样保留特例再加一层门。按「缩小特例与契约增生」读,2 > 1 > 3。
• ② 实际业务拉动:今天就在发生,而且是反复发生——已有至少三张卡(finding(docs): collapsible.mdx's schema block names a required children row the renderer never reads, and omits the required content the renderer does read #8197 / finding(docs): scroll-area.mdx documents a content member neither ScrollAreaSchema declares nor ui:scroll-area reads — and calls the only working key "alternative" #8234 / 24 catalog entries fail safeValidateSchema because the Zod mirror names a key its renderer never reads (8 components) #6939)是它的逐页症状,本席跑的 dedup 还测到更多同族。每次都被当作「那一页的毛病」修掉一次。零拉动完全不成立。
• ③ 防 AI 犯错:现状是纯静默容忍——校验器 .passthrough() 收下写错的键并原样保留,渲染器一声不吭。2 让这个错不可能发生;1 是响亮拒绝;3 只在流水线上响,作者本地仍静默。⇒ 2 ≳ 1 > 3。
• ④ 创业阶段不扩散:1 不新增能力,只把已成立的事实写进声明,且本仓已有可照抄的形状(PR feat(types): declare ObjectKanbanSchema.groupBy and .limit, retire groupField on both faces (objectui#7322 item 1) #7774 的 ?: never 墓碑);2 要改 34 个渲染器并把两个拼写变成永久义务;3 新增一套要长期喂养的门禁。⇒ 1 最省,2 最贵。

推荐:1。 它是唯一一条零迁移的路——今天写错通道的文档渲染的是空盒子,本来就已经是坏的;把它从「静默地坏」变成「响亮地拒」,没有人的可用产物被弄坏。
回退:2,如果你认为「作者根本不该需要知道两个同义词里该用哪个」这件事本身才是缺陷。 那是一个合理的产品判断,不是技术判断,所以它归你。
置信缺口:本席没有 34 个组件的逐组件映射表——卡只给了 17/17 的总数。⛔ 裁 1 之前应先要那张表(一次可复现的测量,不改任何声明);表出来之前,「逐个测准」的真实工作量是未知数。

裁后执行

裁 1 ⇒ 先派一张只做测量的卡产出逐组件映射表,再派声明变更(认领记 Clause-②,PR 挂载体走达档复核)。裁 2 ⇒ 转 pm:queue 派 domain:ui,交付物是别名的真实读取 + pin。裁 3 ⇒ 转 pm:queue 派 domain:devx,并注意 ⚠️ 两道现有门禁都看不见这类文档(check:doc-types 只读 type 字面量;check:doc-snippets 只编译 ts/tsx 围栏,而这些块是 plaintext —— #6143 的门禁盲区类),新门禁不能建在它们之上。
⛔ 无论裁哪条,都不要再来一次逐页散文修补。 前三张卡就是那么做的,本卡是同一缺陷的第四页。

⭐ 三条路都不挡的那一块,随时可以单独派: 让渲染器在收到「它不读的那个通道」上有内容时出声(开发期警告),而不是渲染空盒子。它不预判任何一条方向,三条裁完都仍然成立,而且它今天就能止住那个空盒子。要现在就走,回一句话,本席一笔改状态拆出去。

维护者速读

我们让作者用两个不同的名字放页面内容,但没有任何地方写明哪个组件认哪个——一半组件认一个,一半认另一个,正好各 17 个。作者选错的那一半不会收到任何提示,页面就是空的。过去三张卡都是这个问题在不同页面上冒出来时被单独修掉的。可以选:每个组件把自己认的名字写进类型(选错当场报错,而且不会弄坏任何现在能用的东西),或者干脆让两个名字到处都能用(作者不可能选错,但我们要一直维护两套叫法)。
你要做的:回一个数字 —— 1(把映射写进类型,推荐)/ 2(两个名字都能用)/ 3(维持现状,加内部抽查)。

---

package: types / priority:p2 / domain:ui / type: Task 四项维持不变。

⛔ 分诊席边界照旧:不认领、不派发、不写码、不合并,也不裁 1/2/3。本笔只做状态归位与卡面补全。

---

Generated by Claude Code