Feat: Add PolicyComposition solution and test policies

Author: rian-be

Docs/Roadmap.md

@@ -201,7 +201,7 @@ Why this matters:
 
 ### 2. Governance-Aware Policy Composition
 
-Add composition primitives for complex policy sets.
+Composition primitives for complex policy sets are now available in the core policy abstractions.
 
 Scope:
 

ModularityKit.Mutator.slnx

@@ -8,6 +8,7 @@
     <Project Path="Examples/Core/BillingQuotas/BillingQuotas.csproj" />
     <Project Path="Examples/Core/FeatureFlags/FeatureFlags.csproj" />
     <Project Path="Examples/Core/IamRoles/IamRoles.csproj" />
+    <Project Path="Examples/Core/PolicyComposition/PolicyComposition.csproj" />
     <Project Path="Examples/Core/WorkflowApprovals/WorkflowApprovals.csproj" />
     <Project Path="Examples/Governance/ApprovalWorkflow/ApprovalWorkflow.csproj" />
     <Project Path="Examples/Governance/GovernedExecution/GovernedExecution.csproj" />

Tests/ModularityKit.Mutator.Tests/Runtime/Policies/PolicyCompositionTests.cs

@@ -0,0 +1,131 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Exceptions;
+using ModularityKit.Mutator.Abstractions.Policies;
+using ModularityKit.Mutator.Tests.TestSupport.Engine.Samples;
+using ModularityKit.Mutator.Tests.TestSupport.Mutations;
+using ModularityKit.Mutator.Tests.TestSupport.Policies.Composition;
+using Xunit;
+
+namespace ModularityKit.Mutator.Tests.Runtime.Policies;
+
+public sealed class PolicyCompositionTests
+{
+    [Fact]
+    public async Task AllOf_merges_modifications_side_effects_and_metadata()
+    {
+        var composed = PolicyComposition.AllOf(
+            "FeatureFlagGovernance",
+            [
+                new StateAndSideEffectPolicy(),
+                new SideEffectsAndMetadataPolicy()
+            ],
+            priority: 500,
+            description: "Composed governance rules for feature flag changes.");
+
+        var decision = await composed.EvaluateAsync(new PolicySampleMutation(), new PolicySampleState("initial"));
+
+        Assert.True(decision.IsAllowed);
+        Assert.Equal("governed", GetState(decision).Value);
+        Assert.Equal(2, GetSideEffects(decision).Count());
+        Assert.Equal("FeatureFlagGovernance", decision.PolicyName);
+        Assert.Equal("AllOf", decision.Metadata!["PolicyComposition.Mode"]);
+        Assert.Equal("state-policy", decision.Metadata!["owner"]);
+        Assert.Equal("state-policy", decision.Metadata!["source"]);
+    }
+
+    [Fact]
+    public async Task AllOf_merges_requirements_and_metadata()
+    {
+        var composed = PolicyComposition.AllOf(
+            "ApprovalGate",
+            [
+                new ApprovalPolicy(),
+                new MetadataPolicy()
+            ],
+            priority: 100);
+
+        var decision = await composed.EvaluateAsync(
+            new PolicySampleMutation(),
+            new PolicySampleState("initial")
+        );
+
+        Assert.False(decision.IsAllowed);
+        Assert.Single(decision.Requirements!);
+        Assert.Equal("Approval", decision.Requirements![0].Type);
+        Assert.Equal(PolicyDecisionSeverity.Error, decision.Severity);
+        Assert.Equal("ApprovalGate", decision.PolicyName);
+        Assert.Equal("AllOf", decision.Metadata!["PolicyComposition.Mode"]);
+        Assert.Equal("compliance", decision.Metadata!["team"]);
+        Assert.Equal("platform", decision.Metadata!["owner"]);
+        Assert.Equal(["ApprovalPolicy", "MetadataPolicy"], (string[])decision.Metadata["PolicyComposition.BlockingPolicies"]);
+    }
+
+    [Fact]
+    public async Task AnyOf_uses_only_allowed_branches_when_one_branch_succeeds()
+    {
+        var composed = PolicyComposition.AnyOf(
+            "AlternativeAllow",
+            [
+                new BlockingPolicy(),
+                new AllowedStatePolicy()
+            ],
+            priority: 100);
+
+        var decision = await composed.EvaluateAsync(new PolicySampleMutation(), new PolicySampleState("initial"));
+
+        Assert.True(decision.IsAllowed);
+        Assert.NotNull(decision.Modifications);
+        Assert.Equal("AlternativeAllow", decision.PolicyName);
+        Assert.Equal("AnyOf", decision.Metadata!["PolicyComposition.Mode"]);
+        Assert.Equal(["AllowedStatePolicy"], (string[])decision.Metadata["PolicyComposition.WinningPolicies"]);
+        Assert.Equal(["BlockingPolicy"], (string[])decision.Metadata["PolicyComposition.BlockingPolicies"]);
+        Assert.Equal("allowed", GetState(decision).Value);
+    }
+
+    [Fact]
+    public async Task Priority_composition_returns_first_decisive_higher_priority_policy()
+    {
+        var composed = PolicyComposition.Priority(
+            "PriorityGate",
+            [
+                new LowPriorityStatePolicy(),
+                new HighPriorityStatePolicy()
+            ],
+            priority: 100);
+
+        var decision = await composed.EvaluateAsync(new PolicySampleMutation(), new PolicySampleState("initial"));
+
+        Assert.True(decision.IsAllowed);
+        Assert.Equal("PriorityGate", decision.PolicyName);
+        Assert.Equal("high", GetState(decision).Value);
+        Assert.Single(GetSideEffects(decision));
+        Assert.Equal("high", decision.Metadata!["selectedPolicy"]);
+    }
+
+    [Fact]
+    public async Task AllOf_detects_conflicting_mutation_result_modifications()
+    {
+        var composed = PolicyComposition.AllOf(
+            "ConflictingGate",
+            [
+                new StatePolicy("First", "one"),
+                new StatePolicy("Second", "two")
+            ],
+            priority: 100);
+
+        var exception = await Assert.ThrowsAsync<PolicyCompositionConflictException>(() =>
+            composed.EvaluateAsync(new PolicySampleMutation(), new PolicySampleState("initial")));
+
+        Assert.Equal("ConflictingGate", exception.CompositionName);
+        Assert.Equal("State", exception.ConflictKey);
+        Assert.Equal(["First", "Second"], exception.PolicyNames);
+    }
+
+    private static PolicySampleState GetState(PolicyDecision decision)
+        => (PolicySampleState)decision.Modifications!["State"];
+
+    private static IEnumerable<SideEffect> GetSideEffects(PolicyDecision decision)
+        => (IEnumerable<SideEffect>)decision.Modifications!["SideEffects"];
+
+}

