Feat: Extend PolicyComposition example with governance policies

Author: rian-be

Examples/Core/PolicyComposition/Policies/Emergency/ApprovalFallbackPolicy.cs

@@ -0,0 +1,63 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using PolicyComposition.State;
+
+namespace PolicyComposition.Policies.Emergency;
+
+/// <summary>
+/// Supplies the approval-based fallback branch for the emergency gate.
+/// </summary>
+/// <remarks>
+/// This policy is only intended to make the emergency composition reusable when
+/// the explicit override is unavailable. It checks the same approval count used by
+/// the standard approval policy, but it maps the successful outcome to a different
+/// release stage so the example can show branch selection in the merged decision.
+/// </remarks>
+internal sealed class ApprovalFallbackPolicy : IMutationPolicy<ReleaseGateState>
+{
+    /// <summary>
+    /// Policy identifier used in composed diagnostics.
+    /// </summary>
+    public string Name => "ApprovalFallback";
+
+    /// <summary>
+    /// Lower than the override branch but high enough to participate in emergency gating.
+    /// </summary>
+    public int Priority => 200;
+
+    /// <summary>
+    /// Describes the approval-based fallback path.
+    /// </summary>
+    public string Description => "Fallback branch that allows the release once approvals exist.";
+
+    /// <summary>
+    /// Uses the approval count to decide whether the emergency fallback can proceed.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current release state.</param>
+    /// <returns>
+    /// An allowed decision that advances the release through the fallback stage
+    /// or a blocking decision when approvals are missing.
+    /// </returns>
+    public PolicyDecision Evaluate(IMutation<ReleaseGateState> mutation, ReleaseGateState state)
+    {
+        var approvals = GetInt32(mutation.Context.Metadata, "approvals");
+
+        return approvals >= 2
+            ? new PolicyDecision
+            {
+                IsAllowed = true,
+                PolicyName = Name,
+                Modifications = new Dictionary<string, object>
+                {
+                    ["State"] = state with { Stage = "ApprovedViaFallback" },
+                    ["SideEffect"] = SideEffect.Create("audit", "Fallback approval branch selected.")
+                }
+            }
+            : PolicyDecision.Deny($"Fallback approval branch rejected the release; found {approvals} approvals.", Name);
+    }
+
+    private static int GetInt32(IReadOnlyDictionary<string, object> metadata, string key)
+        => metadata.TryGetValue(key, out var value) && value is int number ? number : 0;
+}

Examples/Core/PolicyComposition/Policies/Emergency/EmergencyOverridePolicy.cs

@@ -0,0 +1,67 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using PolicyComposition.State;
+
+namespace PolicyComposition.Policies.Emergency;
+
+/// <summary>
+/// Enables a hard emergency override when the request explicitly asks for it.
+/// </summary>
+/// <remarks>
+/// This policy demonstrates a decisive allow-or-deny branch inside an AnyOf
+/// composition. It reads the emergency flag from mutation metadata, and when the
+/// flag is present, it promotes the release to an emergency-approved stage and
+/// adds a critical side effect for audit visibility.
+/// </remarks>
+internal sealed class EmergencyOverridePolicy : IMutationPolicy<ReleaseGateState>
+{
+    /// <summary>
+    /// Policy identifier used in metadata and logs.
+    /// </summary>
+    public string Name => "EmergencyOverride";
+
+    /// <summary>
+    /// Higher than the fallback branch, so the explicit override wins first.
+    /// </summary>
+    public int Priority => 400;
+
+    /// <summary>
+    /// Describes the emergency override behavior.
+    /// </summary>
+    public string Description => "Allows an emergency release override when requested explicitly.";
+
+    /// <summary>
+    /// Reads the emergency flag from metadata and either approves the override or denies it.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current release state.</param>
+    /// <returns>
+    /// An allowed override decision when the emergency flag is set, otherwise a
+    /// standard denial that allows the AnyOf composition to keep searching.
+    /// </returns>
+    public PolicyDecision Evaluate(IMutation<ReleaseGateState> mutation, ReleaseGateState state)
+    {
+        var emergency = GetBool(mutation.Context.Metadata, "emergency");
+
+        return emergency
+            ? new PolicyDecision
+            {
+                IsAllowed = true,
+                PolicyName = Name,
+                Modifications = new Dictionary<string, object>
+                {
+                    ["State"] = state with { Stage = "EmergencyApproved" },
+                    ["SideEffect"] = SideEffect.Critical("release.override", "Emergency override applied.")
+                },
+                Metadata = new Dictionary<string, object>
+                {
+                    ["override"] = true
+                }
+            }
+            : PolicyDecision.Deny("Emergency override not requested.", Name);
+    }
+
+    private static bool GetBool(IReadOnlyDictionary<string, object> metadata, string key)
+        => metadata.TryGetValue(key, out var value) && value is true;
+}

Examples/Core/PolicyComposition/Policies/ReleaseGovernancePolicies.cs

