Feat: Add composed mutation policy examples

Author: rian-be

Examples/Core/PolicyComposition/Policies/Approval/AddAuditTrailPolicy.cs

@@ -0,0 +1,56 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using PolicyComposition.State;
+
+namespace PolicyComposition.Policies.Approval;
+
+/// <summary>
+/// Appends audit trail information to an already allowed approval gate decision.
+/// </summary>
+/// <remarks>
+/// This policy does not block or change the release state. It exists to show how
+/// composed policies can contribute side effects and metadata independently of
+/// the policy that made the main business decision.
+/// </remarks>
+internal sealed class AddAuditTrailPolicy : IMutationPolicy<ReleaseGateState>
+{
+    /// <summary>
+    /// Stable policy identifier used in composition metadata and diagnostics.
+    /// </summary>
+    public string Name => "AddAuditTrail";
+
+    /// <summary>
+    /// Medium priority so this policy can be grouped with the approval gate it decorates.
+    /// </summary>
+    public int Priority => 200;
+
+    /// <summary>
+    /// Describes the audit trail side effect this policy adds to the composed result.
+    /// </summary>
+    public string Description => "Adds audit metadata and a notification side effect.";
+
+    /// <summary>
+    /// Emits one audit side effect and a simple metadata flag.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current release state.</param>
+    /// <returns>An allowed decision with audit metadata and a single side effect.</returns>
+    public PolicyDecision Evaluate(IMutation<ReleaseGateState> mutation, ReleaseGateState state)
+        => new()
+        {
+            IsAllowed = true,
+            PolicyName = Name,
+            Modifications = new Dictionary<string, object>
+            {
+                ["SideEffects"] = new[]
+                {
+                    SideEffect.Create("audit", $"Release {state.ReleaseName} passed the composed approval gate.")
+                }
+            },
+            Metadata = new Dictionary<string, object>
+            {
+                ["auditTrail"] = "enabled"
+            }
+        };
+}

Examples/Core/PolicyComposition/Policies/Approval/RequireApprovalsPolicy.cs

@@ -0,0 +1,82 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using PolicyComposition.State;
+
+namespace PolicyComposition.Policies.Approval;
+
+/// <summary>
+/// Blocks release promotion until the expected approval threshold is present.
+/// </summary>
+/// <remarks>
+/// The policy reads the approval count from mutation metadata, so the example can
+/// show how governance input travels alongside the mutation itself.
+/// When the threshold is met, the policy marks the release as approved and emits
+/// an audit side effect. When it is not met, the policy returns a requirement and
+/// error severity so the composed result can surface the missing approval.
+/// </remarks>
+internal sealed class RequireApprovalsPolicy : IMutationPolicy<ReleaseGateState>
+{
+    /// <summary>
+    /// Stable policy identifier used in diagnostics and composition metadata.
+    /// </summary>
+    public string Name => "RequireApprovals";
+
+    /// <summary>
+    /// Higher than the audit only policy, so approval gating is evaluated first.
+    /// </summary>
+    public int Priority => 300;
+
+    /// <summary>
+    /// Explains the minimum-approval requirement that this policy enforces.
+    /// </summary>
+    public string Description => "Requires at least two approvals before the release can proceed.";
+
+    /// <summary>
+    /// Reads the approval count from mutation metadata and either allows or blocks the release.
+    /// </summary>
+    /// <param name="mutation">The mutation carrying government metadata.</param>
+    /// <param name="state">The current release state.</param>
+    /// <returns>
+    /// An allowed decision when approvals are enough, otherwise a blocking
+    /// decision with an approval requirement and error severity.
+    /// </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 = "Approved" },
+                    ["SideEffect"] = SideEffect.Create("audit", $"Release approved with {approvals} approvals.")
+                },
+                Metadata = new Dictionary<string, object>
+                {
+                    ["approvalCount"] = approvals
+                }
+            }
+            : new PolicyDecision
+            {
+                IsAllowed = false,
+                PolicyName = Name,
+                Severity = PolicyDecisionSeverity.Error,
+                Reason = $"Release requires at least two approvals; found {approvals}.",
+                Requirements =
+                [
+                    PolicyRequirement.Approval("release-manager", "Two approvals are required before promotion.")
+                ],
+                Metadata = new Dictionary<string, object>
+                {
+                    ["approvalCount"] = approvals
+                }
+            };
+    }
+
+    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/Deployment/DefaultDeploymentPolicy.cs

