Feat: Add async policy evaluation, typed side effects, and runtime namespace refactor (#43)

## Summary
Add async policy evaluation support with external governance checks,
introduce typed side effect contracts, and refactor the runtime
execution namespace structure for better cohesion.

## Added
- `IMutationPolicy<TState>.EvaluateAsync` contract with default
sync-to-async bridge for backwards compatibility
- `PolicyEvaluationTimeoutException` for explicit timeout failure
semantics during async policy evaluation
- `SideEffect<TData>` typed side effect contract with explicit payload
typing beyond `object?`
- Runtime test coverage for typed side effect payloads and Redis
serialization roundtrips
- `Runtime.Diagnostics` namespace containing `MutationAuditEntryFactory`
and `StateSizeEstimator`
- `Runtime.Internal.Execution` subfolder grouping pipeline
orchestration, concurrency, mode running, batch, and failure handling
- `Runtime.Internal.Evaluation` subfolder grouping policy evaluation and
policy modification application

## Changed
- `MutationPolicyEvaluator` now invokes `EvaluateAsync` with a linked
`CancellationTokenSource` respecting `PolicyEvaluationTimeout` from
engine options
- Sync and async policy paths coexist without ambiguous semantics —
async path is the primary evaluation contract
- `MutationEngine` wired to `Runtime.Diagnostics` namespace and
decomposed execution pipeline
- Governance persistence, query, and Redis flows handle typed side
effect payloads predictably through explicit `SideEffect<TData>`
contracts
- All `/// <inheritdoc />` usages in `MutationEngine` replaced with
explicit XML documentation matching `IMutationEngine` interface
- XML documentation added to all runtime components:
`MutationBatchExecutor`, `PolicyModificationApplier`,
`MutationAuditEntryFactory`, `StateSizeEstimator`

## Result
The runtime execution model is now organized by concern. Policy
evaluation is fully async with explicit timeout and cancellation
behavior. Side effect contracts are typed and survive persistence and
downstream integration scenarios. The execution namespace structure
matches the folder layout, aligning with `Runtime.Audit`,
`Runtime.Metrics`, and `Runtime.Policies` conventions.

## Testing
- dotnet build
- dotnet test
Tests/ModularityKit.Mutator.Tests/ModularityKit.Mutator.Tests.csproj
- dotnet test
Tests/ModularityKit.Mutator.Governance.Tests/ModularityKit.Mutator.Governance.Tests.csproj
- dotnet test
Tests/ModularityKit.Mutator.Governance.Redis.Tests/ModularityKit.Mutator.Governance.Redis.Tests.csproj

## Linked Issues
- Closes #23
- Closes #24

## Checklist
- [x] async policy evaluation path is implemented and tested
- [x] sync and async policy paths coexist without ambiguous semantics
- [x] typed side effect contract is introduced and integrated with
governance persistence
- [x] runtime namespace structure aligns with folder layout and existing
conventions
- [x] XML documentation added to all affected runtime components

Author: rian-be

Examples/Core/WorkflowApprovals/Contracts/WorkflowRejectedSideEffectData.cs

@@ -0,0 +1,13 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+
+namespace WorkflowApprovals.Contracts;
+
+[SideEffectDataContract("workflow.rejected", 1)]
+internal sealed record WorkflowRejectedSideEffectData
+{
+    public required string Rejector { get; init; }
+
+    public required int StepCount { get; init; }
+
+    public required string State { get; init; }
+}

Examples/Core/WorkflowApprovals/Contracts/WorkflowStartedSideEffectData.cs

@@ -0,0 +1,13 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+
+namespace WorkflowApprovals.Contracts;
+
+[SideEffectDataContract("workflow.started", 1)]
+internal sealed record WorkflowStartedSideEffectData
+{
+    public required string Initiator { get; init; }
+
+    public required int StepCount { get; init; }
+
+    public required string WorkflowId { get; init; }
+}

Examples/Core/WorkflowApprovals/Mutations/RejectWorkflowMutation.cs

@@ -4,6 +4,7 @@
 using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Results;
+using WorkflowApprovals.Contracts;
 using WorkflowApprovals.State;
 
 namespace WorkflowApprovals.Mutations;
@@ -48,9 +49,9 @@ public override MutationResult<ApprovalWorkflowState> Apply(ApprovalWorkflowStat
                 SideEffect.Critical(
                     type: "WorkflowRejected",
                     description: "Workflow rejection requires manual follow-up",
-                    data: new
+                    data: new WorkflowRejectedSideEffectData
                     {
-                        Rejector,
+                        Rejector = Rejector,
                         StepCount = steps.Count,
                         State = "Rejected"
                     })

Examples/Core/WorkflowApprovals/Mutations/StartApprovalMutation.cs

@@ -4,6 +4,7 @@
 using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Results;
+using WorkflowApprovals.Contracts;
 using WorkflowApprovals.State;
 
 namespace WorkflowApprovals.Mutations;
@@ -54,9 +55,9 @@ public override MutationResult<ApprovalWorkflowState> Apply(ApprovalWorkflowStat
                 SideEffect.Create(
                     type: "WorkflowStarted",
                     description: "Approval workflow started and ready for first review",
-                    data: new
+                    data: new WorkflowStartedSideEffectData
                     {
-                        Initiator,
+                        Initiator = Initiator,
                         StepCount = steps.Count,
                         WorkflowId = newState.WorkflowId
                     })

Examples/Core/WorkflowApprovals/README.md

@@ -67,7 +67,7 @@ The sample is intentionally sequential. It shows how stateful process can be adv
 - creates workflow steps from names
 - initializes a new workflow ID
 - emits change entry for the created step list
-- emits a `WorkflowStarted` side effect through `SideEffect.Create(...)`
+- emits a `WorkflowStarted` side effect through `SideEffect.Create(...)` with a typed contract payload
 
 ### Approve step
 
@@ -85,7 +85,7 @@ The sample is intentionally sequential. It shows how stateful process can be adv
 - applies rejection to every step
 - records the actor who rejected the workflow
 - emits workflow level change
-- emits a critical `WorkflowRejected` side effect through `SideEffect.Critical(...)`
+- emits a critical `WorkflowRejected` side effect through `SideEffect.Critical(...)` with a typed contract payload
 
 ## Policies
 
@@ -135,7 +135,8 @@ It shows:
 
 - a standard side effect created with `SideEffect.Create(...)`
 - a critical side effect created with `SideEffect.Critical(...)`
-- how `Severity`, `RequiresAction`, and `Data` can be read from `MutationResult.SideEffects`
+- how typed payload contracts are registered through `SideEffectDataContractRegistry`
+- how `Severity`, `RequiresAction`, `DataContractType`, and typed `Data` can be read from `MutationResult.SideEffects`
 
 ## What to read first
 

Examples/Core/WorkflowApprovals/Scenarios/SideEffectsScenario.cs

@@ -1,6 +1,8 @@
 using ModularityKit.Mutator.Abstractions.Context;
 using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Engine;
+using System.Text.Json;
+using WorkflowApprovals.Contracts;
 using WorkflowApprovals.Mutations;
 using WorkflowApprovals.State;
 
@@ -12,6 +14,9 @@ internal static async Task Run(IMutationEngine engine)
     {
         Console.WriteLine("\n=== Side Effects Scenario ===");
 
+        SideEffectDataContractRegistry.Register<WorkflowStartedSideEffectData>();
+        SideEffectDataContractRegistry.Register<WorkflowRejectedSideEffectData>();
+
         var state = new ApprovalWorkflowState();
 
         var startContext = MutationContext.System("Start side effect demo", correlationId: "workflow-side-effects");
@@ -51,9 +56,25 @@ private static void PrintSideEffects(string operation, IReadOnlyList<SideEffect>
                 $"  {effect.Type} | severity={effect.Severity} | requiresAction={effect.RequiresAction}");
             Console.WriteLine($"    {effect.Description}");
 
-            if (effect.Data is not null)
+            var roundtrip = JsonSerializer.Deserialize<SideEffect>(JsonSerializer.Serialize(effect));
+
+            if (roundtrip?.TryGetData<WorkflowStartedSideEffectData>(out var started) == true)
+            {
+                Console.WriteLine(
+                    $"    contract={roundtrip.DataContractType}@v{roundtrip.DataContractVersion} | initiator={started!.Initiator} | workflowId={started.WorkflowId}");
+                continue;
+            }
+
+            if (roundtrip?.TryGetData<WorkflowRejectedSideEffectData>(out var rejected) == true)
+            {
+                Console.WriteLine(
+                    $"    contract={roundtrip.DataContractType}@v{roundtrip.DataContractVersion} | rejector={rejected!.Rejector} | state={rejected.State}");
+                continue;
+            }
+
+            if (roundtrip?.Data is not null)
             {
-                Console.WriteLine($"    data={effect.Data}");
+                Console.WriteLine($"    data={roundtrip.Data}");
             }
         }
     }

Examples/Governance/Queries/Scenarios/GovernanceQueriesSampleData.cs

@@ -1,4 +1,5 @@
 using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Policies;
 using ModularityKit.Mutator.Governance.Abstractions.Approval.Model;
@@ -351,6 +352,16 @@ private static MutationRequest CreateExecutedRequest(
             CreatedAt = executedAt.AddMinutes(-15),
             UpdatedAt = executedAt,
             ExecutedAt = executedAt,
+            SideEffects =
+            [
+                SideEffect.Critical(
+                    type: "QuotaChangeRequiresReview",
+                    description: "Executed quota change requires review",
+                    data: new GovernanceExecutionSideEffectData
+                    {
+                        Ticket = "BILL-22"
+                    })
+            ],
             Metadata = new Dictionary<string, object>
             {
                 ["ticket"] = "BILL-22"
@@ -380,4 +391,10 @@ private static MutationRequest CreateExecutedRequest(
                 }
             ]
         };
+
+    [SideEffectDataContract("examples.governance.execution-side-effect", 1)]
+    private sealed record GovernanceExecutionSideEffectData
+    {
+        public required string Ticket { get; init; }
+    }
 }

Examples/Governance/Queries/Scenarios/RequestQueryScenario.cs

@@ -55,6 +55,16 @@ public static async Task Run(IMutationRequestQueryStore queryStore)
             }
         }));
 
