fix(objectql,lint): 服务端为 requiredWhen 绑定 parent 作用域,并把构建期硬闸扩到同一格 (#4977)

[baozhoutao]

Fixes #4977

按维护者 2026-08-06 裁决执行 A + C;B(不可求值 422 拒写)明确不做,留 ADR-0058 D5 复审。

前提复核(三条,全部成立)

	结论	证据
P1 requiredWhen 的 parent 作用域今天确实不绑	✅ 成立	rule-validator.ts 的 requiredWhen 分支求值上下文只有 { record: merged, previous }。反向验证实测:去掉本 PR 的 parent 传参,新增的 4 条命中用例立刻转红。
P2 #4889 管件在 main 且形态可复用	✅ 成立	resolveMasterDetailRelation / resolveMasterDetailParent(s) / readsParentRoot / unknownVariableOf 全部原样复用,本 PR 没有新建第二套。
P3 仓内暂无 app 使用该形态	✅ 成立	全仓 grep:parent 作用域的 requiredWhen 只出现在 lint 的一条测试 fixture 里;showcase 的 invoice line 用的是行作用域 record.quantity >= 100(invoice.object.ts L212,原注释已写明 "ROW-scoped")。属补潜伏缺口,不改变任何现有 app 行为。

肢 A —— 服务端绑 parent(求值语义不动)

引擎在三个调用点解析主表头并传入求值器:insert(批量一次读)、单 id update(与 readonlyWhen 共用同一次解析)、bulk update(每行一个表头,批量一次读)。

不可求值仍然 fail-open —— 记日志、跳过、放行。唯一变化是诊断:未绑定的根会被点名(复用 unknownVariableOf),因为「表头读不到」和「作者写错 key」是两种故障、两种修法,而它们只有一行日志可分辨。

previousParent:为什么多了这一个绑定

ADR-0113 非回归判定问的是「写入前那一行是否已经违规」,而它挂的是旧表头。改挂(repoint)到另一个主表时,若把落地表头也喂给这个前置判定,就会把「移到 Sent 表头之下」读成既有违规而放行 —— 正是本 issue 要堵的那个收下动作,只是换了个入口。因此新增 previousParent,仅在载荷确实改挂时由引擎解析,其余情况沿用同一行、不多付一次读。

爆炸半径(#4972 当初把本改动挡在范围外的原因)

对象级 script / cross_field 规则共用这个求值调用点,自 #4649 起对不可求值谓词 fail-closed。本 PR 没有给它们绑新根 —— 绑了会把它们今天拒掉的写入翻成接受。已由 pin 测试钉住(单元 + 端到端各一条),实测报错仍是 #4649 的原文案。

肢 C —— 构建期硬闸

packages/lint 的 parent 作用域闸原本刻意只盖 readonlyWhen,现在同样判 requiredWhen。两格共用同一道闸(同一个 masterDetailCount + readsParentRoot,CEL 解析走 formula 规范入口 collectCelRootIdentifiers,未直连 cel-js),但文案分岔:两边运行时失败方向相反(readonlyWhen fail-closed ⇒ 字段永远写不进;requiredWhen fail-open ⇒ 要求永远不生效),文案指错了就等于给了相反的修法。这正是运行时敢保持 fail-open 的前提 —— 会无声烂掉的那条声明进不来。

实现上两个槽位都保持字面量成员读取(f.readonlyWhen / f.requiredWhen),没有改成 f[key] 索引:后者会静默解除 #5017 那道扫源码的 meta-test 的武装。

测试

新增/改写覆盖(命中 / 不命中 / 缺 parent fail-open / repoint / bulk / 对照 / 爆炸半径):

• packages/objectql/src/engine-required-when-parent.test.ts(新,14 条,真引擎 + 真 driver 端到端,driver fixture 沿用 Parent-scoped readonlyWhen is unenforced server-side — the field lock fails open, so a paid invoice's frozen lines can be rewritten over the API #4889 的)
• packages/objectql/src/validation/rule-validator.test.ts(+16 条单元:11 条求值语义 + 5 条 gate)
• packages/lint/src/validate-expressions.test.ts(+5 条)

fixture 处置:原 it('is scoped to readonlyWhen — requiredWhen/visibleWhen verdicts are unchanged') 钉的恰好是本 PR 删掉的那条肢,断言会因为「什么都没产出」而继续通过。按整体替换处理 —— requiredWhen 半边移入新增的正向用例,此处保留的是真正没变的 visibleWhen,fixture 也只声明这一个槽位。

反向验证(方向先写死,两肢分别做)

肢	预测方向	实测
A 摘掉引擎的 parent 传参	转红,且只红「命中」用例	✅ 4 红 / 10 绿。红的正是 insert、update 置空、repoint、bulk 四条;fail-open、诊断、对照、爆炸半径 pin 保持绿(它们本就不依赖该绑定)
C 把闸恢复成只盖 readonlyWhen	转红	✅ 3 红 / 143 绿。红的是三条正向用例

诚实标注:C 肢另有两条「断言 0 个 issue」的负向 pin,在该回退下按构造必然保持绿 —— 它们不构成证据,分量全在那三条正向用例上。

命令与输出

pnpm --filter @objectstack/objectql test   →  Test Files 141 passed (141) / Tests 2351 passed (2351)
pnpm --filter @objectstack/lint     test   →  Test Files  62 passed  (62) / Tests 1541 passed (1541)
pnpm --filter @objectstack/objectql --filter @objectstack/lint typecheck  →  both Done
pnpm check:engine-double-contract          →  OK — 80 pinned, 133 in the DEBT ledger, 4 exempt
node scripts/check-nul-bytes.mjs           →  OK (6070 tracked text files; no raw ASCII control bytes)

以上为 merge origin/main 之后重跑的结果;merge-tree 预检 exit 0(无冲突)。

与同批在飞单的交互(实测)

• update 路径的 stripReadonlyFields 删除的是 hook 已覆写的当前值而非调用方提交的值 —— 调用方回传 readonly 键会连坐抹掉 beforeUpdate hook 的写入,可落出 status=published 而 published_at=null 的行(17.0.0-rc.2) #5591(update 载荷剥离时序):无交互。剥离次序原样保留 —— readonlyWhen 剥离 → 静态 readonly 剥离 → assertNoStrictDrops() → evaluateValidationRules;本 PR 只在第一步之前多解析一个表头行,不碰 suppliedValues。
• 写入载荷里的算子对象:text 型字段不做类型校验,{ title: { $in: [...] } } 原样写进库(number 型会响亮拒绝) #5922(算子对象拒收):无交互。validateRecord 在单 id update 路径上位于 evaluateValidationRules 之前(engine.ts L5866 vs L6000),算子对象在到达本 PR 的代码前就已被拒。operator-object-write-value.test.ts 与 engine-update-dispatch.test.ts 一并重跑,214/214 绿。
• data.id 是算子对象 + multi: true 时,{"$in":[...]} 作为普通列进入 updateMany 的 SET 载荷,写向主键列 #6262(data.id 算子对象 + multi):落点在派发层与 bulk 分支的 SET 载荷;本 PR 在 bulk 分支只上提了 parentForRow 的解析并加了一个 opts 字段,与 SET 载荷的构造互不相干。merge-tree 对当前 origin/main 无冲突。

偏差说明(需 PM 确认)

派单要求 ⛔ 不触 engine.ts。此项与裁决 A 不可兼得:evaluateValidationRules 是纯函数、不持有 driver,只有引擎能读表头,而 engine.ts 是全仓唯一的接线点(已 grep 确认无第二处调用方)。若严守该约束,交付物就只剩「求值器能接受 parent 但没人传」—— declared ≠ enforced 原样留在原地。

故按裁决执行,并把 engine.ts 的改动压到最小、且刻意避开 #6262 的落点。

---

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 8:09pm

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/automation/hook-bodies.mdx (via @objectstack/lint)
• 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 @objectstack/lint)
• 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)
• content/docs/releases/v17.mdx (via @objectstack/lint)

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.

[baozhoutao]

ACCEPT(engine-core 席 #6019,会话 session_019Q7oc7ASjh8yxyS3Yz78We;本件为 PM 代收验收:原实现会话于报告回传前因会话限额亡故,PR 正文即完整报告 —— 前提复核三条、双肢反向验证、爆炸半径 pin、与三张在飞单的交互实测俱全,足以替代结构化报告):

① 偏差裁定(正文「偏差说明」项)——成立,核准。 派单红线「⛔ 不触 engine.ts」与维护者裁决 A 不可兼得:evaluateValidationRules 是纯函数,engine.ts 是全仓唯一接线点(grep 无第二调用方),严守红线交付物即空转。红线的本意是与 #6262 的同文件串行避撞 —— dev 刻意避开其落点,且 #6433 落地后的 merge 实证零冲突(见 ③),该风险已被事实闭环。裁决优先于派单红线,偏差核准。

② 分支 CI 唯一红灯(TEST_DEBT 棘轮)已由接管修复清除。 原会话亡故后由接管 dev 收尾(8890f309):

• merge 前进的 main(be87153,含 fix(objectql): multi update 的 SET 载荷剥掉非 id 的 data.id (#6262) #6433/test(objectql): save-meta-response-conformance 删除悬空调试助手并补齐 registerObject 实参 (#5924) #6431/fix(metadata): sys_view_definition 的「活跃行唯一」补运行时 partial UNIQUE 迁移 (#5839) #6415)—— merge-tree 预检干净,engine.ts 双侧 hunk 不相交,合后语义验证非仅文本:objectql 2366 绿,含 main 新增的 fix(objectql): multi update 的 SET 载荷剥掉非 id 的 data.id (#6262) #6433 测试与本 PR 的 14 条 parent-scope 测试;
• 修正归因:CI 读数 358 = 旧基线 354(test(objectql): save-meta-response-conformance 删除悬空调试助手并补齐 registerObject 实参 (#5924) #6431 尚未摘除 3 条)+ 本 PR +4(非派单简报所写 +3);四处均为 engine-required-when-parent.test.ts 的 registerObject 缺必填 packageId(TS2554),按 fix(objectql): 集合算子的标量比较值答 400 INVALID_FILTER 并点名期望形状,不再 500 (#5869) #6209 先例合法调用点补类型('test-package',沿用仓内既有拼写),行为后果(provenance 戳)实测无断言读取、14/14 绿;
• 只修不抬账:台账数字未动,objectql 回到 main 基线并留出 -4 余量(恰压线 355 的刀锋被主动避开);
• 全量重验六项全绿,CI 实证:原红 job 已 success(20:24Z),head 8890f309 全板 24 项 0 红。

③ 验收结论:裁决 A+C 落地形态、fail-open 语义不动、previousParent 仅 repoint 时解析、#4649 fail-closed 爆炸半径 pin、lint 闸文案分岔、f.readonlyWhen 字面量读取保 #5017 meta-test —— 逐项与裁决及 ADR-0113 对齐。转 ready + auto-merge,合入即 Fixes #4977 自动收官。

---

Generated by Claude Code