feat(examples/polygon): add workflow approvals showcase

- Added WorkflowApprovals example to Polygon solution
- Demonstrates approval workflow modeling using Mutators:
  - Immutable workflow state with steps and initiator
  - High and critical risk mutations (start, approve, reject)
- Showcases policy-driven governance:
  - Sequential step enforcement
  - Manager-only approval constraints
- Includes end-to-end execution scenarios:
  - Happy path with ordered approvals
  - Rejection scenarios with policy diagnostics
- Highlights core Mutators capabilities:
  - System vs user mutation contexts
  - Policy evaluation and decision reporting
  - Deterministic state evolution
  - Metrics and execution statistics output
- Positions Polygon as a real-world governance showcase:
  - Workflow approvals
  - Quotas
  - IAM-style decision flows

Author: rian-be

ModularityKit.Mutator.sln.DotSettings

@@ -0,0 +1,2 @@
+<wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Rejector/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>

ModularityKit.Mutator.slnx

@@ -3,6 +3,7 @@
     <Project Path="Polygon/BillingQuotas/BillingQuotas.csproj" />
     <Project Path="Polygon/FeatureFlags/FeatureFlags.csproj" />
     <Project Path="Polygon/IamRoles/IamRoles.csproj" />
+    <Project Path="Polygon/WorkflowApprovals/WorkflowApprovals.csproj" />
   </Folder>
   <Project Path="ModularityKit.Mutator/ModularityKit.Mutator.csproj" />
 </Solution>

Polygon/WorkflowApprovals/Mutations/ApproveStepMutation.cs

@@ -0,0 +1,58 @@
+using ModularityKit.Mutator.Abstractions.Changes;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Intent;
+using ModularityKit.Mutator.Abstractions.Results;
+using WorkflowApprovals.State;
+
+namespace WorkflowApprovals.Mutations;
+
+/// <summary>
+/// Mutation that approves specific step in an <see cref="ApprovalWorkflowState"/>.
+/// </summary>
+internal sealed record ApproveStepMutation(
+    int StepIndex,
+    string Approver,
+    MutationContext Context
+) : IMutation<ApprovalWorkflowState>
+{
+    public MutationIntent Intent { get; } = new()
+    {
+        OperationName = "ApproveStep",
+        Category = "Workflow",
+        RiskLevel = MutationRiskLevel.High,
+        Description = "Approve a workflow step"
+    };
+
+    public ValidationResult Validate(ApprovalWorkflowState state)
+    {
+        var result = new ValidationResult();
+        if (StepIndex < 0 || StepIndex >= state.Steps.Count)
+            result.AddError("StepIndex", "Invalid step index");
+        if (string.IsNullOrEmpty(Approver))
+            result.AddError("Approver", "Approver cannot be empty");
+        return result;
+    }
+
+    public MutationResult<ApprovalWorkflowState> Apply(ApprovalWorkflowState state)
+    {
+        var steps = state.Steps.ToList();
+        var oldStep = steps[StepIndex];
+        var newStep = oldStep with
+        {
+            Status = StepStatus.Approved,
+            ApprovedBy = Approver
+        };
+        steps[StepIndex] = newStep;
+
+        var newState = state with { Steps = steps };
+
+        var changes = ChangeSet.Single(
+            StateChange.Modified($"Steps[{StepIndex}]", oldStep.Status, newStep.Status)
+        );
+
+        return MutationResult<ApprovalWorkflowState>.Success(newState, changes);
+    }
+
+    public MutationResult<ApprovalWorkflowState> Simulate(ApprovalWorkflowState state) => Apply(state);
+}

Polygon/WorkflowApprovals/Mutations/RejectWorkflowMutation.cs