+        GovernanceQueriesSampleData.PrintSection("Requests With Actionable Execution Side Effects");
+        GovernanceQueriesSampleData.PrintRequests(await queryStore.QueryAsync(new MutationRequestQuery
+        {
+            SideEffects = new MutationRequestSideEffectFilter
+            {
+                DataContractTypes = new HashSet<string> { "examples.governance.execution-side-effect" },
+                RequiresAction = true
+            }
+        }));
+
         GovernanceQueriesSampleData.PrintSection("Recent Approval Driven Requests");
         GovernanceQueriesSampleData.PrintRequests(await queryStore.GetRecentApprovalsAsync(take: 3));
     }

Examples/Governance/RedisQueries/Scenarios/GovernanceRedisQueriesScenario.cs

@@ -1,12 +1,14 @@
 using Microsoft.Extensions.DependencyInjection;
 using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Policies;
 using ModularityKit.Mutator.Governance.Abstractions.Lifecycle.Model;
 using ModularityKit.Mutator.Governance.Abstractions.Queries.Contracts;
 using ModularityKit.Mutator.Governance.Abstractions.Queries.Model.Approvals;
 using ModularityKit.Mutator.Governance.Abstractions.Queries.Model.Decisions;
 using ModularityKit.Mutator.Governance.Abstractions.Queries.Model.Requests;
