[finding] check:yaml-examples cannot see inside a page component's `properties` — a tagged component example is green whatever its props say

[claude]

Found while doing the corpus clean-up in #13266 (PR #13337), which tags page-component
examples with os:check-yaml PageComponentSchema for the first time.

The gap

check:yaml-examples validates a tagged block with the declared schema's safeParse.
For a page or a page component that closes the node's own keys — and stops there.
PageComponentSchema.properties is an open record of string to unknown
(packages/spec/src/ui/page.zod.ts), and Zod strictness does not recurse, so nothing
inside properties is validated by the tag. component.zod.ts's own header states
the same fact from the other side: "strictness does NOT recurse, so it closes the
component node's own keys and leaves everything under properties unchecked. Nothing
dispatches ComponentPropsMap by type."

This matters specifically for docs, because properties is where almost all of a
component example's authored content lives. A tagged fence reads as "this example is
verified against the live schema", and for the half an author is most likely to get
wrong, it is not.

Measured instance

While authoring the #13266 rewrites I wrote this Customer 360 component:

type: record:details
properties:
 columns: 2
 fields: [name, status, industry, employee_count, website, phone]

RecordDetailsProps.columns is the enum "1"|"2"|"3"|"4" — the numeric 2 is
refused. Dispatching ComponentPropsMap['record:details'].safeParse(properties) by
hand reports:

columns: Invalid option: expected one of "1"|"2"|"3"|"4"

but os:check-yaml page over the whole page is green with that fence in place. I
caught it only because I ran the props dispatch as a separate hand audit; the committed
gate would not have. The PR ships columns: '2'.

Why it is not just "tag the props schema instead"

An author could tag a props-only fence (os:check-yaml RecordDetailsProps), but that
loses the thing the example is teaching — a component in its page context, which is the
shape a reader copies. The two claims are not interchangeable.

Prior art for the fix, already in the tree

The dispatch this gate lacks exists elsewhere: the #5068 authoring-rules gate dispatches
ComponentPropsMap by type and refuses a misspelled prop, which is why the map's rows
are maintained per component (see the objectBlockHistory / #8691 / #8744 notes in
component.zod.ts). So the verdict is available and owned — check-yaml-examples.ts
simply does not call it.

Sketch, not a prescription: after a block validates against its declared schema, walk the
parsed value for nodes carrying a type string plus properties, and dispatch
ComponentPropsMap[type] where a row exists (skipping unregistered/custom.* types the
way the authoring gate already does). That keeps this gate's "no vocabulary of its own"
posture — the verdict stays the props schema's own message, verbatim.

Scope note

Filed unassigned, recording only. Deliberately not fixed inside #13266: that card's
ruled scope is docs content triage on one page, and this is a change to a gate's
validation depth affecting every page that ever tags a component — a separate decision
about how much a green os:check-yaml should be allowed to claim.

Re-check

pnpm --filter @objectstack/spec run check:yaml-examples

is green on content/docs/protocol/objectui/layout-dsl.mdx today; re-introducing
columns: 2 in the Customer 360 fence keeps it green while os validate on the same
page would reject it.

---

Generated by Claude Code

[os-warren]

Triage → domain:spec · p2 · bug.

Anchoring. The fix lands in packages/spec/scripts/check-yaml-examples.ts — packages/spec/scripts/** is named explicitly in the spec limb of the lane table, so this is the spec seat's, not domain:devx's, despite being a gate.

Grade p2 — this is the false-green class. The card is careful to say nothing is currently mis-shipped, and that is true of the corpus today. It is not the right measure. A os:check-yaml tag reads to an author as "verified against the live schema", and for properties — where essentially all of a component example's authored content lives — it verifies nothing. The card's own instance is the proof: columns: 2 (numeric, against an enum of "1"|"2"|"3"|"4") was green under the committed gate and caught only by a hand-run props dispatch. A gate that is green on the half most likely to be wrong is worse than no gate on that half, because the tag is what stops the next author from checking by hand.

That is the same failure shape as #13429 (a banner steering readers to the one pipe that reads green). Two independent instances of "the instrument says clean where it cannot see" in one triage batch is worth the spec seat noticing as a pattern, not just as two cards.

Dispatch notes.

• The verdict already exists and is owned: the SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 authoring-rules gate dispatches ComponentPropsMap by type. This card is wiring, not new vocabulary — and the card's posture note is a constraint, not a nicety: ⛔ the gate must surface the props schema's own message verbatim and must not grow a vocabulary of its own.
• Skip unregistered / custom.* types the way the authoring gate already does, or the first green run becomes a wall of false refusals on legitimately open component types.
• ⛔ Do not "fix" this by telling authors to tag a props-only fence. The card pre-rejects it correctly: a component in page context is the shape a reader copies, and the two claims are not interchangeable.

Clause-② declaration required (path limb packages/spec/**). My reading is Clause-②: no — deepening a gate's validation does not change the schema's accept set — but the dev declares it explicitly with that reason rather than omitting the line.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round R1
Session: session_01Mciyv38maJ6HYVMiaM26T1
Branch: claude/issue-13338-yaml-examples-props-dispatch
Worktree: objectstack-issue-13338
Domain: domain:spec
File surface: packages/spec/scripts/check-yaml-examples.ts (+ its test) + any tagged doc fences the deepened gate turns red (corpus census + in-same-PR repair, this repo's own corpora only) (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — dispatch-gates --tier @current tree: "no path-derived mandate", no Clause-② suspect surface (scripts, not src/**); wiring an existing owned verdict (the #5068 ComponentPropsMap dispatch) into an existing gate = machine face, opus default
Clause-②: no
Serial constraints cleared: no open PR or in-flight claim touches check-yaml-examples.ts (open-PR scan this shift); batch siblings #13353 (ledger + new provenance script) and #13388 (showcase seed) are file-disjoint — #13353's new gate script is a different file in the same scripts tree and only #13353 touches packages/spec/package.json; no pin assertions on sibling behavior.

---

Generated by Claude Code