@@ -0,0 +1,48 @@
+using ModularityKit.Mutator.Abstractions.Changes;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Intent;
+using ModularityKit.Mutator.Abstractions.Results;
+using WorkflowApprovals.State;
+
+namespace WorkflowApprovals.Mutations;
+
+/// <summary>
+/// Mutation that rejects the entire workflow in an <see cref="ApprovalWorkflowState"/>.
+/// </summary>
+internal sealed record RejectWorkflowMutation(
+    string Rejector,
+    MutationContext Context
+) : IMutation<ApprovalWorkflowState>
+{
+    public MutationIntent Intent { get; } = new()
+    {
+        OperationName = "RejectWorkflow",
+        Category = "Workflow",
+        RiskLevel = MutationRiskLevel.Critical,
+        Description = "Rejects the entire workflow"
+    };
+
+    public ValidationResult Validate(ApprovalWorkflowState state)
+    {
+        var result = new ValidationResult();
+        if (string.IsNullOrEmpty(Rejector))
+            result.AddError("Reject", "Reject cannot be empty");
+        return result;
+    }
+
+    public MutationResult<ApprovalWorkflowState> Apply(ApprovalWorkflowState state)
+    {
+        var steps = state.Steps.Select(s => s with
+        {
+            Status = StepStatus.Rejected,
+            RejectedBy = Rejector
+        }).ToList();
+
+        var newState = state with { Steps = steps };
+        var changes = ChangeSet.Single(StateChange.Modified("Workflow", null, "Rejected"));
+        return MutationResult<ApprovalWorkflowState>.Success(newState, changes);
+    }
+
+    public MutationResult<ApprovalWorkflowState> Simulate(ApprovalWorkflowState state) => Apply(state);
+}

Polygon/WorkflowApprovals/Mutations/StartApprovalMutation.cs

@@ -0,0 +1,52 @@
+using ModularityKit.Mutator.Abstractions.Changes;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Intent;
+using ModularityKit.Mutator.Abstractions.Results;
+using WorkflowApprovals.State;
+
+namespace WorkflowApprovals.Mutations;
+
+/// <summary>
+/// Mutation that starts new approval workflow in an <see cref="ApprovalWorkflowState"/>.
+/// </summary>
+internal sealed record StartApprovalMutation(
+    string Initiator,
+    string[] StepNames,
+    MutationContext Context
+) : IMutation<ApprovalWorkflowState>
+{
+    public MutationIntent Intent { get; } = new()
+    {
+        OperationName = "StartWorkflow",
+        Category = "Workflow",
+        RiskLevel = MutationRiskLevel.Medium,
+        Description = "Starts a new approval workflow"
+    };
+
+    public ValidationResult Validate(ApprovalWorkflowState state)
+    {
+        var result = new ValidationResult();
+        if (string.IsNullOrEmpty(Initiator))
+            result.AddError("Initiator", "Initiator cannot be empty");
+        if (StepNames.Length == 0)
+            result.AddError("Steps", "Workflow must have at least one step");
+        return result;
+    }
+
+    public MutationResult<ApprovalWorkflowState> Apply(ApprovalWorkflowState state)
+    {
+        var steps = StepNames.Select(name => new WorkflowStep(name)).ToList();
+        var newState = state with
+        {
+            WorkflowId = Guid.NewGuid().ToString(),
+            Steps = steps,
+            Initiator = Initiator
+        };
+
+        var changes = ChangeSet.Single(StateChange.Added("Steps", steps));
+        return MutationResult<ApprovalWorkflowState>.Success(newState, changes);
+    }
+
+    public MutationResult<ApprovalWorkflowState> Simulate(ApprovalWorkflowState state) => Apply(state);
+}

Polygon/WorkflowApprovals/Policies/EnforceOrderPolicy.cs

