fix(core,list): 列身份归一到 ingestion chokepoint — 一列一个身份 (#3104 PR1) - #3119
Merged
Conversation
Column field identity was resolved twice with two different precedences over
the same `schema.columns` array, and the two halves disagreed:
request path ListView's `$expand` / `$select` builders and
ObjectGrid.getSelectFields read `f?.field` and ONLY that.
render path the FLS gate, the hidden-field filter, `fieldOrder`, both
export branches and the hide-fields popover read
`f.name || f.fieldName || f.field` — name FIRST.
So `{field:'account', name:'account_name'}` fetched `account` while the
renderer keyed off `account_name`, and `{name:'account'}` rendered a column
the request dropped entirely. That is the mechanism behind the "relation
column shows a bare id / column is empty / sort does nothing / export is
missing a column" defect class.
Per AGENTS.md #0.1 the fix is not another `?? name` at the read sites. Legacy
acceptance moves to the boundary that already folds this view's vocabulary:
`normalizeListViewSchema` now canonicalizes each column's identity too,
running after the `fields` -> `columns` rename so a doubly-legacy view is
fixed on both axes in one pass.
New in @object-ui/core (`utils/column-identity.ts`):
columnIdentity() the single reader, canonical-first
normalizeColumnIdentity(-ies)() the fold
hasConflictingColumnIdentity() true when a column's keys disagree
The fold MIRRORS rather than deletes the legacy key, unlike the other folds in
normalizeListViewSchema. Deleting works in-repo (every name-first read falls
through to `field`), but `columns` entries cross the package boundary into host
renderers and dropping `name` from under them is a breaking change with no
inventory. An absent legacy key is never invented, and an already-canonical
column is returned by reference so ListView's useMemo deps stay stable.
`accessorKey` is deliberately untouched: it is TanStack Table's column key
(`TableColumn.accessorKey`), not ObjectStack metadata identity.
Tests:
- ListView.columnIdentity.test.tsx — the repro through the real ListView.
`checkField` is the observable: BOTH paths call it, so a column whose keys
disagree checks two different field names. Now exactly one.
- column-identity.ratchet.test.ts — the 34-site inventory with a per-site
precedence and verdict; a new dual read, or an extra one in a listed file,
fails. Shrinking fails too, so the tree and the record cannot drift.
The inventory corrects the issue's framing in two places: resolveActionParams
(3) and dashboard-filters (1) carry BOTH orders legitimately — `name` and
`field` are separately declared there and mean different things, so those are
two layers, not two spellings. The real pollution is worse than "two orders
coexist": ListView and ObjectGrid each disagree with themselves.
Behaviour is unchanged for any column carrying a single identity key. The
entries whose resolution moves are exactly the ones where two sites already
disagreed.
Refs: objectstack#4115, #3090 (playbook), #2598 (chokepoint precedent)
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C2pdPmf2yZSd4wFDs1NHY5
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
Contributor
✅ Console Performance Budget
📦 Bundle Size Report
Size Limits
|
os-zhuang
marked this pull request as ready for review
July 31, 2026 11:27
os-zhuang
added a commit
that referenced
this pull request
Jul 31, 2026
…3104 PR2) (#3122) PR1 (#3119) put a canonicalizing fold at ListView's ingestion boundary. This converges the 22 read sites themselves onto `columnIdentity()`, so a surface that is NOT downstream of that fold resolves the same identity anyway. That distinction is the user-visible part. A standalone `object-grid` node — authored directly on a page, with no `list-view` above it — never passed through `normalizeListViewSchema`. Its `getSelectFields` read `c.field` alone while the `ensureId` probe one line above read `f?.name || f?.field`, so a legacy `{name:'account'}` column reached `$select` as a literal `undefined` hole: the server never returned the field and every cell in that column came back empty. Same for ObjectTree, RelatedList and the record:details / record:related_list renderers. Converged: ListView ×9 + its 2 request builders -> columnIdentity() RelatedList ×8 -> accessorKey || columnIdentity() ObjectGrid (probe + projection) -> columnIdentity() ObjectTree -> columnIdentity() || key buildExpandFields -> columnIdentity() record-details / record-related-list -> columnIdentity() (|| key) `accessorKey` keeps its precedence in RelatedList — it is TanStack Table's column key, not ObjectStack metadata identity, and only the `field || name` tail was converged. `key` stays a tail fallback in ObjectTree and record-related-list for the same reason: it is a generic entry key. Two incidental fixes TypeScript surfaced once the resolver stopped returning `any`: ListView's filter-field options and its hide-fields popover both built entries keyed `undefined` for a column with no resolvable identity. Those entries could never match a column; they are now dropped. Inventory re-triage: PR1 recorded 24 family members. Two were mis-classified and are reclassified rather than converged — reading what they actually feed shows they are not column reads at all. ViewPreview adapts a ViewItem FORM section to what object-form selects by (#3090's two-layer join); SchemaForm renders an arbitrary metadata ARRAY into a popover summary and guesses at a display key. So the family was 22, and it is now 0. The ratchet asserts that, asserts each converged surface actually routes through the shared reader (a surface that dropped identity resolution instead of converging it goes red), and pins accessorKey's precedence in RelatedList. Refs: objectstack#4115, #3090 (playbook), #3119 (PR1) Claude-Session: https://claude.ai/code/session_01C2pdPmf2yZSd4wFDs1NHY5 Co-authored-by: Claude <noreply@anthropic.com>
os-zhuang
added a commit
that referenced
this pull request
Jul 31, 2026
…3124) Closes the battle opened in #3104. PR1 (#3119) put the canonicalizing fold at ingestion; PR2 (#3122) converged all 22 read sites onto columnIdentity(). This is the audible half. A column carrying two identity keys that DISAGREE now logs a one-time dev-mode warning naming which key won and what to change. The fold making the two halves agree is what stops the bug, but silently rewriting `name` to match `field` also hides that the producer is emitting a contradiction. The renderer recovering is not the same as the metadata being right, so the recovery says so. Deliberately narrow: - Only contradictions. `{name:'stage'}` is legacy, not conflicting — stamped without noise. - Warn once per (identity, conflicting spelling). Columns are re-normalized on every render, and a warning that floods the console is one that gets muted. Keyed by the pair rather than the identity alone, so a column carrying two different stale spellings reports both. - Silent under NODE_ENV=production, and the fold still runs there. No lint rule, and that is a measured decision. #3104 asked for no-restricted-syntax on `.field ?? .name` to be evaluated on its false-positive rate first. With the family at zero, all 12 remaining scanner hits are legitimate — a syntactic rule cannot tell a two-layer join from a dual read, because the distinction is what the keys MEAN in that layer, not how the expression is spelled. Adopting it would mean 12 inline disables on correct code, which trains the next author to reach for the disable. The ratchet carries a verdict and a why per site instead. The evaluation is written into its header. Ledger item resolved with no change needed: #3104 flagged ListColumn for disposition under objectstack#4115 (spec-named symbols must be imports, not declarations). ListColumnSchema is already a by-reference re-export of @objectstack/spec/ui, and spec-subschema-parity.test.ts already pins it by reference identity — the only check that distinguishes a re-export from a faithful fork. Already compliant. Verified: M5 (drop the warn call) turns 4 of the new tests red. vitest core+list+grid+detail+tree+view+types -> 188 files / 2663 tests green vitest app-shell -> 250 files / 2089 tests green turbo type-check, eslint -> green Refs: objectstack#4115, #3090 (playbook), #3119 (PR1), #3122 (PR2) Claude-Session: https://claude.ai/code/session_01C2pdPmf2yZSd4wFDs1NHY5 Co-authored-by: Claude <noreply@anthropic.com>
9 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
#3104 PR1(盘点 + 复现 + 归一器)。台账:objectstack#4115。
复现:缺陷比 issue 描述的更严重 —— ListView 和 ObjectGrid 各自和自己打架
issue 的框架是「两种优先序并存于 15+ 处」。逐点位读完源码后,真正的机制不是「不同文件用不同优先序」,而是同一个文件里,请求路径和渲染路径读同一个
schema.columns却解析出两个字段:ListView.tsx的expandFields/selectFieldsmemo;ObjectGrid.getSelectFieldsf?.field,只读 fieldfieldOrder排序、导出 ×2、hide-fields 弹层f.name || f.fieldName || f.field,name 优先两个后果,都是静默的:
{ field: 'account', name: 'account_name' }→ 行数据按account取(含$expand=account),而字段级权限检查、导出、hide-fields 全部按account_name。一列,两个字段。{ name: 'account' }→ 渲染路径把这列画出来,请求路径解析成undefined直接滤掉 ——$select和$expand都不带它。列在那里,后面什么都没有。这就是「关系列显示裸 id / 列全空 / 排序不生效 / 导出缺列」这一缺陷类的机制。
ListColumnSchema(spec 17.0.0-rc.0)只声明了一个必填键field,没有name、没有fieldName、没有accessorKey—— 所以field不是「几种方言之一」,它是契约。归一:挂在已有的 chokepoint 上,不在消费端铺
?? name按 AGENTS.md #0.1,修法不是在读点再加一个
?? name。遗留接纳收进已经在折叠这个视图词汇表的那一处:normalizeListViewSchema(@object-ui/core,ListView 组件边界的唯一 fold,#2890 建立)。它现在多折一层列身份,且排在fields→columns改名之后 —— 一个两轴都遗留的视图(遗留列表键 + 遗留条目键)一趟修完。新增
@object-ui/core的utils/column-identity.ts:columnIdentity(entry)field→name→fieldName,canonical-first,所以与buildExpandFields一致而不是和它赛跑;兼容裸字符串列normalizeColumnIdentity(-ies)()hasConflictingColumnIdentity(entry)CANONICAL_COLUMN_IDENTITY_KEY/LEGACY_COLUMN_IDENTITY_KEYS/TABLE_ADAPTER_COLUMN_KEYstamp 策略 = 镜像,不删除(与
normalizeListViewSchema里其它 fold 相反,这是刻意的):field写入解析出的身份 → 请求路径永远找得到。{ field: 'stage' }原样按引用返回。归一器不去制造它正要退役的词汇。删除在仓内是可行的(每个 name-first 读法都会 fall through 到
field),但columns条目会越过包边界进入宿主渲染器,把name从它们脚下抽掉是一个我们没有清单的破坏性变更。删除留给 PR3,等仓内消费者都改读columnIdentity()之后。accessorKey刻意不碰:它是 TanStack Table 自己的列键(TableColumn.accessorKey,types/src/data-display.ts),命名的是表格库列模型里的槽位,不是 ObjectStack 元数据身份。跨这条边界做归一只会把这次合并固化下来 —— 正是本战役要拆的东西。行为:任何只带一个身份键的列,每个读点解析出的字符串与改动前完全相同。解析结果发生变化的,恰好是那些两个读点本来就不一致的条目 —— 那是缺陷,不是回归。
盘点(ratchet)
column-identity.ratchet.test.ts扫描packages/*/src,把 34 个点位连同每处的优先序和判定冻结入库。新增双读、或已列文件里多出一处 → 红;变少也红(要求在移除读点的同一个 commit 里把数字降下来,树里的实况和台账不会漂移)。column-identitytwo-layerform-clusterunrelatedcolumn-identity24 处:ListView.tsx×9(name-first)、RelatedList.tsx×8(adapter-first)、ObjectGrid.tsx/ObjectTree.tsx×1(name-first)、expand-fields.ts/record-details.tsx/record-related-list.tsx/ViewPreview.tsx/SchemaForm.tsx×1(field-first)。对 issue 盘点的两处更正
issue 把
dashboard-filters.ts:146和resolveActionParams.ts列为优先序对立的证据。读完声明后,这两处不是同一身份的双读:resolveActionParams.ts(3 处) —— 同一文件里两种优先序都对。field ?? name选的是从 row 上读哪个键(行数据按对象字段做键);name ?? field命名的是动作负载里的 param,缺省用它绑定的字段名。两个概念。core/utils/dashboard-filters.ts(1 处) ——DashboardFilterDef把两个键都显式声明了:name是过滤器变量的句柄,field是它指向的对象字段。f.name || f.field是「没起名的过滤器,句柄缺省取所绑字段」,是一个派生,不是双读。也就是说「两种优先序对半分 ⇒ 污染已经发生」这个推论,有一部分其实是两层概念(正是 #3090 的判别法)。真正的污染在别处,而且更糟:ListView 和 ObjectGrid 各自和自己不一致。
未知项(issue 要求查清)
fieldName第三键的写入方与存量 —— 全仓没有写入方。grep 'fieldName:'的每一处命中都是函数形参或无关的接口成员(AIFieldSuggestion.fieldName),没有任何代码往列对象上写fieldName。它只活在读者里(防御性写法)。归一器仍然接纳它(宿主存量元数据可能带),ratchet 也计它,但结论是:这个键没有生产者。accessorKey—— TanStack Table 的适配键,见上,不属于本战役。闸门 mutation-test(逐个删机制,证明会红)
normalizeListViewSchema里的列身份 foldexpected [] to include 'account')c.name ?? c.fieldsort-values.ts:149被点名expand-fields.ts的双读收敛成单键0 dual reads, inventory says 1 — good news; lower the count复现测试怎么观测「一列两个身份」
ListView.columnIdentity.test.tsx走真实的 ListView,checkField是最利落的观测点:两条路径都会调它(渲染侧来自effectiveFields,请求侧来自selectFields),所以两个键不一致的列会让同一列检查两个不同的字段名。断言是「恰好一个身份」,外加$select/$expand的正向断言。复现测试落地即绿(不是红着合进 main):缺陷由 M1 变异证明 —— 摘掉 fold 立刻红。
验证
（首轮
type-check的Cannot find module '@object-ui/permissions'是packages/permissions/dist未构建导致的既有构建顺序问题,与本 PR 无关;构建该包后即绿。）破坏面
@object-ui/coreminor(按 AGENTS.md §9,objectui 的破坏性变更也标 minor)。纯新增 API + 一处 ingestion fold。单键列零行为变化。后续
columnIdentity(),ratchet 计数随之下降。hasConflictingColumnIdentity已就位)、fold 从镜像改为删除、台账条目处置。关联:objectstack#4115(台账)、#3090(playbook 与判别法)、#2598(chokepoint 先例)、#3103(热身件,已合)。
Generated by Claude Code