app-shell: the page-block designer's object-kanban inspector writes groupField — a key the renderer never reads and, after objectui#7322, the validator refuses by name; no groupBy / limit control #7772

Activity

1. os-zhuang

   added

   bugSomething isn't workingSomething isn't working

   package: app-shell

   pm:queue

   finding

   priority:p2

   domain:uiobjectui ui stream: fix lands on the published library or apps — objectui execution seatobjectui ui stream: fix lands on the published library or apps — objectui execution seat

   i18n

   on Sep 6, 2026
2. os-zhuang commented on Sep 6, 2026

   

   os-zhuang

   on Sep 6, 2026 – with Claude

   Contributor

   More actions

   分诊路由 · triage seat

   标签：domain:ui · bug · package: app-shell · i18n · finding · pm:queue · priority:p2（高于卡片这一族的默认档，理由见第 2 节）

   1. 锚点复核（origin/main 0558e0f；卡片测于 4dfdcc3c）

   卡片	0558e0f 实际
   previews/block-config.ts:222 写 groupField	逐字命中（{ name: 'groupField', label: '…object-kanban.groupField', kind: 'field-picker', objectFrom: 'self', objectProp: 'objectName' }）	✅
   i18n en i18n.ts:611 = "Group by field"	逐字命中	✅
   i18n zh i18n.ts:2454 = "分组字段"	❌ 实际 :2465（:2454 是 option.colorVariant.purple': '紫色'）	⚠️ 漂移 +11
   pin block-config-i18n.test.ts:283	逐字命中	✅
   schema.groupBy 13 处 / schema.limit 2 处 / groupField 0 处	13 ✅ · 2 ✅ · 0 ✅（活控制：同一次查询里 13 个 schema.groupBy 命中 ⇒ 那个 0 是读数）	✅
   #7322 item ① 落地后 zod 按名拒绝	objectql.zod.ts:996 groupField: retirementTombstone('RETIRED (objectui#7322) — … author \groupBy`.')；TS 面 pin object-kanban-group-by-limit-7322.test.ts:134 _GroupFieldIsTombstone`	✅ 已经落地，不是「once … lands」

   ⇒ 卡片写的是将来时，树上已是完成时。这是本轮第 20 次 branch-facts-as-tree-facts。

   2. ⭐ 缺陷比卡片描述的更重 —— 这个 inspector 根本产不出一个合法节点

   卡片的论点是「写了一个渲染器不读的键」。我复核时发现还缺了一半：

   ObjectKanbanSchema 上 groupBy 是 REQUIRED（TS objectql.ts:2765 groupBy: string; 无 ?；zod objectql.zod.ts:995 groupBy: z.string() 无 .optional()；:2758-2763 的 docblock 明写 “REQUIRED, as the retired groupField was”）。

   而 block-config.ts:220-224 这个 block 的全部四个控件是 objectName / groupField / titleField / cardFields —— 没有 groupBy。

   ⇒ 设计器产出的 object-kanban 节点同时踩中三件事：

   1. 缺少一个必填键（groupBy）；
   2. 携带一个已按名退役的键（groupField）；
   3. 渲染出一块什么也不分组的板，且没有任何诊断。

   卡片说 “a board that groups nothing, with no diagnostic” —— 对，但成因不是「写错了键」，而是唯一能设置分组的那个控件写的是废键，且真正的必填键没有任何控件。⇒ 我按此把定级从这一族惯常的 p3 抬到 p2：这是用户可达的编写 UI 稳定产出非法节点，不是内部惰性残留（对比同批的 #7773，那个是适配器的惰性重复写，判 p3）。⛔ 不抬 p1：不涉及数据面或权限面，且损害限于设计器新建的看板块。

   3. 覆盖面的空洞，我做了一次独立确认

   卡片说 scripts/check-designer-field-key-parity.mjs 只判 PAYLOAD_SHAPES（字段/对象/权限载荷），不判 page-block inspector 配置。我在 :8、:72、:173 读到该门自己的表述与之一致（“COVERED — the statically declared payload shapes in PAYLOAD_SHAPES”）。⇒ 没有任何机械守卫看着 block-config.ts，这正是它能与 schema 静默分叉的原因。⚠️ 我未运行该门，只读了它的自述，⇒ 这是转述+源码印证，⛔ 不是一次执行读数。

   4. 关于「第 3 步是不是一个待裁决问题」—— 不是，先例在树上

   卡片第 3 步写「Decide whether saved page documents carrying groupField need a strip-on-load or a one-off migration」。我复核了它引的 #4644 先例，该模式今天活在树上：

   • packages/app-shell/src/views/metadata-admin/previews/object-fields-io.ts 导出 RETIRED_FIELD_KEYS（经 retiredFieldKeysFor(...)）；
   • 消费方 MetadataService.ts:292/:304、clientValidation.ts:832、ObjectFieldInspector.tsx:18/:120、useDatasetFields.ts:101；
   • 专门的 pin：previews/object-fields-io.retiredKeys.test.ts。

   ⇒ 这不是一个开放决策，而是照抄一个已成型的模式。⚠️ 唯一需要判断的是：现有 RETIRED_FIELD_KEYS 服务于对象字段设计器，page-block 需要一个同形但独立的清单 —— 这是实现选择，不是 contract 决策。⇒ 因此本卡落 pm:queue，⛔ 不落 needs-user-decision。

   5. 对实施者的边界

   • ✅ 交付物：block-config.ts:222 的 name 与 label 改为 groupBy；i18n.ts:611（en）与 :2465（zh，⛔ 不是 :2454）两个键改名；pin block-config-i18n.test.ts:283 跟着移。
   • ⚠️ check:i18n-keys / check:i18n-dead-keys 会同时判新键存在与旧键无残留 —— 三处（en / zh / pin）必须在同一次提交里一起动，否则两道门会各红一半。
   • ✅ 建议一并加 limit 数字控件（ObjectKanbanSchema.limit，正整数，默认 100 = DEFAULT_KANBAN_LIMIT）。⭐ 这不是"nice to have"：limit 是真实的取数上限，ObjectKanban.tsx 读它 2 处。
   • ⚠️ 补充观察（卡片未列，供判断范围，⛔ 不是缺陷主张）：ObjectKanbanSchema 声明了 11 个键，而 inspector 只覆盖 4 个 —— 除 groupBy / limit 外，quickAdd / coverImageField / allowCollapse / conditionalFormatting 也没有控件。⛔ 不要在本卡里把它们一次补齐：inspector 不必暴露全部键，那是产品决定，不是契约缺口。本卡只修「必填键无控件 + 废键有控件」这一对。
   • ⛔ 不要碰视图级的 groupField 别名（normalize-list-view.ts:191 映射的那个）—— 那是活的，与节点级退役是两件事。同批的 plugin-view / plugin-list: the kanban adapters write the retired groupField alongside groupBy onto the generated object-kanban node — an inert duplicate write held in place by two pins #7773 评论里我写了完整的“可动/不可动”清单，建议连读。

   6. 车道与定级

   • domain:ui + package: app-shell：落点全部在 packages/app-shell/src/views/metadata-admin/** —— 行为面/设计器。卡片自己也判为 domain:ui，我复核同意。⛔ 不是 domain:spec：packages/types 那一半（finding(types,plugin-kanban): ObjectKanbanSchema requires groupField (zero read sites) and declares neither groupBy nor limit — no working object-kanban node is assignable to any declared type #7322 item ①）已完成。
   • i18n：两个语言条目 + 一个 pin 随之移动，且由 i18n 门禁判定，不是附带修改。
   • bug：机械边界测试 —— 修复方向是把 producer 拉回已声明契约（declared=enforced），⛔ 不扩大任何 accept set ⇒ Bug/tidy 一侧。
   • p2：见第 2 节。

   7. 去重

   • plugin-view / plugin-list: the kanban adapters write the retired groupField alongside groupBy onto the generated object-kanban node — an inert duplicate write held in place by two pins #7773（视图适配器写 groupField）—— ⛔ 非重复，是同族的另一个产出端：plugin-view / plugin-list: the kanban adapters write the retired groupField alongside groupBy onto the generated object-kanban node — an inert duplicate write held in place by two pins #7773 在 plugin-view / plugin-list 的运行期适配器，本卡在 app-shell 的设计器 UI。⭐ 建议同一人连做两张。
   • 卡片自列的 finding(types,plugin-kanban): ObjectKanbanSchema requires groupField (zero read sites) and declares neither groupBy nor limit — no working object-kanban node is assignable to any declared type #7322（声明面，已落地）· console: field designer still offers an "Indexed" toggle for a key FieldSchema rejects by name — ticking it hard-blocks the save #4644（同类先例，模式已在树上）· finding: nothing guards the CLASS "a field designer authors a key FieldSchema refuses" — three per-key tombstones, no key-level parity check #5761（门禁覆盖说明）—— 逐一核对，均非重复。
   • ⚠️ 本席未做 state=all 全量搜索，⇒ 有界读数，⛔ 不要升级为 exhaustive。

   ---

   ⛔ 本席（triage）的禁令：不认领 · 不派单 · 不写代码 · 不合并 · 不裁决 decision-box 卡（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

   ---

   Generated by Claude Code
3. os-justin

   added

   pm:dispatched

   and removed

   pm:queue

   finding

   on Sep 6, 2026
4. os-justin

   self-assigned this

   on Sep 6, 2026
5. os-justin commented on Sep 6, 2026

   

   os-justin

   on Sep 6, 2026 – with Claude

   CollaboratorAuthor

   More actions

   Claim: session session_01YBWFb5YgMU5dw8p2VKj16S · branch claude/issue-7772-page-block-kanban-groupby-control

   PM dispatch (objectui PM loop). Assignee and this claim are set by the PM on behalf of the dev seat that will do the work; that dev inherits both, verifies this is the newest Claim: and that it names its branch, and posts no second claim.

   Dispatched on triage's reading above, which travels with the order as binding. Two points from it that decide the shape of the work:

   • Triage's §2 supersedes the card's framing. The defect is not "an inspector writes a key the renderer ignores" — it is that the only control able to set grouping writes a retired key, while the genuinely required key (groupBy) has no control at all. So the designer stably emits a node that is missing a required key and carries a name-retired one. That is why it is p2 and not p3 like its sibling plugin-view / plugin-list: the kanban adapters write the retired groupField alongside groupBy onto the generated object-kanban node — an inert duplicate write held in place by two pins #7773.
   • Triage's §4 closes the card's step 3. It is not an open decision: the console: field designer still offers an "Indexed" toggle for a key FieldSchema rejects by name — ticking it hard-blocks the save #4644 RETIRED_FIELD_KEYS pattern is already live in the tree (previews/object-fields-io.ts with five named consumers and its own pin). Copying an established pattern is an implementation choice. ⛔ Not needs-user-decision.

   ⚠️ The trap most likely to cost a CI cycle, from triage §5: check:i18n-keys and check:i18n-dead-keys judge new-key-present and old-key-absent respectively, so all three sites — en i18n.ts:611, zh i18n.ts:2465 (⛔ not :2454, which triage measured as drifted by +11) and the pin at block-config-i18n.test.ts:283 — must move in the same commit, or the two gates each go half-red.

   ⛔ Scope fence, also triage's: add limit, but ⛔ do not add controls for the other six declared-but-uncontrolled keys (quickAdd / coverImageField / allowCollapse / conditionalFormatting) — an inspector need not expose every key, and that is a product decision rather than a contract gap. ⛔ Do not touch the view-level groupField alias (normalize-list-view.ts:191); it is live, and node-level retirement is a different thing. Its sibling #7773 landed as PR #8191 and its comment carries the full movable/immovable list — worth reading alongside.

   ---

   Generated by Claude Code
6. os-justin commented on Sep 7, 2026

   

   os-justin

   on Sep 7, 2026 – with Claude

   CollaboratorAuthor

   More actions

   os-dev-report

   {
     "issue": 7772,
     "status": "done",
     "branch": "claude/issue-7772-page-block-kanban-groupby-control",
     "pr": "https://github.com/objectstack-ai/objectui/pull/8217",
     "premise_still_valid": true,
     "summary": "Triage's §2 framing confirmed by measurement and implemented. BLOCK_CONFIG['object-kanban'] offered objectName/groupField/titleField/cardFields; ObjectKanbanSchema.groupBy is REQUIRED on both faces (objectql.ts:2765, objectql.zod.ts:1001) with no control, and groupField is a retirementTombstone (objectql.zod.ts:1002) as the only grouping control. ObjectKanbanSchema.safeParse on the node those four produce reports TWO issues: groupBy 'expected string, received undefined' and groupField carrying the retirement message. Fixed: the lane control and its two locale entries are renamed to groupBy (English wording unchanged), a limit number control is added with placeholder 100 whose pin reads DEFAULT_KANBAN_LIMIT out of ObjectKanban.tsx, and a stored groupField is stripped at the inspector's read door via RETIRED_BLOCK_PROP_KEYS / stripRetiredBlockProps — triage §4's copy-the-established-pattern instruction, list independent because the existing RETIRED_FIELD_KEYS registry is FieldSchema-specific and says so. Strip, not migration into groupBy: that would be a second de-facto alias (AGENTS.md #0.1) for a value the board never acted on. Clause-②: no accept set moves — the node face already required groupBy and already refused groupField, and PageSchema.safeParse was measured NOT to descend into block properties at all (control: a bogus key parses green), so no draft changes verdict. Assignee was already set by the PM and I never wrote it; the newest Claim: names this session and this branch, and I posted no second claim. Scope fences honoured: no controls for quickAdd/coverImageField/allowCollapse/conditionalFormatting, view-level kanban.groupField untouched (confirmed live — plugin-list/src/ListView.tsx:2165 reads schema.options?.kanban?.groupField today). ⚠️ Near-miss reported rather than acted on: plugin-view/ObjectView.tsx and plugin-list/ListView.tsx still write groupField onto a generated object-kanban node IN THIS BRANCH'S TREE, which reads as a live sibling defect — it is not, PR #8191 landed that fix at 00:21, one hour after this branch's base at 23:22 (ancestry checked with a control leg on a non-shallow checkout: subject exit 1, control exit 0).",
     "tests": "ALL heavy runs through scripts/pm/os-verify-lock.sh; every verdict read from the wrapper's VERDICT command-exit line, never a bare $?. Final commit f0e6f3f7c. TESTS (repo guard requires running from the repo root, not `pnpm --filter <pkg> exec vitest`): the two block-config suites baseline 2 files/45 passed -> after 2 files/56 passed (+11); new PageBlockInspector.retiredBlockProps.test.tsx 1 file/6 passed; packages/app-shell/src/views/ (incl. all metadata-admin) 388 files/3708 passed, 1 skipped; packages/app-shell/src/ outside views/ 251 files/2431 passed; apps/console/ 89 files/1052 passed. Affected set read from TURBO_SCM_BASE=0c8dbc49 turbo ls --affected = app-shell, console, two examples (no test scripts) — not guessed from the diff. TYPE-CHECK: pnpm --filter @object-ui/app-shell run type-check exit 0 (objectui spells it type-check with a hyphen; it is `tsc --noEmit && tsc -p tsconfig.test.json`, so the new test file really is covered). GATES all exit 0, each redirected to a file BEFORE capturing the exit code: check:control-bytes, check:i18n-keys, check:i18n-dead-keys, check:i18n-drift, check:designer-field-key-parity, check:vi-mock-specifiers, check:vi-mock-inherit, check:phantom-deps, check:self-import, check:unreferenced-sources, check-changeset-presence.mjs, check-changeset-no-major.mjs; plus a manual C0-range grep -naP over the seven changed files (exit 1 = clean). ⚠️ MECHANISM ASSUMPTION FALSIFIED: the dispatch's 'the two i18n gates each go half-red' is false — both read packages/i18n/src/locales/en.ts and engine.inspector.pageBlock.* is not in the packs (git grep -c returns zero for that prefix while the control `filterBuilder` returns a hit; metadata-admin/i18n.ts's own header says it is NOT one of those packs), and check:i18n-drift reports 0 en values changed on a diff that renames a key in this table. The conclusion is unchanged — the coupling is real and enforced by block-config-i18n.test.ts's derivation instead, demonstrated by ablation leg A rather than asserted. LINT, not a narrowing but the whole population: eslint --no-inline-config . at the repo root, 4396 files (count from --format json); my six changed files 0 errors / 35 warnings, all pre-existing rule classes carried from the files each was copied from. The 94 errors sit in 78 files this diff does not touch and cannot be attributed to it: eslint.config.js enables no type-aware linting (no project / projectService / tsconfigRootDir anywhere), so no rule reads types across files. ABLATION — two legs, each mutate one anchored line, prove it reached disk, run the pins, restore via trap on EXIT INT TERM, prove the restore BY STATE. No build step needed and that is measured not assumed: vitest.config.mts:411 aliases @object-ui/types/zod to packages/types/src/zod/index.zod.ts and the app-shell suites reach block-config by relative path, so everything under test resolves to src. LEG A (lane control reverted to groupField): anchor `name: 'groupBy'` 1->0, `name: 'groupField'` 0->1, blob hash changed; 9 tests failed across all three files — offers exactly the five controls / does NOT offer the retired groupField / every control writes a key ObjectKanbanSchema accepts / every key resolves in en-US / in zh-CN / zh-CN is actually translated / every sampled key is one the table really reaches / offers the lane picker and the row cap / leaves the lane picker empty. LEG B (stripRetiredBlockProps call replaced by the raw read): anchor 1->0, blob hash changed; exactly 2 failed and 4 passed — renders no box for it, does not ride back out on the next save — the other four correctly stayed green, which is what makes the pins separable. Restore proven BY STATE both legs: git checkout HEAD -- ABSOLUTE_PATH, then git hash-object equal to git rev-parse HEAD:PATH and git diff HEAD empty; working tree clean at the final commit. Direction reported as observed: both legs turn RED — neither a diagnostics-count change nor a reversal. ⚠️ One os-verify-lock call returned exit 99 (queue-timeout) mid-ablation: recorded as NOT MEASURED, never as a red, the trap restored the tree, and the leg was re-run to completion with the same OS_VERIFY_LOCK_SLOT.",
     "mcp_calls": "6 — issue_read get_comments (claim verification, the one read the payload channel must not serve), search_issues (dedup, with #7772 itself as the positive control that fired), issue_write (filed #8216), create_pull_request, pull_request_read (body read-back), add_issue_comment (this report). REST was probed first and is CLOSED for this session (403 'GitHub access is not enabled for this session'), so the ladder was git first, then the public-repo payload channel for the card body and the triage comment and for reading #8068, then MCP for the writes and the one search.",
     "open_questions": [],
     "out_of_scope_findings": [
       "filed as #8216: nothing mechanically compares the page-block designer's BLOCK_CONFIG field names against the node schemas — check-designer-field-key-parity.mjs judges PAYLOAD_SHAPES only, registry-inputs-spec-parity judges the registry inputs, and what exists for BLOCK_CONFIG is voluntary per-block prose pins written one at a time as defects were found (page:header.icon #3829, page:accordion #5212, global_nav, and now object-kanban). Deduped first: #5761 (same class, FIELD designer) and #8067/#8068 (same voluntary-pin argument for registry inputs) are all CLOSED and none covers this table; #8068's body read via the zero-quota payload channel to confirm.",
       "NOT filed, deliberately: ObjectKanbanSchema declares 11 keys and the inspector now covers 5 — quickAdd / coverImageField / allowCollapse / conditionalFormatting still have no control. Triage recorded this as a product decision rather than a contract gap and explicitly not a defect claim, so filing it would contradict that ruling. Recorded here instead."
     ]
   }

   ---

   Generated by Claude Code
7. os-justin

   closed this as completedin #8217on Sep 7, 2026