Validation language: conditional rules, cross-property operands, and state-based business rules

[woksin]

Summary

The validate sub-language covers per-property declarative rules with messages, plus a validate csharp escape hatch — and nothing in between. Validating a real Arc application's document against its source shows three recurring rule shapes that fall straight through to the escape hatch (or are lost entirely when the document is generated), even though they are the most important rules an application has:

1. Conditional rules — FluentValidation's .When(...): a rule that only applies under a condition.
2. Cross-property comparison semantics — endDate >= startDate. The parser already accepts a bare path as a rule operand (operands are mapping-source expressions), but nothing specifies that the path resolves against a sibling property, so the meaning is undefined for consumers like Stage.
3. State-based business rules — the Arc/DCB idiom where a command validates against injected read-model state (Must(_ => !state.IsStarted), "phase must be Contract", "candidate must exist on the work surface"). These are the rules that actually guard the domain, and they are inexpressible declaratively.

Evidence

From the Ada application (generated with Cratis.Arc.Screenplay 20.65.0):

• 18+ whole-command rules (RuleFor(c => c).Must(...)) dropped with "'RuleFor(c => c)' does not name a property directly, so the rules declared on it were left out" — every one of them a domain business rule reading read-model state, e.g.:

RuleFor(c => c).Must(_ => !state.IsStarted)
    .WithMessage(_ => HourRegistrationMessages.StartMonth_AlreadyStarted);
RuleFor(c => c).Must(_ => summary.Phase is RequestPhase.Contract);

• .When(...) chains dropped (no counterpart in the rule grammar).
• 6 × SP0011 drops of the shape GreaterThanOrEqualTo(x => x.StartDate) — "carries no value to compare against" — where the natural emission endDate >= startDate parses today but has unspecified semantics.

The result is that a generated document's validate blocks contain the string-length/regex layer of validation while the domain-rule layer — the part a reader of the Screenplay actually needs to understand the behavior — is absent.

Suggested direction

• Specify property-path operands: state in the grammar docs that a bare path operand resolves against the validated artifact's properties (endDate >= startDate), so emitters and Stage agree on the meaning. This one may be documentation-only.
• Rule-level conditions: an optional when <condition> on a rule line or an indented condition block, reusing the existing produces when condition parser:

validate
  newEndDate > endDate when isExtension == true message "…"

• State-based rules: a declarative form for command rules that read a read model, e.g.

validate
  require <ReadModel>.<path> <op> <value> message "…"

syntax open — the ask is that the concept exists, so generated documents (and hand-written ones) can state "this command is rejected while the month is already started" without dropping to validate csharp.

Related: closed #8 added concept-level validation; this is the command/business-rule layer on top of it. Cratis.Arc.Screenplay currently drops all of these shapes with SP0011/SP0016 diagnostics — a companion issue on Cratis/Arc covers recovering them once the language can carry them.

Context

Found while validating a generated 5,348-line document from a production Arc application (643 SP0016 warnings in one generation run; the domain-rule layer of every command is missing from the document).

[woksin]

Verified

Re-verified against main, and (a) and (b) are addressed in #45 — which is open for review, not merged, because both are language decisions.

(a) Property-path operands. ValidationRuleParser fed rule operands through ExpressionParser.ParseMappingSource, the same path produces mappings use, so endDate >= startDate already parsed as a PathExpressionSyntax — while grammar.md said Value = Number | StringLiteral | "today" | "true" | "false", contradicting the parser, and no consumer semantics were written down. #45 fixes the EBNF (Value now includes PropertyPath) and states in commands.md that a bare path operand resolves against the sibling properties of the validated artifact.

It also makes today a distinct TodayExpressionSyntax rather than a path, which it had been — meaning it was indistinguishable from a property called today. The property is now written @today, using the keyword escape from #27.

(b) Rule-level conditions. <rule> when <condition> reusing the produces when condition parser:

validate
  newEndDate > endDate when isExtension == true  message "An extension has to move the end date out"

The condition sits between the rule and the message, and the split is done on whitespace-separated words rather than a regular expression so a when inside a quoted operand — matches "^when$" — is not mistaken for the keyword.

(c) State-based rules are not implemented, deliberately. That is what the rest of this comment is about.

Design alternatives for (c)

The rules in your evidence — Must(_ => !state.IsStarted), "phase must be Contract" — are not a validation-grammar problem. They are a dependency problem: the rule cannot be written because the document has no way to say the command reads that state. Any syntax that skips that step describes something ambiguous.

1. Declare the dependency, then use it as an operand (the shape I recommended on #35):

command StartMonth
  engagementId EngagementId

  reads MonthlyHoursState by engagementId

  validate
    MonthlyHoursState.isStarted == false  message "The month is already started"

The operand is (a)'s path operand with a declared-name prefix: a bare path resolves against the command's own properties, a prefixed one against the named read model. No new rule grammar at all — the extension is entirely in what a path may name.

2. A dedicated require form, per this issue's original sketch:

validate
  require MonthlyHoursState.isStarted == false  message "The month is already started"

Makes state-based rules visually distinct, which is honest — they fail for a different reason, at a different point in the pipeline, and under concurrency they are the ones that matter. But it creates a second rule grammar beside the one (b) just extended with when, and the two will drift: the first time someone wants require … when … we are maintaining both.

3. Operand-only, no reads declaration. Cheapest, and I would not ship it. It leaves how the read model is keyed unstated, which is the single most error-prone part of the Arc idiom — a read model injected into a command resolves by the command's event-source id, and silently hands you the wrong instance when the key differs. A document that says "this rule reads MonthlyHoursState" without saying "keyed by engagementId" is describing something that cannot be checked.

Recommendation

Alternative 1, and therefore co-designed with #35, not here. Concretely: reads <ReadModel> by <property> lands as a command-body declaration (worth having on its own — it makes the command's consistency boundary visible in the document), and state-based rules then need no new rule syntax, only a prefixed path operand.

No require keyword. It adds emphasis and a second grammar; the prefix on the operand already tells a reader that the rule consults state.

Sequencing

(c) is blocked on #39 before it is blocked on #35: read models are not declarable entities today, so MonthlyHoursState resolves against nothing. Order:

1. Read models without a declarative projection: reducers and computed views are undeclarable #39 — read models become declarable
2. Define reference scoping and qualified references for screen data/action/navigate targets #28/No way to declare complex value types (child records) - generated documents reference shapes they cannot define #29 — one symbol table resolving every declared name
3. command: declare read-model dependencies (DCB reads) and state-fed produces mappings #35 — reads <ReadModel> by <property>
4. (c) here — prefixed path operands in validate, no new rule grammar

(a) and (b) in #45 are the base step 4 builds on and depend on none of it.

@einari — two calls I would like from you: whether state-based rules read as ordinary rules with a prefixed operand or get their own require form, and whether you are happy with the when-before-message ordering that landed in #45, since that fixes the shape any later conditional form has to match.