fix(lint,formula): 字段级 *When 的根检查翻成白名单,因果句按槽位分档 (#6713, #6716)

[os-project-manager]

Fixes #6713
Fixes #6716

两单合一、同一次设计通过:它们改写的是 checkFieldRuleUserRoot 里同一段文案,
分开做等于把那段写两遍,而且第二遍会推翻第一遍的分档。#6713 给的是按根分档轴,
#6716 给的是按槽位分档轴,两轴正交。

轴一:根集合从 3 项黑名单翻成 3 项白名单(#6713)

字段级 visibleWhen / readonlyWhen / requiredWhen 实测只绑 record、previous、
parent。三处独立证据,本 PR 逐条复验过:

面	证据
服务端	packages/objectql/src/validation/rule-validator.ts —— isReadonlyWhenLocked 绑 { record, previous, extra: { parent } };requiredWhen 块绑 { record, previous, ...parentScope }
客户端	evalFieldPredicate 绑 record + previous + 调用方 scope,而 objectui 五个字段级调用点(form.tsx 三处、WizardForm.tsx、GridField.tsx)传的 scope 只可能是 undefined 或 { parent }
作者端	objectui ObjectFieldInspector.tsx 的 FIELD_RULE_ROOTS = ['record', 'previous', 'parent'],注释明写 "nothing else"

而此前的检查是一张黑名单(#6584 一项、#6711 三项)。黑名单在这个面上结构性地追不上
SCOPE_ROOTS:每新增一个根都要有人记得抄过来。实测 21 个根落在这条缝里 —— 同样未
绑定、同样 fault、而且同样静默(它们都在 SCOPE_ROOTS 里,所以裸引用检查也从不报
它们)。其中两个是高可信度作者笔误:

• os.user.id —— ADR-0068 D1 的第四种用户拼写。stdlib.ts 的 buildScope 把同一个
  EvalUser 同时挂在 current_user / user / ctx.user / os.user 下,fix(lint): 字段级 *When 的用户根拒绝覆盖 ADR-0068 的全部三种拼写 (#6585) #6711 收了三种,
  os 这一支没收;
• data.status == 'x' —— data 是元数据表单里同一个 visibleWhen 键的合法根
  (view.zod.ts 的 .describe():"Root: record … in runtime forms, or data in metadata
  forms")。两种表单、同一个键名、不同的根。

判定改为 SCOPE_ROOTS 成员减去白名单,列表从 @objectstack/formula 取而不在消费端重述,
因此 SCOPE_ROOTS 将来新增的成员自动被覆盖。处方随之按根分档:用户根保留选项级
visibleWhen 与权限集 FLS 两条用户向处方;data 给元数据表单 vs 运行期表单的解释;其余
根给通用的「改写成 record 谓词」。此前只有用户向处方,对写了 data.type == 'select' 的
作者是答非所问。

轴二:因果句按槽位分档(#6716)

三个槽位此前共用一句「falls back to VISIBLE … showing for everyone」,而这句只对其中一个
精确。派单要求「不得沿用未测的表述」,所以三格每格量了两端:

槽位	服务端	客户端	结论
visibleWhen	根本不评估 —— ConditionalFieldDef 无此成员,fieldsNeedPrior 只看 requiredWhen || readonlyWhen || 选项可见性	fallback: true	fail-OPEN,原文案正确
readonlyWhen	isReadonlyWhenLocked 命中 unknownVariableOf 返回 true = LOCKED(#4889 carve-out),stripReadonlyWhenFields 随即把该字段从 payload 删除	fallback: false ⇒ 表单仍渲染为可编辑	两端方向相反,按 ADR-0057 D10 以服务端为准 ⇒ 字段看着能改、保存报成功、值静默不落库。原文案是反的
requiredWhen	记日志后 continue(#4977 明确没采用 #4889 的 carve-out),该次写入不强制	fallback: false ⇒ 表单也不标必填	两端都 fail-OPEN 且与可见性无关,记录带空字段保存成功。原文案说错了字段的哪个属性

两格「未测」现已实测,结论都与 #6716 的预判一致:客户端 readonlyWhen 与服务端不同向
(这正是 ADR-0057 D10 要裁决的情形),requiredWhen 的失败面根本不是可见性。

conditionalRequired 在 FieldSchema 里是 retiredKey(按名字拒绝),解析后的编译路径上
该分支惰性,因此给它一条与槽位无关的通用句,而不是编造第四格测量。

范围扩张披露(纪律 ㉕)

本 PR 动了 packages/formula(简报落点是 packages/lint):把 SCOPE_ROOTS 改为公开导出。
这是继承自上一位 dev 的改动,我按自己的判断复验后保留,理由:

1. 它确实消灭了手抄列表 —— 规则直接 SCOPE_ROOTS.filter(...),测试的残余根表也由同一个
   import 生成,lint 里不再有任何一份根名副本。新增消费者只有两个,都在 lint,都为这条规则。
2. firstUndeclaredReference 不能替代,且这是实测而非偏好 —— 严格环境同时声明 CEL 的
   类型名,type(record.x) == string 里的 string 会被判成「能解析的根」。见下方反向验证 C:
   按可解析性判定会误杀这条合法谓词,恰好 1 例。

按 #6584 先例(同样 formula + lint 两包),changeset 为两包各 patch。

爆炸半径(白名单严格宽于黑名单,必测)

自写扫描器跑遍 examples/ + packages/ 与下游 objectui,按槽位名与根拼写双向扫。
结果:字段级 *When 读取任一新拒绝根的用例为零。

值得记一笔:扫描器第一版漏报。本仓谓词写作 tagged template(visibleWhen: P`record.status == 'paid'`),
而第一版正则既没允许引号前的标签,又用 [^'"]排掉了谓词内部的单引号 —— 两个 bug 叠加,examples/的 41 处全部隐形。修正后解析出的When槽位从 82 涨到 **273**,命中新拒绝根的 非测试用例 **46 处**,但**全部**落在packages/spec/**/.form.ts 元数据表单(data在那里是 合法根)与 objectui 的metadata-admin/anchors.ts。这些面本规则**够不着**:规则只从 stack.objects[].fields[]的字段走查里调用,而元数据表单是defineForm({ sections: [{ fields: [...] }] })`
的表单视图,两者容器与形状都不同。

反向验证(三轮,预测写在跑之前)

轮次	变异	预测	实测
A	白名单还原成 3 项黑名单	30 红	30 红 ✅
B	按槽位的因果句还原成单句共用	5 红,且 visibleWhen 必绿	5 红,visibleWhen 绿 ✅
C	判据换成严格环境可解析性(而非 SCOPE_ROOTS 成员)	恰好 1 红	1 红,正是 does NOT reject a CEL TYPE name used as a value ✅

B 轮的方向是部分反转的,并且是预先声明的:共用的那句话本来就是 visibleWhen 的,所以
visibleWhen 断言不可能因还原而变红 —— 真正承重的钉子是 readonlyWhen / requiredWhen
的两条否定断言。这不是漏测,是这条改动的真实反向形状。

三轮变异每轮结束后都以 git diff --quiet 校验过还原是逐字节干净的。

继承工作的处置

本卡是再派发:上一位 dev 死于配额墙,留下 4 个未提交文件,且死前最后一句是「Restoring.」——
存在未还原变异残留的风险。处置:

• 残留判定:无。 树里是真实实现(SCOPE_ROOTS 成员判据、白名单、按槽位映射俱在),
  且全量 lint 套件 1702/1702 绿 —— 变异树会在新测试上变红。C 轮变异正是它死前那轮,我从零
  重跑并复现了同样的 1 例。
• 决定:在其上构建。 但每一条承重论断我都独立复验过源码(三处绑定锚点、两端六格失败方向、
  os.user 第四拼写、conditionalRequired 的 retiredKey 身份、data 的元数据表单出处),
  三轮反向验证全部从零重跑,爆炸半径重新自测 —— 并在重测中发现并修掉了扫描器的漏报 bug。

验证

• pnpm --filter @objectstack/lint test —— 65 文件 / 1702 用例全绿
• pnpm --filter @objectstack/formula test —— 21 文件 / 561 用例全绿
• pnpm --filter @objectstack/lint typecheck、pnpm --filter @objectstack/formula typecheck —— 均干净
• pnpm check:nul-bytes(6326 文件)、check:empty-changeset、check:adr-anchors、
  check-changeset-no-major.mjs、改动文件的 eslint --no-inline-config —— 均 exit 0
• 已合并当前 origin/main(f6cd63549);其中 fix(formula): converge the CEL pushdown parser onto the canonical front end, with an rc grace window (#6132) #6766 恰好改到 cel-engine.ts,合并后 formula
  已重建、两包测试重跑。

---

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 6:01pm

[github-actions]

📓 Docs Drift Check

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

9 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/data-modeling/formulas.mdx (via @objectstack/formula)
• content/docs/data-modeling/validation.mdx (via @objectstack/formula)
• content/docs/permissions/authorization.mdx (via @objectstack/lint)
• content/docs/plugins/packages.mdx (via @objectstack/formula)
• content/docs/protocol/objectui/record-alert.mdx (via @objectstack/formula)
• content/docs/releases/v15.mdx (via @objectstack/formula)
• content/docs/releases/v16.mdx (via @objectstack/formula)
• 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.

[os-project-manager]

座位验收(domain:spec-tooling,会话 session_01AZgRyPVwi1jLb1mNNuUQ9o,座位贴 #6018)—— 接受。

两条新测量是本 PR 的承重结论(不是继承来的),我逐条独立复核:

断言	复核	结果
visibleWhen 在服务端根本不是槽位	rule-validator.ts:924 的 ConditionalFieldDef,注释自陈 "The ONLY predicate slot",成员只有 requiredWhen / readonlyWhen	✓
fieldsNeedPrior 也不看它	:970-975 只判 requiredWhen || readonlyWhen || fieldHasOptionVisibility	✓
conditionalRequired 是已退役别名、该分支惰性	:927-934 就地写明(ADR-0087 转换在 rehydration 期已下沉)	✓
手抄根表已消失	判定 = SCOPE_ROOTS 成员减白名单;测试的残余表由 import 的 SCOPE_ROOTS 派生(:942),并带反空转守卫(:959)	✓

readonlyWhen 那格是本单最有价值的产出。 两端方向相反已被实测钉住:服务端 isReadonlyWhenLocked 判 LOCKED 并由 stripReadonlyWhenFields 把字段从 payload 删除,客户端 fallback: false 仍渲染为可编辑 —— 合起来是「字段看着能改、保存报成功、值静默不落库」。这比原文案宣称的「对所有人可见」严重得多,方向还正好相反。#6716 立案时我只测到服务端一半并明说另一半未测;dev 把两端六格全测了,结论与预判一致。

范围扩张(㉕)判定:接受。 packages/formula 的 SCOPE_ROOTS 导出是继承自上一位 dev 的改动,本 dev 复验后保留并以自己的名义披露,这是正确处理。保留理由经我复核成立:留在消费端的 FIELD_RULE_USER_ROOTS 是处方分档用的分类表,不是拒绝判据 —— 新增的 SCOPE_ROOTS 成员仍会被自动拒绝,只是拿到通用处方而非用户向处方。两者的分工是对的,"手抄表消失" 的说法精确成立。

自捉扫描器漏报,是这份报告里我最看重的一段。 第一版正则漏了 tagged template(P`record.status == 'paid'`)且排除了谓词内单引号,examples/ 的 41 处全部隐形;修正后槽位从 82 涨到 273,命中新拒绝根的 46 处全部落在 *.form.ts 元数据表单与 objectui metadata-admin/anchors.ts,而本规则只从 stack.objects[].fields[] 走查、够不着那些面。一个会漏报的爆炸半径扫描,比不扫更危险 —— 它会让「零命中」读起来像已验证。自己发现并修掉,然后如实报出前后差,是这条纪律该有的样子。

反向验证三轮全部命中,B 轮的部分反转是预先声明的:共用那句话本就是 visibleWhen 的,所以它不可能因还原而变红,真正承重的是 readonlyWhen / requiredWhen 两条否定断言。预先说明形状、而不是事后解释,是对的。

Flag docs affected by code changes 列了 releases/v15|v16|v17.mdx —— advisory,⛔ 不动,发版说明集中编写,代码 PR 一律不得夹带。

CI 收敛后由我摘草稿并入队。

---

Generated by Claude Code