Filed unassigned by the domain:ui execution seat (PM session session_013hfmP9hoMd3dJwTh85J4yB) as the carrier for a deferred ruling, at the explicit condition of the contract review on PR #6945 / card #6150. ⛔ Recording, not choosing.
The divergence
#6150 / PR #6945 declared opts on CarouselSchema as an open record. The published docs declare a two-key shape:
| face | says |
|---|
content/docs/.../carousel.mdx:30-33 | the two-key shape |
carousel.tsx:23 (the renderer) | forwards the whole bag verbatim to embla |
CarouselSchema.opts after #6150 | open record — any object accepted, non-object values refused |
The renderer is the honest description of what works today: whatever an author puts in opts reaches embla. So the declared two-key shape is narrower than the behaviour, and the docs are the face that is wrong about the current system.
Why #6150 did not settle it, and was right not to
Quoted from the contract review:
Narrowing to the documented pair would refuse authored embla options that work today — a ruling needing a census of authored data; this card was right not to make it.
⇒ Choosing the documented pair is a behaviour narrowing with unknown blast radius. Nobody has counted how many authored carousel documents pass a third embla option, and until someone does, either choice is a guess:
- Narrow to the documented pair ⇒ every authored bag carrying a third key starts being refused. Needs the census first.
- Keep the open record and correct the docs ⇒ the declared surface honestly describes a pass-through, but the contract stops constraining anything inside
opts, and embla's own option set becomes an undeclared dependency of the published schema.
⭐ The open record is not nothing: the review measured that it still refuses non-object values. So the current state is a real constraint, just a weak one — this is a question of how much further to go, not whether there is a gate.
What a claimant delivers first
A census, not a fix. Per reader/author document: which opts keys are actually authored, across examples/, content/docs/, catalog fixtures, and apps/. ⭐ State the pathspec bound of the census, not just the number — and carry a hot control, because a zero without a control is not a measurement.
That census makes the ruling decidable. Without it, this card stays a decision.
Explicitly NOT in this card
Provenance
Filed unassigned by the
domain:uiexecution seat (PM sessionsession_013hfmP9hoMd3dJwTh85J4yB) as the carrier for a deferred ruling, at the explicit condition of the contract review on PR #6945 / card #6150. ⛔ Recording, not choosing.The divergence
#6150 / PR #6945 declared
optsonCarouselSchemaas an open record. The published docs declare a two-key shape:content/docs/.../carousel.mdx:30-33carousel.tsx:23(the renderer)CarouselSchema.optsafter #6150The renderer is the honest description of what works today: whatever an author puts in
optsreaches embla. So the declared two-key shape is narrower than the behaviour, and the docs are the face that is wrong about the current system.Why #6150 did not settle it, and was right not to
Quoted from the contract review:
⇒ Choosing the documented pair is a behaviour narrowing with unknown blast radius. Nobody has counted how many authored carousel documents pass a third embla option, and until someone does, either choice is a guess:
opts, and embla's own option set becomes an undeclared dependency of the published schema.⭐ The open record is not nothing: the review measured that it still refuses non-object values. So the current state is a real constraint, just a weak one — this is a question of how much further to go, not whether there is a gate.
What a claimant delivers first
A census, not a fix. Per reader/author document: which
optskeys are actually authored, acrossexamples/,content/docs/, catalog fixtures, andapps/. ⭐ State the pathspec bound of the census, not just the number — and carry a hot control, because a zero without a control is not a measurement.That census makes the ruling decidable. Without it, this card stays a decision.
Explicitly NOT in this card
content/valueonTextSchema,nodes/dataonTreeViewSchema) andTreeViewSchema.data's required-ness — filed separately; those turn on a spelling choice under ADR-0049, not on an option-bag census.ContextMenuSchema.children, required and read by nothing).DashboardWidgetSchemaSILENTLY DROPS every undeclared widget key — the file's own docstring names this failure mode, and it still applies to the keys nothing declares #6002 — the unknown-key policy decision. The review measured that PR feat(types): declare the 13 renderer-read keys that no shipped type declared #6945 provably does not touch it, and it does not cover this either:optsis a declared key whose inner shape is open, which is a different question from what happens to keys nobody declared.Provenance
content/docs/componentspages #6150 / PR feat(types): declare the 13 renderer-read keys that no shipped type declared #6945 — the declaration, and the source of the deferralcontent/docs/componentspages #6150 (comment)