finding(types): `ContextMenuSchema.children` is declared REQUIRED, no read site consumes it, and the only shipped fixture omits it

[claude]

Found while implementing #7073 (docs correction on overlay/context-menu.mdx). Filed rather than decided: the docs row was mine, this is a declaration that looks wrong, which is not.

Measured on origin/main 592acafbeed97c5aed81a18f4d848b6179d3c044.

The measurement

fact	evidence
children is declared required on the TS type	packages/types/src/overlay.ts:471 — children: SchemaNode | SchemaNode[]; inside ContextMenuSchema, no ?
...and required in the zod mirror	packages/types/src/zod/overlay.zod.ts:190 — children: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).describe('Context menu children'), no .optional()
no read site consumes it	grep -rn 'schema\.children' packages/components/src/renderers/overlay/ returns nothing. The renderer renders schema.trigger instead: context-menu.tsx:95 — renderChildren(schema.trigger || { type: 'text', value: 'Right click here' })
the type's own doc comment already says so	overlay.ts:477-479 — "the renderer renders trigger, NOT the declared ContextMenuSchema.children, which no read site consumes"
the only shipped catalog fixture omits it	examples/schema-catalog/src/schemas/components-overlay-context-menu/basic-context-menu.json has type, trigger, items and no children

Why it is worth a card

This is the ADR-0049 declared-vs-enforced shape, in its most awkward form: a required key that nothing reads, so the contract obliges every author to write something the platform then ignores — and the one document this repo ships for the component does not write it. Any consumer that strict-parses ContextMenuSchema refuses the repo's own fixture.

It is also the reason overlay/context-menu.mdx cannot simply publish the key. #7073's PR deliberately left children off that page: publishing a required-but-unread key would teach authors to emit dead metadata, and publishing it as optional would contradict the declaration. The page can only be made complete once this is decided.

The options, not a recommendation to adopt without triage

1. Make it optional (children?:) — smallest change, keeps the key available for a future read site, stops obliging authors. Leaves a declared-but-unread key, which ADR-0049 exists to discourage.
2. Retire it (enforce-or-remove) — trigger already covers the right-clickable area and is the key the renderer actually reads. Removing children makes trigger unambiguously the one spelling. Needs the ADR-0087 registry treatment for a removal.
3. Give it a read site — only if children was meant to be the right-clickable area and trigger is the accident. The doc comment and finding(types): 13 top-level schema keys that component renderers genuinely READ are declared by no shipped type — measured across all 76 content/docs/components pages #6150 both point the other way, so this looks like the weakest option, but it is the one that would explain why the key is required.

Refs: #7073 (the docs card that surfaced it) · #6150 (declared trigger, did not touch children) · ADR-0049.

---

Generated by Claude Code

[os-sam]

⚖️ RULED — maintainer, 2026-09-01, director decision batch D, verbatim 「同意」: option 2 — retire children from ContextMenuSchema

trigger becomes the one spelling for the right-clickable area — it is the key the renderer actually reads, the type's own doc comment already records the split, and the shipped fixture omits children. Making it optional (option 1) was weighed and not adopted: it downgrades the lie from required to optional and still leaves a declared-but-unread key for ADR-0049 to hunt later. Option 3 (invent a read site) contradicts the recorded evidence.

Mechanics: TS type + zod mirror both drop the member; ADR-0087 disposition for the published-type narrowing; changeset per the launch-window convention; docs page (#7073's held half) publishes cleanly afterwards. Family note: same retire-a-dialect class as #6771 (ruled batch A) — the domain:ui lane may evaluate the five family gates for a combined dispatch.

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

---

Generated by Claude Code