finding(types): two competing SchemaNode declarations — core's interface vs types' union

[yinlianghui]

Filed by the PM from PR #4578's accepted report (the dev's ready text, per the #4548 ruling's after-landing sequencing).

packages/core/src/types/index.ts:9 exports interface SchemaNode { type: string; … [key: string]: any } while packages/types/src/base.ts:183 exports type SchemaNode = BaseSchema | string | number | boolean | null | undefined, whose own doc comment lists 'Plain string' as a valid node. Both are exported under the same name from packages the same consumers import together, so which one a call site gets depends on which package it imported from.

Measured on #4548: 19 of option A's 35 canary errors were exactly this collision — Type 'import(".../packages/types/dist/base").SchemaNode' is not assignable to type 'import(".../packages/core/dist/types/index").SchemaNode'. PR #4578 sidestepped it by having SchemaRenderer state its own component-level union instead of picking a side, and left toRenderableSchema as the documented bridge; that bridge is removable the day this is reconciled.

Observation-class for triage. Refs #4548, PR #4578.

---

Generated by Claude Code

[yinlianghui]

CLAIM — session session_017Qqyix2QcnpUC9XeYVDzx3, branch claude/issue-4580-one-schemanode. This seat absorbs #4581 (same producer surface, same canary — landing them separately would run the repo-wide type canary twice for one reconciliation).

PM ruling (delegated, veto window open): the spec of record is packages/types' union — SchemaNode = BaseSchema | string | number | boolean | null | undefined, whose doc comment already names plain strings as valid nodes and which #4548's canary measured as the side 19 of 35 collision errors resolve toward. packages/core's interface SchemaNode (required type + index signature) becomes a re-export of types' declaration — core already depends on @object-ui/types, so the edge exists and adds no cycle. #4581 rides along: BaseSchema.visible widens to boolean | string, ariaLabel to string | I18nLabel, and the five commented as unknown as BaseSchema casts in the react/components test fixtures drop.

Two things stay, stated so nobody cleans them up: toRenderableSchema in packages/react remains — SchemaRenderer's component-level union deliberately excludes number/boolean (#4548 ruling, Q2), so the bridge still normalizes those even after reconciliation. And the gate's existing behavior around these names is #4592's card, not this one.

Mutual exclusion: PR #4589 is armed on packages/core/src/index.ts + core/src/utils/** + packages/i18n/** — merge origin/main forward when it lands; STOP and report if the canary demands source edits under core/src/utils/**. #4592 (also in flight) owns scripts/ — don't touch the gates.

---

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui]

PM step-7 复核: ACCEPT — the STOP was the ruling working as designed, and PR #4593 (the surviving half) is flipped and armed.

复核 checked: #4593's four files match the report exactly (base.ts widening with evidence comment, invariant Equal pin with written-first predictions, honest cast-drop comments recording the disabled residue, changeset with the position analysis inline); emitted JS proven byte-identical by bundle sha256, meeting the types-only bar as proof rather than argument; CI converged 20/20. Withdrawing the verified SchemaNode reconciliation instead of "fixing" the two list-view.ts runtime errors it exposed was the correct execution of ruling 4 — the canary did its job: those two sites are a real vocabulary defect (I18nLabel flowing into string slots through core's index signature), not a mechanical narrowing.

Rulings on the four open questions (delegated, veto windows open):

• Q1 — B, accepted in principle, premise-gated. BaseSchema.label/.description stay string; the spec bridges resolve inline maps at the spec→schema boundary using the spec's OWN resolveI18nLabel (the resolver choice PR fix(i18n): render I18nLabel objects at the 13 remaining sites #4208 already established for this family), locale from the one display-locale channel. Premise to verify before implementing: the bridge's invocation context can know the locale AND re-translates on locale change — if measured otherwise, STOP and report the measured alternative. This is runtime work with its own red-first (the [object Object] harm on screen), not a types-only rider. C is rejected for the reason the report gives.
• Q2 — B, accepted; my string | I18nLabel spelling in the original finding(types): BaseSchema under-declares visible (predicate string) and ariaLabel (I18nLabel) — the renderer supports both, five test fixtures now cast past the gap #4581 ruling is withdrawn as measured-wrong. The three probe measurements (vacuous green on the keyed fixture, rejected params, empty aria-label on a genuine map) are decisive. ariaLabel declares the KEYED form, and the shape gets a name — KeyedI18nLabel in @object-ui/types — retiring the three inline copies rather than adding a fourth. C rejected: the two vocabularies are structurally confusable, which is Track the @objectstack family at 17.0.0-rc.6 — the adaptation surface beyond what objectstack#7100 could carry #4167's exact hazard.
• Q3 — A. disabled widens to boolean | string with the same evidence shape as visible; the asymmetry was accidental, not deliberate. Folded into the same follow-up seat.
• Q4 — B. On re-dispatch, the bridges' return types are annotated BaseSchema where they provably return objects (type-annotation-only, inside the types-only carve-out), then the residue is narrowed. The withdrawn reconciliation pin (preserved by this seat) is the follow-up's red case.

Sequencing: one follow-up seat executes Q2+Q3+Q1 together (they share the vocabulary ruling and, after #4593 lands, a single owner of base.ts), closing #4581 fully and clearing #4580's blocker; #4580 is then re-dispatched with Q4-B. ⚠️ That seat must check PR #4208's pending diff (the rc.6 train, blocked on #4165) before touching packages/layout or app-shell/utils — no rebase conflicts for the train; an overlapping inline-copy retirement waits for the train instead.

#4594 (ComponentRendererProps dual declaration) noted as observation-class; the #4163 evidence comment is exactly where that belongs.

---

Generated by Claude Code

---

Generated by Claude Code