+using ModularityKit.Mutator.Governance.Abstractions.Queries.Model.Requests.Filters;
 using ModularityKit.Mutator.Governance.Abstractions.Requests.Decisions;
 using ModularityKit.Mutator.Governance.Abstractions.Requests.Factory;
 using ModularityKit.Mutator.Governance.Abstractions.Requests.Model;
@@ -50,6 +52,16 @@ public static async Task Run()
                 ApproverIds = new HashSet<string> { "security-lead" }
             }));
 
+            PrintSection("Requests With Actionable Side Effects");
+            PrintRequests(await queryStore.QueryAsync(new MutationRequestQuery
+            {
+                SideEffects = new MutationRequestSideEffectFilter
+                {
+                    DataContractTypes = new HashSet<string> { "examples.redis.execution-side-effect" },
+                    RequiresAction = true
+                }
+            }));
+
             PrintSection("Recent Execution Outcomes");
             PrintDecisions(await queryStore.GetRecentDecisionsAsync(
                 MutationRequestDecisionQuery.RecentExecutionOutcomes(),
@@ -152,6 +164,16 @@ private static MutationRequest CreateExecutedRequest(
             CreatedAt = executedAt.AddMinutes(-15),
             UpdatedAt = executedAt,
             ExecutedAt = executedAt,
+            SideEffects =
+            [
+                SideEffect.Critical(
+                    type: "ExecutedRequestRequiresFollowUp",
+                    description: "Executed request still requires manual follow-up",
+                    data: new RedisExecutionSideEffectData
+                    {
+                        Ticket = "BILL-12"
+                    })
+            ],
             Decisions =
             [
                 MutationRequestDecision.Lifecycle(
@@ -178,6 +200,12 @@ private static MutationRequest CreateExecutedRequest(
             ]
         };
 
+    [SideEffectDataContract("examples.redis.execution-side-effect", 1)]
+    private sealed record RedisExecutionSideEffectData
+    {
+        public required string Ticket { get; init; }
+    }
+
     private static void PrintSection(string title)
     {
         Console.WriteLine();

Tests/ModularityKit.Mutator.Governance.Redis.Tests/Serialization/Converters/RedisMutationRequestSerializerTests.cs

@@ -1,4 +1,5 @@
 using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Policies;
 using ModularityKit.Mutator.Governance.Abstractions.Lifecycle.Model;
@@ -61,7 +62,17 @@ public void Roundtrip_preserves_request_shape_needed_by_governance_runtime()
         with
         {
             CreatedAt = new DateTimeOffset(2026, 6, 25, 9, 0, 0, TimeSpan.Zero),
-            UpdatedAt = new DateTimeOffset(2026, 6, 25, 9, 5, 0, TimeSpan.Zero)
+            UpdatedAt = new DateTimeOffset(2026, 6, 25, 9, 5, 0, TimeSpan.Zero),
+            SideEffects =
+            [
+                SideEffect.Critical(
+                    type: "WorkflowRejected",
+                    description: "Workflow rejection requires action",
+                    data: new RedisGovernanceSideEffectData
+                    {
+                        Ticket = "INC-42"
+                    })
+            ]
         };
 
         var json = RedisMutationRequestSerializer.Serialize(request);
@@ -75,9 +86,20 @@ public void Roundtrip_preserves_request_shape_needed_by_governance_runtime()
         Assert.Equal(BlastRadiusScope.Module, roundtrip.Intent.EstimatedBlastRadius?.Scope);
         Assert.Equal("platform", roundtrip.Intent.Metadata["risk-owner"]);
         Assert.Equal("security", roundtrip.Metadata["team"]);
+        Assert.Single(roundtrip.SideEffects);
+        Assert.Equal("WorkflowRejected", roundtrip.SideEffects[0].Type);
+        Assert.Equal("redis.governance.side-effect", roundtrip.SideEffects[0].DataContractType);
+        Assert.True(roundtrip.SideEffects[0].TryGetData<RedisGovernanceSideEffectData>(out var sideEffectData));
+        Assert.Equal("INC-42", sideEffectData!.Ticket);
         Assert.Single(roundtrip.Requirements);
         Assert.Single(roundtrip.ApprovalRequirements);
         Assert.Equal("security-lead", roundtrip.ApprovalRequirements[0].ApproverId);
         Assert.Equal(3, roundtrip.Decisions.Count);
     }
+
+    [SideEffectDataContract("redis.governance.side-effect", 1)]
+    private sealed record RedisGovernanceSideEffectData
+    {
+        public required string Ticket { get; init; }
+    }
 }