refactor(runtime): reorganize Internal into Execution and Evaluation subfolders

Split the flat Internal directory into two purpose-scoped subdirectories:
- Execution: pipeline orchestration, concurrency, mode running, batch, failure handling
- Evaluation: policy evaluation and policy modification application

Namespaces updated accordingly to match folder structure.

Author: rian-be

src/Runtime/Internal/Evaluation/MutationPolicyEvaluator.cs

@@ -0,0 +1,107 @@
+using ModularityKit.Mutator.Abstractions;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Exceptions;
+using ModularityKit.Mutator.Abstractions.Policies;
+
+namespace ModularityKit.Mutator.Runtime.Internal.Evaluation;
+
+/// <summary>
+/// Evaluates registered mutation policies in runtime priority order.
+/// </summary>
+internal sealed class MutationPolicyEvaluator(
+    IPolicyRegistry policyRegistry,
+    MutationEngineOptions options)
+{
+    private readonly IPolicyRegistry _policyRegistry = policyRegistry ?? throw new ArgumentNullException(nameof(policyRegistry));
+    private readonly MutationEngineOptions _options = options ?? throw new ArgumentNullException(nameof(options));
+
+    /// <summary>
+    /// Evaluates all registered policies for the supplied mutation and state.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+    /// <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 first blocking or modifying <see cref="PolicyDecision"/>, or an allow decision when all policies pass.
+    /// </returns>
+    public async Task<PolicyDecision> EvaluateAsync<TState>(
+        IMutation<TState> mutation,
+        TState state,
+        CancellationToken cancellationToken)
+    {
+        var policies = _policyRegistry.GetPolicies<TState>();
+
+        foreach (var policy in policies.OrderByDescending(p => p.Priority))
+        {
+            var decision = await EvaluatePolicyAsync(
+                policy,
+                mutation,
+                state,
+                cancellationToken).ConfigureAwait(false);
+
+            if (!decision.IsAllowed || decision.Modifications != null)
+                return decision;
+        }
+
+        return PolicyDecision.Allow();
+    }
+
+    private async Task<PolicyDecision> EvaluatePolicyAsync<TState>(
+        IMutationPolicy<TState> policy,
+        IMutation<TState> mutation,
+        TState state,
+        CancellationToken cancellationToken)
+    {
+        if (!_options.PolicyEvaluationTimeout.HasValue)
+            return await InvokePolicyAsync(policy, mutation, state, cancellationToken).ConfigureAwait(false);
+
+        using var timeoutSource = new CancellationTokenSource(_options.PolicyEvaluationTimeout.Value);
+        using var linkedSource = CancellationTokenSource.CreateLinkedTokenSource(
+            cancellationToken,
+            timeoutSource.Token);
+
+        try
+        {
+            return await policy.EvaluateAsync(mutation, state, linkedSource.Token).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (OperationCanceledException) when (timeoutSource.IsCancellationRequested)
+        {
+            throw new PolicyEvaluationTimeoutException(policy.Name, _options.PolicyEvaluationTimeout.Value);
+        }
+        catch (Exception ex)
+        {
+            throw new PolicyEvaluationException(
+                policy.Name,
+                $"Policy '{policy.Name}' evaluation failed: {ex.Message}",
+                ex);
+        }
+    }
+
+    private static async Task<PolicyDecision> InvokePolicyAsync<TState>(
+        IMutationPolicy<TState> policy,
+        IMutation<TState> mutation,
+        TState state,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            return await policy.EvaluateAsync(mutation, state, cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            throw new PolicyEvaluationException(
+                policy.Name,
+                $"Policy '{policy.Name}' evaluation failed: {ex.Message}",
+                ex);
+        }
+    }
+}

…me/Internal/PolicyModificationApplier.cs …/Evaluation/PolicyModificationApplier.cssrc/Runtime/Internal/PolicyModificationApplier.cs renamed to src/Runtime/Internal/Evaluation/PolicyModificationApplier.cs src/Runtime/Internal/PolicyModificationApplier.cs renamed to src/Runtime/Internal/Evaluation/PolicyModificationApplier.cs

@@ -1,10 +1,27 @@
 using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Results;
 
-namespace ModularityKit.Mutator.Runtime.Internal;
+namespace ModularityKit.Mutator.Runtime.Internal.Evaluation;
 
+/// <summary>
+/// Applies policy-level state and side-effect modifications to a mutation result.
+/// </summary>
 internal static class PolicyModificationApplier
 {
+    /// <summary>
+    /// Applies the given policy modifications to <paramref name="result" />, returning an updated result.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+    /// <param name="result">The original mutation result to apply modifications to.</param>
+    /// <param name="modifications">
+    /// A dictionary of modifications. Recognised keys are <c>"State"</c> (overrides the new state),
+    /// <c>"SideEffect"</c> (appends a single <see cref="SideEffect" />), and
+    /// <c>"SideEffects"</c> (appends a collection of <see cref="SideEffect" />).
+    /// </param>
+    /// <returns>
+    /// The original <paramref name="result" /> unchanged when no applicable modifications exist or the result is not successful;
+    /// otherwise a new result record with the modifications applied.
+    /// </returns>
     public static MutationResult<TState> Apply<TState>(
         MutationResult<TState> result,
         IReadOnlyDictionary<string, object>? modifications)

…untime/Internal/MutationBatchExecutor.cs …ernal/Execution/MutationBatchExecutor.cssrc/Runtime/Internal/MutationBatchExecutor.cs renamed to src/Runtime/Internal/Execution/MutationBatchExecutor.cs src/Runtime/Internal/MutationBatchExecutor.cs renamed to src/Runtime/Internal/Execution/MutationBatchExecutor.cs

@@ -3,10 +3,27 @@
 using ModularityKit.Mutator.Abstractions.Results;
 using System.Diagnostics;
 
-namespace ModularityKit.Mutator.Runtime.Internal;
+namespace ModularityKit.Mutator.Runtime.Internal.Execution;
 
+/// <summary>
+/// Executes a sequence of mutations against an evolving state, accumulating results and changes.
+/// </summary>
 internal static class MutationBatchExecutor
 {
+    /// <summary>
+    /// Iterates over <paramref name="mutations" /> in order, executing each against the current state.
+    /// Successful mutations advance the state; failed mutations are recorded and may halt the batch.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutations.</typeparam>
+    /// <param name="mutations">The ordered sequence of mutations to execute.</param>
+    /// <param name="initialState">The starting state before any mutation is applied.</param>
+    /// <param name="stopOnFirstFailure">When <see langword="true" />, halts execution after the first unsuccessful mutation.</param>
+    /// <param name="executeAsync">The delegate used to execute a single mutation against the current state.</param>
+    /// <param name="cancellationToken">Token used to cancel batch execution.</param>
+    /// <returns>
+    /// A <see cref="BatchMutationResult{TState}" /> containing all individual results, the aggregated
+    /// change set, the final state (when all mutations succeeded), and the total execution time.
+    /// </returns>
     public static async Task<BatchMutationResult<TState>> ExecuteAsync<TState>(
         IEnumerable<IMutation<TState>> mutations,
         TState initialState,

…rnal/MutationExecutionConcurrencyGate.cs …tion/MutationExecutionConcurrencyGate.cssrc/Runtime/Internal/MutationExecutionConcurrencyGate.cs renamed to src/Runtime/Internal/Execution/MutationExecutionConcurrencyGate.cs src/Runtime/Internal/MutationExecutionConcurrencyGate.cs renamed to src/Runtime/Internal/Execution/MutationExecutionConcurrencyGate.cs

@@ -1,6 +1,6 @@
 using System.Collections.Concurrent;
 
-namespace ModularityKit.Mutator.Runtime.Internal;
+namespace ModularityKit.Mutator.Runtime.Internal.Execution;
 
 /// <summary>
 /// Coordinates core mutation execution concurrency across the engine.

src/Runtime/Internal/Execution/MutationExecutionContext.cs

@@ -0,0 +1,42 @@
+using System.Diagnostics;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Metrics;
+
+namespace ModularityKit.Mutator.Runtime.Internal.Execution;
+
+/// <summary>
+/// Carries shared execution state across the runtime mutation pipeline.
+/// </summary>
+/// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+internal sealed record MutationExecutionContext<TState>
+{
+    /// <summary>
+    /// The mutation being executed.
+    /// </summary>
+    public IMutation<TState> Mutation { get; init; } = null!;
+
+    /// <summary>
+    /// The current state snapshot being mutated.
+    /// </summary>
+    public TState State { get; init; } = default!;
+
+    /// <summary>
+    /// The unique identifier for this execution run.
+    /// </summary>
+    public string ExecutionId { get; init; } = string.Empty;
+
+    /// <summary>
+    /// The shared stopwatch tracking total execution time.
+    /// </summary>
+    public Stopwatch Stopwatch { get; init; } = null!;
+
+    /// <summary>
+    /// The optional metrics scope for detailed runtime metrics.
+    /// </summary>
+    public IMetricsScope? MetricsScope { get; init; }
+
+    /// <summary>
+    /// The cancellation token for the current execution.
+    /// </summary>
+    public CancellationToken CancellationToken { get; init; }
+}

src/Runtime/Internal/Execution/MutationExecutionFailureHandler.cs

@@ -0,0 +1,106 @@
+using ModularityKit.Mutator.Abstractions.Audit;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Exceptions;
+using ModularityKit.Mutator.Abstractions.Interception;
+using ModularityKit.Mutator.Runtime.Diagnostics;
+
+namespace ModularityKit.Mutator.Runtime.Internal.Execution;
+
+/// <summary>
+/// Centralizes interceptor notification and audit persistence for mutation execution failures.
+/// </summary>
+internal sealed class MutationExecutionFailureHandler(
+    IInterceptorPipeline interceptorPipeline,
+    IMutationAuditor auditor)
+{
+    private readonly IInterceptorPipeline _interceptorPipeline =
+        interceptorPipeline ?? throw new ArgumentNullException(nameof(interceptorPipeline));
+
+    private readonly IMutationAuditor _auditor = auditor ?? throw new ArgumentNullException(nameof(auditor));
+
+    /// <summary>
+    /// Processes known mutation exception without wrapping it again.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+    /// <param name="executionContext">The shared execution context for the failed mutation.</param>
+    /// <param name="exception">The known mutation exception.</param>
+    /// <param name="duration">The elapsed execution time before failure.</param>
+    public async Task HandleKnownExceptionAsync<TState>(
+        MutationExecutionContext<TState> executionContext,
+        MutationException exception,
+        TimeSpan duration)
+    {
+        await NotifyFailureAsync(
+            executionContext,
+            exception,
+            executionContext.CancellationToken).ConfigureAwait(false);
+
+        await AuditExceptionAsync(
+            executionContext.Mutation,
+            exception,
+            executionContext.ExecutionId,
+            duration).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Processes an unexpected exception and converts it into runtime level mutation exception.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+    /// <param name="executionContext">The shared execution context for the failed mutation.</param>
+    /// <param name="exception">The unexpected exception.</param>
+    /// <param name="duration">The elapsed execution time before failure.</param>
+    /// <returns>The wrapped runtime exception to rethrow.</returns>
+    public async Task<MutationException> HandleUnexpectedExceptionAsync<TState>(
+        MutationExecutionContext<TState> executionContext,
+        Exception exception,
+        TimeSpan duration)
+    {
+        await NotifyFailureAsync(
+            executionContext,
+            exception,
+            executionContext.CancellationToken).ConfigureAwait(false);
+
+        await AuditExceptionAsync(
+            executionContext.Mutation,
+            exception,
+            executionContext.ExecutionId,
+            duration).ConfigureAwait(false);
+
+        return new MutationException(
+            $"Mutation execution failed: {exception.Message}",
+            exception)
+        {
+            ExecutionId = executionContext.ExecutionId
+        };
+    }
+
+    private async Task NotifyFailureAsync<TState>(
+        MutationExecutionContext<TState> executionContext,
+        Exception exception,
+        CancellationToken cancellationToken)
+    {
+        await _interceptorPipeline.OnMutationFailedAsync(
+            executionContext.Mutation.Intent,
+            executionContext.Mutation.Context,
+            executionContext.State!,
+            exception,
+            executionContext.ExecutionId,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    private async Task AuditExceptionAsync<TState>(
+        IMutation<TState> mutation,
+        Exception exception,
+        string executionId,
+        TimeSpan duration)
+    {
+        var entry = MutationAuditEntryFactory.CreateException(
+            mutation,
+            exception,
+            executionId,
+            duration);
+
+        await _auditor.AuditAsync(entry).ConfigureAwait(false);
+    }
+}

src/Runtime/Internal/Execution/MutationExecutionModeRunner.cs

@@ -0,0 +1,55 @@
+using ModularityKit.Mutator.Abstractions;
+using ModularityKit.Mutator.Abstractions.Changes;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Results;
+using ModularityExecutionContext = ModularityKit.Mutator.Abstractions.Context.ExecutionContext;
+
+namespace ModularityKit.Mutator.Runtime.Internal.Execution;
+
+/// <summary>
+/// Executes mutation behavior according to the current mutation mode.
+/// </summary>
+internal sealed class MutationExecutionModeRunner(
+    IMutationExecutor executor,
+    MutationEngineOptions options)
+{
+    private readonly IMutationExecutor _executor = executor ?? throw new ArgumentNullException(nameof(executor));
+    private readonly MutationEngineOptions _options = options ?? throw new ArgumentNullException(nameof(options));
+
+    /// <summary>
+    /// Runs the mutation using simulate, validate, or commit execution semantics.
+    /// </summary>
+    public Task<MutationResult<TState>> ExecuteAsync<TState>(MutationExecutionContext<TState> executionContext)
+    {
+        var executorContext = new ModularityExecutionContext
+        {
+            ExecutionId = executionContext.ExecutionId,
+            Timeout = _options.ExecutionTimeout,
+            CancellationToken = executionContext.CancellationToken
+        };
+
+        return executionContext.Mutation.Context.Mode switch
+        {
+            MutationMode.Simulate => Task.FromResult(executionContext.Mutation.Simulate(executionContext.State)),
+            MutationMode.Validate => Task.FromResult(BuildValidationOnlyResult(
+                executionContext.Mutation,
+                executionContext.State)),
+            _ => _executor.ExecuteAsync(
+                executionContext.Mutation,
+                executionContext.State,
+                executorContext,
+                executionContext.CancellationToken)
+        };
+    }
+
+    private static MutationResult<TState> BuildValidationOnlyResult<TState>(
+        IMutation<TState> mutation,
+        TState state)
+    {
+        var validation = mutation.Validate(state);
+        return validation.IsValid
+            ? MutationResult<TState>.Success(state, ChangeSet.Empty)
+            : MutationResult<TState>.Failure(validation);
+    }
+}