@@ -0,0 +1,109 @@
+using ModularityKit.Mutator.Abstractions.Policies;
+using PolicyComposition.Policies.Approval;
+using PolicyComposition.Policies.Deployment;
+using PolicyComposition.Policies.Emergency;
+using PolicyComposition.Policies.Shared;
+using PolicyComposition.State;
+
+namespace PolicyComposition.Policies;
+
+/// <summary>
+/// Named composed policy sets used by the release governance example.
+/// </summary>
+/// <remarks>
+/// This class acts as the composition root for the example. It keeps the concrete
+/// child policies isolated from the scenarios and exposes reusable policy sets that
+/// demonstrate the three composition modes:
+/// <list type="bullet">
+/// <item><description><c>AllOf</c> for mandatory approval gates.</description></item>
+/// <item><description><c>AnyOf</c> for emergency fallback flows.</description></item>
+/// <item><description><c>Priority</c> for deterministic ordered selection.</description></item>
+/// </list>
+/// </remarks>
+internal static class ReleaseGovernancePolicies
+{
+    /// <summary>
+    /// Builds the standard approval gate used for release promotion.
+    /// </summary>
+    /// <remarks>
+    /// The gate combines:
+    /// <list type="bullet">
+    /// <item><description><see cref="RequireApprovalsPolicy"/> to enforce the approval threshold.</description></item>
+    /// <item><description><see cref="AddAuditTrailPolicy"/> to add traceability once the gate succeeds.</description></item>
+    /// </list>
+    /// The composed policy only succeeds when both child policies can contribute
+    /// without a conflict and the approval requirement is satisfied.
+    /// </remarks>
+    public static IMutationPolicy<ReleaseGateState> ApprovalGate() =>
+        ModularityKit.Mutator.Abstractions.Policies.PolicyComposition.AllOf(
+            "ReleaseApprovalGate",
+            [
+                new RequireApprovalsPolicy(),
+                new AddAuditTrailPolicy()
+            ],
+            priority: 500,
+            description: "Requires two approvals and adds audit metadata.");
+
+    /// <summary>
+    /// Builds the emergency gate that prefers an explicit override and falls back to approvals.
+    /// </summary>
+    /// <remarks>
+    /// The gate combines:
+    /// <list type="bullet">
+    /// <item><description><see cref="EmergencyOverridePolicy"/> for explicit emergency approval.</description></item>
+    /// <item><description><see cref="ApprovalFallbackPolicy"/> for the approval-based fallback path.</description></item>
+    /// </list>
+    /// The first allowed branch wins, which makes the result deterministic while
+    /// still allowing a reusable emergency path to be expressed in one place.
+    /// </remarks>
+    public static IMutationPolicy<ReleaseGateState> EmergencyGate() =>
+        ModularityKit.Mutator.Abstractions.Policies.PolicyComposition.AnyOf(
+            "ReleaseEmergencyGate",
+            [
+                new EmergencyOverridePolicy(),
+                new ApprovalFallbackPolicy()
+            ],
+            priority: 400,
+            description: "Chooses the emergency override branch when available.");
+
+    /// <summary>
+    /// Builds the deployment gate that evaluates production checks before the default path.
+    /// </summary>
+    /// <remarks>
+    /// The gate combines:
+    /// <list type="bullet">
+    /// <item><description><see cref="ProductionGuardPolicy"/> to block production releases early.</description></item>
+    /// <item><description><see cref="DefaultDeploymentPolicy"/> as the fallback branch for non-production releases.</description></item>
+    /// </list>
+    /// Because this is a priority composition, the first decisive policy short-circuits
+    /// the rest of the chain.
+    /// </remarks>
+    public static IMutationPolicy<ReleaseGateState> DeploymentGate() =>
+        ModularityKit.Mutator.Abstractions.Policies.PolicyComposition.Priority(
+            "ReleaseDeploymentGate",
+            [
+                new ProductionGuardPolicy(),
+                new DefaultDeploymentPolicy()
+            ],
+            priority: 300,
+            description: "Uses a production guard first, then falls back to the default deployment path.");
+
+    /// <summary>
+    /// Builds a composed gate that intentionally conflicts on the owner field.
+    /// </summary>
+    /// <remarks>
+    /// The gate composes two <see cref="SetOwnerPolicy"/> instances that target the
+    /// same state field with different values. The example uses this to show that
+    /// the composition layer detects conflicting mutation results explicitly instead
+    /// of silently picking one branch.
+    /// </remarks>
+    public static IMutationPolicy<ReleaseGateState> ConflictingOwnerGate() =>
+        ModularityKit.Mutator.Abstractions.Policies.PolicyComposition.AllOf(
+            "ReleaseOwnerConflictGate",
+            [
+                new SetOwnerPolicy("platform"),
+                new SetOwnerPolicy("security")
+            ],
+            priority: 200,
+            description: "Demonstrates explicit conflict handling when two policies set the same field differently.");
+}

Examples/Core/PolicyComposition/Policies/Shared/SetOwnerPolicy.cs

@@ -0,0 +1,48 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using PolicyComposition.State;
+
+namespace PolicyComposition.Policies.Shared;
+
+/// <summary>
+/// Forces the release owner to fixed value, so conflict handling is easy to observe.
+/// </summary>
+/// <remarks>
+/// The policy only touches one field. That makes it useful for the conflict
+/// example because two instances of the same class can be composed and produce a
+/// deterministic clash when they disagree on the owner.
+/// </remarks>
+internal sealed class SetOwnerPolicy(string owner) : IMutationPolicy<ReleaseGateState>
+{
+    /// <summary>
+    /// Policy identifier that includes the target owner value.
+    /// </summary>
+    public string Name => $"SetOwner[{owner}]";
+
+    /// <summary>
+    /// Middle priority because the policy is only used as a composed leaf rule.
+    /// </summary>
+    public int Priority => 150;
+
+    /// <summary>
+    /// Describes the owner assignment performed by the policy.
+    /// </summary>
+    public string Description => "Sets the release owner.";
+
+    /// <summary>
+    /// Updates only the owner field and leaves the rest of the state unchanged.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current release state.</param>
+    /// <returns>An allowed decision that changes only the owner field.</returns>
+    public PolicyDecision Evaluate(IMutation<ReleaseGateState> mutation, ReleaseGateState state)
+        => new()
+        {
+            IsAllowed = true,
+            PolicyName = Name,
+            Modifications = new Dictionary<string, object>
+            {
+                ["State"] = state with { Owner = owner }
+            }
+        };
+}