Feat: policy decision merging and evaluation types

Author: rian-be

src/Abstractions/Policies/PolicyDecisionMetadataMerger.cs

@@ -0,0 +1,101 @@
+using ModularityKit.Mutator.Abstractions.Exceptions;
+
+namespace ModularityKit.Mutator.Abstractions.Policies;
+
+/// <summary>
+/// Merges metadata for composed policy decisions.
+/// </summary>
+/// <remarks>
+/// The merger preserves composition audit metadata and folds child policy
+/// metadata into the final decision. Metadata keys are merged deterministically.
+/// When two child policies provide the same metadata key with different values,
+/// the merge fails with policy composition conflict so ambiguous audit data is
+/// never silently overwritten.
+/// </remarks>
+internal static class PolicyDecisionMetadataMerger
+{
+    /// <summary>
+    /// The metadata key used to store the policy composition mode.
+    /// </summary>
+    private const string CompositionModeKey = "PolicyComposition.Mode";
+
+    /// <summary>
+    /// The metadata key used to store the ordered child policy evaluation summary.
+    /// </summary>
+    private const string CompositionPoliciesKey = "PolicyComposition.Policies";
+
+    /// <summary>
+    /// The metadata key used to store the policies that contributed to the composed result.
+    /// </summary>
+    private const string CompositionWinningPoliciesKey = "PolicyComposition.WinningPolicies";
+
+    /// <summary>
+    /// The metadata key used to store the policies that blocked the composed result.
+    /// </summary>
+    private const string CompositionBlockingPoliciesKey = "PolicyComposition.BlockingPolicies";
+
+    /// <summary>
+    /// Merges composition metadata with metadata produced by child policy decisions.
+    /// </summary>
+    /// <typeparam name="TState">The state type used by the evaluated policies.</typeparam>
+    /// <param name="compositionName">The composed policy name.</param>
+    /// <param name="mode">The composition mode used to produce the final decision.</param>
+    /// <param name="evaluations">The ordered child policy evaluations.</param>
+    /// <param name="winningPolicyNames">The policies that contributed to the composed result.</param>
+    /// <param name="blockingPolicyNames">The policies that blocked the composed result.</param>
+    /// <returns>The merged metadata dictionary for the composed policy decision.</returns>
+    /// <exception cref="PolicyCompositionConflictException">
+    /// Thrown when multiple child policies provide the same metadata key with different values.
+    /// </exception>
+    public static IReadOnlyDictionary<string, object> Merge<TState>(
+        string compositionName,
+        PolicyCompositionMode mode,
+        IReadOnlyList<PolicyEvaluation<TState>> evaluations,
+        IReadOnlyList<string> winningPolicyNames,
+        IReadOnlyList<string> blockingPolicyNames)
+    {
+        var metadata = new Dictionary<string, object>(StringComparer.Ordinal)
+        {
+            [CompositionModeKey] = mode.ToString(),
+            [CompositionPoliciesKey] = evaluations
+                .Select((evaluation, index) => new
+                {
+                    index,
+                    policy = evaluation.Policy.Name,
+                    severity = evaluation.Decision.Severity.ToString(),
+                    allowed = evaluation.Decision.IsAllowed
+                })
+                .ToArray(),
+            [CompositionWinningPoliciesKey] = winningPolicyNames.ToArray(),
+            [CompositionBlockingPoliciesKey] = blockingPolicyNames.ToArray()
+        };
+
+        foreach (var evaluation in evaluations)
+        {
+            if (evaluation.Decision.Metadata is null)
+                continue;
+
+            foreach (var (key, value) in evaluation.Decision.Metadata)
+            {
+                if (!metadata.TryGetValue(key, out var existing))
+                {
+                    metadata[key] = value;
+                    continue;
+                }
+
+                if (Equals(existing, value))
+                    continue;
+
+                throw new PolicyCompositionConflictException(
+                    compositionName,
+                    $"metadata:{key}",
+                    [.. evaluations
+                        .Where(candidate => candidate.Decision.Metadata is not null && candidate.Decision.Metadata.ContainsKey(key))
+                        .Select(candidate => candidate.Policy.Name)
+                        .Distinct(StringComparer.Ordinal)]);
+            }
+        }
+
+        return metadata;
+    }
+}