Tests/ModularityKit.Mutator.Tests/TestSupport/Policies/Composition/AllowedStatePolicy.cs

@@ -0,0 +1,47 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using ModularityKit.Mutator.Tests.TestSupport.Engine.Samples;
+
+namespace ModularityKit.Mutator.Tests.TestSupport.Policies.Composition;
+
+/// <summary>
+/// Test policy that allows the mutation and replaces the sample state value.
+/// </summary>
+/// <remarks>
+/// Used by policy composition tests to verify that state modifications from
+/// allowed policies are propagated correctly through composed decisions.
+/// </remarks>
+internal sealed class AllowedStatePolicy : IMutationPolicy<PolicySampleState>
+{
+    /// <summary>
+    /// Gets the policy name.
+    /// </summary>
+    public string Name => "AllowedStatePolicy";
+
+    /// <summary>
+    /// Gets the evaluation priority.
+    /// </summary>
+    public int Priority => 100;
+
+    /// <summary>
+    /// Gets the policy description.
+    /// </summary>
+    public string Description => "Applies the allowed branch.";
+
+    /// <summary>
+    /// Produces an allowed decision containing a modified sample state.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current sample state.</param>
+    /// <returns>An allowed decision with replacement state modification.</returns>
+    public PolicyDecision Evaluate(IMutation<PolicySampleState> mutation, PolicySampleState state)
+        => new()
+        {
+            IsAllowed = true,
+            PolicyName = Name,
+            Modifications = new Dictionary<string, object>
+            {
+                ["State"] = new PolicySampleState(Value: "allowed")
+            }
+        };
+}

Tests/ModularityKit.Mutator.Tests/TestSupport/Policies/Composition/ApprovalPolicy.cs

@@ -0,0 +1,46 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using ModularityKit.Mutator.Tests.TestSupport.Engine.Samples;
+
+namespace ModularityKit.Mutator.Tests.TestSupport.Policies.Composition;
+
+/// <summary>
+/// Test policy that blocks execution and requires explicit approval.
+/// </summary>
+/// <remarks>
+/// Used by policy composition tests to verify approval requirements,
+/// blocking decisions, and requirement aggregation.
+/// </remarks>
+internal sealed class ApprovalPolicy : IMutationPolicy<PolicySampleState>
+{
+    /// <summary>
+    /// Gets the policy name.
+    /// </summary>
+    public string Name => "ApprovalPolicy";
+
+    /// <summary>
+    /// Gets the evaluation priority.
+    /// </summary>
+    public int Priority => 200;
+
+    /// <summary>
+    /// Gets the policy description.
+    /// </summary>
+    public string Description => "Requires signoff for sensitive work.";
+
+    /// <summary>
+    /// Produces a blocking decision that requires explicit approval.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current sample state.</param>
+    /// <returns>A blocking decision with an approval requirement.</returns>
+    public PolicyDecision Evaluate(IMutation<PolicySampleState> mutation, PolicySampleState state)
+        => new()
+        {
+            IsAllowed = false,
+            PolicyName = Name,
+            Severity = PolicyDecisionSeverity.Error,
+            Reason = "Sensitive change requires approval.",
+            Requirements = [PolicyRequirement.Approval("approver-a", "Sensitive change requires approval.")]
+        };
+}

