docs(runtime): replace inheritdoc with explicit XML docs in MutationEngine

Replace all /// <inheritdoc /> usages in MutationEngine with explicit
XML documentation matching the IMutationEngine interface contract:
- ExecuteAsync
- ExecuteBatchAsync (both overloads, with remarks)
- RegisterPolicy, RegisterInterceptor (with remarks)
- GetHistoryAsync, GetStatisticsAsync

Add param/returns/exception tags to private helpers:
- ExecutePipelineAsync
- CreateConcurrencyGate (ArgumentNullException, ArgumentOutOfRangeException)

Author: rian-be

Tests/ModularityKit.Mutator.Tests/Runtime/MutationEnginePolicyTests.cs

@@ -0,0 +1,176 @@
+using Microsoft.Extensions.DependencyInjection;
+using ModularityKit.Mutator.Abstractions;
+using ModularityKit.Mutator.Abstractions.Changes;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Exceptions;
+using ModularityKit.Mutator.Abstractions.Intent;
+using ModularityKit.Mutator.Abstractions.Policies;
+using ModularityKit.Mutator.Abstractions.Results;
+using ModularityKit.Mutator.Runtime;
+using Xunit;
+
+namespace ModularityKit.Mutator.Tests.Runtime;
+
+public sealed class MutationEnginePolicyTests
+{
+    [Fact]
+    public async Task ExecuteAsync_supports_async_policy_evaluation()
+    {
+        var engine = CreateEngine();
+        engine.RegisterPolicy(new AsyncBlockingPolicy());
+
+        var result = await engine.ExecuteAsync(new SampleMutation(), new SampleState("initial"));
+
+        Assert.False(result.IsSuccess);
+        Assert.Single(result.PolicyDecisions);
+        Assert.Equal("AsyncBlocking", result.PolicyDecisions[0].PolicyName);
+        Assert.Equal("External compliance check rejected the mutation.", result.PolicyDecisions[0].Reason);
+    }
+
+    [Fact]
+    public async Task ExecuteAsync_throws_policy_evaluation_timeout_exception_for_slow_policy()
+    {
+        var engine = CreateEngine(options => options.PolicyEvaluationTimeout = TimeSpan.FromMilliseconds(50));
+        engine.RegisterPolicy(new SlowAsyncPolicy());
+
+        var exception = await Assert.ThrowsAsync<PolicyEvaluationTimeoutException>(() =>
+            engine.ExecuteAsync(new SampleMutation(), new SampleState("initial")));
+
+        Assert.Equal("SlowExternalCheck", exception.PolicyName);
+    }
+
+    [Fact]
+    public async Task ExecuteAsync_wraps_policy_evaluation_failures()
+    {
+        var engine = CreateEngine();
+        engine.RegisterPolicy(new FailingAsyncPolicy());
+
+        var exception = await Assert.ThrowsAsync<PolicyEvaluationException>(() =>
+            engine.ExecuteAsync(new SampleMutation(), new SampleState("initial")));
+
+        Assert.Equal("FailingExternalCheck", exception.PolicyName);
+        Assert.IsType<InvalidOperationException>(exception.InnerException);
+    }
+
+    [Fact]
+    public async Task ExecuteAsync_preserves_caller_cancellation_during_policy_evaluation()
+    {
+        var engine = CreateEngine();
+        engine.RegisterPolicy(new CancelAwareAsyncPolicy());
+        using var cancellationSource = new CancellationTokenSource(millisecondsDelay: 50);
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(() =>
+            engine.ExecuteAsync(new SampleMutation(), new SampleState("initial"), cancellationSource.Token));
+    }
+
+    [Fact]
+    public async Task ExecuteAsync_uses_sync_policy_path_without_async_override()
+    {
+        var engine = CreateEngine();
+        engine.RegisterPolicy(new SyncAllowPolicy());
+
+        var result = await engine.ExecuteAsync(new SampleMutation(), new SampleState("initial"));
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal("updated", result.NewState!.Value);
+    }
+
+    private static IMutationEngine CreateEngine(Action<MutationEngineOptions>? configure = null)
+    {
+        var services = new ServiceCollection();
+        services.AddMutators(configure: configure);
+
+        var provider = services.BuildServiceProvider();
+        return provider.GetRequiredService<IMutationEngine>();
+    }
+
+    private sealed record SampleState(string Value);
+
+    private sealed class SampleMutation : MutationBase<SampleState>
+    {
+        public SampleMutation()
+            : base(
+                CreateIntent(
+                    operationName: "UpdateSample",
+                    category: "Test",
+                    description: "Exercise policy evaluation"),
+                MutationContext.System("Policy test") with { StateId = "sample-1" })
+        {
+        }
+
+        public override MutationResult<SampleState> Apply(SampleState state)
+            => Success(state with { Value = "updated" }, StateChange.Modified("Value", state.Value, "updated"));
+    }
+
+    private sealed class SyncAllowPolicy : IMutationPolicy<SampleState>
+    {
+        public string Name => "SyncAllow";
+        public int Priority => 10;
+        public string? Description => "Simple synchronous allow policy.";
+
+        public PolicyDecision Evaluate(IMutation<SampleState> mutation, SampleState state)
+            => PolicyDecision.Allow(Name, "Synchronous policy allowed the mutation.");
+    }
+
+    private sealed class AsyncBlockingPolicy : IMutationPolicy<SampleState>
+    {
+        public string Name => "AsyncBlocking";
+        public int Priority => 100;
+        public string? Description => "Simulates an external compliance check.";
+
+        public async Task<PolicyDecision> EvaluateAsync(
+            IMutation<SampleState> mutation,
+            SampleState state,
+            CancellationToken cancellationToken = default)
+        {
+            await Task.Delay(10, cancellationToken);
+            return PolicyDecision.Deny("External compliance check rejected the mutation.", Name);
+        }
+    }
+
+    private sealed class SlowAsyncPolicy : IMutationPolicy<SampleState>
+    {
+        public string Name => "SlowExternalCheck";
+        public int Priority => 100;
+        public string? Description => "Simulates a slow external dependency.";
+
+        public async Task<PolicyDecision> EvaluateAsync(
+            IMutation<SampleState> mutation,
+            SampleState state,
+            CancellationToken cancellationToken = default)
+        {
+            await Task.Delay(TimeSpan.FromSeconds(5), cancellationToken);
+            return PolicyDecision.Allow(Name, "Finished too late.");
+        }
+    }
+
+    private sealed class FailingAsyncPolicy : IMutationPolicy<SampleState>
+    {
+        public string Name => "FailingExternalCheck";
+        public int Priority => 100;
+        public string? Description => "Simulates an external dependency failure.";
+
+        public Task<PolicyDecision> EvaluateAsync(
+            IMutation<SampleState> mutation,
+            SampleState state,
+            CancellationToken cancellationToken = default)
+            => throw new InvalidOperationException("Remote ticketing system unavailable.");
+    }
+
+    private sealed class CancelAwareAsyncPolicy : IMutationPolicy<SampleState>
+    {
+        public string Name => "CancelAware";
+        public int Priority => 100;
+        public string? Description => "Waits for cancellation.";
+
+        public async Task<PolicyDecision> EvaluateAsync(
+            IMutation<SampleState> mutation,
+            SampleState state,
+            CancellationToken cancellationToken = default)
+        {
+            await Task.Delay(TimeSpan.FromSeconds(5), cancellationToken);
+            return PolicyDecision.Allow(Name, "Completed.");
+        }
+    }
+}