@@ -0,0 +1,55 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using PolicyComposition.State;
+
+namespace PolicyComposition.Policies.Deployment;
+
+/// <summary>
+/// Supplies the fallback deployment path for non production releases.
+/// </summary>
+/// <remarks>
+/// The policy does not inspect environment-specific risk beyond the fact that it
+/// is the default branch in the composed deployment gate. It moves the release to
+/// a deploy-ready stage and contributes both a side effect and metadata so the
+/// composition result stays auditable.
+/// </remarks>
+internal sealed class DefaultDeploymentPolicy : IMutationPolicy<ReleaseGateState>
+{
+    /// <summary>
+    /// Policy identifier used in composition metadata.
+    /// </summary>
+    public string Name => "DefaultDeployment";
+
+    /// <summary>
+    /// Lowest priority in the deployment composition, so it acts as the fallback branch.
+    /// </summary>
+    public int Priority => 100;
+
+    /// <summary>
+    /// Describes the fallback deployment behavior.
+    /// </summary>
+    public string Description => "Default non-production deployment path.";
+
+    /// <summary>
+    /// Moves the release into the ready for deployment stage and emits an audit trace.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current release state.</param>
+    /// <returns>An allowed decision that marks the release ready for deployment.</returns>
+    public PolicyDecision Evaluate(IMutation<ReleaseGateState> mutation, ReleaseGateState state)
+        => new()
+        {
+            IsAllowed = true,
+            PolicyName = Name,
+            Modifications = new Dictionary<string, object>
+            {
+                ["State"] = state with { Stage = "ReadyForDeploy" },
+                ["SideEffect"] = SideEffect.Create("audit", "Default deployment path selected.")
+            },
+            Metadata = new Dictionary<string, object>
+            {
+                ["deploymentPath"] = "default"
+            }
+        };
+}

Examples/Core/PolicyComposition/Policies/Deployment/ProductionGuardPolicy.cs

@@ -0,0 +1,53 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+using PolicyComposition.State;
+
+namespace PolicyComposition.Policies.Deployment;
+
+/// <summary>
+/// Stops production releases before fallback policies can be applied.
+/// </summary>
+/// <remarks>
+/// This policy exists to demonstrate the priority composition mode. It evaluates
+/// first, looks at the environment metadata, and returns a decisive denial when
+/// the release targets production. For any other environment, it allows the
+/// composition to continue to the next policy.
+/// </remarks>
+internal sealed class ProductionGuardPolicy : IMutationPolicy<ReleaseGateState>
+{
+    /// <summary>
+    /// Policy identifier used in decision metadata.
+    /// </summary>
+    public string Name => "ProductionGuard";
+
+    /// <summary>
+    /// Highest priority in the deployment gate, so the production check runs first.
+    /// </summary>
+    public int Priority => 500;
+
+    /// <summary>
+    /// Summarizes the production protection rule enforced by this policy.
+    /// </summary>
+    public string Description => "Blocks production releases before lower priority policies can run.";
+
+    /// <summary>
+    /// Checks the environment metadata and either denies production or allows fallback.
+    /// </summary>
+    /// <param name="mutation">The mutation being evaluated.</param>
+    /// <param name="state">The current release state.</param>
+    /// <returns>
+    /// A critical denial for production deployments, or an allowed decision that
+    /// hands control to lower-priority policies.
+    /// </returns>
+    public PolicyDecision Evaluate(IMutation<ReleaseGateState> mutation, ReleaseGateState state)
+    {
+        var environment = GetString(mutation.Context.Metadata, "environment");
+
+        return string.Equals(environment, "production", StringComparison.OrdinalIgnoreCase)
+            ? PolicyDecision.DenyCritical("Production releases require a dedicated change window.", Name)
+            : PolicyDecision.Allow(Name, $"Environment '{environment}' falls through to the next policy.");
+    }
+
+    private static string GetString(IReadOnlyDictionary<string, object> metadata, string key)
+        => metadata.TryGetValue(key, out var value) && value is string text ? text : string.Empty;
+}