Feat: Enhance policy evaluation ordering

Author: rian-be

src/Runtime/Internal/Evaluation/MutationPolicyEvaluator.cs

@@ -8,6 +8,11 @@ namespace ModularityKit.Mutator.Runtime.Internal.Evaluation;
 /// <summary>
 /// Evaluates registered mutation policies in runtime priority order.
 /// </summary>
+/// <remarks>
+/// The evaluator resolves policies from the registry, applies deterministic
+/// priority ordering, invokes each policy with optional timeout handling, and
+/// returns the first blocking or modifying decision.
+/// </remarks>
 internal sealed class MutationPolicyEvaluator(
     IPolicyRegistry policyRegistry,
     MutationEngineOptions options)
@@ -32,7 +37,10 @@ public async Task<PolicyDecision> EvaluateAsync<TState>(
     {
         var policies = _policyRegistry.GetPolicies<TState>();
 
-        foreach (var policy in policies.OrderByDescending(p => p.Priority))
+        foreach (var policy in policies
+            .OrderByDescending(p => p.Priority)
+            .ThenBy(p => p.Name, StringComparer.Ordinal)
+            .ThenBy(p => p.GetType().FullName ?? string.Empty, StringComparer.Ordinal))
         {
             var decision = await EvaluatePolicyAsync(
                 policy,
@@ -47,6 +55,21 @@ public async Task<PolicyDecision> EvaluateAsync<TState>(
         return PolicyDecision.Allow();
     }
 
+    /// <summary>
+    /// Evaluates a single policy with optional runtime timeout handling.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the policy.</typeparam>
+    /// <param name="policy">The policy to evaluate.</param>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current state snapshot.</param>
+    /// <param name="cancellationToken">Token used to cancel policy evaluation.</param>
+    /// <returns>The decision produced by the policy.</returns>
+    /// <exception cref="PolicyEvaluationTimeoutException">
+    /// Thrown when policy evaluation exceeds the configured timeout.
+    /// </exception>
+    /// <exception cref="PolicyEvaluationException">
+    /// Thrown when the policy evaluation fails with a non-cancellation exception.
+    /// </exception>
     private async Task<PolicyDecision> EvaluatePolicyAsync<TState>(
         IMutationPolicy<TState> policy,
         IMutation<TState> mutation,
@@ -82,6 +105,18 @@ private async Task<PolicyDecision> EvaluatePolicyAsync<TState>(
         }
     }
 
+    /// <summary>
+    /// Invokes a policy and normalizes unexpected failures into policy evaluation exceptions.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the policy.</typeparam>
+    /// <param name="policy">The policy to invoke.</param>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current state snapshot.</param>
+    /// <param name="cancellationToken">Token used to cancel policy evaluation.</param>
+    /// <returns>The decision produced by the policy.</returns>
+    /// <exception cref="PolicyEvaluationException">
+    /// Thrown when the policy evaluation fails with a non-cancellation exception.
+    /// </exception>
     private static async Task<PolicyDecision> InvokePolicyAsync<TState>(
         IMutationPolicy<TState> policy,
         IMutation<TState> mutation,