Tests/ModularityKit.Mutator.Tests/TestSupport/Policies/Composition/BlockingPolicy.cs

@@ -0,0 +1,39 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using ModularityKit.Mutator.Tests.TestSupport.Engine.Samples;
+
+namespace ModularityKit.Mutator.Tests.TestSupport.Policies.Composition;
+
+/// <summary>
+/// Test policy that unconditionally blocks mutation execution.
+/// </summary>
+/// <remarks>
+/// Used by policy composition tests to verify blocking behavior,
+/// precedence rules, and denial propagation.
+/// </remarks>
+internal sealed class BlockingPolicy : IMutationPolicy<PolicySampleState>
+{
+    /// <summary>
+    /// Gets the policy name.
+    /// </summary>
+    public string Name => "BlockingPolicy";
+
+    /// <summary>
+    /// Gets the evaluation priority.
+    /// </summary>
+    public int Priority => 400;
+
+    /// <summary>
+    /// Gets the policy description.
+    /// </summary>
+    public string Description => "Rejects the mutation.";
+
+    /// <summary>
+    /// Produces a blocking policy decision.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current sample state.</param>
+    /// <returns>A denial decision.</returns>
+    public PolicyDecision Evaluate(IMutation<PolicySampleState> mutation, PolicySampleState state)
+        => PolicyDecision.Deny("Blocked by policy.", Name);
+}

Tests/ModularityKit.Mutator.Tests/TestSupport/Policies/Composition/HighPriorityStatePolicy.cs

@@ -0,0 +1,54 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using ModularityKit.Mutator.Tests.TestSupport.Engine.Samples;
+
+namespace ModularityKit.Mutator.Tests.TestSupport.Policies.Composition;
+
+/// <summary>
+/// Test policy that contributes high priority state modification.
+/// </summary>
+/// <remarks>
+/// Used by policy composition tests to verify priority selection,
+/// metadata propagation, and side effect aggregation.
+/// </remarks>
+internal sealed class HighPriorityStatePolicy : IMutationPolicy<PolicySampleState>
+{
+    /// <summary>
+    /// Gets the policy name.
+    /// </summary>
+    public string Name => "HighPriorityStatePolicy";
+
+    /// <summary>
+    /// Gets the evaluation priority.
+    /// </summary>
+    public int Priority => 500;
+
+    /// <summary>
+    /// Gets the policy description.
+    /// </summary>
+    public string Description => "Higher priority branch.";
+
+    /// <summary>
+    /// Produces an allowed decision with a high-priority state modification,
+    /// metadata, and an audit side effect.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current sample state.</param>
+    /// <returns>An allowed decision with state, metadata, and side effects.</returns>
+    public PolicyDecision Evaluate(IMutation<PolicySampleState> mutation, PolicySampleState state)
+        => new()
+        {
+            IsAllowed = true,
+            PolicyName = Name,
+            Modifications = new Dictionary<string, object>
+            {
+                ["State"] = new PolicySampleState(Value: "high"),
+                ["SideEffect"] = SideEffect.Create("audit", "High priority branch selected.")
+            },
+            Metadata = new Dictionary<string, object>
+            {
+                ["selectedPolicy"] = "high"
+            }
+        };
+}

Tests/ModularityKit.Mutator.Tests/TestSupport/Policies/Composition/LowPriorityStatePolicy.cs

@@ -0,0 +1,51 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using ModularityKit.Mutator.Tests.TestSupport.Engine.Samples;
+
+namespace ModularityKit.Mutator.Tests.TestSupport.Policies.Composition;
+
+/// <summary>
+/// Test policy that contributes low priority state modification.
+/// </summary>
+/// <remarks>
+/// Used by policy composition tests to verify deterministic priority ordering
+/// and metadata conflict handling.
+/// </remarks>
+internal sealed class LowPriorityStatePolicy : IMutationPolicy<PolicySampleState>
+{
+    /// <summary>
+    /// Gets the policy name.
+    /// </summary>
+    public string Name => "LowPriorityStatePolicy";
+
+    /// <summary>
+    /// Gets the evaluation priority.
+    /// </summary>
+    public int Priority => 100;
+
+    /// <summary>
+    /// Gets the policy description.
+    /// </summary>
+    public string Description => "Lower priority branch.";
+
+    /// <summary>
+    /// Produces an allowed decision with a low-priority state modification.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current sample state.</param>
+    /// <returns>An allowed decision with state and metadata.</returns>
+    public PolicyDecision Evaluate(IMutation<PolicySampleState> mutation, PolicySampleState state)
+        => new()
+        {
+            IsAllowed = true,
+            PolicyName = Name,
+            Modifications = new Dictionary<string, object>
+            {
+                ["State"] = new PolicySampleState(Value: "low")
+            },
+            Metadata = new Dictionary<string, object>
+            {
+                ["selectedPolicy"] = Name
+            }
+        };
+}