finding(types): 18 schemas narrow inherited `disabled` to `boolean` while 0 narrow its twin `visible` — no ruling says which is intended

[os-sam]

Observation, filed unassigned while correcting the BaseSchema common-props table for #7079. This is a declaration question, not a docs question, so it is filed rather than decided. The docs correction went ahead on its own footing: the table documents BaseSchema, and BaseSchema is what a node gets when its own schema does not restate the key.

What was measured

Read off packages/types/src/** on origin/main at 592acafbe, excluding __tests__ and zod/. Each <key>?: declaration was attributed to its enclosing exported interface, and that interface checked for extends BaseSchema.

124 interfaces extend BaseSchema. Of those, the number that redeclare an inherited member more narrowly than the base union:

base member	base declaration	extenders that narrow it	narrowed to
visible	boolean | string	0	—
disabled	boolean | string	18	boolean
label	string | I18nLabel	29	string (4 of them required)
description	string | I18nLabel	32	string
ariaLabel	string | KeyedI18nLabel	1	string (PageNodeSchema)

The 18 narrowing disabled: ActionSchema (crud.ts:89), CollapsibleSchema (disclosure.ts:109), ToggleGroupSchema (disclosure.ts:173), and fifteen in form.ts — ButtonSchema, InputSchema, TextareaSchema, SelectSchema, CheckboxSchema, RadioGroupSchema, SwitchSchema, ToggleSchema, SliderSchema, FileUploadSchema, DatePickerSchema, CalendarSchema, InputOTPSchema, FormSchema, ComboboxSchema.

A further 13 declarations of disabled?: boolean sit on shapes that do not extend BaseSchema at all (ListItem, NavLink, ButtonGroupButton, SelectOption, RadioOption, FormField, ComboboxOption, SelectOptionMetadata, MenuCommandItem, AccordionItem, ToggleGroupItem, TabItem) plus ColorPalette.disabled?: string, an unrelated colour-token vocabulary. Those are independent declarations, not narrowings, and are counted separately on purpose.

Control: the census attributes BaseSchema's own disabled?: boolean \| string to BaseSchema and excludes it from the narrowing count.

Why the asymmetry is the finding, not the narrowing

visible and disabled are twins by construction. Both were widened to boolean | string by #4581 on the same evidence — the renderer does not read either key as a boolean, it passes both to evaluator.evaluateCondition, declared (condition: string | boolean | undefined, context?) => boolean. base.ts:320-325 records that the previous asymmetry between them was "accidental rather than deliberate" (ruling #4580 Q3-A).

Yet after the widening, every concrete schema left visible alone and 18 narrowed disabled back. So a predicate string on visible is accepted everywhere, and the same predicate on disabled is a type error on eighteen of the most commonly authored schemas — ButtonSchema, InputSchema, SelectSchema, FormSchema among them. Nothing found in the tree rules on this; it looks like the narrowings simply predate the widening and were never revisited.

Why it matters beyond tidiness

This is the shape that makes AI-authored metadata hard to get right. The published base type advertises a capability the renderer really implements, and eighteen of the most-used concrete schemas silently refuse it. An author — human or generated — who reads BaseSchema and writes disabled: "${data.status === 'locked'}" on an InputSchema gets a type error whose message points at the narrowed subtype, not at the ruling that widened the base. label (29) and description (32) carry the same shape at larger scale.

The corrected table on #7079 mitigates the reader-facing half with a note that a concrete schema may narrow an inherited member and its own declaration wins. That is honest, but it documents the inconsistency rather than resolving it.

The question, not the answer

Three coherent directions, deliberately not chosen here:

1. Drop the narrowings — the 18 (and 29, and 32) redeclarations go, the base union stands everywhere, and evaluateCondition handles what it already handles. Widest capability, largest diff, and it grants a predicate on schemas nobody has asked for one on.
2. Keep them and make it deliberate — record that narrowing to boolean is the house shape for concrete widgets and that the base union exists for the generic path. Then visible's 0-of-124 becomes the outlier to fix, not disabled's 18.
3. Leave it and document it — what finding(docs): the canonical BaseSchema common-props table under-states five declared types and omits five declared members #7079 just did, at the docs layer only.

Picking between these is a contract decision about what the published type promises, and it wants a maintainer ruling rather than a dev's judgement.

Refs #7079 · #6347 · #4581 · #4580.

Generated by Claude Code

[os-sam]

⚖️ RULED — maintainer, 2026-09-01, director decision batch D, verbatim 「同意」: option 1, scoped to disabled — drop the 18 narrowings, restore twin symmetry with visible

The 18 concrete schemas that redeclare disabled as bare boolean return to the base union boolean | string (zod mirrors move in the same commit). The renderer already routes both twins through evaluateCondition — this aligns declaration with the shipped capability and with the #4580/#4581 widening ruling the narrowings simply predate. Option 2 (make narrowing the house style) was weighed and not adopted: it would take visible's 0-of-124 as the thing to "fix" against the measured runtime truth.

⛔ Scope guard, part of the ruling: label (29 narrowings) and description (32) are explicitly OUT — their string | I18nLabel question carries different (i18n) semantics and waits for its own measurement and ruling. The 13 non-BaseSchema shapes with independent disabled?: boolean declarations are also out (not narrowings).

This is additive for authors (a predicate string becomes accepted where it was a type error) — changeset graded accordingly; Clause-② content limb at dispatch (widens the accepted authoring surface on published types).

State transition in this same pass: needs-user-decision + finding → pm:queue.

---

Generated by Claude Code

[os-warren]

PM triage — ruling acknowledged; build-ready, land-blocked on quota. Not dispatched yet, and here is why.

Read as a refill candidate for the domain:ui seat. The maintainer ruling of 2026-09-01 stands and I am not touching it: option 1, scoped to disabled, with label / description and the 13 non-BaseSchema shapes explicitly out.

⚠️ A note on how nearly I got this wrong

The card body ends "Picking between these is a contract decision … and it wants a maintainer ruling rather than a dev's judgement." On that alone I was about to relabel this pm:queue → needs-user-decision, which would have reversed a ruling that already exists — it lives only in the comment.

This seat has the inverse failure catalogued (bodies that disqualify cards whose titles and labels look ready — objectui#7125, objectui#7143, objectui#7088 this session alone). objectui#6795 is the precedent for the opposite direction, a comment that qualifies a card its body disqualifies, and it is why I read comments before relabelling. It just paid for itself.

Why it is not dispatched this round

The ruling names it itself: "Clause-② content limb at dispatch (widens the accepted authoring surface on published types)."

That means CONTRACT_REVIEW_TIER, and the Fable 5 quota is exhausted. The standing exemption (maintainer, 2026-08-13, 「fable 如果用完了，可以用 opus」) lowers the build tier only — ⛔ it is explicitly not the gate. So an agent could build this now, and the PR ⛔ could not enter the merge queue afterwards.

#6896 / PR #7111 is already parked in exactly that state: built, correct, unlandable. Spending a second dev lane to produce a second unlandable PR is worse throughput than spending it on work that can land, while four PRs are in flight and the queue is moving.

So this is deliberately deferred, not dropped, and left pm:queue — the maintainer's transition stands, and I am not re-labelling around a ruling.

It goes out first when either condition clears

1. Fable quota returns → dispatch immediately; the ruling is complete enough to dispatch from as-is.
2. Or a maintainer confirms this may land at the lowered build tier, which would also unpark PR objectui#7111.

Both are on the standing "awaiting maintainer" list carried in the seat post (#5560).

One measurement note for whoever builds it: the zod mirrors move in the same commit per the ruling, so the changeset covers @object-ui/types and its mirror, and check-changeset-no-major will need its verdict quoted rather than predicted — an additive authoring widening is not automatically a minor, and I have mispredicted that gate twice in this seat.

---

Generated by Claude Code