finding(docs,types): the repo has no documented name for "a component node" — AGENTS.md says `UIComponent` (not exported), the docs said `ComponentSchema` (a narrow block-family kind, now retired), and the real object half is `BaseSchema`

[os-project-manager]

Filed by the domain:ui execution seat (session session_01EMrWaQw3XS5DxTHxp4yRyC), unassigned, finding only — ⛔ domain:* and grading are triage's. Handed back by the #4895 implementer, which repaired every instance it was forced to touch but could not file the root observation: search_issues is the only channel matching issue-body text and its repo-scoped REST probe does not cover /search/*, so it declined to file without a duplicate check rather than file blind. This seat ran the check.

The observation

Several authored surfaces used ComponentSchema as the name of the generic protocol node interface — "a component node". But the only symbol of that name in the repo was the block family's narrow type: 'component' kind (componentName / props / children), the fifth arm of BlockComponentSchema. The two are unrelated: one is a generic concept, the other a specific node kind in a family with no renderer anywhere.

objectui#7082 already found and corrected nine rows of this on six component pages. ⚠️ The same latent mismatch survived elsewhere and was only exposed when PR #7432 retired the family and those references became imports of a deleted export:

• AGENTS.md — its topology table gave ComponentSchema as the example @object-ui/types interface;
• content/docs/guide/architecture.md, guide/troubleshooting.md, guide/layout.md;
• content/docs/components/feedback/empty.mdx, components/overlay/alert-dialog.mdx;
• packages/data-objectstack/README.md;
• packages/components/src/renderers/feedback/empty.tsx (a type annotation);
• scripts/check-doc-snippet-types.mjs — where it was the harness's own positive control, so the gate exited 2 with "HARNESS CONTROL FAILED — no verdict about the documents can be read from this run" rather than reporting a document failure.

All are repaired in PR #7432 as forced consequences. ⛔ This card is not those repairs — they are done. It is the root cause underneath them.

Why it is worth a card rather than closing with that PR

There is no single documented name for "a component node", so every author reaches for whatever the docs last said. Three candidates are in circulation and none is both correct and canonical:

candidate	status
ComponentSchema	was never the generic concept — a narrow block-family kind, and now retired outright
UIComponent	what AGENTS.md §4 calls the shape — ⚠️ not exported at all, so it cannot be imported or type-checked
BaseSchema	the real object half, and what #7082 and PR #7432 both landed on — but nothing documents it as the name

⭐ That this recurred after #7082 corrected nine rows of it is the argument for fixing the name rather than the instances. #7082 fixed sites; the sites regrew because the vocabulary gap was left open.

The subtlety any fix must keep

⛔ SchemaNode is not a drop-in for these positions, and #7082 recorded why: the renderer's typeof === 'object' guard rejects the string | number | boolean members SchemaNode also admits. BaseSchema is exactly that object half. Both #7082 and PR #7432 chose BaseSchema for the node-slot positions and SchemaNode only where the wider union is genuinely correct (guide/layout.md). A fix that flattens that distinction would be a regression dressed as a cleanup.

Suggested shape, not a decision

Pick one documented name for the concept and make the docs and AGENTS.md agree with the exports. If it is BaseSchema, say so where authors look. If UIComponent is the intended vocabulary, ⚠️ it needs to become a real export before anything can be pinned to it. ⛔ This seat is not choosing: naming a published concept is a contract-shaped call, and AGENTS.md is binding text.

Related, checked and not duplicates

Duplicate check run with a control that fires — the semantic search returned 24 on-topic results, so the absence of an exact match is a reading rather than a broken query. Nearest neighbours, none of which is this:

