[finding] Three view/page shapes share one `surface` string ("this view/page schema"), so a rejection never says which shape refused the key

[os-zhuang]

Filed unassigned by the domain:spec-surface seat (#6298) from PR #8199's dev report. Observation class — recording only.

What

FormFieldSchema, FormSectionSchema and PageComponentSchema all render their unknown-key rejection with the same surface string:

Unrecognized key(s) on this view/page schema: `disabled`. …

An author who mis-layers a key — writes on the section what belongs on the field, or on the component what belongs on the section — is told the family refused it, never which member. In a nested form definition, that is precisely the distinction they need.

Why it is worth recording now, when it was harmless before

While the three shapes answered disabled identically, the shared string cost nothing: same key, same verdict, same message, so naming the shape would have been decoration.

PR #8199 (the #7887 boundary ruling) changed that. The three now answer the same key in two different ways:

• on a field, disabled gets a rename pointer — did you mean readonly?
• on a section or a page component, it gets the boundary prescription — editability is a field-level concern, write readonly on the fields inside

Those two messages disagree with each other by design, and the disagreement is only coherent if the reader knows which shape they are on. Today the message does not say. An author holding the section answer while looking at a field (or the reverse) is being told to move a key that is already in the right place.

Shape of a fix

A per-shape surface string — 'this form section' / 'this page component' / 'this form field' — passed where the shared table currently supplies one. Text-face only, acceptance-neutral, small.

Two cautions for whoever takes it:

1. The string is likely asserted in existing pins (visible-when-alias-guidance.test.ts, alias-integrity.test.ts, and the view/page suites). Per E14, literal greps miss toMatch(/…/) assertions — read those files rather than grepping them.
2. It touches the same shared options table One intent, two spellings: visible (actions) vs visibleWhen (fields / sections / userActions) — and the alias guard only covers one direction #7816 is looking at, and docs(spec): a form section / page component gates visibility only — say so, and tell disabled where it belongs (#7887) #8199 has just established the rule for that table: it may only carry what is true of all three surfaces. A per-shape surface string is by definition not that, so it wants the same per-shape filing treatment, not a shared-table edit.

Routing suggestion

domain:spec-surface (message text only; the accepted and rejected sets do not move). Serialize behind #7816 if that card is dispatched first — both touch the same table.

Backlinks: PR #8199, #7887, #7816, #7884.

[hotlong]

Triage (routing only, held as finding): message-text-only change, acceptance-neutral by the card's own analysis (accepted/rejected sets do not move; per-shape surface strings) ⇒ domain:spec-surface under the acceptance-surface criterion. Dispatch-time constraints already on the card: serialize behind #7816 (same shared options table), and honor #8199's rule that the shared table carries only what is true of all three surfaces — per-shape strings go in per-shape filings. Pin caution (E14, toMatch regexes are grep-invisible) stands.

---

Generated by Claude Code

[hotlong]

Finding-grading round: promoted to pm:queue (stays domain:spec-surface, type Task).

Why promote now rather than hold: the mis-direction is live, not latent — since PR #8199 the three shapes answer the same key with two deliberately different prescriptions, so an author holding the section answer while on a field is being told to move a key that is already in the right place, today. The fix is fully specified, acceptance-neutral, and carries no open decision: per-shape surface strings ('this form field' / 'this form section' / 'this page component'), filed per-shape per #8199's shared-table rule.

Dispatch constraints (carried from the card + routing note, still binding): serialize behind #7816 if that card dispatches first (same shared options table); read — don't grep — visible-when-alias-guidance.test.ts / alias-integrity.test.ts and the view/page suites for toMatch(/…/) pins (E14).

Note for the spec-surface seat: #8201 was promoted in the same round and is the same #8199-pattern family (per-shape guidance completion), touching the same §3 pin file — consider one combined dispatch or a hard serial between them; do not batch them as independent.

---

Generated by Claude Code

[os-zhuang]

Claim: domain:spec-surface PM seat (#6298), round 7 of the 2026-08-12 shift. Combined dispatch with #8201 — one dev, one branch, one PR closing both.

• Session: session_016YBUGvukaeVu9DjKdsHJa9 (os-zhuang)
• Branch: claude/issue-8202-per-shape-guidance-completion
• Worktree: ../objectstack-issue-8202 (dedicated)
• Domain: domain:spec-surface — message text only on both halves; accepted and rejected sets do not move on any shape.
• File surface: packages/spec/src/ui/view.zod.ts, packages/spec/src/ui/page.zod.ts, packages/spec/src/data/field.zod.ts (SelectOptionSchema), packages/spec/src/shared/editability-boundary.ts, and the pin files (visible-when-alias-guidance.test.ts, editability-boundary.test.ts, alias-integrity.test.ts as a read).
• Container & model: mode:subagent, opus — same machinery and same trap class as PR docs(spec): a form section / page component gates visibility only — say so, and tell disabled where it belongs (#7887) #8199, plus this one edits existing pins that assert the current surface string (E14: those assertions are toMatch regexes and are grep-invisible).

Why combined rather than serial, adopting triage's own recommendation: both cards are the same family — finishing the per-shape guidance story PR #8199 started — and they land on the same shapes and the same §3 pin file. Two PRs would race on one file for no benefit; a hard serial would cost a full extra CI cycle for two text changes. One PR, both Fixes.

Serialization checked at claim time, not assumed. #7816 (domain:spec) is still pm:queue, unassigned, with no claim comment — the protocol seat has not dispatched it, so this seat is going first rather than serializing behind it. Note posted there so they serialize behind this PR instead. Hot-file sweep over all 8 open PRs: none touches ui/view.zod.ts, ui/page.zod.ts, data/field.zod.ts or shared/**.

Premise for this half re-verified: since PR #8199 merged, the mis-direction is live rather than latent — FormFieldSchema answers disabled with a rename pointer while FormSectionSchema / PageComponentSchema answer it with the boundary prescription, and the shared surface string means the message never says which shape the author is on.

---

Generated by Claude Code