[rockfordlhotka]

Related to #3736 and #4235

This PR adds the design document for batch, priority-ordered CheckRules() (docs/dev/CheckRules-Batch-Priority-Plan.md), with no code changes. It started as the plan, reviewed here before implementation. The work is now implemented in #4990 (on top of the baseline tests in #4981), and the doc has been updated to record the design as built, including where and why it differs from the original plan.

What the doc covers

• Why Optimize CheckRules to minimize re-running rules #3736 and CheckRules[Async] should respect rule priority to run rules #4235 are one piece of work: both come from the recursive "for each property, run its rules and cascade" loop in CheckRules().
• The rule runner split:
  • The internal IRuleRunner (policy) is implemented by LegacyRuleRunner (the CSLA 10 behavior) and BatchRuleRunner (the new default).
  • The internal IRuleRunnerHost (mechanics) is implemented by BusinessRules.
• The batch algorithm:
  • object rules first;
  • every property rule once, in priority order across properties;
  • then reruns only for groups invalidated by changed values, up to MaxRerunPasses with cascading;
  • per-property short-circuiting kept, and results of rules excluded on rerun kept.
• Behavior changes, matching Upgrading to CSLA 11.md in Run CheckRules() as a priority-ordered batch through internal rule runners #4990.
• How it was delivered: Add baseline tests for BusinessRules.CheckRules() #4981, plus one commit per step in Run CheckRules() as a priority-ordered batch through internal rule runners #4990, including the review follow-ups.
• Measurements, and why step 6 (skipping stale reruns) was measured but not merged: it saved no rule runs on a 104-rule object and was 10–20% slower.
• Final decisions: per-behavior options (UseBatchCheckRules(b => b.MaxRerunPasses = …) / UseLegacyCheckRules()), object rules first, a cap that throws, v11 only, runners internal.
• What's in place for future priority-ordered async execution, and what isn't.
• Follow-ups: WaitForIdle returns before async rule completion notifications finish #4991 (WaitForIdle() returns before async rule completion finishes), the legacy clear-then-skip cascade, the CascadeIfDirty check, and the ignored CascadeTests.

Review feedback addressed here: the pass-2 set notation, and per-runner options (both from Stefan Ossendorf).

🤖 Generated with Claude Code

[StefanOssendorf]

I'm not sure if this is the correct place:
Currently a BO is busy while it's rules are running. But the Rule completion is done after the busy state is set to non busy. At work that behavior results in a race condition. We are using WaitForIdle which triggers because IsBusy = false is set, but the async rule hasn't completed yet. But we go ahead and are done an dispose stuff. But the BO accesses the now disposed DI scope which results in exceptions. I managed that with a Settle method which listens in addition on the completed event handler. I'll post the method tomorrow when I'm at work.

Should we consider that in this rework or is this something independent?

[StefanOssendorf]

This equation means D union Primary property. The intersection is irrelevant because it will be absorbed according to set operations.
I interpreted the | as an or.

[rockfordlhotka]

Good point, that notation was ambiguous. The | was meant as set-builder "such that", not "or". So the set is "the primary property of every rule whose input properties overlap D", and the intersection is the filter condition, not a set operation on the result.

I rewrote it in 94d2c9a. The doc now says it in words first: the properties in D, plus the primary property of every rule with at least one input in D. It then gives Q = D ∪ P, where P = { r.PrimaryProperty : r.InputProperties ∩ D ≠ ∅ }, with : for "such that".

For reference, this is BatchPlan.GroupsInvalidatedBy in #4990: for each dirty property, it adds that property's group and the groups of the rules that list it as an input.

[StefanOssendorf]

Shouldn't we create runner dependent options? It's not very intuitive to have such a property but it's not respected by the configured runner. 🤔

[rockfordlhotka]

Agreed. A flat MaxCheckRulesPasses that the legacy runner silently ignores is confusing, and it would get worse once there's an async runner with options of its own.

#4990 now chooses the behavior with a method, and each method takes only that behavior's settings (fcc0dcd):

o.Rules(r => r.UseBatchCheckRules(b => b.MaxRerunPasses = 200));   // default; MaxRerunPasses defaults to 100
o.Rules(r => r.UseLegacyCheckRules());                             // CSLA 10 behavior, temporary

• MaxCheckRulesPasses became BatchCheckRulesOptions.MaxRerunPasses, so it's only reachable when you choose the batch behavior.
• If both methods are called, the last call wins (covered by RuleOptions_LastRunnerChoiceWins).
• A future runner, such as priority-ordered async execution, adds its own Use…(…) method with its own options.
• Removing the legacy behavior later means deleting UseLegacyCheckRules().

The runners themselves stay internal, so these methods are the public way to choose one. The plan doc's Decisions section is updated to match (94d2c9a).