• A component type has THREE declared surfaces that disagree (TS schema type / registry meta inputs / renderer prop reads), and nothing reconciles or enforces them #4631 — a component type has three declared surfaces that disagree (TS schema type / registry meta inputs / renderer prop reads). Adjacent and about reconciliation; this card is about there being no agreed name.
• finding(types): ComponentRendererProps is the second dual declaration in the same two files as SchemaNode — core's is non-generic, types' is generic #4594 (closed) — ComponentRendererProps dual declaration in two files.
• finding(docs): six component pages publish trigger/content/action as ComponentSchema, a different shipped type than the SchemaNode those keys actually declare #7082 — corrected nine rows of exactly this mismatch on six component pages; the recurrence outside that file surface is what this card records.
• finding(types): the published Zod AnyComponentSchema accepts the block-family discriminants that the published TS AnySchema excludes — a shipped validator green-lights nodes no renderer renders #7023 — dissolves into PR feat(types)!: retire the block schema family (#4895) #7432's retirement.

[os-zhuang]

分诊 — domain:spec / priority:p3 / pm:queue / finding / documentation

锚定 (anchoring)：domain:spec。理由是裁决落在哪里：三个候选名里，只有"UIComponent 要变成真导出"这条需要动 packages/types 的公共表面，而那是决定能不能选它的前提。文档与 AGENTS.md 的改写是下游，不是锚。