@@ -0,0 +1,43 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using WorkflowApprovals.Mutations;
+using WorkflowApprovals.State;
+
+namespace WorkflowApprovals.Policies;
+
+/// <summary>
+/// Policy that enforces sequential approval of workflow steps in an <see cref="ApprovalWorkflowState"/>.
+/// </summary>
+internal sealed class EnforceOrderPolicy : IMutationPolicy<ApprovalWorkflowState>
+{
+    public string Name => "EnforceOrderPolicy";
+    public int Priority => 100;
+    public string Description => "Ensures steps are approved in order.";
+    
+    /// <summary>
+    /// Evaluates mutation against the policy.
+    /// Step can only be approved if the previous step is already approved.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">Current workflow state.</param>
+    /// <returns>A <see cref="PolicyDecision"/> indicating whether the mutation is allowed or denied.</returns>
+    public PolicyDecision Evaluate(IMutation<ApprovalWorkflowState> mutation, ApprovalWorkflowState state)
+    {
+        if (mutation is not ApproveStepMutation { StepIndex: > 0 } stepMut) 
+            return PolicyDecision.Allow();
+        
+        if (stepMut.StepIndex - 1 >= state.Steps.Count)
+        {
+            return PolicyDecision.Deny(
+                $"Step index {stepMut.StepIndex} is out of range for the current workflow.");
+        }
+
+        var previous = state.Steps[stepMut.StepIndex - 1];
+        if (previous.Status != StepStatus.Approved)
+        {
+            return PolicyDecision.Deny(
+                $"Cannot approve step {stepMut.StepIndex} before previous step is approved");
+        }
+        return PolicyDecision.Allow();
+    }
+}

Polygon/WorkflowApprovals/Policies/RequireManagerApprovalPolicy.cs

@@ -0,0 +1,35 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using WorkflowApprovals.Mutations;
+using WorkflowApprovals.State;
+
+namespace WorkflowApprovals.Policies;
+
+/// <summary>
+/// Policy that requires workflow steps to be approved by designated manager in <see cref="ApprovalWorkflowState"/>.
+/// </summary>
+internal sealed class RequireManagerApprovalPolicy : IMutationPolicy<ApprovalWorkflowState>
+{
+    private readonly HashSet<string> _managers = ["alice", "bob"];
+
+    public string Name => "RequireManagerApproval";
+    public int Priority => 100;
+    public string Description => "Ensures only managers can approve workflow steps.";
+  
+    /// <summary>
+    /// Evaluates a mutation against the policy.
+    /// Only designated managers in <see cref="_managers"/> can approve steps.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">Current workflow state.</param>
+    /// <returns>A <see cref="PolicyDecision"/> indicating whether the mutation is allowed or denied.</returns>
+    public PolicyDecision Evaluate(IMutation<ApprovalWorkflowState> mutation, ApprovalWorkflowState state)
+    {
+        if (mutation is not ApproveStepMutation stepMut) return PolicyDecision.Allow();
+        if (!_managers.Contains(stepMut.Approver))
+        {
+            return PolicyDecision.Deny($"Approver '{stepMut.Approver}' is not manager");
+        }
+        return PolicyDecision.Allow();
+    }
+}

Polygon/WorkflowApprovals/Program.cs

@@ -0,0 +1,40 @@
+using Microsoft.Extensions.DependencyInjection;
+using ModularityKit.Mutator.Abstractions;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Runtime;
+using WorkflowApprovals.Policies;
+
+namespace WorkflowApprovals;
+
+internal static class Program
+{
+    private static async Task Main()
+    {
+        var services = new ServiceCollection();
+        services.AddMutators(MutationEngineOptions.Strict, addDefaultLoggingInterceptor: true);
+       
+        var provider = services.BuildServiceProvider();
+        var engine = provider.GetRequiredService<IMutationEngine>();
+        
+        engine.RegisterPolicy(new EnforceOrderPolicy());
+        engine.RegisterPolicy(new RequireManagerApprovalPolicy());
+        
+        Console.WriteLine("=== ModularityKit.Mutators - Complete Example ===\n");
+        
+        await Scenarios.HappyPathScenario.Run(engine);
+        await Scenarios.RejectedScenario.Run(engine);
+
+        
+        Console.WriteLine("\n METRICS & STATISTICS");
+
+        var stats = await engine.GetStatisticsAsync();
+
+        Console.WriteLine($"\n Mutation Statistics:");
+        Console.WriteLine($"  Total executed: {stats.TotalExecuted}");
+
+        Console.WriteLine($"\n Performance Metrics:");
+        Console.WriteLine($"  Average execution time: {stats.AverageExecutionTime.TotalMilliseconds:F2} ms");
+        Console.WriteLine($"  Median execution time: {stats.MedianExecutionTime.TotalMilliseconds:F2} ms");
+        Console.WriteLine($"  P95 execution time: {stats.P95ExecutionTime.TotalMilliseconds:F2} ms");
+    }
+}

