feat(abstractions): add async mutation policy contract

Author: rian-be

src/Abstractions/MutationEngineOptions.cs

@@ -36,6 +36,16 @@ public sealed class MutationEngineOptions
     /// </remarks>
     public TimeSpan? ExecutionTimeout { get; set; }
 
+    /// <summary>
+    /// The maximum allowed evaluation time for a single policy.
+    /// </summary>
+    /// <remarks>
+    /// When specified, each registered policy evaluation gets its own timeout window.
+    /// This is primarily intended for async policies that call external identity, ticketing,
+    /// quota, or compliance systems.
+    /// </remarks>
+    public TimeSpan? PolicyEvaluationTimeout { get; set; }
+
     /// <summary>
     /// Indicates whether batch execution should stop after the first failure.
     /// </summary>
@@ -49,7 +59,7 @@ public sealed class MutationEngineOptions
     /// Enables collection of detailed execution metrics.
     /// </summary>
     /// <remarks>
-    /// Detailed metrics provide deep observability but may have a measurable
+    /// Detailed metrics provide deep observability but may have measurable
     /// performance impact in high-throughput scenarios.
     /// </remarks>
     public bool EnableDetailedMetrics { get; set; } = false;
@@ -82,7 +92,7 @@ public sealed class MutationEngineOptions
     };
 
     /// <summary>
-    /// Performance-oriented configuration minimizing overhead.
+    /// Performance oriented configuration minimizing overhead.
     /// </summary>
     /// <remarks>
     /// Intended for trusted environments where validation and detailed metrics

src/Abstractions/Policies/IMutationPolicy.cs

@@ -3,8 +3,8 @@
 namespace ModularityKit.Mutator.Abstractions.Policies;
 
 /// <summary>
-/// Represents a policy that decides whether a mutation can be applied.
-/// Policies are a FIRST-CLASS governance mechanism in the mutation framework.
+/// Represents policy that decides whether a mutation can be applied.
+/// Policies are FIRST CLASS governance mechanism in the mutation framework.
 /// </summary>
 /// <typeparam name="TState">Type of the state the mutation operates on.</typeparam>
 public interface IMutationPolicy<TState>
@@ -31,5 +31,19 @@ public interface IMutationPolicy<TState>
     /// <param name="mutation">The mutation to evaluate.</param>
     /// <param name="state">The current state before applying the mutation.</param>
     /// <returns>A <see cref="PolicyDecision"/> representing the result of the evaluation.</returns>
-    PolicyDecision Evaluate(IMutation<TState> mutation, TState state);
+    PolicyDecision Evaluate(IMutation<TState> mutation, TState state)
+        => throw new NotSupportedException("This policy does not implement synchronous evaluation.");
+
+    /// <summary>
+    /// Evaluates whether the given mutation is allowed on the current state asynchronously.
+    /// </summary>
+    /// <param name="mutation">The mutation to evaluate.</param>
+    /// <param name="state">The current state before applying the mutation.</param>
+    /// <param name="cancellationToken">Token used to cancel the policy evaluation.</param>
+    /// <returns>A <see cref="PolicyDecision"/> representing the result of the evaluation.</returns>
+    Task<PolicyDecision> EvaluateAsync(
+        IMutation<TState> mutation,
+        TState state,
+        CancellationToken cancellationToken = default)
+        => Task.FromResult(Evaluate(mutation, state));
 }