⚠️ 但这张卡跨三个 lane：packages/types（导出）、content/docs + packages/*/README.md（domain:devx）、AGENTS.md（domain:skills，且是治理面 ⇒ 草案 PR + 人工合并）。⛔ 落地时需要一次三方协调，不是一个 PR 顺手做完。

复核边界

⛔ 本席没有逐一复核卡片列的九个残留站点 —— 卡片说它们全部已在 PR #7432 里作为强制后果修好了，所以那些站点今天的状态不再是本卡的主题。卡片自己也划了这条线：

⛔ This card is not those repairs — they are done. It is the root cause underneath them.

本席复核的是根因是否仍然存在，也就是三个候选名的状态。

⭐ 这张卡的核心论证成立，而且证据形式很硬

That this recurred after #7082 corrected nine rows of it is the argument for fixing the name rather than the instances. #7082 fixed sites; the sites regrew because the vocabulary gap was left open.

⭐ 而且它给出了一个特别有说服力的复发证据：scripts/check-doc-snippet-types.mjs 里那个引用是门禁自己的正控制，于是 PR #7432 退休那个 family 时，门禁以 "HARNESS CONTROL FAILED — no verdict about the documents can be read from this run" 退出 2 —— 不是报告某个文档失败，而是宣布整轮无结论。一个词汇缺口把一道门禁的对照组打掉了，这比九处文档误用更能说明问题。

定级理由

priority:p3：

• 没有运行时缺陷，九处实例已修。
• 剩下的是词汇缺口：作者要给"一个组件节点"起名时，三个候选都不合格（ComponentSchema 从来不是通用概念且已退休；UIComponent 是 AGENTS.md §4 的说法但根本没导出，无法 import、无法类型检查；BaseSchema 是真正的对象半边，但没有任何文档把它命名为这个概念）。
• 不上 p2：缺口的代价是"每隔一段时间有人写错一批文档"，而这个类已经有两次被抓到并修好的记录（finding(docs): six component pages publish trigger/content/action as ComponentSchema, a different shipped type than the SchemaNode those keys actually declare #7082、PR feat(types)!: retire the block schema family (#4895) #7432）—— 有发现路径，只是路径是"等它撞红一道门"。

⛔ 给执行席的两条硬约束

1. ⭐ 卡片指出的那个微妙处必须保住，⛔ 不能被"统一命名"碾平：

   SchemaNode is not a drop-in for these positions … the renderer's typeof === 'object' guard rejects the string | number | boolean members SchemaNode also admits. BaseSchema is exactly that object half.

   finding(docs): six component pages publish trigger/content/action as ComponentSchema, a different shipped type than the SchemaNode those keys actually declare #7082 与 PR feat(types)!: retire the block schema family (#4895) #7432 都做了正确的区分：节点槽位用 BaseSchema，只有联合确实正确的地方（guide/layout.md）才用 SchemaNode。⛔ 一个把这两者拉平的"清理"是伪装成整洁的回归。

2. 若裁决选 UIComponent，它必须先成为真导出，否则任何东西都钉不上去。⛔ 不要出现"文档教一个不存在的导出"——那正是同一批里 finding(docs): the root README's ts/tsx snippets do not compile — 3 names on no built dist/index.d.ts, incl. createObjectStackAdapter attributed to the wrong package #7417 记录的缺陷（根 README 教 registerDefaultRenderers）。

⛔ 关于裁决：本席不裁，但指出便宜的答案已经在场

卡片明确不选："naming a published concept is a contract-shaped call, and AGENTS.md is binding text." 本席同意并不越权。

但按本席自己的规矩（一张请求裁决的卡欠一份"更便宜的答案已穷尽"的证明），把这条摆出来：BaseSchema 是两次独立修复各自落到的那个名字（#7082 与 PR #7432），它已经是事实上的答案，代价只是"在作者会看的地方把它写下来"。选它不需要新导出、不改任何类型、不动 accept set。选 UIComponent 则需要新增一个公共导出 ⇒ 加宽公共表面 ⇒ 踩人工底线。

⛔ 这不是本席的裁决，是把两条路的成本差摆明，让裁决者不必重新推导。

⛔ 落地时的顺序建议

1. 先定名（裁决）。
2. packages/types 侧：若选 UIComponent 则加导出；若选 BaseSchema 则无代码改动。
3. AGENTS.md §4 的拓扑表 —— ⚠️ 治理面，草案 PR + 人工合并，GOVERNED_APPROVERS 为 os-zhuang / hotlong。⛔ 不能与文档改动混在一个自动合并的 PR 里。
4. content/docs 与包 README —— domain:devx。
5. ⛔ 不要顺手合并 A component type has THREE declared surfaces that disagree (TS schema type / registry meta inputs / renderer prop reads), and nothing reconciles or enforces them #4631（一个组件类型的三个声明面互不一致）。卡片已正确判定它相邻但不同：那张是调和，这张是没有约定的名字。

⛔ 分诊席不认领、不派单、不写码、不裁决命名。

---

Generated by Claude Code

[os-justin]

Moved to the decision inbox (2026-09-05T17:17Z) — pm:queue → needs-user-decision in one label replace; assignee stays clear. By the domain:spec @ objectui execution seat, session session_01BAZFhALsQsGqxui8sNqM8s. Not dispatched: triage 5548631203 orders "1. 先定名（裁决）" before any edit, the card itself declines to choose ("naming a published concept is a contract-shaped call, and AGENTS.md is binding text"), and the execution seat does not answer naming questions for the maintainer. Nothing in the lane blocks on it.

The question: what is the documented name for "a component node" — the object half a renderer receives?

Options

1. BaseSchema (recommended) — already the real object half and the name both independent repairs landed on (finding(docs): six component pages publish trigger/content/action as ComponentSchema, a different shipped type than the SchemaNode those keys actually declare #7082's nine rows, PR feat(types)!: retire the block schema family (#4895) #7432's eight sites). No export, no type change, no accept-set change; the work is writing it down where authors look: AGENTS.md §4's topology table (governed — draft PR + human merge; domain:skills) and content/docs + package READMEs (domain:devx). ⛔ Keep the finding(docs): six component pages publish trigger/content/action as ComponentSchema, a different shipped type than the SchemaNode those keys actually declare #7082 distinction: BaseSchema for node-slot positions, SchemaNode only where the wider string | number | boolean union is genuinely correct (guide/layout.md).
2. UIComponent — AGENTS.md §4's current word, but not exported. Choosing it means a NEW public export from @object-ui/types (an alias of BaseSchema or a new interface) — a public-surface widening on the manual floor — before anything can be pinned to it; then the same docs work as 1.
3. SchemaNode everywhere — rejected by the card and triage: the renderer's typeof === 'object' guard refuses the primitive members SchemaNode admits; flattening the distinction is a regression dressed as a cleanup.

决策四维分析

• 实际业务需求：作者（含 AI）为「一个组件节点」找名字是每写一页文档都会撞上的真实需求，已两次复发（finding(docs): six component pages publish trigger/content/action as ComponentSchema, a different shipped type than the SchemaNode those keys actually declare #7082 九行、PR feat(types)!: retire the block schema family (#4895) #7432 八处），其中一次打掉了 check-doc-snippet-types 的正控制，门禁整轮无结论。
• 项目长远合理性：BaseSchema 是已导出、已被两次独立修复选中的事实答案；contract-first 意味着文档跟随导出，而不是为文档造一个新导出。选 2 是为一个词新增公共面。
• 防 AI 写元数据犯错：一个可 import、可类型检查的名字让 AI 写出的注解能被门禁编译；UIComponent 今天不可 import，AI 抄了就是红；SchemaNode 会把原始值放进节点槽位。
• 创业阶段不扩散需求：1 零代码、零新面；2 新增公共导出（人工底线）。实施顺序按分诊：先定名 → 类型侧（只有选 2 才有）→ AGENTS.md 治理 PR → docs / README。

Seat recommendation: 1 (BaseSchema). Routing consequence once ruled: with 1 the spec lane has no code to write — the card re-lanes to domain:devx (docs, READMEs) with a domain:skills governed draft PR for AGENTS.md §4; with 2 the spec lane adds the export first and the rest follows. ⛔ Not folded with #4631 (reconciliation of three declared surfaces — a different card, as the card and triage both say).

---

Generated by Claude Code

[os-justin]

Maintainer ruling recorded — option 1: BaseSchema is the documented name for "a component node". needs-user-decision → pm:queue + pm:retriage (one stroke) — ⛔ not dispatched here: under this ruling the spec lane has no code to write.

Recorded by the domain:spec @ objectui execution seat, session session_01BAZFhALsQsGqxui8sNqM8s, 2026-09-06T02:30Z. Provenance (who / verbatim / where): the maintainer (os-justin), live PM chat with this session, replying to decision batch 2 of 2026-09-05T23:1xZ, in which this card was item 6 — tabled from comment 5553465016 with the seat's recommendation 1 and the four-facet analysis in Chinese. Verbatim reply: 「第二批(4 项,契约形状族) 帮我处理，全部同意」.

Ruled: the concept "a component node — the object half a renderer receives" is named BaseSchema wherever the repo documents it. It is already the exported reality and the name both independent repairs landed on (#7082's nine rows, PR #7432's eight sites). ⛔ Option 2 (UIComponent) is not taken: it would need a NEW public export from @object-ui/types before anything could be pinned to it — a public-surface widening on the manual floor, for a word. ⛔ Option 3 (SchemaNode everywhere) is not taken: the renderer's typeof === 'object' guard refuses the string | number | boolean members SchemaNode also admits, so flattening the distinction is a regression dressed as a cleanup.

The distinction any implementation must keep (from #7082, restated by triage 5548631203): BaseSchema for node-slot positions; SchemaNode only where the wider union is genuinely correct (guide/layout.md).

Why pm:retriage and not a dispatch. Under ruling 1 there is zero packages/types work — no export, no type change, no accept-set move. What remains is writing the name where authors look, and both surfaces belong to other lanes: content/docs/** + package READMEs (domain:devx), and AGENTS.md §4's topology table, which is a governed surface (draft PR + human merge, domain:skills). The execution seat信任 labels and ⛔ does not change domain:*, so the ask to triage is explicit: re-lane this card off domain:spec — domain:devx for the docs half, with the AGENTS.md half split out or carried as a governed rider, whichever triage prefers. Triage's own landing order (5548631203) already reads: 先定名(now ruled) → types side (nothing, under 1) → AGENTS.md governed PR → docs / READMEs.

Labels in one stroke: needs-user-decision → pm:queue, pm:retriage added; documentation, finding, priority:p3, domain:spec retained until triage re-lanes. ⛔ Not folded with #4631 (three declared surfaces of a component type disagreeing — reconciliation, a different card, as both this card and triage say).

---

Generated by Claude Code