serve 面保证 stored metadata 规范拼写：reference_to → reference 归一化 + spec 裁定 reference_field/referenceField 协议归属（ui#6837 半 1）

[zhuangjianguo]

背景

ui#6837（objectui 删除 17 处 legacy 兼容臂）经维护者裁定按「两半」执行，本卡为 半 1（objectstack 侧，先行）。裁定评论：objectstack-ai/objectui#6837 (comment id 5475017957)。

维护者定调（逐字）：「objectui不是前端的项目吗？后端的元数据只要对，前端按协议执行就行了呀」——协议归一化属于服务端；前端只按协议执行，不背兼容臂。

关键事实（为什么 serve 面保证是承重件，编译不是）：stored metadata 是运行时 JSON，经 API 下发，不经过任何 TypeScript 编译；zod 拒绝面只在新文档 parse/publish 时生效，不回溯已存量数据；TS 编译错误只保护手写 BYO schema。因此若 serve 面不归一化，前端删臂后存量 reference_to 会静默降级——必须先由本卡兜底。

工作项

1. 测量：ADR-0087 conversion 链是否已覆盖 reference_to → reference？若已覆盖，出具 serve 面证据（存量含 reference_to 的 metadata 经 serve 路径下发后只含 reference）即可关此项。
2. 若未覆盖：按 page-header-subtitle-alias 先例落 conversion + os migrate meta 支持，使 serve 面只出现规范拼写。
3. spec 裁定（同卡）：reference_field vs referenceField 的协议归属——哪个是规范拼写、另一个是否进 conversion/拒绝面。spec 域按既定豁免由 spec 席位自审。

下游

半 2 = objectui 删 17 处臂 + 调用链 + 52 处仓内 legacy 发射点（ui#6837，Blocked-by: 本卡），BYO/手写 TS 破坏性在 changeset 显式声明，附 dev-mode 警告 pin。

Blocks: objectstack-ai/objectui#6837

[os-warren]

分诊 → domain:spec · pm:blocking · p2（自 p3 上调，理由见末）· bug。

锚定。 ADR-0087 的 conversion 链在 packages/spec/src/conversions/registry.ts（page-header-subtitle-alias 先例即在此），⇒ domain:spec（唯一所有者）。os migrate meta 的 CLI 半边随卡，由 spec 席在认领评论申报文件面。pm:blocking：objectui#6837 半 2 挂在本卡上。

工作项 1 已经答了：未覆盖

在 origin/main 上直接查了，省掉这一步：

git grep -n "reference_to" -- packages/spec/src/conversions packages/spec/src/migrations
  → 0 命中
控制:同文件 registry.ts 对 subtitle|alias 有 89 处命中 —— 查询有效,零是读数不是空查

旁证同向且更强，packages/drivers/driver-mongodb/src/mongodb-schema.ts:114 的 docblock 逐字写着：

reference_to is a REJECTED ALIAS, not a normalised one.
FieldSchema.safeParse({ name:'company_id', type:'lookup', reference_to:'company' })
→ "Unrecognized key(s) on this field: reference_to. Did you mean reference_to -> reference?"

⇒ 现状是拒收面有、归一化面无。而本卡的论证恰恰指出拒收面不解决问题：stored metadata 是运行时 JSON，不过 zod parse、不回溯存量。所以工作项 2 成立，直接按 page-header-subtitle-alias 先例落 conversion + os migrate meta。 ⛔ 不要再花一轮去测「是不是已经覆盖了」。

⚠️ 工作项 3 的前提可能不成立 —— 请先证伪再裁

卡片把它写成「reference_field vs referenceField，哪个是规范拼写」，即假定其中一个是现行 spec 键。查下来不是：

git grep -rn "reference_field\|referenceField" -- packages/spec/src   (非测试)
  → 仅 2 处,且都在 describe 散文里作占位符:
     field.zod.ts:1172  `{ [referenceField]: parentId }` — the effective predicate is …
     field.zod.ts:1201  …AND-composed with the parent-relationship condition { [referenceField]: parentId }…

两处都是方括号里的变量占位（「以引用字段名为键」），不是声明的 schema 键。⚠️ 这是一次限定在 packages/spec/src 的部分读数（有控制：邻近词命中，查询有效），不是全树结论。但它把问题掉了个头：要裁的可能不是「两个拼写谁规范」，而是 —— 这两个拼写到底由谁发射、又被谁读？objectui 那 17 处 legacy 臂读的是什么，需要先做一次全树 + objectui 的发射点普查，再谈协议归属。⛔ 不要在普查之前就把其中一个写进 conversion 表。

定级 p2（原 p3）

上调的理由是承重性，不是严重性：本卡是「两半」执行的半 1，而半 2（objectui 删 17 处臂）一旦先落或误落，存量带 reference_to 的 metadata 会静默降级 —— 卡片自己把这条论证得很清楚，且这正是维护者定调「后端的元数据只要对，前端按协议执行就行了呀」所依赖的前提。一张挡着跨仓下游、且失败模式是静默数据降级的卡，不该在 p3。不判 p1：目前没有实际发生的降级，前端臂还在。

⚠️ 跨仓顺序是硬的：本卡落地 且 serve 面证据出具之后，objectui#6837 半 2 才可动。请在半 2 的卡上确认 Blocked-by: 已经落到标签与评论上，而不是只写在正文散文里 —— 散文对解锁扫描不可见。

Clause-② 申报必填（路径肢 packages/spec/src/**）。加一条 conversion 是把先前被拒的拼写变成可接受并归一化 ⇒ 我的读数是 Clause-②: yes（扩宽 accept 面），按 CONTRACT_REVIEW_TIER 派发。spec 域按既定豁免自审，但该行不得省略。

---

Generated by Claude Code

[os-warren]

Claim: session_01PBjwYLS6BciTQW3c9xQiD2 · branch claude/issue-13700-reference-to-conversion · seat domain:spec (os-warren)

Clause-②: yes(采分诊读数:conversion 把先前被拒拼写变为可接受并归一化 = 扩 accept 面)⇒ fable 派发;PR 创建时 draft + needs:contract-review 双载体停靠,放行走 席内 contract review 新流程(维护者 2026-08-31 裁定,固化中 #13795)。

文件面申报(分诊要求):packages/spec/src/conversions/registry.ts(+migrations 若先例带)+ conversion 测试;os migrate meta CLI 半边预计触 packages/cli 的 migrate 命令面——⛔ 不触 packages/rest/src/rest-server.ts(cli 席跨席围栏);若实际需要触碰,dev 停下回报,本席与 cli 席协调后再动。

范围钉死(按分诊):工作项 1 已答(未覆盖,⛔ 不再花轮重测);工作项 2 直接按 page-header-subtitle-alias 先例落 reference_to → reference conversion + os migrate meta + serve 面证据(存量含 reference_to 的 metadata 经 serve 路径下发只含 reference);工作项 3 只做普查不裁(reference_field/referenceField 全树+objectui 发射/读取点普查,⛔ 普查前不把任一拼写写进 conversion 表,结果交回本席送裁)。下游 ui#6837 半 2 的 Blocked-by 落标核查随卡带回。

---

Generated by Claude Code