fix(ui): judge requiredWhen as the engine's transition gate on the record Edit form - #30216

domain:ui#2 · os-justin · session_01QSeKYnE9YNkSZen7sijLA3
Fixes #30184

Clause-②: yes (widening)
Metadata-protocol: none

This widens the public surface of @object-ui/core: the new export requiredWhenRestsOnStoredRecord and the new requiredWhenAtRest field in the return type of resolveFieldRuleState.

维护者速读

• 改了什么:Console 记录编辑表单按引擎的方式判 requiredWhen(转移闸门):已存记录本来就处在闸门内且缺值时,不再挡住无关编辑;创建表单与「把记录移入闸门」的编辑照旧拦截。
• 为什么改:HotCRM 实测,合同在签字件规则出现前就已激活,REST PATCH 返回 200,但 Console 编辑一律报「Signed Copy is required」,存量记录在 Console 里改不了。
• 风险与回滚:只改客户端判定,服务端不动;最坏情况是客户端放行、服务端拒绝,拒绝信息照常落在字段上。回滚即还原本 PR。
• 先看:ui/packages/core/src/evaluator/fieldRules.ts(resolveFieldRuleState 的 requiredByRule / requiredWhenAtRest 段)、ui/packages/components/src/renderers/form/form.tsx(渲染路径传入 name,与动作提示的 !ruleState.requiredWhenAtRest)、form-required-when-submit.test.tsx 新增的 describe。
• 两分钟验证:pnpm --dir ui exec vitest run packages/components/src/renderers/form/__tests__/form-required-when-submit.test.tsx,预期 9 个用例全绿,其中「saves an unrelated edit to a record already in the gate」通过。
• 需要你做的:无,席位落地。

What changes

The engine's rule, read on origin/main 31fe289f: objectql evaluateValidationRules (packages/objectql/src/validation/rule-validator.ts, the "ADR-0113 non-regression: reject iff the MERGED state violates AND the PRE state complied" block) refuses an update only when the predicate holds over the merged record with the field missing AND the stored row did not already violate it (the preViolated check). A predicate that cannot be evaluated over the stored row counts it as compliant. An insert complies vacuously. Field.requiredWhen in @objectstack/spec states the same contract: "the write is refused only when the merged record violates the requirement AND the pre-write record complied".

The client side is re-bound to that rule in the one place every form verdict comes from:

