`requiredWhen` is a transition gate, not an invariant: a record already in the required state is never re-validated, so every such rule in this repo has a silent legacy hole

[huangyiirene]

Found while implementing #1017 (PR #1068). Out of scope there — that card was a single field's gate; this is a property of the idiom the whole repo enforces with.

What was measured

Building the stock-data disposition for #1017 meant answering "what happens to a row that entered the gated state before the rule existed". Built the honest way — insert through an engine whose schema has no requiredWhen, then re-open the same store with the shipped schema — on InMemoryDriver (sparse rows) and on SqliteWasmDriver (column-complete, crm_contact = NULL). Same verdict on both:

legacy row: status = presented | crm_contact = null   (rule now says: required when presented/accepted)

READ                                    → works
update { total_price }                  → ADMITTED
update { internal_notes }               → ADMITTED
update { status: 'presented' }  (no-op) → ADMITTED
update { status: 'expired' }            → ADMITTED
update { crm_contact: 'con_x' }         → ADMITTED   (the repair)
update { status: 'accepted' }           → ADMITTED   ← the hole

Compare, on the same schema, a record that was not already gated:

draft → presented, no contact           → 400 VALIDATION_FAILED "Contact is required"
INSERT born presented, no contact       → 400 VALIDATION_FAILED
presented (with contact) → clear it     → 400 VALIDATION_FAILED

So the engine evaluates the requirement on the write that makes the predicate become true (or that empties the field while it holds). Once the predicate already held before the write, the requirement is not re-checked — presented → accepted on a contact-less row sails through even though accepted is squarely inside the rule's own condition.

Why this is worth a card

Half of it is a feature, and #1017 leans on it deliberately: it is exactly why adding a requiredWhen does not brick existing rows, and PR #1068 pins all three behaviours and documents the boundary for admins.

The other half is that "declared = enforced" is weaker than this repo has been reading it, and not just for crm_quote. Every requiredWhen here inherits the same hole for records that predate the rule (or that reach the state through any path where the predicate was already true):

• crm_opportunity.win_reason / loss_reason (Require win/loss reasons on close and surface win/loss analytics #593) — a deal already at closed_won with no win_reason keeps taking edits, and can be re-saved indefinitely, without ever supplying one;
• crm_lead.duplicate_of_lead / duplicate_of_contact (ADR-0113) — same shape;
• crm_quote.crm_contact (crm_quote.crm_contact 要不要自 presented 起 requiredWhen——缺 contact 的报价永远起草不出合同,失败只出现在服务器日志里(源自 #714) #1017) — measured above.

test/win-loss-capture.test.ts opens with a table of five metadata surfaces that accept a rule and then do not apply it. This is a sixth entry of a different kind: the rule is applied, on the transition only. Nothing in the repo said so until now, and the natural reading of "required when stage == closed_won" is an invariant, not an edge trigger.

Not asserting this is a platform bug

Validating only what changes is a defensible engine design, and turning it into a full invariant would make any newly-added requiredWhen retroactively freeze existing rows — the opposite of the "no silent breakage" property #1017's ruling asked for. So the question this card is for is a product one:

1. Accept and document — write the transition semantics into AGENTS.md next to "Validation predicates must be TOTAL", so future cards state the boundary in the PR instead of rediscovering it. (PR feat(quote): a quote may not be presented without a recipient (#1017) #1068 documents it for quotes only.)
2. Backfill-and-check per rule — where the invariant genuinely matters, pair the requiredWhen with a hook or a data audit that catches rows already in the state.
3. Raise upstream — if requiredWhen is meant to be an invariant, this belongs against @objectstack/objectql's evaluateValidationRules, with the two-driver measurement above as the repro.

Measured on @objectstack 17.0.0-rc.5, hotcrm main at c5bc586. Repro: the a row that was ALREADY presented when the rule landed describe-block in test/quote-contact-required-when.test.ts (PR #1068) is the measurement in runnable form.

[huangyiirene]

The same hole exists in a second instrument — Field.percent({ max }) — and a type: 'script' validation is measurably free of it. Measured while implementing #599, which needed a hard ceiling on crm_quote.discount and therefore had to choose an instrument rather than copy one.

Same method as this card: insert through an engine whose schema has no rule, re-open the SAME store with the shipped schema, then write. Legacy row is discount = 90, ceiling is 60. InMemoryDriver, @objectstack 17.0.0-rc.6, hotcrm main at f71b5350.

                                       Field.percent({max: 60})   script validation (> 60)
fresh INSERT discount=70                REFUSED  max_value          REFUSED  rule_violation
fresh UPDATE discount=70                REFUSED  max_value          REFUSED  rule_violation
legacy(90) update {internal_notes}      ADMITTED  <-- the hole      REFUSED
legacy(90) update {status: in_review}   ADMITTED  <-- the hole      REFUSED
legacy(90) update {discount: 10}        ADMITTED  (repair)          ADMITTED  (repair)

So the boundary this card draws is not a property of requiredWhen specifically — it is the difference between validating the value being written and validating the merged record. Field-level bounds (max, and by the same construction min) sit on the first side, alongside requiredWhen. Object-level validations[] of type: 'script' sit on the second, and are a true invariant: the predicate is re-evaluated on every write while the record holds, so a row that predates the rule is refused on any edit until it is brought into compliance. The repair is always admitted, so it freezes rather than bricks.

That is a useful thing for option 1 of this card ("accept and document") to record, because it turns "declared = enforced is weaker than we read it" into a choice with two known sides rather than a blanket caveat:

• an invariant ("X may never exceed Y") is expressible today, with validations[] — at the cost that adding one retroactively freezes non-conforming rows until they are repaired;
• a transition condition ("X is required by the time it reaches state S") is what requiredWhen and field bounds give you, and its legacy hole is the flip side of the "no silent breakage" property crm_quote.crm_contact 要不要自 presented 起 requiredWhen——缺 contact 的报价永远起草不出合同,失败只出现在服务器日志里(源自 #714) #1017's ruling asked for.

Neither is a bug; picking the wrong one silently is. The three rules this card lists (win_reason/loss_reason #593, the crm_lead duplicate lookups under ADR-0113, crm_quote.crm_contact #1017) all read as invariants in prose and are implemented as transitions — the same mismatch, and for at least some of them a validations[] predicate would express the stated intent exactly.

Runnable form: the the ceiling is an INVARIANT describe-block in test/quote-discount-ceiling.test.ts (#599's PR), whose last case builds the max-based schema specifically to show the admission side by side.

---

Generated by Claude Code