src/README.md

@@ -102,6 +102,47 @@ Core runtime concurrency is controlled by `MutationEngineOptions.MaxConcurrentMu
 - `PolicyDecision`
 - `PolicyRequirement`
 
+### Async policies and external checks
+
+`IMutationPolicy<TState>` supports both synchronous and asynchronous evaluation.
+
+- implement `Evaluate(...)` for lightweight in-process rules
+- implement `EvaluateAsync(..., CancellationToken)` for external identity, ticketing, quota, or compliance checks
+- the runtime evaluates policies in descending `Priority` order
+- when `MutationEngineOptions.PolicyEvaluationTimeout` is set, the timeout is applied per policy evaluation
+- caller cancellation still flows through unchanged
+- policy failures are surfaced as `PolicyEvaluationException`
+- policy timeouts are surfaced as `PolicyEvaluationTimeoutException`
+
+```csharp
+public sealed class RequireApprovedTicketPolicy : IMutationPolicy<QuotaState>
+{
+    private readonly ITicketGateway _tickets;
+
+    public RequireApprovedTicketPolicy(ITicketGateway tickets)
+    {
+        _tickets = tickets;
+    }
+
+    public string Name => "RequireApprovedTicket";
+    public int Priority => 200;
+    public string? Description => "Checks ticket approval status before quota changes execute.";
+
+    public async Task<PolicyDecision> EvaluateAsync(
+        IMutation<QuotaState> mutation,
+        QuotaState state,
+        CancellationToken cancellationToken = default)
+    {
+        var ticketId = mutation.Context.CorrelationId;
+        var approved = await _tickets.IsApprovedAsync(ticketId!, cancellationToken);
+
+        return approved
+            ? PolicyDecision.Allow(Name, "External ticket is approved.")
+            : PolicyDecision.Deny("External ticket is not approved.", Name);
+    }
+}
+```
+
 ### Results and changes
 
 - `MutationResult<TState>`