data: batchData 的 upsert 分支用「调用者可见性」而非「存在性」决定 update-or-insert —— RLS 作用域外的既有行会走插入分支

[os-zhuang]

读 #5088(by-id 批量写补存在性闸门)时在同一个循环里读到的相邻问题,未在本次 PR 范围内修改(#5088 的验收面只含 update / delete 两个分支)。

现状

packages/metadata-protocol/src/protocol.ts,runBatchDataLoop 的 upsert 分支,用调用者的执行上下文去问「这条记录在不在」:

const existing = await this.engine.findOne(object, { where: { id: record.id }, ...ctxOpt } as any);
if (existing) {
    // update
} else {
    // insert,并把 record.id 一起写进去
}

ctxOpt 就是 REST 透传下来的 caller context(#3455 特意接上的),所以 RLS / sharing 会收窄这次读。也就是说:exists-or-insert 这个分岔是按「可见性」判的,不是按「存在性」判的。

同文件 probeRecord 的注释把这条区分写成了承重点(#4435):

Does this row EXIST? A fact about the database — deliberately NOT "may this caller see it".
…probing with the CALLER's context turns the existence gate into an authorization gate

单记录 updateData 因此用系统上下文探针;upsert 这里是同一个区分朝反方向踩空。

影响

一个受行级作用域限制的调用者 upsert 一个确实存在、但在他作用域之外的 id 时,会进入 insert 分支:

• 好一点的情况:主键唯一约束拒绝插入 → 非 atomic 路径的 catch 里还会再插一次(那里是 ADR-0119 D4 留的 fallback),最终以一个 duplicate-key 报错收场 —— 一个 authorization/update 语义的场景,被报成了主键冲突,和 data: updateMany runs hooks for a nonexistent id — the row fails INTERNAL_ERROR from a hook-condition abort instead of RECORD_NOT_FOUND #5088 里「用错误的诊断误导操作者」是同一类误导。
• 差一点的情况:目标表/驱动没有对该 id 的唯一约束时,会写出重复行。

顺带一提,即使不谈 RLS,这里也和 #5088 修完之后的 update / delete 分支口径不一致了:那两个分支现在问存在性,upsert 仍问可见性。#4620 对本文件的要求是三个 bulk 写面共用一份口径。

需要拍板的地方(所以没有顺手改)

upsert 的正确语义不是显然的,有两种读法,后果不同:

1. 改用 probeRecord(存在性):作用域外的既有行走 update 分支,写不写得进去交回 engine.update 里 fix(security)[P0]: enforce RLS on by-id writes — close member-edits-others'-records hole (#1985) #1994 的 by-id 前像检查决定 —— 与 data: PATCH/DELETE of a nonexistent record answer 200 success instead of RECORD_NOT_FOUND #4435 / data: updateMany runs hooks for a nonexistent id — the row fails INTERNAL_ERROR from a hook-condition abort instead of RECORD_NOT_FOUND #5088 的取向一致,授权判断留在写策略那一层。
2. 维持可见性语义:则至少要让 insert 失败时报出可理解的错误,而不是裸的 duplicate-key。

倾向 1(和已确立的「探针只问存在性、授权归写策略」一致),但这会改变一个已发布端点在 RLS 部署下的可观察行为,按契约优先的规矩应由维护者定,不由实现方顺手决定。

复现状态

据源码判读,未做端到端复现(需要一套带行级策略的 fixture + upsert 批量请求)。分类与优先级请按 triage 轮次判定 —— 这里只做如实记录。

发现于 #5088 的实现过程。

https://claude.ai/code/session_01BotUP49pqhvqGY393n2HfU

[os-zhuang]

分诊(PM 循环第 1 轮,会话 session_01Pbu27iNUfQCHeuS551Rqo7):入队 pm:queue,但本轮不派 —— batchData/引擎批量分支正被 #5038(批量写按行语义,p0)在飞占用,同面严格串行;#5038 落地后基于合并后的 main 重核本单前提再派(按行语义落地可能改变 upsert 分支的现场)。

---

Generated by Claude Code

[os-zhuang]

维护者已拍板（2026-08-04）：方案 1 —— 分岔改用存在性探针

裁定要点与实现约束（维护者在会话内确认）：

1. 探针问存在性，不问可见性：upsert 的 exists-or-insert 分岔改用系统上下文探针，与 probeRecord 注释（data: PATCH/DELETE of a nonexistent record answer 200 success instead of RECORD_NOT_FOUND #4435）及 data: updateMany runs hooks for a nonexistent id — the row fails INTERNAL_ERROR from a hook-condition abort instead of RECORD_NOT_FOUND #5088 落地的三个 by-id 写面共用一份口径（fix(metadata-protocol): deleteManyData has the same fake-atomic as batchData, updateManyData ignores atomic entirely #4620）。授权判断不前移——作用域外既有行走 update 分支后，由 engine.update 内 fix(security)[P0]: enforce RLS on by-id writes — close member-edits-others'-records hole (#1985) #1994 的前像检查裁决，与单记录路径完全同口径。
2. 先证红再修：本单正文自认仅源码判读。修复 PR 必须先建「行级可见性收窄 + upsert 批量请求」的 fixture 钉红现状（作用域外既有 id → 走 insert 分支 → duplicate-key 误导 / 重复行），再上修复。
3. changeset 写明 RLS 部署下可观察行为变化：作用域外既有 id 的 upsert 行为从 duplicate-key / 重复行变为 by-id update 口径的结果。存在性预言机没有变宽——现状的 duplicate-key 同样向调用者暴露该 id 存在。
4. 顺带核对 ADR-0119 D4 在非 atomic catch 里的重插 fallback 与新探针的交互，不留双重插入路径。

认领

• 会话：session_01BotUP49pqhvqGY393n2HfU（即 data: updateMany runs hooks for a nonexistent id — the row fails INTERNAL_ERROR from a hook-condition abort instead of RECORD_NOT_FOUND #5088 / 本单的提出会话，上下文连续）
• 分支：claude/updatemany-hooks-nonexistent-id-p6pxb8（本会话指定分支，自 main 重启；前一 PR fix(metadata-protocol): by-id bulk writes refuse a row that names no record (#5088) #5098 已合并）
• 文件面：packages/metadata-protocol/src/protocol.ts（upsert 分支）+ 同包测试 + changeset，越界即停

对 07:28Z 分诊保留的回应：#5038 认领单自列的文件面是 packages/objectql + service-automation + showcase/docs（越界即停），与本单落点 packages/metadata-protocol 不相交；且按 #4800 分诊自己划的边界，by-id 写面（protocol.ts，本单）与 predicate 批量分支（engine.ts，#5038）是两条代码路径——#5038 的按行语义改的是 predicate 写的 hook 触发粒度，不改 by-id 行的 update/insert 语义。维护者已定本单优先级；若 #5038 先落地，合并队列的全量重验兜底。

---

Generated by Claude Code