[rockfordlhotka]

Closes #3736
Closes #4235

Implements the plan in #4978. The baseline tests from #4981 are the safety net.

What changes

BusinessRules.CheckRules() / CheckRulesAsync() now runs rules as a batch:

1. Object rules run first, as before.
2. Every property rule runs once, in priority order across all properties (CheckRules[Async] should respect rule priority to run rules #4235). Ties keep the CSLA 10 order. Short-circuiting (ProcessThroughPriority, StopProcessing) still applies per property.
3. Only property groups invalidated by values that rules changed through output values rerun: the changed properties' own rules and the rules that use them as inputs (Optimize CheckRules to minimize re-running rules #3736).
4. With CascadeOnDirtyProperties, step 3 repeats until nothing changes, up to MaxRerunPasses (default 100). Past the cap it throws InvalidOperationException naming the properties still changing. Before, rules that never settled recursed until a StackOverflowException killed the process.

CheckRules(property) (the property-changed path) and CheckObjectRules() are unchanged.

How it's built

As the plan describes, rule execution is split into policy and mechanics:

• IRuleRunner (internal) decides which rules run, in what order, when to rerun and when to stop. It owns CheckRules(), CheckRules(property) and CheckObjectRules().
  • LegacyRuleRunner: the CSLA 10 code, moved out of BusinessRules unchanged.
  • BatchRuleRunner: the new CheckRules(). It inherits the other two entry points from LegacyRuleRunner.
• IRuleRunnerHost (internal, implemented by BusinessRules) keeps the mechanics: RunRule reads inputs, executes, applies outputs, records broken rules and tracks busy state. The post-completion cascade for async rules is passed in as a handler.
• Runners keep no state between calls. They're registered as singletons in AddCsla() and resolved lazily by BusinessRules, so they're still available after deserialization.

New public API: RuleOptions with UseBatchCheckRules(...) and UseLegacyCheckRules(), BatchCheckRulesOptions.MaxRerunPasses, CslaOptions.RuleOptions, and the CslaOptions.Rules(...) extension. Each method takes only the settings for that behavior, so no setting is silently ignored by the chosen runner; the last call wins:

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

Commits

Each commit builds and passes the tests:

1. Extract single-rule execution behind IRuleRunnerHost. Refactor only, no behavior change.
2. Move rule execution policy into LegacyRuleRunner. Refactor only, no behavior change. The full suite passed at this commit.
3. BatchRuleRunner (Optimize CheckRules to minimize re-running rules #3736) plus RuleOptions, the resource string and the upgrade doc.
4. Priority order across properties (CheckRules[Async] should respect rule priority to run rules #4235). Changes only the sort key, so it can be reverted on its own.

Review follow-ups:

5. Keep excluded rules' results on rerun, and reset RunningRules on failure. Fixes the two Copilot review findings, each covered by a new test.
6. Make the options specific to the chosen behavior (Stefan Ossendorf's review of Design doc for batch and priority-ordered CheckRules #4978).

Tests

• CheckRulesBaselineTests (Add baseline tests for BusinessRules.CheckRules() #4981) now runs with UseLegacyCheckRules() and passes unchanged, so the legacy runner still matches CSLA 10.
• New CheckRulesBatchTests covers the same scenarios against the default runner, so the two classes show each behavior change side by side. It adds the cycle cap (the never-settling cycle that crashes the legacy runner now throws), MaxRerunPasses configuration and validation, last-choice-wins for the options, rerun handling of DenyAsAffectedProperty and short-circuited rules, the rule engine staying usable after the cap exception, and CheckRules() after serialization.

Scenario	Legacy rule runs	Batch rule runs
#3736 credit-hold scenario, cascade on / off	24 / 21	9 / 9
Increment chain N1→N2→N3→N4, cascade on / off	6 / 5	5 / 5
Rule on P with Q as an affected property	4	3
Rules that use K as an input	4	3
Never-settling cycle, cascade on	stack overflow	InvalidOperationException after 100 passes

• Full CI suite (csla.test.sln, TestCategory!=SkipOnCIServer) passes on net10.0 and net11.0, after the refactor commits and on the final commit.

Measurements

These come from a throwaway timing test (not committed) on a 20-property object with 104 rules (Release, net10.0, average per CheckRules() call). Csla.Benchmarks references the published Csla 10.1.0 package, so it can't measure this branch.

Values	Legacy	Batch
Already consistent	619 rule runs, ~330–450 µs	104 runs, ~75 µs
All zero (rules change 19 values)	619 runs (cascade off) / 1,083 runs (cascade on), ~340–740 µs	208 runs, ~115–145 µs

Where this differs from the plan

• Step 6 (skip reruns for rules that already ran after a value changed) isn't included. The plan made it conditional on the benchmark. On the 104-rule object it saved no rule runs and was 10–20% slower, because there the reruns are real dependencies. It helps in narrower shapes, such as a chain registered in order or an object rule that sets a value. The code is on a local branch if real-world objects turn out to need it.
• No Csla.Benchmarks case, for the reason above.

Behavior changes (documented in Upgrading to CSLA 11.md)

• Cross-property order follows priority.
• Reruns depend on values changed through output values. A rule that changes a property some other way no longer triggers dependent reruns in CheckRules().
• Affected properties' rules don't rerun in CheckRules() unless a value changed.
• CascadeIfDirty has no effect in CheckRules().
• Rules that never settle throw instead of overflowing the stack.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Rerun passes can erase validation errors and incorrectly mark objects valid, while cascade-limit exceptions leave RunningRules set and suppress subsequent completion notifications.

2 open issues

• Preserve errors for mode-excluded rules on rerun · New
• Reset RunningRules after cascade-limit exceptions · New

1 file not reviewed

• Source/Csla/Properties/Resources.Designer.cs: Generated file

What changed in this PR

This PR changes CSLA’s full-object rule checks to priority-ordered batches, reducing redundant execution for interdependent rules while retaining a legacy compatibility option.

Changes:

• Separates rule-execution policy into internal runners and keeps execution mechanics in BusinessRules.
• Adds dirty-value-driven reruns, a configurable cascade-pass limit, and cross-property priority ordering.
• Adds batch behavior tests, preserves legacy baseline tests, and documents migration considerations.

File	Description
Source/​tests/​Csla.test/​ValidationRules/​CheckRulesBatchTests.cs	Tests batch ordering, reruns, limits, and serialization.
Source/​tests/​Csla.test/​ValidationRules/​CheckRulesBaselineTests.cs	Runs existing baselines with legacy behavior enabled.
Source/​Csla/​Rules/​RuleRunners/​LegacyRuleRunner.cs	Extracts legacy rule-execution policy.
Source/​Csla/​Rules/​RuleRunners/​IRuleRunnerHost.cs	Defines single-rule execution and outcome contracts.
Source/​Csla/​Rules/​RuleRunners/​IRuleRunner.cs	Defines internal runner entry points.
Source/​Csla/​Rules/​RuleRunners/​BatchRuleRunner.cs	Implements priority-ordered batches and bounded reruns.
Source/​Csla/​Rules/​BusinessRules.cs	Delegates policy to runners and retains execution mechanics.
Source/​Csla/​Properties/​Resources.resx	Adds the cascade-limit error message.
Source/​Csla/​Properties/​Resources.Designer.cs	Exposes the new resource string.
Source/​Csla/​Configuration/​Fluent/​RuleOptions.cs	Adds legacy-mode and cascade-limit settings.
Source/​Csla/​Configuration/​Fluent/​RuleConfigurationExtensions.cs	Adds fluent rule configuration.
Source/​Csla/​Configuration/​Fluent/​CslaOptions.cs	Exposes rule options.
Source/​Csla/​Configuration/​ConfigurationExtensions.cs	Registers the selected runner as a singleton.
docs/​Upgrading to CSLA 11.md	Documents behavior changes and compatibility settings.

_{Review effort: Balanced}

[rockfordlhotka]

Confirmed and fixed in 823eba4.

A failing test reproduced it: a rule that changes its own property forces a rerun, and a failing validator on that property is marked DenyAsAffectedProperty. Pass 2 cleared the validator's error without rerunning it, and the object reported itself valid.

Rerun passes now keep the broken rules of rules that can't run in the rerun mode, and clear everything else in the group as before. So results from rules that are short-circuited on the rerun still get removed. The new BrokenRulesCollection.ClearRules(property, keepRuleNames) does this. Pass 1 still clears everything, matching the legacy runner.

Tests:

• CheckRules_RerunKeepsResultsOfRulesThatDenyRunningAsAffectedProperty: the error is kept.
• CheckRules_RerunClearsResultsOfShortCircuitedRules: a rule short-circuited on the rerun has its old error removed.

LegacyRuleRunner has the same clear-then-skip pattern in its cascades (CheckRulesForProperty clears the property's broken rules before filtering by CanRunRule), including the property-changed path. That's existing CSLA 10 behavior: there it only appears depending on rule order, while the batch rerun pass made it happen every time. I left the legacy runner unchanged because it's meant to reproduce CSLA 10 exactly. The property-changed path is worth a separate issue.