sprints work

src/__Libraries/StellaOps.Evidence.Pack/IEvidencePackService.cs

@@ -0,0 +1,134 @@
+// <copyright file="IEvidencePackService.cs" company="StellaOps">
+// Copyright (c) StellaOps. Licensed under the AGPL-3.0-or-later.
+// </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; }
+}