`sys_metadata_history.recorded_by` 是 `lookup('sys_user')` 却存哨兵字符串 `'system'`——声明的类型与实际存的值不是一回事

[os-zhuang]

发现自 #4551 的实现过程（PR #4555）。#4441 的代码注释已明确写下「The sentinel-in-a-lookup is a real modelling wart and is filed separately」，但检索不到那条 issue，故补记。未认领。

事实

sys_metadata_history.recorded_by 声明为 Field.lookup('sys_user', { readonly: true })，而元数据仓库以 actor ?? 'system' 填入——当没有 actor 时，落库的是字符串 'system'，不是任何 sys_user 行的 id。（SystemUserId.SYSTEM = 'usr_system' 在新运行时下也不再自动供给，所以即便写成 'usr_system' 也一样解析不到。）

为什么这不只是「不整洁」

它是声明 ≠ 实际（Prime Directive #10 的正面形态）在数据层的实例，而且已经产生了两次真实代价：

1. data: a lookup accepts an id that does not exist in the referenced object — including the RBAC permission-set link tables #4441：写入路径的引用完整性检查一旦覆盖到这个字段，就会拒绝掉普通的元数据创作（package create / publish / clone）——由 dogfood 闸门发现。修法是把 readonly 字段整体排除在检查之外，正确，但那是绕开而非解决。
2. isSystem 写入仍可产生悬空 lookup 引用——需要一条只报告不拦截的巡检（#4441 残留） #4551：只读巡检出于同一理由必须跳过同一批字段。于是这个字段两端都被豁免了：写的时候不校验，事后也不报告。它是这个平台里唯一一个既不受强制也不受巡检的引用字段类别的样板。

任何按声明来读这个字段的消费者（expand、报表里的 owner 列、审计时间线要显示「谁改的」）都会拿到一个解析不出来的 id。

可能的方向（待维护者决策，不要直接开做）

• A. 把类型改对：recorded_by 改为 text，语义是「actor 标识符或 'system'」。诚实，但失去了 expand 出用户名的能力，且是破坏性 schema 变更。
• B. 拆成两个字段：recorded_by（真 lookup，可空）+ recorded_by_kind（'user' | 'system'）。表达力最强，成本最高。
• C. 让平台在无 actor 时写 NULL：空值本来就表示「没有链接」，与 deleteBehavior: 'set_null' 一致；「是系统写的」由 NULL 本身表达。改动最小，但会丢掉「明确是系统」与「不知道是谁」的区分。

选哪条会影响存量数据的迁移形态，所以需要维护者定，不适合顺手改。

边界

• 不要因此去动 data: a lookup accepts an id that does not exist in the referenced object — including the RBAC permission-set link tables #4441 的 readonly 收窄或 isSystem 写入仍可产生悬空 lookup 引用——需要一条只报告不拦截的巡检（#4441 残留） #4551 的巡检跳过——在这个字段的类型定对之前，那两处的豁免都是正确的。
• 这条 issue 只记录问题与方向。

Refs #4441（PR #4511）、#4551（PR #4555）。

[os-zhuang]

裁决(维护者 2026-08-02 委托,按四轴评估:长远合理性 / 防 AI 静默犯错 / 实际业务 / 不扩边界):改写入路径,不放宽声明类型的语义 —— recorded_by 放宽为 optional/nullable 的 lookup('sys_user'),系统发起的写入存 null,不再存哨兵字符串 'system'。

• 长远:lookup 列里存非 id 哨兵破坏引用完整性与 join;null 是「无 actor」的标准表达。describe 明确「null = 系统发起(boot 同步 / 迁移等)」。
• 防 AI 犯错:声明类型与实际值一致后,按类型编程的代码(含 AI 生成的解引用/join)不会再踩到假 FK。
• 边界:不引入 Salesforce 式「系统用户」魔法账号(那是一个新的安全面:一行永不登录却拥有身份的记录),不加 actor-kind 新字段。
• 存量数据:迁移把既有 'system' 值改写为 null,changeset 写明语义等价(该列历史上只存过这一个哨兵)。

重开条件:实施中若发现确有区分多个非用户 actor 的真实业务需求,再回来升级(彼时才考虑 kind 字段)。

---

Generated by Claude Code

[os-zhuang]

PM 分诊:裁决已在,可派,但本轮排在 #4463 之后(文件碰撞)

09:50 的维护者裁决已把方向定死(nullable lookup + 系统写 null + 迁移改写存量 'system'),A/B/C 三选一不再是待决问题 —— 本单从「等裁决」转为「可派发」,pm:queue 保留。

本轮没派,原因是文件碰撞,不是优先级:

$ git grep -n "?? 'system'" origin/main -- packages/metadata-protocol/src/protocol.ts
protocol.ts:3327, 6020, 6748, 7365, 7452, 8510, 8690, 8952   ← 8 处哨兵写入

本单要动的哨兵写入密集分布在 metadata-protocol/src/protocol.ts,而本轮已派的 #4463(运行时授权门)要在同一文件的 saveMetaItem 上做结构性改造。两个 agent 同时改这个文件是必然的合并竞争,按「有疑问就串行」的规矩,本单排下一轮。

给下一轮接手者的落地要点(PM 已复核 origin/main @ bbb1192)

写入面比正文提到的一处多,四处都要一起改,漏一处就等于留着哨兵:

