// <copyright file="IEvidencePackService.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under the BUSL-1.1.
// </copyright>

using StellaOps.Evidence.Pack.Models;

namespace StellaOps.Evidence.Pack;

/// <summary>
/// Service for creating, signing, and managing evidence packs.
/// Sprint: SPRINT_20260109_011_005 Task: EVPK-002
/// </summary>
public interface IEvidencePackService
{
    /// <summary>
    /// Creates an Evidence Pack from grounding validation results.
    /// </summary>
    /// <param name="claims">The claims to include in the pack.</param>
    /// <param name="evidence">The evidence items supporting the claims.</param>
    /// <param name="subject">The subject of the evidence pack.</param>
    /// <param name="context">Optional context information.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created evidence pack.</returns>
    Task<EvidencePack> CreateAsync(
        IEnumerable<EvidenceClaim> claims,
        IEnumerable<EvidenceItem> evidence,
        EvidenceSubject subject,
        EvidencePackContext? context,
        CancellationToken cancellationToken);

    /// <summary>
    /// Creates an Evidence Pack from a Run's artifacts.
    /// </summary>
    /// <param name="runId">The run identifier.</param>
    /// <param name="subject">The subject of the evidence pack.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created evidence pack.</returns>
    Task<EvidencePack> CreateFromRunAsync(
        string runId,
        EvidenceSubject subject,
        CancellationToken cancellationToken);

    /// <summary>
    /// Adds evidence items to an existing pack (creates new version).
    /// </summary>
    /// <param name="packId">The pack identifier.</param>
    /// <param name="items">The evidence items to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The updated evidence pack (new version).</returns>
    Task<EvidencePack> AddEvidenceAsync(
        string packId,
        IEnumerable<EvidenceItem> items,
        CancellationToken cancellationToken);

    /// <summary>
    /// Signs an Evidence Pack with DSSE.
    /// </summary>
    /// <param name="pack">The evidence pack to sign.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The signed evidence pack.</returns>
    Task<SignedEvidencePack> SignAsync(
        EvidencePack pack,
        CancellationToken cancellationToken);

    /// <summary>
    /// Verifies a signed Evidence Pack.
    /// </summary>
    /// <param name="signedPack">The signed pack to verify.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The verification result.</returns>
    Task<EvidencePackVerificationResult> VerifyAsync(
        SignedEvidencePack signedPack,
        CancellationToken cancellationToken);

    /// <summary>
    /// Exports a pack to various formats.
    /// </summary>
    /// <param name="packId">The pack identifier.</param>
    /// <param name="format">The export format.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The exported pack.</returns>
    Task<EvidencePackExport> ExportAsync(
        string packId,
        EvidencePackExportFormat format,
        CancellationToken cancellationToken);

    /// <summary>
    /// Gets a pack by ID.
    /// </summary>
    /// <param name="tenantId">The tenant identifier.</param>
    /// <param name="packId">The pack identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The evidence pack, or null if not found.</returns>
    Task<EvidencePack?> GetAsync(
        string tenantId,
        string packId,
        CancellationToken cancellationToken);

    /// <summary>
    /// Lists evidence packs for a tenant.
    /// </summary>
    /// <param name="tenantId">The tenant identifier.</param>
    /// <param name="query">Optional query parameters.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The list of evidence packs.</returns>
    Task<IReadOnlyList<EvidencePack>> ListAsync(
        string tenantId,
        EvidencePackQuery? query,
        CancellationToken cancellationToken);
}

/// <summary>
/// Query parameters for listing evidence packs.
/// </summary>
public sealed record EvidencePackQuery
{
    /// <summary>Gets or sets the subject CVE ID filter.</summary>
    public string? CveId { get; init; }

    /// <summary>Gets or sets the subject component filter.</summary>
    public string? Component { get; init; }

    /// <summary>Gets or sets the associated run ID filter.</summary>
    public string? RunId { get; init; }

    /// <summary>Gets or sets the creation time filter (packs after this time).</summary>
    public DateTimeOffset? Since { get; init; }

    /// <summary>Gets or sets the maximum number of results.</summary>
    public int Limit { get; init; } = 50;

    /// <summary>Gets or sets the pagination cursor.</summary>
    public string? Cursor { get; init; }
}