Polygon/WorkflowApprovals/Scenarios/HappyPathScenario.cs

@@ -0,0 +1,75 @@
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using WorkflowApprovals.Mutations;
+using WorkflowApprovals.State;
+
+namespace WorkflowApprovals.Scenarios;
+
+/// <summary>
+/// HappyPathScenario
+/// 
+/// Demonstrates a "happy path" execution of an approval workflow using <see cref="IMutation{TState}"/> 
+/// and <see cref="StartApprovalMutation"/> where all steps are approved successfully.
+/// 
+/// Scenario Details:
+/// - Starts a new approval workflow using <see cref="ApproveStepMutation"/>.
+/// - Sequentially approves each step in the workflow using <see cref="MutationContext.System"/>.
+/// - Uses <see cref="MutationContext"/> to provide system metadata and correlation ID for audit purposes.
+/// - Logs success and failure for each mutation.
+/// - Works with <see cref="ApprovalWorkflowState"/> which tracks workflow steps and their approval status.
+/// 
+/// Key Steps:
+/// 1. Initialize <see cref="StartApprovalMutation"/> as empty workflow state.
+/// 2. Start workflow with multiple steps via <see cref="IMutationEngine"/>.
+/// 3. Sequentially approve each step using predefined approvers.
+/// 4. Update workflow state after each mutation.
+/// 5. Print final state of all steps, including approved or rejected information.
+/// 
+/// Example Use Case:
+/// - Simulating normal workflow progression for testing or documentation purposes.
+/// - Verifying that policies allow proper step approvals in sequence.
+/// - Demonstrating auditability and traceability with correlation IDs and system metadata.
+/// 
+/// Notes:
+/// - If a mutation is blocked due to a policy decision, the scenario logs the blocking reason.
+/// - This scenario assumes all mutations succeed under normal conditions.
+/// - Can be extended with rejection scenarios or conditional approvals for more complex workflows.
+/// </summary>
+internal static class HappyPathScenario
+{
+    internal static async Task Run(IMutationEngine engine)
+    {
+        Console.WriteLine("\n=== Happy Path Scenario ===");
+
+        var state = new ApprovalWorkflowState();
+
+        var ctx = MutationContext.System("Start workflow", correlationId: "workflow-123");
+
+        var start = new StartApprovalMutation("initiator", ["Step1", "Step2", "Step3"], ctx);
+        var result = await engine.ExecuteAsync(start, state);
+        state = result.NewState!;
+        
+        var approvers = new[] { "alice", "bob", "alice" };
+
+        for (var i = 0; i < state.Steps.Count; i++)
+        {
+            var approve = new ApproveStepMutation(i, approvers[i], ctx);
+            var res = await engine.ExecuteAsync(approve, state);
+            if (res.IsSuccess)
+                state = res.NewState!;
+            else
+            {
+                Console.WriteLine($"✗ Step {i} blocked:");
+                foreach (var dec in res.PolicyDecisions)
+                    Console.WriteLine($"  {dec.PolicyName} – {dec.Reason}");
+            }
+        }
+
+        Console.WriteLine("Workflow final state:");
+        for (var i = 0; i < state.Steps.Count; i++)
+        {
+            var s = state.Steps[i];
+            Console.WriteLine($"  Step{i}: {s.Status} by {(s.ApprovedBy ?? s.RejectedBy ?? "-")}");
+        }
+    }
+}