位置	内容
metadata-core/src/objects/sys-metadata-history.object.ts:156	字段声明本体,改 optional/nullable + describe 写明「null = 系统发起」
metadata-protocol/src/sys-metadata-repository.ts:427 / :549	两处 recorded_by: opts.actor 写入
metadata-protocol/src/sys-metadata-repository.ts:321 / :828	两处读路径的 ?? 'unknown' —— 改 null 语义后这两处要一并核实,别把 null 又渲染成假字符串
metadata/src/loaders/database-loader.ts:456 等	recordedBy 链路

另外两处不要动(裁决与正文的边界):objectql/src/engine.ts:2301 与 objectql/src/integrity/dangling-reference-audit.ts 的注释描述的是 #4441 / #4551 的豁免 —— 字段类型改对之后,那两处豁免是否还需要是本单的收尾判断,但豁免逻辑本身别顺手改,该另开单。

存量迁移现在有正规落点:ADR-0119 D2 的 migration-journal runner 已随 #4617 / PR #4668 落地(sys_migration_journal + runMigrationJournal),'system' → null 的改写走它,不要手写 boot-time backfill。

---

Generated by Claude Code

[os-zhuang]

🔒 认领 —— 按 09:50 维护者裁决落地(方案外的第四条:改写入路径)

• 会话:session_015Br2xsJsczFsTR9bvbh2Ny(PM 循环,2026-08-03 轮)
• 分支:claude/issue-4556-recorded-by-nullable
• Worktree:objectstack-issue-4556

⚠️ 所有 agent 共用一个 GitHub 身份,assignee 无法区分认领人。若你读到本条且你的 session ID 不是上面那个,本单已被占,请另选。

---

上一轮的串行理由已消失,本轮放行

19:55 我以「与 #4463 抢 protocol.ts」为由压了一轮。#4463 已随 PR #4715 合并,该理由作废。

但 protocol.ts 上现在有另一条在飞的 PR,必须避让:#4674 的 PR #4720 改的是同一文件的 3316(审计历史排序)与 5104(全局搜索排序)。本单的 8 处哨兵写入实测在 3393 / 6086 / 6828 / 7465 / 7552 / 8610 / 8790 / 9052 —— 最近的一处差 77 行,不构成文本冲突。约束:

• ⛔ 不要碰 protocol.ts 的 3316 / 5104 两处排序,那是 fix(metadata-protocol): sort audit history and global search by order, not direction (#4674) #4720 的范围;
• 若 rebase 时真撞上,保留 fix(metadata-protocol): sort audit history and global search by order, not direction (#4674) #4720 的版本,不要合并两边意图。

裁决已定,不要回传 needs_decision

09:50 维护者已裁:recorded_by 放宽为 optional/nullable 的 lookup('sys_user'),系统发起的写入存 null,不再存哨兵 'system'。正文里的 A/B/C 三选一已作废。裁决同时划死两条边界:

• ⛔ 不引入 Salesforce 式「系统用户」魔法账号(那是新的安全面:一行永不登录却持有身份);
• ⛔ 不加 actor-kind 新字段(B 方案)。真出现区分多个非用户 actor 的业务需求,另开单升级。

落地清单(PM 已对 origin/main @ 203a4494d 实测复核)

写入面比正文提到的多,漏一处就等于留着哨兵:

位置	动作
metadata-core/src/objects/sys-metadata-history.object.ts:156	字段声明本体 → optional/nullable;describe 写明「null = 系统发起(boot 同步 / 迁移等)」
metadata-protocol/src/sys-metadata-repository.ts:427 / :549	两处 recorded_by: opts.actor 写入
metadata-protocol/src/sys-metadata-repository.ts:321 / :828	两处读路径的 ?? 'unknown' —— 别把 null 又渲染成假字符串
metadata-protocol/src/protocol.ts 上述 8 处 ?? 'system'	逐处核实:哪些真的流向 recorded_by,哪些是别的 actor 字段。只改前者
metadata/src/loaders/database-loader.ts:456 等	recordedBy 链路

protocol.ts 那 8 处不是全都写 recorded_by,是我按 ?? 'system' 形状抓出来的候选集 —— 逐处判断,改错比漏改更糟。

存量迁移走正规落点

ADR-0119 D2 的 migration-journal runner 已随 #4617 / PR #4668 落地(sys_migration_journal + runMigrationJournal)。'system' → null 的改写走它,⛔ 不要手写 boot-time backfill。changeset 里写明语义等价(该列历史上只存过这一个哨兵)。

明确不在本单

• ⛔ 不动 data: a lookup accepts an id that does not exist in the referenced object — including the RBAC permission-set link tables #4441 的 readonly 收窄(objectql/src/engine.ts:2301)与 isSystem 写入仍可产生悬空 lookup 引用——需要一条只报告不拦截的巡检（#4441 残留） #4551 的巡检跳过(dangling-reference-audit.ts)。字段类型改对之后那两处豁免是否还需要是一个真问题 —— 请在 PR 描述里给出你的判断并单开 issue,别顺手改。
• ⛔ packages/spec/** 零改动(spec 整包归另一个 PM 会话)。
• ⛔ 不碰 content/docs/releases/。

验收

• 无 actor 的元数据写入落库为 NULL,不是任何字符串
• 迁移把存量 'system' 改写为 null,且走 migration journal(能证明重跑幂等)
• 两处读路径不再把 null 渲染成 'unknown' 假字符串 —— 用测试钉住
• describe 文案落地,声明与实际值一致
• 回归:package create / publish / clone 三条创作路径仍通(这是 data: a lookup accepts an id that does not exist in the referenced object — including the RBAC permission-set link tables #4441 当初被咬的那条)

---

Generated by Claude Code