src/Abstractions/Policies/PolicyDecisionModificationMerger.cs

@@ -0,0 +1,101 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.Exceptions;
+
+namespace ModularityKit.Mutator.Abstractions.Policies;
+
+/// <summary>
+/// Merges modification payloads for composed policy decisions.
+/// </summary>
+/// <remarks>
+/// The merger folds child policy modification payloads into single composed
+/// modification dictionary. Regular modification keys must either be unique or
+/// contain equal values across contributing policies. Side effects are treated
+/// specially and are collected into a single side effects collection.
+/// </remarks>
+internal static class PolicyDecisionModificationMerger
+{
+    /// <summary>
+    /// The modification key used for single side effect.
+    /// </summary>
+    private const string SideEffectKey = "SideEffect";
+
+    /// <summary>
+    /// The modification key used for collection of side effects.
+    /// </summary>
+    private const string SideEffectsKey = "SideEffects";
+
+    /// <summary>
+    /// Merges modification payloads produced by child policy decisions.
+    /// </summary>
+    /// <typeparam name="TState">The state type used by the evaluated policies.</typeparam>
+    /// <param name="compositionName">The composed policy name.</param>
+    /// <param name="evaluations">The child policy evaluations that contribute modifications.</param>
+    /// <returns>
+    /// The merged modification dictionary, or <c>null</c> when no modifications were produced.
+    /// </returns>
+    /// <exception cref="PolicyCompositionConflictException">
+    /// Thrown when multiple policies provide the same modification key with different values,
+    /// or when the side effects payload has an unsupported shape.
+    /// </exception>
+    public static IReadOnlyDictionary<string, object>? Merge<TState>(
+        string compositionName,
+        IReadOnlyList<PolicyEvaluation<TState>> evaluations)
+    {
+        var merged = new Dictionary<string, object>(StringComparer.Ordinal);
+        var sources = new Dictionary<string, string>(StringComparer.Ordinal);
+        var sideEffects = new List<SideEffect>();
+
+        foreach (var evaluation in evaluations)
+        {
+            if (evaluation.Decision.Modifications is null)
+                continue;
+
+            foreach (var (key, value) in evaluation.Decision.Modifications)
+            {
+                if (key == SideEffectKey)
+                {
+                    if (value is SideEffect sideEffect)
+                    {
+                        sideEffects.Add(sideEffect);
+                    }
+
+                    continue;
+                }
+
+                if (key == SideEffectsKey)
+                {
+                    if (value is IEnumerable<SideEffect> effects)
+                    {
+                        sideEffects.AddRange(effects);
+                        continue;
+                    }
+
+                    throw new PolicyCompositionConflictException(
+                        compositionName,
+                        SideEffectsKey,
+                        [evaluation.Policy.Name]);
+                }
+
+                if (!merged.TryGetValue(key, out var existing))
+                {
+                    merged[key] = value;
+                    sources[key] = evaluation.Policy.Name;
+                    continue;
+                }
+
+                if (Equals(existing, value))
+                    continue;
+
+                throw new PolicyCompositionConflictException(
+                    compositionName,
+                    key,
+                    [sources[key], evaluation.Policy.Name]);
+            }
+        }
+
+        if (sideEffects.Count > 0)
+            merged[SideEffectsKey] = sideEffects;
+
+        return merged.Count == 0 ? null : merged;
+    }
+}

src/Abstractions/Policies/PolicyEvaluation.cs

@@ -0,0 +1,13 @@
+using ModularityKit.Mutator.Abstractions.Engine;
+
+namespace ModularityKit.Mutator.Abstractions.Policies;
+
+/// <summary>
+/// Captures one evaluated policy and its decision.
+/// </summary>
+/// <typeparam name="TState">The state type used by the evaluated policy.</typeparam>
+/// <param name="Policy">The policy that was evaluated.</param>
+/// <param name="Decision">The decision produced by the policy.</param>
+internal readonly record struct PolicyEvaluation<TState>(
+    IMutationPolicy<TState> Policy,
+    PolicyDecision Decision);