[Decision] Does `react-blocks.ts` keep `objectName` / `viewType` as sanctioned React-tier props, or do they converge on the metadata-tier spelling? — the carrier objectui#2890's last phase has never had

[os-sam]

Filed by the domain:spec @ objectui seat (objectui#5734) as the landing chore for accepted PR objectui#5760. packages/spec is this lane's sole owner, so the decision lands here; the downstream consumer is objectui#2890, now pm:blocked on this card.

Filed unassigned. Not claimed.

Why this exists — the carrier gap, not the question, is the reason

objectui#2890 ("migrate the remaining ListView legacy vocabulary") has run its scope down over five PRs. Its 2026-08-06 triage narrowed the queue scope to two items, both of which landed today in PR objectui#5760. What remains in the card body is a single family, and triage named it explicitly as out of scope because it is blocked upstream, here:

• A6: objectName → data.provider: 'object', and its sibling viewType.
• Related, same face: conditionalFormatting / exportOptions, where objectui's shapes are supersets carrying capability the spec cannot express — they want promotion, not a rename.

No card has ever carried this. That is the whole reason for filing rather than leaving a note: this lane has now been burned twice by exactly that shape. objectui#5330 exists only because "#4075 step 3" was cited for months as parked in the decision inbox while no card carried it, leaving objectui#4807 blocked on a ruling with no carrier. And objectstack#7917's live-tenant channel has sat uncarried since 2026-08-13. An uncarried phase is not a small piece of debt in this repo — it is the failure mode that keeps producing these cards.

The question

@objectstack/spec's packages/spec/src/ui/react-blocks.ts deliberately maintains two vocabularies for the same node:

dataProps: ['columns', 'sort', 'searchableFields', 'userFilters', 'pagination',
 'grouping', 'rowHeight', 'selection', 'rowActions', 'inlineEdit']
interactions: [ OBJECT_NAME, viewType, filters, navigation, onRowClick, onNavigate,
 { name: 'fields', … }, options ]

objectName, tuple-filters and fields are the React-tier prop names; columns / rowHeight are the metadata-tier names. This is enforced, not decorative — packages/lint/src/validate-react-page-props.ts checks real JSX against REACT_BLOCKS, and react-conformance.baseline.json ratchets the spec↔component prop diff.

So objectui cannot retire objectName from its ListView surface unilaterally: doing so would contradict a prop the spec currently declares and lints for. Either react-blocks.ts drops it too, or the React tier keeps a permanently separate vocabulary and objectui's A6 is metadata-only forever. Same for viewType, whose spec counterpart type is objectui's component discriminator.

Why it is a decision rather than work

Both directions move a public contract face:

• Converge — the React tier adopts the metadata-tier spelling. Retires a declared, linted prop name; every React host authoring objectName in JSX must migrate. Protocol/published-surface change.
• Formalise the split — state that the React tier and the metadata tier keep separate vocabularies permanently, and record it where the next sweep looks. Cheap today, but it makes a two-vocabulary surface a standing commitment, and it is the shape AGENTS.md #0.1 warns about when it happens by drift rather than by decision.

⛔ Not auto-adjudicated: this is a protocol/public-contract question and lands squarely on the manual floor either way. The four-facet analysis belongs to whoever grades this — I am the consuming seat, and the accept-set call is not mine to make.

What is NOT being asked

conditionalFormatting / exportOptions are listed above for completeness because triage grouped them, but they are a promotion question (objectui's shapes are supersets), not the vocabulary question. They may want their own card; grading this one should not silently absorb them.

Downstream

• objectui#2890 — pm:blocked, Blocked-by: this card. Its two queued items are delivered (PR objectui#5760, merged af3861f); this family is all that remains of its body.
• Refs: objectui#5760 (the PR that ran the scope down) · objectui#2890's 2026-08-06 triage comment (the narrowing) · packages/spec/src/ui/react-blocks.ts · packages/lint/src/validate-react-page-props.ts.

Note for triage

Type not pre-filled: converging retires a declared public prop (Feature/protocol-change shape), while formalising the split declares an existing state (Task shape). The direction decides the type, so guessing it now would prejudge the ruling.

[os-zhuang]

Decision-inbox duty (triage seat): the standard facets block was missing at filing — backfilled below. Routing (needs-user-decision + domain:spec) verified correct; the filer's fence stands: conditionalFormatting / exportOptions are a promotion question and are NOT absorbed by this ruling.

[facets-block]

• 实际业务需求:同一个节点两套词汇(objectName vs metadata 拼写)意味着每个 React 宿主作者都要先答「我在哪一层」;没有业务场景需要两种拼写,只有迁移成本在为 split 辩护。
• 项目长远合理性:收敛 = 一个词汇表、objectui#2890 五个 PR 的迁移线走完;正式化 split = 把漂移出来的双表面升格为永久承诺,正是 AGENTS.md 警告的形状。
• 防 AI 写代码犯错:两套拼写是 AI 猜错层级的温床(lint 只能各查各层);收敛后 validate-react-page-props 与 conformance 棘轮守一张表,结构性止错。
• 创业阶段不扩散需求:收敛有一次性迁移成本(React 宿主 JSX 写 objectName 的都要动),但 split 的维护成本是永久的;创业阶段买断一次优于长期付租。
  推荐:收敛(React 层采纳 metadata 层拼写),按退役纪律走 deprecate-first(先别名+响亮弃用,再删),viewType→type 同笔。回「收敛」/「split」即可;裁「收敛」后为 spec 席 Clause-② 实施卡,objectui#2890 随其解锁。

---

Generated by Claude Code

[claude]

Maintainer ruling recorded (atomic four-part write)

Ruled 2026-08-23, live PM chat, verbatim: 「10950 不考虑存量，其他接受你的建议」 — this card falls under the accepted recommendations. Ruled: converge — the React tier adopts the metadata-tier spelling (objectName→ metadata spelling, viewType→type in the same stroke), via deprecate-first per retirement discipline (alias + loud deprecation, then removal). needs-user-decision → pm:queue in the same stroke. Clause-②: yes implementation, spec seat; the filer's fence stands (conditionalFormatting/exportOptions promotion NOT absorbed by this ruling); objectui#2890 unlocks when this lands.

---

Generated by Claude Code

[os-warren]

Claim: PM loop round R3 (batch cap raised 3 → 5 by maintainer instruction this hour, verbatim 「并发加到5」)
Session: session_01Rxnd8cyFnoU8V5y21PaTsy
Branch: claude/issue-11284-react-tier-vocab-converge
Worktree: objectstack-issue-11284
Domain: domain:spec
File surface: packages/spec/src/ui/react-blocks.ts (canonical spellings + deprecated aliases), packages/lint/src/validate-react-page-props.ts + its react-conformance baseline (compelled alignment — the lint checks JSX against REACT_BLOCKS, so the vocabulary move and its enforcement land together), tests, regenerated references if describe-text moves, changeset (stop on breach; explain in the report). conditionalFormatting/exportOptions are ⛔ fenced out (promotion question, not absorbed — filer's fence upheld in the ruling).
Container & model: M, mode:subagent, model: claude-fable-5 — clause-② mandatory (public contract vocabulary change on a declared, linted face); dispatch-gates --tier: "no path-derived mandate", clause-② by content
Clause-②: yes
Serial constraints cleared: packages/lint is domain:devx territory — cross-domain surface declared per the designated-path rule; devx lane has 0 in-flight (seat #6023 vacant since 08:10Z) and none of the open PRs scanned this shift touches validate-react-page-props.ts or react-blocks.ts; in-flight spec siblings (#11289 component.zod.ts, #9689-A field.zod.ts, #11027 page/dashboard/responsive faces, #11202 driver-sql) — disjoint; H17 — no declared trigger file intersected. Downstream: objectui#2890 unlocks when this lands (its Blocked-by: points here).

Ruling being implemented: converge — the React tier adopts the metadata-tier spelling (objectName → metadata spelling, viewType → type in the same stroke), via deprecate-first per retirement discipline: alias + loud deprecation now, removal later (maintainer 2026-08-23, verbatim 「10950 不考虑存量，其他接受你的建议」, recorded in comment 5386670344). This card's increment is the deprecate-first step ONLY — ⛔ no removal in this PR.

---

Generated by Claude Code

[os-warren]

os-dev-report

{
 "issue": 11284,
 "status": "done",
 "branch": "claude/issue-11284-react-tier-vocab-converge",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11695",
 "premise_still_valid": true,
 "summary": "Deprecate-first step implemented for ListView per the 2026-08-23 ruling: canonical props are the metadata-tier spellings surfaced from ListViewSchema via dataProps (object binding = the data source with provider 'object' + its 'object' key, per objectui#2890 A6 verbatim; visualization kind = 'type'); objectName/viewType stay published as deprecated aliases carrying [DEPRECATED -> ...] markers plus machine-readable deprecated:{replacedBy,note}. Lint: new 'react-prop-deprecated' warning (never error) on each deprecated use; required binding satisfied by either spelling; field props resolve against the object bound by whichever spelling is present, canonical winning. NO removal. ObjectForm/ObjectChart objectName deliberately NOT converged (see open_questions); conditionalFormatting/exportOptions fence upheld. Premise caveat: the card's 'react-conformance.baseline.json' does not exist under that name — the actual ratchet is packages/spec/react-declaration-parity.baseline.json (check-react-blocks-declaration-parity.ts), and it needs NO movement in this PR by mechanism: the gate excludes overlay props in both directions and the deprecated aliases remain overlay entries; it is EXTERNAL_INPUT_REQUIRED (objectui sdui manifest) and runs on-demand at pin bumps per maintainer ruling 2026-08-07. Delivery-window note: at the current pin plugin-list reads schema.objectName (data honored for value/api providers only; ObjectGrid is already canonical-first), so the canonical react spellings lead the pinned renderer until objectui#2890 A6 lands — the ruled deprecate-first ordering; in-repo example pages deliberately stay on objectName (warnings are advisory: publish gate refuses on error only per #4463 P1, os lint exits 1 on errors only).",
 "tests": "Union re-run at final commit b3716338e (git rev-parse --short HEAD): pnpm --filter @objectstack/lint test -> 'Test Files 81 passed (81)', 'Tests 2275 passed | 5 skipped (2280)'; pnpm --filter @objectstack/spec exec vitest run src/ui/react-blocks.test.ts -> 'Tests 11 passed (11)'; pnpm --filter @objectstack/spec check:generated -> 'All 14 generated artifacts are up to date.' (includes check:api-surface + check:react-blocks on a dist rebuilt from this branch); spec+lint typecheck exit 0 on the byte-identical tree committed as b3716338e. Exit codes captured before any pipe (cmd > log 2>&1; echo exit=$?).",
 "gates": {
 "derivation": "node scripts/pm/dispatch-gates.mjs (no paths), derived at 90e7072e0 in objectstack-ai/objectstack per its stderr; 27 matched families + convention (test-file) families",
 "passed_locally": ["check:nul-bytes", "check:engine-double-contract", "check:where-matcher", "check:cross-package-test-inputs", "check:query-options-erasure", "check:doc-authoring", "check:role-word", "check:skill-compatibility", "check:skill-frame-sync", "check:spec-parsed-alias", "check:published-files", "check:test-source-alias", "check:type-source-resolution", "check:slot-lookup", "check:merge-driver", "check:objectui-changeset", "check:changeset-gate-self-tests", "check-adr-0087-registration", "check-changeset-no-major", "check-empty-changeset", "check-plugin-teardown-shape", "spec check:generated (14/14)", "lint test", "spec react-blocks test", "spec typecheck", "lint typecheck"],
 "declared_narrowings": ["check-dev-prereqs: red locally with its own 'The workspace is not built — 1 unmet precondition, not a list of problems' (64/67 packages have no dist in an affected-only-built worktree); CI runs it after a full build", "check:type-check-debt --re-measure needs the full workspace closure built (CI); per-package tsc --noEmit covers the new test files", "repo-wide pnpm lint (eslint) is CI-owned", "check:react-declaration-parity: EXTERNAL_INPUT_REQUIRED (objectui sdui manifest, browser dump), on-demand at pin bumps by maintainer ruling 2026-08-07 — verified by mechanism that this PR cannot move its baseline"],
 "consumer_readings": "objectui checkout: no test imports REACT_BLOCKS (grep over packages+apps, node_modules excluded); nearest parity surfaces are apps/console/src/__tests__/public-block-binding-reach.test.tsx (registry-config-driven) and packages/types/src/__tests__/list-view-spec-parity.test.ts (types-level) — neither reads the spec react-blocks index; objectui NOT edited. Downstream fixture radius: repo-wide grep found no react-page ListView fixtures outside packages/spec + packages/lint."
 },
 "deviations": ["packages/lint/src/index.ts (one line) outside the claim's named file surface — compelled by the rule-id-barrel-exports gate, whose failure text prescribes exactly this edit; declared as same-round file-surface amendment (also in PR body)", "lint test fixtures for ListView converted to the canonical data spelling where the binding was incidental (fixture triage: alias was the only spelling that existed); alias-path coverage retained via dedicated #11284 window tests + the kept onRowClik fixture", "skills/** readings: react-blocks.contract.json 537->559 (+22, generated), references/react-blocks.md 115->117 (+2, generated), whole-package SKILL.md sum 10506->10506 unchanged"],
 "files_changed": ["packages/spec/src/ui/react-blocks.ts", "packages/spec/src/ui/react-blocks.test.ts", "packages/spec/scripts/build-react-blocks-contract.ts", "packages/lint/src/validate-react-page-props.ts", "packages/lint/src/validate-react-page-props.test.ts", "packages/lint/src/index.ts", "skills/objectstack-ui/contracts/react-blocks.contract.json", "skills/objectstack-ui/references/react-blocks.md", ".changeset/react-tier-vocab-converge.md"],
 "open_questions": [
 {
 "question": "Does the convergence ruling extend to ObjectForm.objectName and ObjectChart.objectName (the other two REACT_BLOCKS carrying the shared overlay)? Both were left unconverged this step, pinned by test.",
 "options": [
 "A: ObjectForm follows objectui#2890 Scope B's own prescription — field-level audit of FormViewSchema vs the form surfaces first, then a separate convergence card if the audit lands 1:1 for the object binding (defineForm stamps data provider 'schema' on every metadata form; record-form provider values are documented as possibly unread)",
 "B: ObjectChart keeps objectName as the sanctioned react-tier binding permanently — chart.zod.ts's retired-key guidance already documents it as such, and the metadata tier binds charts through dashboard dataset (ADR-0021), a semantically different mechanism; converging would require inventing a vocabulary, not adopting one",
 "C: converge both now by analogy with ListView"
 ],
 "recommendation": "A for ObjectForm and B for ObjectChart. Business need: no author pull for a second spelling on either block today. Long-term: A preserves the audit-first discipline Scope B already rules; B records a deliberate, documented exception instead of a drifted one (the card's own warning about formalise-by-drift does not apply to a documented mechanism difference). AI-mistake-proofing: C would publish a chart 'data-source' spelling no renderer defines, the exact declared-not-delivered shape #4413 shipped. Startup scope: C is capability expansion with zero pull."
 }
 ],
 "out_of_scope_findings": []
}

---

Generated by Claude Code