• @object-ui/core resolveFieldRuleState takes statics.name. With previous (the stored row of an UPDATE) and name, a stored row that already violates requiredWhen resolves required: false and the new requiredWhenAtRest: true. A caller that passes no name keeps the plain verdict. The stored-row check is exported alone as requiredWhenRestsOnStoredRecord. "Missing" is isMissingForRequired, the same answer the client's required check gives.
• @object-ui/components form renderer passes name at the render path (asterisk, aria-required and the submit validator all read that one verdict) and at the stale-error cleanup that reads required. The update-action heads-up (the "Required to run" note, objectstack#28382) is suppressed when requiredWhenAtRest is true: the engine judges an action's write against the same stored row, so the action is not refused for that field either.

Chosen: mirror, not defer. Everything the rule reads is in the form: the Edit form's previousValues is the record from findOne with no $select, seeded with null for every declared field, the same assembly the live evaluation already uses. Where the form's stored row could differ from the server's (a column the caller cannot read), the client answers "at rest" and lets the write through, and the server's field-attributed refusal still lands at the field through the existing extractFieldErrors path. The client is never stricter than the engine here, except for the existing empty-array case (the client counts [] as missing, the engine does not), which this PR does not change.

Create forms (previousValues absent) are unchanged.

Tests

• New top-level describe in form-required-when-submit.test.tsx (the real form renderer): (a) an already-activated record with no signed copy saves an unrelated edit; (b) moving a record into activated without the copy is refused in the form; clearing the copy of a record that held it is refused; (c) a Create form still enforces.
• New case in form-required-for-action-28382.test.tsx: a stored row already inside the gate without the value shows neither the asterisk nor the action note, and Save writes.
• New describe in core fieldRules.test.ts: the six verdict cases, including no name keeps the plain verdict, static required: true is never relaxed, and a fault over the stored row counts it as compliant. The existing "all three compose" toEqual gains requiredWhenAtRest: false.

Acceptance notes

• Same verdict, callers that do not pass name yet (same defect class, outside this claim's file surface, so not edited):
  • Console FormPage (ui/apps/console/src/components/FormPage.tsx, resolveRowState) edits through /forms/:name?recordId= with the stored record as previous; it gets the fix by adding name: field.name to its statics.
  • plugin-form WizardForm gateFinalSubmit passes no previous in either mode, deliberately ("persistedRecord is deliberately NOT bound here", objectui#8069's ruling). An Edit wizard's steps render through the fixed form renderer, but its cross-step final gate still refuses a stored row already in the gate. Fixing it means using persistedRecord for the stored-row check, which that note forbids today, so it needs the seat's word.
  • plugin-kanban collectRequiredWhenPromptFields passes the pre-drop record as previous and no name, so a drop still prompts for a field the engine would let rest.
• The file header of fieldRules.ts still says an unevaluable requiredWhen "is skipped on BOTH ends". That has been stale since ADR-0137 D2 (the engine refuses). Not changed here.

Verification

Head: 0e6a6f475 (every reading below was taken on this head; base 31fe289f). c03f4ecac after it changes only the changeset's Clause-②: line and adds one sentence; the changeset gates were rerun on it (check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check:changeset-fixed, check:nul-bytes, all exit 0).

pnpm --dir ui exec vitest run --maxWorkers=2 packages/core/src/evaluator/ (+ 61 named files)
 Test Files  82 passed (82)
      Tests  1711 passed | 27 skipped (1738)
os-verify-lock: VERDICT command-exit 0

ablation-replace: ok mutation landed: anchor 1 -> 0, blob f7e06a716bca -> dbbe71790dc3
     × saves an unrelated edit to a record already in the gate without the value
     × notes nothing when the stored row already lacks the value inside the gate (objectstack#30184)
     × an already-activated stored row with no value rests: not required, at rest
 Tests  3 failed | 77 passed (80)
ablation-replace: ok restored: blob == HEAD (f7e06a716bca) and `git diff HEAD` is empty

pnpm --filter @object-ui/core --filter @object-ui/components run type-check
ui/packages/core type-check: Done
ui/packages/components type-check: Done

node scripts/check-adr-0087-registration.mjs --base origin/main :: exit 0
node scripts/check-adr-0087-registration.mjs --self-test :: exit 0
node scripts/check-changeset-no-major.mjs --base origin/main :: exit 0
node scripts/check-closing-keyword-parity.mjs :: exit 0
node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
node scripts/check-empty-changeset.mjs --base origin/main :: exit 0
node scripts/check-empty-changeset.mjs --self-test :: exit 0
node scripts/check-sdui-manifest.mjs :: exit 0
node scripts/check-sdui-manifest.mjs --self-test :: exit 0
node scripts/pm/release-rehearsal-clone.mjs --self-test :: exit 0
node scripts/release-pending-publish.mjs --self-test :: exit 0
pnpm --dir ui exec vitest run scripts/ :: exit 1
pnpm --filter @objectstack/spec run check:duration-unit-keys :: exit 0
pnpm check:changeset-gate-self-tests :: exit 0
pnpm check:closed-ceremony-text :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:dispatcher-error-vocabulary :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:engine-double-contract :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:published-files :: exit 0
pnpm check:query-options-erasure :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:registry-log-declared :: exit 0
pnpm check:rest-log-spy-declared :: exit 0
pnpm check:skill-identifier-liveness :: exit 0
pnpm check:test-source-alias :: exit 0
pnpm check:tier-file-adoption :: exit 0
pnpm check:type-check-coverage :: exit 0
pnpm check:type-check-debt :: exit 0
pnpm check:undeclared-dep-imports :: exit 0
pnpm check:watch-hint-literal :: exit 0
pnpm check:where-matcher :: exit 0
pnpm check:changeset-fixed :: exit 0

Generated by Claude Code