fix(objectql): update 剥离作用于调用方提交的值,不再连坐抹掉 beforeUpdate hook 的写入 (#5591)

[baozhoutao]

Fixes #5591

问题

静态 readonly 剥离跑在 beforeUpdate 之后,但判据是入口处快照的调用方键名集合。一旦 hook 往某个 readonly 列写了值,「调用方提交过这个键」与「这个键上现在还是调用方的值」就是两件事,而 delete data[name] 删的是后者 —— 于是调用方 payload 里碰巧带了同名键,hook 同一次写入的戳就跟着被删。

前提核验(三条,均在 origin/main 实测,非纸面推断)

前提	结论	证据
P1 suppliedKeys 快照在 hook 前、strip 在 hook 后且 delete 当前值	✅ 成立	engine.ts:5697(快照)→ :5781(triggerHooks('beforeUpdate'))→ :5928 / :6020(两处 strip);rule-validator.ts 的 delete result[name]
P2 正文实测(published_at = null)可复现	✅ 复现	真 ObjectQL + InMemory 驱动 + sys_fetch_previous_update 复刻 + 真 publish hook,落库 {"status":"published","published_at":null,"last_reviewed_at":"2026-08-05T10:00:00.000Z"} —— 与 issue 正文逐字一致,含 last_reviewed_at 活着这一非对称
P3 #4903 对照面(hook 写新 key 能落库)仍成立	✅ 成立,且修法未动它	同一 hook 在调用方不回传该键时落库 published_at = NOW

P2 的那条非对称是本单最有力的证据:同一次写、同一个 hook、两个都是 readonly 的列,调用方回传过的那个死了,没回传的那个活着。存亡只取决于 payload 里有没有同名键 —— 不可能是有意语义。

三路线取舍(按实测,不按偏好)

路线	实测判据	取舍
A. hook 前剥离	探针实测:beforeUpdate hook 当前能看到 ["id","title","published_at"]。hook 前剥离会把 readonly 键从 hook 视野里抹掉	❌ 否决
B. 快照携带值,剥离时比对身份	时序一动不动,只收窄 strip 的判据	✅ 采用
C. supplied 快照与 hook 写入分账	需要在引擎里维护第二套 payload 账本;B 已用一个参数达到同一效果	❌ 过重

否决 A 的实测依据具体到在案代码:plugin-auth 的 ADR-0092 身份写守卫(identity-write-guard.ts guardUpdate)读 ctx.input.data 的键集,并把非白名单键写进它抛出的错误正文和 warn 正文(None of the submitted fields (…) are editable)。hook 前剥离会让这些键在守卫看到之前就消失:纯 readonly 提交时该错误退化成 (—),混合提交时 warn 不再点名 —— 一条 loud 诊断被静默削弱。B 路线让调用方 payload 原封不动地到达 hook,只收窄剥离自己的判定。

修法

入口快照改为携带调用方的值(必须是浅拷贝:hook 原地改 opCtx.data,hookContext.input.data 起初就是同一引用),剥离时多一道身份比对:

• 键不在快照里 → 服务端戳,保留(security: 服务端 readonly 字段在 UPDATE 时未强制（可被用户上下文覆盖） #2948 原有语义,未动)
• 键在快照里但值已被 hook 换掉 → 平台写入,保留(update 路径的 stripReadonlyFields 删除的是 hook 已覆写的当前值而非调用方提交的值 —— 调用方回传 readonly 键会连坐抹掉 beforeUpdate hook 的写入,可落出 status=published 而 published_at=null 的行(17.0.0-rc.2) #5591 新增)
• 键在快照里且值仍是调用方的 → 剥离(security: 服务端 readonly 字段在 UPDATE 时未强制（可被用户上下文覆盖） #2948 逐字不变)

两处细节写进了注释,因为都是会被后人「顺手简化」掉的:用 Object.is 而非 ===(=== 认为 NaN !== NaN,会把调用方伪造的 NaN 读成「hook 改过」而保留伪造值 —— 唯一一处松散运算符会反转结论的输入);用 own-property 而非 in(字段机器名正则允许 constructor,in 会在任意普通对象上为它返回 true,从而剥掉一个 hook 戳)。

stripReadonlyFields 未从 packages/objectql/src/index.ts 导出,是包内函数,故签名可直接收敛,无对外破坏面。

语义边界(#2948 / #3003 / #3015 一字未弱化)

调用方提交、无 hook 覆写的 readonly 值,照旧被剥 —— 单条与谓词两条路径都有用例钉住。isSystem / preserveAudit 未动。insert 面未动:其自身更窄的 stripRuntimeOwnedFields 带同类缺陷(实测:调用方提交 + hook 覆写 → hook 写入被删、序列补发),已另立 #6339,本 PR 不修,并留了一条 insert 不受影响的回归钉。

反向验证(方向先写死,再跑)

肢 A = 还原剥离判据(删掉值身份比对,回到键集读法)。预测:正文场景用例翻红,published_at 回 null;#2948 与 #4903 全绿。 预测在跑之前写死在 8 条具名用例上。

实测结果 —— 8 红,与预测逐条吻合,预测为绿的 130 条全绿:

× KEEPS a readonly key a hook OVERWROTE, even though the caller supplied it
× KEEPS a hook-REWRITTEN record number the caller DID supply (#5591)
× THE REPORT: a whole-record write-back lands the hook stamp, not null
× the two read-only columns of one write now agree (the asymmetry is gone)
× the BULK path is fixed on the same terms
× a hook-overwritten key is NOT reported as dropped to onFieldsDropped
× strictReadonlyWrites refuses the forge and admits the hook write
× [#5591] a hook OVERWRITING a key the caller supplied now survives the strip

AssertionError: expected null not to be null      ← 正文那一行,原样翻红
Test Files  3 failed (3)
     Tests  8 failed | 130 passed (138)

expected null not to be null 就是 issue 正文报告的那行数据本身。

用例处置(三档分开判,不批量重拼)

engine-readonly-strip-signal.test.ts 里那条 a hook cannot rescue a key the CALLER supplied 是整条替换,不是改写:它钉的正是本 PR 删掉的那条肢,原注释自己写着「pinned as EXISTING behaviour so the next change to it is deliberate. Nothing here endorses it」—— 本 PR 就是那个 deliberate change,替换后连同该文件头部的机制描述一并更新。其余单测是重拼(new Set([...]) → 调用方 payload 快照对象,值与 data 一致,判定不变)。

测试

新增 packages/objectql/src/engine-readonly-strip-caller-values.test.ts(13 例):正文场景、非对称消失、#2948 两例(含「hook 存在但本次未触发」这一档)、#4903 对照、bulk 两面、onFieldsDropped 两面、strictReadonlyWrites 两面、hook 仍能看见调用方值(A 路线否决理由的钉子)、isSystem、insert 回归。

pnpm --filter @objectstack/objectql test      → Test Files 140 passed, Tests 2298 passed
pnpm --filter @objectstack/objectql typecheck → tsc --noEmit, 干净
node scripts/check-engine-double-contract.mjs → OK — 77 pinned, 133 DEBT, 2 exempt
node scripts/check-durability-degradation-log-level.mjs → ✓ 24 seam(s) all loud
node scripts/check-nul-bytes.mjs → OK (5990 files)
pnpm lint (eslint . --no-inline-config) → 干净
pnpm check:query-options-erasure → ✓ 267 test site(s),在天花板上,未新增

远端 CI:24 个 check 全绿(2 个 skipped 属正常路径过滤),含 Check Changeset、TypeScript Type Check、Test Core ×3、Dogfood Regression Gate ×3。首推曾红一次,原因不是 ESLint 本身而是同 job 的后续步骤 check:query-options-erasure:新用例里复刻 sys_fetch_previous_update 的那次 by-id 查询用了 as any,把 #4918 的测试面计数顶到 267 → 268。该查询并非有意脱离契约(就是一次普通 by-id 读),故按该 ratchet 指定的两条出路里选了「把 options 定型」而非 as unknown as,计数回到 267。

消费半径扫过(该规则只由 engine.ts 消费,故按行为半径跑下游包):
plugin-pinyin-search 14 / plugin-audit 112 / plugin-sharing 359 / platform-objects 275 / metadata-protocol 502 / plugin-security 768,全绿。顺带一提:plugin-pinyin-search 的 __search(readonly + system)正是被 beforeUpdate hook 写的投影列,整记录回传下旧行为会静默删掉 hook 重算的值、让搜索投影变陈旧 —— 本 PR 一并修好。

packages/qa/dogfood/test/authz-conformance.matrix.ts 的 enforcement 描述同步收敛为「caller-supplied VALUES」,避免留下一处 declared ≠ enforced 的陈述。

已知边界(写进代码与 changeset,不粉饰)

快照是浅拷贝,所以 hook 若原地修改调用方提交的对象/数组,身份不变、无法与「hook 没动」区分,该字段仍会被剥。除非每次写都深拷贝 payload,否则任何比较都看不见这一档,这条路径不付这个代价;回落方向是 #5591 前的行为(剥离),即 fail-safe。已单独钉成用例并写明:hook 要写 readonly 列请赋值。

必答项

• 单 id update 把同一行前置状态读了 3 次(engine 前置行门 + sys_fetch_previous_update + plugin-audit captureBefore),且后两次不受任何按对象需求门约束 #5846(单 id update 三读前置状态):未触其面。本 PR 没动 wantsPriorRecord 门、没动 sys_fetch_previous_update、没新增任何读。定价影响:中性偏易。单 id update 把同一行前置状态读了 3 次(engine 前置行门 + sys_fetch_previous_update + plugin-audit captureBefore),且后两次不受任何按对象需求门约束 #5846 的修法形状是把 delete 侧的时序(先读前像再派发 before 钩子)搬到 update 侧;本 PR 让 strip 不再依赖「执行到剥离时值是什么」,只依赖入口快照,因此那次时序搬迁少了一个必须同步推理的耦合点。
• delete() 的按对象前置行门在任何 kernel 托管引擎上恒真 —— ObjectQLPlugin 自带的 sys_fetch_previous_delete 以 object: '*' 注册在 beforeDelete #5929(delete 门恒真):未触其面(如预期)。改动全在 update 剥离判据,delete 路径与其 dispatch 门一行未动;check-engine-double-contract 的 delete 切片仍 OK。
• [objectql] readonly 字段:服务端插件 data.update 直写被静默剥离(200但值不变),与 beforeUpdate Hook 补写可落库不对称 #4903 定价:变简单。[objectql] readonly 字段:服务端插件 data.update 直写被静默剥离(200但值不变),与 beforeUpdate Hook 补写可落库不对称 #4903 的争点是「插件无 context 被当成不可信调用方」这一身份判定;本 PR 不碰身份判定,但把它的对照面补齐了 —— hook 派生写此前的存亡取决于调用方 payload 有无同名键,现在统一为「hook 写入即平台写入,一律存活」。[objectql] readonly 字段:服务端插件 data.update 直写被静默剥离(200但值不变),与 beforeUpdate Hook 补写可落库不对称 #4903 从此只剩一个变量(context 的身份判定),不再需要同时解释「为什么同为 hook 写、有的活有的死」。
• 写入载荷里的算子对象:text 型字段不做类型校验,{ title: { $in: [...] } } 原样写进库(number 型会响亮拒绝) #5922 交互(实测答):拒收在剥离之前,且对 readonly 字段根本不适用,顺序不引入新问题。validateRecord 在 engine.ts:5831,strip 在 :5928,故先拒后剥。但实测:readonly 字段提交算子对象 → 不抛,随后被剥(record-validator 对 readonly 字段本就跳过校验);非 readonly 字段提交算子对象 → 正常抛 ValidationError: title has an invalid text value: $gt is a filter operator, not a value。两条顺序本 PR 均未移动,写入载荷里的算子对象:text 型字段不做类型校验,{ title: { $in: [...] } } 原样写进库(number 型会响亮拒绝) #5922 与本单无冲突面。

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 7, 2026 2:39pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/dogfood.

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

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx (via @objectstack/objectql)
• content/docs/deployment/vercel.mdx (via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx (via packages/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/permissions/authorization.mdx (via packages/qa/dogfood)
• content/docs/permissions/delegated-administration.mdx (via packages/qa/dogfood)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql)
• content/docs/protocol/kernel/index.mdx (via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx (via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
• content/docs/releases/implementation-status.mdx (via @objectstack/objectql)

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.