fix(metadata-protocol): PATCH /data/:object/:id binds the PATH row, not the body's id (#6479)

[os-zhuang]

Fixes #6479

结论先说

PATCH /data/:object/:id 这一条 ingress 上,行标识以路径 :id 为准。请求体里的标量 id 不再能把写落到别的行上。

实现落在 packages/metadata-protocol/src/protocol.ts 的 updateData 区,一处派发前的载荷合并;引擎、packages/spec 都没动。

前提复核(在 origin/main 上逐条读过,不是照抄 issue)

Issue 说的三方打架,在合并后的 main 上完整成立(行号已漂移,以下按当时 e6025e9 重新定位,现已再合并至 d6d1a50be):

• protocol.ts:5743 const current = await this.probeRecord(request.object, request.id) —— 存在性探测判路径 id;
• :5748 this.assertVersionOf(request.object, request.id, current, request.expectedVersion) —— OCC 判路径 id;
• :5749 const opts = { where: { id: request.id } },:5759 await this.engine.update(request.object, request.data, opts) —— request.data 原样下发;
• :5760–5764 回执 { id: request.id, record: result }。

而 packages/metadata-core/src/engine-update-dispatch.ts 的规则是载荷优先,案例表里写着 a SCALAR data.id still wins over a scalar where.id(expectId: 'rec_1')。两者相加:PATCH /data/task/rec_1 带 body {"id":"rec_2","title":"x"} 会探测 rec_1、按 rec_1 校 If-Match、写 rec_2、再回一个 id: rec_1 配 rec_2 的回读。rec_2 从未被探测、也从未被 OCC 校验。

线上到引擎之间确实没有任何一层剥 id:rest-server.ts 的 PATCH 路由只解构掉 expectedVersion;UpdateDataRequestSchema 把 data 声明为 z.record(z.string(), z.unknown())。

做法(裁决路线 A)

派发前把路径 id 盖到载荷上,和批量 ingress 对同一问题的既有答案同形:

// 单条(本 PR)
{ ...request.data, id: request.id }
// 批量(rest-server.ts,一直如此)
ql.update(op.object, { ...data, id }, …)

