`requiredWhen`(与字段级 min/max)是转换门,`validations[]` script 是真不变量 —— 边界是刻意的、已被双驱动实测,但平台没有任何一处教它

[huangyiirene]

按维护者指示上行立卡(2026-08-31,hotcrm#1069 决裁,逐字:「1069 如果是平台的问题就提交平台卡片。」)。

实测事实(hotcrm#1069 + 其工具对比评论,双驱动同判,可运行复现在 hotcrm test/quote-contact-required-when.test.ts 与 test/quote-discount-ceiling.test.ts)

• requiredWhen 只在「谓词变为真的那次写入」或「清空字段的那次写入」校验。规则生效前已处于门内状态的行:改任意字段、状态在门内推进(presented → accepted)全部放行 —— 而 accepted 在规则自己的条件里。对照:draft → presented 拒、生而 presented 的 INSERT 拒、清空字段拒 —— 边触发精确成立;
• 字段级 max/min 同侧:存量 90 的折扣在 60 上限下,改无关字段、推进状态均放行(修复性写入亦放行);
• validations[] 的 type:'script' 规则是真不变量:每次写入对合并后记录重评,存量违规行在任何编辑上被拒、修复性写入放行 —— 冻结而不砖死。

两种语义都是刻意的,⛔ 本卡不要求改任何一种:「只校验所写内容」使新增规则不砖存量(#1017 裁决要求的 no-silent-breakage);「校验合并记录」提供真不变量。缺的是平台没有任何一处写明这条边界与工具选择 —— 「required when X」的自然读法是不变量,AI 作者会静默选错工具:hotcrm 三条散文读作不变量的规则(win/loss_reason、lead 重复回指、quote 联系人)全部用了转换门工具,零信号。

交付物(平台侧文档/教学,statement of the boundary)

1. spec docblock:requiredWhen 键与字段级 bounds 的声明处,各一段写明转换语义(以上表为例);validations[] script 的声明处写明不变量语义与「冻结不砖死」行为;
2. 发布 skills(教应用作者那套):工具选择行 ——「要不变量(X 永不得超过 Y)⇒ validations[] script,代价是存量违规行冻结至修复;要转换条件(到达状态 S 时 X 须已备)⇒ requiredWhen / 字段 bounds,代价是先于规则的存量行放行」。受管面照旧;
3. 可选(先估价):evaluateValidationRules 处的实现注记互链。

⛔ 范围外:改语义;「不变量捷径」类新 affordance(有拉力另立设计卡)。

Refs: hotcrm#1069(测量原卡)· hotcrm#1017(转换语义的受益方)· 今日应用仓三原则 objectstack#13848(应用不自建平台级机制,平台统一教)。

[os-sam]

Claim: domain:spec execution seat.

• Session: session_017RbbUMnxkUnWhE4j94v8FE
• Branch: claude/issue-13879-required-when-transition-gate-docblocks
• Worktree: /home/user/objectstack-issue-13879 (os-dev subagent; created at dispatch)
• Domain: domain:spec (fix lands in packages/spec docblocks / describe() text)
• File surface: packages/spec/src/data/field.zod.ts — the describe() text of requiredWhen (:801 and the object-extension twin :1449), min / max (:990–991) and minLength / maxLength (:950 / :958): state the transition-gate semantics (evaluated on the write that flips the predicate true or clears the cell / on the written value only; rows already inside the gate before the rule existed pass on unrelated edits and on in-gate state moves); packages/spec/src/data/validation.zod.ts — the script rule docblock (:69–:152): state the invariant semantics (re-evaluated on the merged record on every write; pre-existing violating rows are frozen until repaired, never bricked); the generated spec references these describe texts feed (regenerated with the generator, never by hand); one pin on the docblock text; a changeset per repo convention. Deliverable 2 of the card (the tool-choice line in the published skills/**) is domain:skills + governed and goes to that lane as a follow-up card filed by this seat at ACCEPT, carrying the wording the dev proposes in the PR body — not in this PR. Deliverable 3 (an implementation note in packages/objectql/src/validation/rule-validator.ts) is ⛔ not touched: PR chore(lint): delete inert eslint-disable family comments in package sources #14801 is open on that file; the spec docblock names evaluateValidationRules by symbol instead.
• Container & model: os-dev subagent, opus.
• Clause-②: no — describe/docblock text only; no accept-set or behaviour change. If measurement shows the stated semantics are NOT what the engine does (the card's hotcrm measurements are the premise), stop and report — a text that states a false rule is worse than none.
• Serial constraints: field.zod.ts is shared with autonumber 业务标识字段默认不唯一,可铸重号 —— 裁定:默认唯一(租户复合形状),显式退出才不唯一 #13894 (this seat, dispatched in the same round) on a region split — this card writes the requiredWhen / bounds describe texts only; autonumber 业务标识字段默认不唯一,可铸重号 —— 裁定:默认唯一(租户复合形状),显式退出才不唯一 #13894 writes the unique line (:939) and the autonumber block (:1620–:1650) only; this PR lands first, autonumber 业务标识字段默认不唯一,可铸重号 —— 裁定:默认唯一(租户复合形状),显式退出才不唯一 #13894 rebases. No open PR touches field.zod.ts or validation.zod.ts (scan 06:49Z over the open PRs).
• Premise re-read on origin/main 2263ca4d6: requiredWhen's describe reads "Predicate (CEL) — the cell is required when TRUE…" and validation.zod.ts's script docblock discusses governance metadata; neither states the transition-vs-invariant boundary. Premise holds. H17 on-hold trigger-file index ([Half-state patrol] check-half-states live sweep — generated view (please pin) #9857, 01:59Z) names none of these files.

---

Generated by Claude Code

[os-sam]

Dispatch (2026-09-03T06:58Z) — domain:spec seat, session_017RbbUMnxkUnWhE4j94v8FE, seat post #6017. mode:subagent — os-dev subagent in the seat's container, model opus, size S, clause ② no (describe/docblock text only). Branch claude/issue-13879-required-when-transition-gate-docblocks, worktree ../objectstack-issue-13879 from origin/main 2263ca4d6. The dev leaves its own Claim: comment below (with Clause-②: no); the assignee stays the PM's.

Dispatch text handed to the dev, in brief (the card's scope fence — ⛔ no semantic change to either mechanism — is carried as binding):

• Deliverable 1 only: state the boundary in the spec's own text — requiredWhen (both sites in field.zod.ts) and the field bounds (min / max / minLength / maxLength) as transition gates (checked on the write that carries the value; rows already inside the gate pass on unrelated edits and in-gate moves); the script validation rule in validation.zod.ts as the invariant (re-evaluated on the merged record every write; violating rows frozen until repaired, never bricked); each side names the other as the tool for the other need.
• Deliverable 2 (the tool-choice line in the published skills/**) is domain:skills + governed and is NOT in this PR — this seat files the follow-up card in that lane at ACCEPT with the wording the dev proposes in the PR body. Deliverable 3: ⛔ no edit to rule-validator.ts (PR chore(lint): delete inert eslint-disable family comments in package sources #14801 is open on it); the docblock names evaluateValidationRules by symbol.
• PM mechanism hypotheses to measure first, evidence back to the PM: H1 the engine implements the card's five requiredWhen cases as measured in hotcrm (any divergence ⇒ ship only the sentences the code supports and report the case); H2 bounds are checked on the written value only; H3 script / cross_field rules evaluate on the merged record and accept a repairing write; H4 describe text regenerates the references via the spec generator (never hand-edited); H5 one pin reads the describe text through the schema, not a source grep.
• Serial constraint: field.zod.ts is region-split with autonumber 业务标识字段默认不唯一,可铸重号 —— 裁定:默认唯一(租户复合形状),显式退出才不唯一 #13894 (same seat, same round) — this card writes the requiredWhen / bounds describe texts only and lands first.
• Gates: 42 commands derived at 2263ca4d6 handed as a clue; re-derived by the dev on the actual diff after the changeset exists; CI on the draft PR is the final reading. Board reading (485 open issues, 06:09Z) handed once.
• Delivery: draft PR Fixes #13879 (no needs:contract-review), PR body with the measured-case table, the added sentences per site, the proposed skills wording, the regenerated artifacts and the verification record; os-dev-report comment on the card first, then the final JSON.

---

Generated by Claude Code

[claude]

Claim: os-dev subagent seat (execution).

• Session: session_017RbbUMnxkUnWhE4j94v8FE — os-dev subagent of that PM session, dispatched by the domain:spec seat (post [PM seat] domain:spec — 🟢 zhuangjianguo #6017) under the PM claim above.
• Branch: claude/issue-13879-required-when-transition-gate-docblocks (pushed empty at 06:57Z as the write-routing probe, before the first edit)
• Worktree: /home/user/objectstack-issue-13879, cut from origin/main 2263ca4d6
• Clause-②: no
• Scope: deliverable 1 only — the .describe() / docblock text at Field.requiredWhen, the field bounds (min / max / minLength / maxLength), the inline-grid column requiredWhen, and the validations[] script rule in packages/spec, plus the regenerated reference pages and one schema-reachable pin. No semantic change to either mechanism. packages/objectql/src/validation/rule-validator.ts is not touched (PR chore(lint): delete inert eslint-disable family comments in package sources #14801 is open on it); the spec text names evaluateValidationRules by symbol instead. Deliverable 2 (the published skills/** tool-choice line) is not in this PR — the wording is proposed in the PR body for the domain:skills follow-up card.
• Assignee: left as the PM set it; never written by this seat.

Generated by Claude Code

---

Generated by Claude Code