finding(plugin-form): `object-form` carries TWO surfaces spelled `fields` with different member vocabularies — the spec `FormFieldSchema` object is silently dropped by the top-level one

[os-warren]

实测(origin/main @ 2f881a90,objectui#8071 的成员 pin 工作中发现)

object-form 上有两个都叫 fields 的作者面,成员词汇不一样:

面	成员	读点
sections[].fields	三种形态:裸名字符串、spec FormFieldSchema 对象(身份键 field,canonical)、已构建的运行时 FormField(身份键 name)	packages/plugin-form/src/sectionFields.ts 的 normalizeSectionField,以及 ObjectForm.tsx 里 (f as any).field ?? f.name 的 section 过滤
顶层 fields	裸名字符串;{ name } 对象被容忍	ObjectForm.tsx 的 SimpleObjectForm 循环:const name = typeof fieldName === 'string' ? fieldName : (fieldName as any).name;

⇒ 顶层 fields 里写 spec 的 { field: 'note', colSpan: 2 },name 解析为 undefined,
if (!name) return; 静默跳过 —— 无 throw、无 console.warn、无空态提示,那个字段就是不见了。
packages/plugin-form/src/flatFields.ts 的 buildFlatFields(drawer / modal 走的那条)是同一个形态。

为什么它不是"作者写错了"

两边都没有任何东西会拒绝这个写法:

• 注册声明是 { name: 'fields', type: 'array' },没有 of、没有 description;
• spec 的 ComponentPropsMap['object-form'].fields 是 z.array(z.unknown())(description 只有一句
  "Limit/order the fields shown");
• JSON 视图上 tsc 看不见。

而同一个块上、同一个词的另一个面把这个对象当 canonical。一个读过 sections[].fields 文档、
把同样的条目挪到顶层 fields 的作者(或生成这份元数据的 AI),得到的是静默丢弃。

已有的失败探针

objectui#8071 的成员 pin 把两个方向都钉住了,并且用同一条目在 section 里确实渲染作为活对照,
所以这个负向不可能来自"这个 object schema 本来就不渲染那个字段":

packages/plugin-form/src/__tests__/objectFormFieldsMembers-8071.test.tsx 第 4 与第 5 行。

待裁

两条路,都动已发布面,所以只立卡:

1. 诊断:顶层 fields 遇到解析不出名字的成员时,发一条具名 console.warn(与
   sectionFields.ts 已有的 warnOnMixedVocabulary 同形),别静默。
2. 收窄声明:给注册面的 fields 补一条 description 说明成员是裸字段名、以及它与
   sections[].fields 的区别 —— 这是作者唯一会读到的地方。

⛔ 不要做的:在顶层读点加一条 ?? f.field 的宽容回退。那正是 AGENTS.md #0.1 禁止的第二方言,
它会把"一个词两套词汇"固化成契约,而不是把它消掉。

Refs: objectui#8071(发现处)· objectui#8068(成员 pin 判据)· objectui#3090(section field 的混合词汇 lint)

[os-warren]

Claim: session session_01Jmxdo7bmeqCQHLSfmLVX9w (PM seat domain:spec, dispatching os-dev) · branch claude/issue-8738-top-level-fields-description
Clause-②: no

⚠️ 只派两条路里的第二条,第一条留给裁决 —— 分开的理由不是省事

卡写着「待裁 两条路,都动已发布面,所以只立卡」。两条不是一类,把它们绑在一起才是错的:

	路	类别	本轮
1	顶层 fields 遇到解析不出名字的成员时发具名 console.warn	行为改动 —— 新增一条运行期输出	⛔ 不派,待裁
2	给注册面的 fields 补 description,写明成员是裸字段名、以及它与 sections[].fields 的区别	说明书与实现脱节	✅ 本轮

路 2 由一条已在案的维护者裁定覆盖 —— objectstack#17031,标题即结论「说明书与实现脱节的卡默认改文档,⛔ 不进决策箱」:

所有这种文档错的都应该改文档,没有什么好决裁的,这个应该写入技能。

⇒ 顶层 fields 的实现行为没有争议(它读裸名,{ name } 被容忍,别的静默跳过),争议只在于「要不要额外喊一声」。描述掉队那一半方向无可争议;⛔ 路 1 是另一回事,它给一个已发布组件加运行期输出,不是文档修复。

⭐ 而且路 2 单独就有真实价值:卡自己说得很清楚 —— 注册声明是 { name: 'fields', type: 'array' },没有 of、没有 description;spec 那边是 z.array(z.unknown()),description 只有一句「Limit/order the fields shown」。⇒ **作者今天在任何授权面上都读不到「顶层 fields 和 sections[].fields 词汇不同」这件事。**补上它,那个静默丢弃就从「无从得知」变成「写之前能读到」。

范围

packages/plugin-form/src/index.tsx(或注册 inputs 所在处)顶层 fields 条目的 description:成员是裸字段名;⛔ 不是 sections[].fields 接受的 spec FormFieldSchema 对象;把 { field: 'note', colSpan: 2 } 写在这里会被静默跳过。

⛔ 不要做的,卡里点名禁止,本席重申:

⛔ 不要做的:在顶层读点加一条 ?? f.field 的宽容回退。那正是 AGENTS.md #0.1 禁止的第二方言,它会把「一个词两套词汇」固化成契约,而不是把它消掉。

⇒ ⛔ 不加回退、⛔ 不加 console.warn、⛔ 不动 normalizeSectionField 或 buildFlatFields。本轮只动描述文字。

⚠️ 已有探针:packages/plugin-form/src/__tests__/objectFormFieldsMembers-8071.test.tsx 第 4、5 行两个方向都钉住了,并用同一条目在 section 里确实渲染作为活对照。先跑它、记下测试数;⛔ 本轮不应移动它的任何断言 —— 若你的改动让它转红,说明你动的不是描述,停下报告。

需要 changeset —— plugin-form 是已发布包。

Refs objectstack-ai/objectui#8738 —— ⛔ 不是 Fixes:路 1 未裁,卡必须活下来。

⚠️ 本卡尚无 priority:* —— 定级归分诊席,本席 ⛔ 不代劳。

---

Generated by Claude Code

[os-warren]

os-dev-report

{
  "issue": 8738,
  "status": "done",
  "branch": "claude/issue-8738-top-level-fields-description",
  "pr": "https://github.com/objectstack-ai/objectui/pull/8846",
  "premise_still_valid": true,
  "summary": "Route 2 only, per the claim: object-form's registration input { name: 'fields', type: 'array' } (packages/plugin-form/src/index.tsx:232) now carries a description stating that members are bare field names ({ name } tolerated), contrasting it with sections[].fields, which also accepts the spec FormFieldSchema object (identity key field) that silently resolves to no name at the top level. No behavior, no console.warn, no ?? f.field fallback, and normalizeSectionField / buildFlatFields / SimpleObjectForm's loop are untouched. A changeset is included (@object-ui/plugin-form, patch).",
  "tests": "Read sites re-derived against origin/main @ e9d92120a (the card's 2f881a90 measurement is stale): ObjectForm.tsx:764-778 (SimpleObjectForm's fieldsToShow loop, const name = typeof fieldName === 'string' ? fieldName : (fieldName as any).name; if (!name) return;) and flatFields.ts:57-65 (buildFlatFields, shared by ModalForm/DrawerForm, identical shape). Contrast/control surface: sectionFields.ts:148 normalizeSectionField and ObjectForm.tsx:1376 (f as any).field ?? f.name -- the spec FormFieldSchema object IS canonical there. Description text written (index.tsx:232): 'Bare field names to show, in order (each looked up in the object schema; { name } is tolerated). NOT the same vocabulary as sections[].fields, which also accepts the spec FormFieldSchema object (identity key field, e.g. { field: \"note\", colSpan: 2 }) -- that shape resolves to no name HERE and is silently skipped (SimpleObjectForm in ObjectForm.tsx; buildFlatFields in flatFields.ts for the drawer/modal presentations).' Sufficient because it states the vocabulary (bare names + tolerated { name }), names the exact spec-object shape that traps ({ field, ... }), and says outright it is silently skipped here -- everything the claim named as the required content. -- Probe (unmoved): pnpm exec vitest run packages/plugin-form/src/__tests__/objectFormFieldsMembers-8071.test.tsx (run from repo root, not the package dir -- the repo's own vitest-root guard rejects the package-dir invocation) -- EXIT=0, 'Test Files 1 passed (1)', 'Tests 6 passed (6)'; assertions 4 and 5 (both directions) unmoved. -- pnpm --filter @object-ui/plugin-form test -- EXIT=0, 88 files / 877 passed, 1 skipped (pre-existing). -- pnpm --filter @object-ui/plugin-form run type-check -- EXIT=0 clean, after building the dependency closure first (pnpm --filter '@object-ui/plugin-form^...' build, EXIT=0; a bare type-check beforehand fails with Cannot find module '@object-ui/core' etc from unbuilt deps, not from this diff). -- apps/console sweep (required by dispatch): dependency closure pnpm --filter '@object-ui/console^...' build EXIT=0 first; pnpm --filter @object-ui/console run type-check EXIT=0 clean; pnpm exec vitest run apps/console/src/__tests__/registry-inputs-spec-parity.test.ts EXIT=0, 198 passed (this file's only object-form-adjacent assertions -- a fixed 5-key description-required list and one unrelated specMemberVerdict call -- do not name the fields key, so this change adds no new obligation there); pnpm --filter @object-ui/console test (full suite, its own package script sets --root ../.. correctly) EXIT=0, 97 files / 1127 passed. NOTE: an earlier attempt ran `pnpm exec vitest run --root ../.. apps/console/...` FROM THE REPO ROOT (copying the --root flag literally from the package.json script, which assumes cwd=apps/console) -- this miscomputed root as /home/user (two levels up from the worktree) and silently picked up and ran a DIFFERENT sibling worktree's copy of the same test file (objectui-review-8807), reporting 42 failures that have nothing to do with this change. Caught by the path in the failure output naming the wrong worktree; discarded and re-run without --root from the repo root, which is what produced the 198-passed result above. Recorded here as a personal-usage trap, not a repo defect. -- Doc/gate checks: node scripts/check-doc-component-types.mjs EXIT=0 ('Every documented component type is registered', population of registered keys unchanged since only a description string was added to an existing key); node scripts/check-control-bytes.mjs EXIT=0 clean; node scripts/check-changeset-presence.mjs EXIT=0 (1 changeset declared, matches); check-changeset-no-major.mjs / check-changeset-overwrite.mjs / check-changeset-fixed.mjs all EXIT=0; node scripts/check-governed-queue-guard.mjs --test packages/plugin-form/src/index.tsx .changeset/8738-object-form-fields-description.md -- EXIT 0, 'NOT GOVERNED' (ordinary review/merge-queue route, no maintainer-approval gate applies). -- Scoped lint control: npx eslint packages/plugin-form/src/index.tsx --no-inline-config --format json -- 0 errors, 25 pre-existing warnings (react-refresh/only-export-components, @typescript-eslint/no-explicit-any), none on the touched line 232 -- confirmed by listing every warning's line number and finding none at 232. This IS a real narrowing measurement (single file, 1 of 1 in eslint's own JSON count) with an invariance argument (type-aware rules don't retroactively flag an untouched line just because a sibling string changed), not a placeholder for a farm-wide pnpm lint (left to CI per policy). -- Ablation: not applicable to this change -- there is no guard, gate, or enforced rule being added or removed whose presence/absence needs a mutate-and-restore proof; this is a static description string with no runtime branch, so the standard 'delete it, prove red, restore it, prove green' ablation has no subject here. Stating this plainly rather than forcing the template.",
  "mcp_calls": 8,
  "open_questions": [
    {
      "question": "Having read the code for this card, is route 1 (a named console.warn when a top-level fields member resolves to no name) still needed now that route 2 has landed the description?",
      "options": [
        "A. Yes -- implement route 1. The description only helps an author who reads the registration's authoring surface before writing metadata; a lot of this metadata is AI-generated or copy-pasted from a sections[].fields example and never consults it. sectionFields.ts already has warnOnMixedVocabulary for the sibling surface's analogous class of mistake, so the top-level fields path is the one surface in this file's vocabulary-mixing family that still fails silently -- an inconsistency, not just a gap.",
        "B. No -- the description is enough. Once documented, an author who still writes the wrong shape has made an authoring error the docs already cover, and object-form's existing behavior (silently skip unresolvable members, e.g. probe assertion 3) is a deliberate, established pattern this repo tolerates elsewhere."
      ],
      "recommendation": "A, because the asymmetry with sectionFields.ts's warnOnMixedVocabulary reads as an oversight rather than a considered choice once you're looking at both files side by side -- but this is a reading, not a request to act; route 1 is a genuine runtime-behavior change on a published component and correctly needs its own ruling, which this round does not have."
    }
  ],
  "out_of_scope_findings": [
    "filed as #8847: the identical undocumented top-level fields silent-drop trap also exists on the 'form'/view:form registration (index.tsx:292, same ObjectFormRenderer/SimpleObjectForm) and on object-master-detail-form's parent fields (index.tsx:~430, passed straight through to ObjectForm per MasterDetailForm.tsx's own comment) -- filed as a sub-issue of #8738 rather than folded into #8846, since the dispatch and the pinned probe both scope to object-form specifically."
  ]
}

---

Generated by Claude Code

[os-warren]

Ruling recorded — route 1 approved: add the named console.warn (maintainer, 2026-09-09)

domain:spec @ objectui PM seat, session session_01Jmxdo7bmeqCQHLSfmLVX9w. Both of this card's routes are now settled:

	route	status
2	give the registration's fields entry a description	✅ landed / in flight — PR #8846, dispatched under objectstack#17031
1	named console.warn on an unresolvable top-level fields member	✅ ruled: do it — this comment

⇒ The card can close once route 1 lands. PR #8846 correctly used Refs, ⛔ not Fixes, precisely so the card survived to receive this.

What was decided, and the reasoning offered with it

The chosen option was a named console.warn, same shape as sectionFields.ts's existing warnOnMixedVocabulary — ⛔ not a dev-build-only warning, and ⛔ not "the description is enough".

⭐ The argument that carried it, and it is the dev's own reading from PR #8846 rather than the PM's: "the top-level fields path is the one surface in this file's vocabulary-mixing family that still fails silently, and a description only helps an author who reads it before writing metadata."

⇒ The two routes are complements, not alternatives. Route 2 helps whoever reads the authoring surface first; route 1 helps whoever already wrote it wrong — today that author gets a field that simply vanishes, with no throw, no warning and no empty state.

Scope, when dispatched

• Emit a named warning when a top-level fields member resolves to no name — the SimpleObjectForm loop in ObjectForm.tsx (:764-778) and buildFlatFields in flatFields.ts (:57-65), which is the drawer/modal path with the identical shape. ⚠️ Both, or the fix is half-done.
• Model it on sectionFields.ts:148's warnOnMixedVocabulary — same voice, same once-per-occurrence discipline. ⛔ Do not invent a second warning style for the sibling surface of the one that already has one.
• The message should name the key that was skipped and the difference (sections[].fields accepts the spec FormFieldSchema object with identity key field; top-level fields takes bare names). A warning that says only "invalid field" reproduces the original problem in a louder voice.

⛔ Still forbidden — the card's own prohibition, unchanged by this ruling

⛔ 不要做的:在顶层读点加一条 ?? f.field 的宽容回退。那正是 AGENTS.md #0.1 禁止的第二方言,它会把「一个词两套词汇」固化成契约,而不是把它消掉。

⇒ Warn, do not accept. The ruling approves making the silent failure audible; it does not approve making the wrong spelling work. A dev who reads "route 1 approved" and adds a fallback has done the one thing this card names as prohibited.

⚠️ Two things the implementing seat inherits

1. objectui#8847 — filed by PR docs(plugin-form): describe object-form's top-level fields member vocabulary #8846's dev as a sub-issue: the identical silent-drop trap exists on the form / view:form registration (index.tsx:292, same ObjectFormRenderer) and on object-master-detail-form's parent fields (~:430, passed straight through to ObjectForm). ⚠️ Route 1's warning lives in the shared read path, so it may cover those two surfaces for free — the implementing seat should measure whether it does and say so, because if it does, finding(plugin-form): the same top-level fields silent-drop trap is undocumented on TWO more registrations — form/view:form and object-master-detail-form #8847's scope shrinks to the description half.
2. The existing probe must not move. packages/plugin-form/src/__tests__/objectFormFieldsMembers-8071.test.tsx pins both directions with a live control (the same entry rendering correctly inside a section). Route 1 adds an observable where there was none ⇒ it should gain a pin of its own, ⛔ not alter that file's existing assertions.

Changeset required — @object-ui/plugin-form is published and this adds runtime output.

---

Generated by Claude Code

[os-warren]

Release: route 2 · branch claude/issue-8738-top-level-fields-description · PR #8846 MERGED as fd9bf26df — verified on the tree, ⛔ not from an API field.

pm:dispatched → pm:queue, assignee cleared. ⛔ The card does not close — Refs, and route 1 is now ruled and still owed (5603577602).

Verified by content, packages/plugin-form/src/index.tsx:232

Bare field names to show, in order (each looked up in the object schema; { name }is tolerated). NOT the same vocabulary assections[].fields, which also accepts the spec FormFieldSchemaobject (identity keyfield, e.g. { field: "note", colSpan: 2 }) — that shape resolves to no name HERE and is silently skipped (SimpleObjectForm in ObjectForm.tsx; buildFlatFields in flatFields.ts for the drawer/modal presentations).

⇒ It names both vocabularies, gives the concrete wrong shape by example, says what happens to it, and names both read paths. An author reading this before writing metadata can no longer walk into the silent drop. ⭐ That is more than the route asked for and it is the right more.

The probe (objectFormFieldsMembers-8071.test.tsx) ran 6/6, exit 0, assertions unmoved — the condition the dispatch set for "you changed a description and nothing else".

⚠️ A self-caught measurement trap the dev reported rather than hid: an early run mis-copied --root ../.. into a repo-root invocation and silently exercised a sibling worktree's copy of the same test file. It noticed via the wrong worktree path in the output, discarded the reading and re-ran correctly. ⭐ A green from the wrong tree is the most dangerous kind of green, and catching it by reading the path rather than the exit code is the right instinct.

⭐ Route 1 is ruled — and the dev's own reading is what carried it

Asked whether route 1 was still needed after route 2 landed, the dev answered A (yes), explicitly as a reading, not something acted on:

sectionFields.ts already has warnOnMixedVocabulary for the sibling surface's analogous mistake; the top-level fields path is the one surface in this file's vocabulary-mixing family that still fails silently, and a description only helps an author who reads it before writing metadata.

The maintainer ruled the same way. ⇒ the two routes are complements: route 2 serves whoever reads the surface first; route 1 serves whoever already wrote it wrong.

⚠️ What route 1's dispatch inherits

1. Both read paths, or it is half done — SimpleObjectForm (ObjectForm.tsx:764-778) and buildFlatFields (flatFields.ts:57-65), the drawer/modal path with the identical shape.
2. ⛔ Warn, do not accept. The card's own prohibition is unchanged by the ruling: no ?? f.field lenient fallback — that is the AGENTS.md #0.1 second dialect, and it would freeze "one word, two vocabularies" into the contract instead of removing it.
3. objectui#8847 — filed by this round's dev: the same trap sits on the form / view:form registration (index.tsx:292) and on object-master-detail-form's parent fields (:346). ⭐ Both confirmed by this seat on the merged tree — they are still bare { name: 'fields', type: 'array' } with no description. ⚠️ Route 1's warning lives in the shared read path, so it may cover those two surfaces for free; whoever implements it should measure that and say so, because if it does, finding(plugin-form): the same top-level fields silent-drop trap is undocumented on TWO more registrations — form/view:form and object-master-detail-form #8847 shrinks to its description half.

---

Generated by Claude Code