finding(app-shell): `paramToField` is now the LAST private copy of the reference-bearing rule — and its "moves in lockstep with plugin-grid" comment stopped being true

[os-support-ai]

发现于 #4815 的实施(PR 见该卡)。不在 #4815 范围内(该卡正文只点名 plugin-grid 的表,文件面也只给了 packages/plugin-grid/src/** + packages/core/src/**),单独立此单记录。

事实(实读 origin/main @ de4e29a)

packages/app-shell/src/utils/paramToField.ts:44,97:

const LOOKUP_WIDGET_TYPES = new Set(['lookup', 'master_detail']);
...
// `|| type === 'owner'` stood here until objectui#4814 retired that spelling
// (ruling A'). It moves in lockstep with plugin-grid's `bulkParamToField`
// twin — the two param faces are never split.
if (LOOKUP_WIDGET_TYPES.has(type) || type === 'user') {
 Object.assign(field, { reference_to: ..., display_field: ..., id_field: ..., ... });
}

这条 LOOKUP_WIDGET_TYPES.has(type) || type === 'user' 判的正是 #4770 / #4790 / #4815 三次收敛的同一件事 ——「这个 widget 要查记录,所以要把 reference 目标递给它」—— 写成一条内联析取,成员集 {lookup, master_detail, user}。

为什么现在才值得单独记

#4815 落地后,四个消费面里已有三个 派生自 @object-ui/core 的 EXPANDABLE_FIELD_TYPES(buildExpandFields、predicate-record、表单的 needsDataSourceWiring,加上刚接上的 bulk 对话框),paramToField 是唯一仍在自己重述的那一面。

而上面那条注释说它「moves in lockstep with plugin-grid's bulkParamToField twin」—— 这句话在 #4815 之前是靠人守的,#4815 之后机制上已不成立:twin 现在读共享对象,这里读自己的字面量,两边再不共享任何东西。这正是 #4770 / #4790 / #4815 三张卡各自描述过的前夜状态:注释声称同步、机制不保证。

为什么今天没有用户症状(据此判为 observation-class)

与 #4815 同因:两个 param 面的 type 都先过 resolveFormWidgetType,而 tree 不在 fields 的 widget map 里、mapFieldTypeToFormType 把它送到 field:lookup,所以 core 多出的 tree 这一格在这里同样到不了;owner 已随 #4814 退役。即成员差异当前全部无症状 —— 但没有任何 gate 能发现它开始漂。

修法方向(与 #4790 / #4815 同型)

派生 + 归一化 + identity 钉(钉对象身份,成员相同的私有副本必须红)。plugin-grid 侧刚落地的形状可直接照抄:EXPANDABLE_FIELD_TYPES.has(t),需要本面扩展时 OR 上一张 surface-local 表,不要 new Set([...EXPANDABLE_FIELD_TYPES, ...])(复制会重新分叉,且钉子按设计会红)。钉子写法见 packages/plugin-grid/src/__tests__/bulkParamToField.test.ts 与 packages/components/src/renderers/form/__tests__/form-data-source-wiring.test.tsx。

一并复核:LOOKUP_WIDGET_TYPES 在这两个文件里还各自承担「哪些类型需要 reference 目标、缺了就降级为文本」的第二条规则(与 data-source 规则不同集),收敛时别把两条规则合成一条。

参考

• CASCADE option 允许表现存三份未导出的重复(app-shell / components / plugin-grid)—— 抬升到 @object-ui/fields 并让三处 import 同一常量 #4770 / PR refactor(core,fields): one exported cascade option allow-table, not three private copies (#4770) #4789、DATA_SOURCE_FIELD_TYPES(form 层)与 core 的 EXPANDABLE_FIELD_TYPES 已知不同集且零 gate —— 同 #4770 的第二张允许表待收敛 #4790、finding(plugin-grid): DATA_SOURCE_WIDGET_TYPES 是「哪些 widget 要 DataSource」的第四份私有副本 —— 与表单规则不同集、零 gate #4815(本单的前三次同型收敛)
• packages/app-shell/src/utils/paramToField.ts:44,97、packages/core/src/utils/expand-fields.ts:62

[os-zhuang]

Triage first-touch grading (finding centralized round, 2026-08-20, triage seat session session_016A4EBi3ky1mjTi6vD2kCvA): promote to pm:queue, type Task. Re-verified on origin/main: paramToField.ts:44 still restates the expandable-type set inline under a "lockstep with bulkParamToField" comment that is mechanically false since the twin derives from @object-ui/core's EXPANDABLE_FIELD_TYPES (identity-pinned in bulkParamToField.test.ts:16). Fourth and final application of an already-ruled convergence pattern, with pin templates to copy — and it retires a false lockstep comment, the planted-premise class this repo keeps paying for.

---

Generated by Claude Code

[os-sales]

Claim: PM loop round 11
Session: session_012u2pRjcqAYtoEjgr3wwhnK
Branch: claude/issue-5312-paramtofield-derive
Worktree: objectui-5312
Domain: domain:ui (execution seat)

File surface: packages/app-shell/src/utils/paramToField.ts. ⛔ OUT: packages/app-shell/src/views/metadata-admin/** and packages/app-shell/src/index.ts — held by #5596 this round. If the convergence turns out to need the root barrel, report it rather than editing it; I will serialise the two.

Clause ②: not tripped, and the card is the archetype of why. This replaces a restated member set with one derived from @object-ui/core's EXPANDABLE_FIELD_TYPES — three of the four consumer faces already derive; paramToField is the last one restating. Derived from an authority → repair.

The comment is a claim to test, not a fact to inherit. The source says the disjunction "moves in lockstep with plugin-grid's bulkParamToField twin — the two param faces are never split." Measure whether that is still true of the current tip before relying on it. If the twin has already diverged, that is a finding worth filing, and it changes what "converge" means here.

app-shell scale: ~488 test files; the full suite exceeds the container's 10-minute foreground cap. Derive a provable superset from the code and state the principle that makes it a superset — never sample and never call a sample a suite. Note also that four devs run concurrently on 4 CPUs this round, so contention is expected; if a run hits the cap, narrow by derivation, not by dropping files.

---

Generated by Claude Code