up

src/Policy/__Libraries/StellaOps.Policy/PolicyExplanation.cs

@@ -0,0 +1,48 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Policy;
+
+/// <summary>
+/// Structured explanation describing how a policy decision was reached.
+/// </summary>
+/// <param name="FindingId">Identifier of the evaluated finding.</param>
+/// <param name="Decision">Final verdict status (e.g., Allow, Block, Warned).</param>
+/// <param name="RuleName">Name of the rule that matched, if any.</param>
+/// <param name="Reason">Human-readable summary.</param>
+/// <param name="Nodes">Tree of evaluated nodes (rule, match, action, penalties, quieting, unknown confidence).</param>
+public sealed record PolicyExplanation(
+    string FindingId,
+    PolicyVerdictStatus Decision,
+    string? RuleName,
+    string Reason,
+    ImmutableArray<PolicyExplanationNode> Nodes)
+{
+    public static PolicyExplanation Allow(string findingId, string? ruleName, string reason, params PolicyExplanationNode[] nodes) =>
+        new(findingId, PolicyVerdictStatus.Allowed, ruleName, reason, nodes.ToImmutableArray());
+
+    public static PolicyExplanation Block(string findingId, string? ruleName, string reason, params PolicyExplanationNode[] nodes) =>
+        new(findingId, PolicyVerdictStatus.Blocked, ruleName, reason, nodes.ToImmutableArray());
+
+    public static PolicyExplanation Warn(string findingId, string? ruleName, string reason, params PolicyExplanationNode[] nodes) =>
+        new(findingId, PolicyVerdictStatus.Warned, ruleName, reason, nodes.ToImmutableArray());
+}
+
+/// <summary>
+/// A single explanation node with optional children to capture evaluation breadcrumbs.
+/// </summary>
+/// <param name="Kind">Short classifier (e.g., "rule", "match", "penalty", "quiet", "unknown").</param>
+/// <param name="Label">Human-readable label.</param>
+/// <param name="Detail">Optional detail (numeric or string rendered as text).</param>
+/// <param name="Children">Nested explanation nodes.</param>
+public sealed record PolicyExplanationNode(
+    string Kind,
+    string Label,
+    string? Detail,
+    ImmutableArray<PolicyExplanationNode> Children)
+{
+    public static PolicyExplanationNode Leaf(string kind, string label, string? detail = null) =>
+        new(kind, label, detail, ImmutableArray<PolicyExplanationNode>.Empty);
+
+    public static PolicyExplanationNode Branch(string kind, string label, string? detail = null, params PolicyExplanationNode[] children) =>
+        new(kind, label, detail, children.ToImmutableArray());
+}