git.stella-ops.org/src/AdvisoryAI/StellaOps.AdvisoryAI/Explanation/ExplanationResult.cs

namespace StellaOps.AdvisoryAI.Explanation;

/// <summary>
/// Citation linking an explanation claim to evidence.
/// </summary>
public sealed record ExplanationCitation
{
    /// <summary>
    /// Claim text from the explanation.
    /// </summary>
    public required string ClaimText { get; init; }

    /// <summary>
    /// Evidence node ID supporting this claim.
    /// </summary>
    public required string EvidenceId { get; init; }

    /// <summary>
    /// Type of evidence (sbom, reachability, runtime, vex, patch).
    /// </summary>
    public required string EvidenceType { get; init; }

    /// <summary>
    /// Whether the citation was verified against the evidence.
    /// </summary>
    public required bool Verified { get; init; }

    /// <summary>
    /// Excerpt from the evidence supporting the claim.
    /// </summary>
    public string? EvidenceExcerpt { get; init; }
}

/// <summary>
/// Authority level of the explanation.
/// </summary>
public enum ExplanationAuthority
{
    /// <summary>
    /// All claims are evidence-backed (≥80% citation rate, all verified).
    /// </summary>
    EvidenceBacked,

    /// <summary>
    /// AI suggestion requiring human review.
    /// </summary>
    Suggestion
}

/// <summary>
/// Result of explanation generation.
/// Sprint: SPRINT_20251226_015_AI_zastava_companion
/// Task: ZASTAVA-07
/// </summary>
public sealed record ExplanationResult
{
    /// <summary>
    /// Unique ID for this explanation.
    /// </summary>
    public required string ExplanationId { get; init; }

    /// <summary>
    /// The explanation content (markdown supported).
    /// </summary>
    public required string Content { get; init; }

    /// <summary>
    /// 3-line summary for compact display.
    /// </summary>
    public required ExplanationSummary Summary { get; init; }

    /// <summary>
    /// Citations linking claims to evidence.
    /// </summary>
    public required IReadOnlyList<ExplanationCitation> Citations { get; init; }

    /// <summary>
    /// Overall confidence score (0.0-1.0).
    /// </summary>
    public required double ConfidenceScore { get; init; }

    /// <summary>
    /// Citation rate (verified citations / total claims).
    /// </summary>
    public required double CitationRate { get; init; }

    /// <summary>
    /// Authority classification.
    /// </summary>
    public required ExplanationAuthority Authority { get; init; }

    /// <summary>
    /// Evidence node IDs used in this explanation.
    /// </summary>
    public required IReadOnlyList<string> EvidenceRefs { get; init; }

    /// <summary>
    /// Model ID used for generation.
    /// </summary>
    public required string ModelId { get; init; }

    /// <summary>
    /// Prompt template version.
    /// </summary>
    public required string PromptTemplateVersion { get; init; }

    /// <summary>
    /// Input hashes for replay.
    /// </summary>
    public required IReadOnlyList<string> InputHashes { get; init; }

    /// <summary>
    /// Generation timestamp (UTC ISO-8601).
    /// </summary>
    public required string GeneratedAt { get; init; }

    /// <summary>
    /// Output hash for verification.
    /// </summary>
    public required string OutputHash { get; init; }
}

/// <summary>
/// 3-line summary following the AI UX pattern.
/// </summary>
public sealed record ExplanationSummary
{
    /// <summary>
    /// Line 1: What changed/what is it.
    /// </summary>
    public required string Line1 { get; init; }

    /// <summary>
    /// Line 2: Why it matters.
    /// </summary>
    public required string Line2 { get; init; }

    /// <summary>
    /// Line 3: Next action.
    /// </summary>
    public required string Line3 { get; init; }
}