enhancement: `state_machine` 校验规则在 INSERT 上是 no-op —— 无法强制记录的初始状态(declared ≠ enforced)

[os-zhuang]

概述

state_machine 验证规则(ADR-0020)在 insert 模式下直接 no-op,因此无法强制记录的初始状态——例如「新建的审批单必须以 draft 开始,不能直接建成 approved」这类约束今天并不生效。

packages/objectql/src/validation/rule-validator.ts checkStateMachine:

function checkStateMachine(rule, mode, data, previous) {
  // Insert has no prior state — the field-level select check already
  // constrains the initial value to a declared option.
  if (mode === 'insert' || !previous) return null;   // ← insert 直接放过
  ...
}

注释的理由是「field-level select 校验已把初始值约束在声明的选项内」——但 select 只保证「值是合法枚举之一」,不保证「是合法的初始状态」。一个 4 级审批 FSM 的 approved 也是合法枚举值,select 校验拦不住「初始即 approved」。

为什么现在提

这是在 #3043(静态 readonly INSERT 剥离)探索中浮现的:#3043 备选方案 1 曾设想「审批/状态字段叠 state_machine 强制初始状态」作为缓解,但该能力今天不存在。属于 ADR-0049「enforce-or-remove」精神下的 declared ≠ enforced 候选,也呼应 AGENTS.md Prime Directive #10。

备选方向

1. 实现 insert 时的初始态强制:给 state_machine 规则一个可选的 initial(或 initialStates)声明;insert 时校验状态字段值 ∈ 允许的初始态集合。未声明则维持现状(向后兼容)。
2. 仅文档化:在 spec describe / 文档里明确 state_machine 只约束 UPDATE 的 transition,不管初始态;让作者改用 defaultValue + readonly(+ 现已修复的 安全/设计:静态 readonly 的 INSERT 豁免让审批/状态字段可在创建时被直接播种(比 #3003 少一步) #3043 INSERT 剥离)来固定初始态。
3. 维持现状但把注释里「select 已约束」这一不成立的理由更正,避免误导后来者。

关联

• ADR-0020(state_machine converge and enforce)
• ADR-0049(no unenforced security properties)
• 安全/设计:静态 readonly 的 INSERT 豁免让审批/状态字段可在创建时被直接播种(比 #3003 少一步) #3043 / PR fix(metadata-protocol): strip static readonly on INSERT at the data-write ingress (#3043) #3162(探索来源;README 式缓解设想的落空点)

[os-zhuang]

已修复 · PR #3188(已合并 04ecd4e)。

state_machine 规则新增可选 initialStates: string[] —— 记录允许被创建于的状态集合。声明后,INSERT 时状态字段(经默认值解析后)若不在集合内,服务端拒绝(code: 'invalid_initial_state');不声明则维持旧行为(insert 不做初始态检查),transitions(UPDATE)不受影响。强制点在引擎已有的 evaluateValidationRules(..., 'insert')(engine.ts,字段默认值之后)。

证明:单测(放行 / 拒绝 / 空值 no-op / 不影响 UPDATE / 未声明的旧行为)+ 引擎集成(真机 insert:approved 被拒不落库;draft 与默认补全的 draft 通过)。文档 data-modeling/validation.mdx + 生成的 reference 同步。

补上了 #3043 备选缓解思路所依赖、但此前并不存在的能力(declared ≠ enforced,ADR-0049)。

---

Generated by Claude Code