于是探测的行、OCC 校的行、真正写的行、回执 id/record 指的行,是同一行 —— URL 里那一行。一个仓库对「一次单行写绑定哪一行」只剩一个答案(#4550 / #4434 那一族)。

几点边界,都是刻意的:

• 不改任何引擎判定。 这次调用照旧 dispatch 成 by-id,绑定的还是 where 本来就带着的那个 id。ObjectQL.update 的 data.id 不做标量测试 —— 载荷里的算子对象被当成主键绑定,且盖过显式 options.multi: true #5748 的载荷优先规则、update 的 **by-id** 路径同样把非标量 data.id 交给驱动写主键列(#6262 的孪生形状,where.id 胜出时) #6435 / PR fix(objectql): by-id 更新不再把「已判定不是主键」的载荷 id 写进 SET 子句 (#6435) #6475 的 by-id 载荷剥离,都没碰,ENGINE_UPDATE_DISPATCH_CASES 一行未动。
• 不是路线 B,也不是路线 C。 裁决明确否掉了「body id 与路径不等就 400」和「在 UpdateDataRequestSchema 层禁 id」;前者在已发布 API 上新增一条拒绝,后者改的是被接受的请求形状。本 PR 两者都不做,接受的 body 形状一字未变。
• 非记录载荷原样透传(undefined / null / 数组)。引擎是故意不做保护地读 data.id 的,所以 undefined 在那边就该是 TypeError;ingress 若在这里合并出一个 { id },就会把一次坏调用答成一次成功的空写 —— 比 producer 更宽容,正是 engine-update-dispatch.ts 存在的目的所要防的那件事。这些形状本身也没有标量 id 去压 where.id,所以不变式对它们靠 opts.where 就成立。
• 没有加 warn 日志。 import-runner.ts 每匹配一行都走这条 ingress,body 里带 id 是 CSV 导入的常态,逐行 warn 会在导入路径上产生无界日志;批量 ingress 也一直是静默覆盖。两条 ingress 保持同一种沉默。

测试

新增 packages/metadata-protocol/src/protocol.update-path-id-wins.test.ts(16 例)。钉的是 ingress 级不变式,不是「这行代码在」:探测的行、OCC 校的行、写的行、回执的 id/record,是同一行 —— 路径行。

fake engine 的 update 不自己复刻规则,而是调用 producer 的 assertEngineUpdateDispatch(data, options) 并服从它给出的绑定行(delete 同样开在 assertEngineDeleteDispatch(options))。这一点是关键:若在这里手抄一个 if (opts?.where?.id),每条用例都会写 rec_1,整套测试会把「早就修好了」报成绿。

覆盖:

• (a) body id === 路径 id —— 最常见的「GET 一条、改字段、整份 PUT 回来」仍然成功,落在路径行;
• (b) body id ≠ 路径 id —— 写落在路径行,另一行未被触碰(断言的是它存下来的行体,不是返回值);回执 id 与 record.id 不再互相矛盾;body id 指向一条不存在的行时,仍然写路径行(修复前这里回的是 { id: 'rec_1', record: null });
• (c) OCC —— 匹配路径行的 If-Match 放行,且放行的是路径行的写;过期 token 是 CONCURRENT_UPDATE / 409 且两行都没动;送另一行的版本号(正是 body 指向的那行)照样 409,currentVersion 报的是路径行的 —— OCC 判的是路径行,现在守的也正是被写的那一行;
• (d) 对照钉:路径 id 指向空行仍是 RECORD_NOT_FOUND / 404 且 engine.update 完全未被调用;无 id 的普通 PATCH、非标量 / 假值 body id(算子对象 / 数组 / null / 0,即 update 的 **by-id** 路径同样把非标量 data.id 交给驱动写主键列(#6262 的孪生形状,where.id 胜出时) #6435 那一族)、数组载荷,全都绑定路径行;undefined / null 载荷仍然抛引擎自己的 TypeError。

最后一条刻意不按 ADR-0112 断言 code + status,差别正是要点:那不是本 ingress 新装的一条拒绝,而是 ObjectQL.update 对缺失载荷不做保护地读 data.id 的调用方编程错误,原样浮出来。报告里照实说明,而不是套模板凑一个信封断言。

反向验证(方向先预测,再执行)

预测:撤掉修复后,只有「被写的行会变」的那几条转红,对照钉保持绿。

git checkout origin/main -- packages/metadata-protocol/src/protocol.ts 后重跑该文件:4 红 / 12 绿,与预测一致 ——

× (b) body id !== path id …            AssertionError: expected 'rec_2' to be 'rec_1'
× (b2) 回执自洽 …                       AssertionError: expected 'rec_2' to be 'rec_1'
× (b3) body id 指向不存在的行 …          AssertionError: expected null to match object { id: 'rec_1', title: 'x' }
× (c) 匹配的 If-Match 放行的是路径行 …    AssertionError: expected 'rec_2' to be 'rec_1'
Test Files  1 failed (1)      Tests  4 failed | 12 passed (16)

转绿的 12 条不是凑数:(a)、404、非标量 body id、TypeError 那几条在修复前后本来就该同样是绿,它们钉的是这次改动不许动的行为。

本地跑过的

pnpm --filter @objectstack/metadata-protocol test   → 59 files / 643 tests passed
pnpm --filter @objectstack/rest test                → 68 files / 1039 tests passed
objectql: engine-update-dispatch / engine-update-by-id-payload-id
          / engine-update-multi-payload-id          → 3 files / 58 tests passed  (#5748 / #6435 的钉未受影响)
pnpm lint                                           → clean
turbo run typecheck (packages/* + packages/*/* + apps/*) → 120/120 successful
lint.yml 里 40 条 check:* 逐条跑过                    → 全 PASS(含 check:engine-double-contract、
                                                       check:kernel-hook-pairs、check:type-check-debt)

check:type-check-debt 第一次在我自己批量脚本给的 3 GB 堆上 OOM 了,单独用 6 GB 重跑通过 —— 是我的资源设置,不是门禁判定。

后继定价(PM 要的三张卡)

• meta overlays: a deleted overlay stays in the /meta listing though dispatch correctly 404s (#4432 residual) #5079(已删 overlay 仍出现在 /meta 列表):不受影响。那条走 getMetaItems 的读路径与 overlay 索引,与单条数据写 ingress 无交集。
• [metadata-protocol] ensureOverlayIndex 先 DROP 后 CREATE：partial 索引建失败时 sys_metadata 会静默地失去覆盖层唯一约束 #6418(ensureOverlayIndex DROP-then-CREATE 窗口):不受影响。同一文件、不同区域(索引维护),本 PR 未触及;两处的临近只是文件级的,不是逻辑上的。
• [转移] 发布期护栏:多组织下「平台级 + schedule + create_record + 未显式 organization_id」拒绝——#6155 Q3=A 裁决的 lint 半边 #6285(runtime authoring gate 缺少输入):略微变容易。该 gate 的输入取自写 ingress 交给引擎的载荷;现在这条 ingress 交出去的载荷里,id 一定等于被写的行,少了一种「载荷说一行、被写的是另一行」的输入歧义要先澄清。仅此而已,不构成它的修复。

范围外发现

无。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 1:15pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

4 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx (via @objectstack/metadata-protocol)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/metadata-protocol)
• content/docs/releases/v9.mdx (via @objectstack/metadata-protocol)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.