git.stella-ops.org/src/AdvisoryAI/StellaOps.AdvisoryAI/PolicyStudio/PolicyIntent.cs

namespace StellaOps.AdvisoryAI.PolicyStudio;

/// <summary>
/// Type of policy intent.
/// Sprint: SPRINT_20251226_017_AI_policy_copilot
/// Task: POLICY-01
/// </summary>
public enum PolicyIntentType
{
    /// <summary>
    /// Override default verdict for specific conditions.
    /// </summary>
    OverrideRule,

    /// <summary>
    /// Escalate findings under specific conditions.
    /// </summary>
    EscalationRule,

    /// <summary>
    /// Define exception conditions that bypass normal rules.
    /// </summary>
    ExceptionCondition,

    /// <summary>
    /// Define precedence when multiple rules match.
    /// </summary>
    MergePrecedence,

    /// <summary>
    /// Set thresholds for automatic verdicts.
    /// </summary>
    ThresholdRule,

    /// <summary>
    /// Define scope restrictions for rules.
    /// </summary>
    ScopeRestriction
}

/// <summary>
/// Condition in a policy rule.
/// </summary>
public sealed record PolicyCondition
{
    /// <summary>
    /// Field to evaluate (severity, cvss_score, reachable, has_vex, etc.).
    /// </summary>
    public required string Field { get; init; }

    /// <summary>
    /// Operator (equals, greater_than, less_than, contains, in, not_in).
    /// </summary>
    public required string Operator { get; init; }

    /// <summary>
    /// Value to compare against.
    /// </summary>
    public required object Value { get; init; }

    /// <summary>
    /// Logical connector to next condition (and, or).
    /// </summary>
    public string? Connector { get; init; }
}

/// <summary>
/// Action to take when conditions match.
/// </summary>
public sealed record PolicyAction
{
    /// <summary>
    /// Action type (set_verdict, escalate, notify, block, allow).
    /// </summary>
    public required string ActionType { get; init; }

    /// <summary>
    /// Action parameters.
    /// </summary>
    public required IReadOnlyDictionary<string, object> Parameters { get; init; }
}

/// <summary>
/// Authority level of the policy draft.
/// </summary>
public enum PolicyDraftAuthority
{
    /// <summary>
    /// AI suggestion requiring review.
    /// </summary>
    Suggestion,

    /// <summary>
    /// Validated draft ready for approval.
    /// </summary>
    Validated,

    /// <summary>
    /// Approved and ready for production.
    /// </summary>
    Approved
}

/// <summary>
/// A parsed policy intent from natural language.
/// Sprint: SPRINT_20251226_017_AI_policy_copilot
/// Task: POLICY-04
/// </summary>
public sealed record PolicyIntent
{
    /// <summary>
    /// Unique intent ID.
    /// </summary>
    public required string IntentId { get; init; }

    /// <summary>
    /// Type of intent.
    /// </summary>
    public required PolicyIntentType IntentType { get; init; }

    /// <summary>
    /// Original natural language input.
    /// </summary>
    public required string OriginalInput { get; init; }

    /// <summary>
    /// Conditions for the rule.
    /// </summary>
    public required IReadOnlyList<PolicyCondition> Conditions { get; init; }

    /// <summary>
    /// Actions to take when conditions match.
    /// </summary>
    public required IReadOnlyList<PolicyAction> Actions { get; init; }

    /// <summary>
    /// Scope of the rule (all, service, team, project).
    /// </summary>
    public required string Scope { get; init; }

    /// <summary>
    /// Scope identifier.
    /// </summary>
    public string? ScopeId { get; init; }

    /// <summary>
    /// Rule priority (higher = evaluated first).
    /// </summary>
    public required int Priority { get; init; }

    /// <summary>
    /// Confidence in the parsing (0.0-1.0).
    /// </summary>
    public required double Confidence { get; init; }

    /// <summary>
    /// Alternative interpretations if ambiguous.
    /// </summary>
    public IReadOnlyList<PolicyIntent>? Alternatives { get; init; }

    /// <summary>
    /// Clarifying questions if ambiguous.
    /// </summary>
    public IReadOnlyList<string>? ClarifyingQuestions { get; init; }
}

/// <summary>
/// Result of parsing natural language to policy intent.
/// </summary>
public sealed record PolicyParseResult
{
    /// <summary>
    /// Primary parsed intent.
    /// </summary>
    public required PolicyIntent Intent { get; init; }

    /// <summary>
    /// Whether parsing was successful.
    /// </summary>
    public required bool Success { get; init; }

    /// <summary>
    /// Error message if parsing failed.
    /// </summary>
    public string? ErrorMessage { get; init; }

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

    /// <summary>
    /// Parsed timestamp.
    /// </summary>
    public required string ParsedAt { get; init; }
}