sprints enhancements

src/__Libraries/StellaOps.Provcache/IEvidenceChunkRepository.cs

@@ -0,0 +1,203 @@
+namespace StellaOps.Provcache;
+
+/// <summary>
+/// Repository for evidence chunk storage and retrieval.
+/// </summary>
+public interface IEvidenceChunkRepository
+{
+    /// <summary>
+    /// Gets all chunks for a proof root.
+    /// </summary>
+    /// <param name="proofRoot">The proof root to get chunks for.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Ordered list of chunks.</returns>
+    Task<IReadOnlyList<EvidenceChunk>> GetChunksAsync(
+        string proofRoot,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets a specific chunk by index.
+    /// </summary>
+    /// <param name="proofRoot">The proof root.</param>
+    /// <param name="chunkIndex">The chunk index.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The chunk or null if not found.</returns>
+    Task<EvidenceChunk?> GetChunkAsync(
+        string proofRoot,
+        int chunkIndex,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets chunks in a range (for paged retrieval).
+    /// </summary>
+    /// <param name="proofRoot">The proof root.</param>
+    /// <param name="startIndex">Starting chunk index (inclusive).</param>
+    /// <param name="count">Number of chunks to retrieve.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Ordered list of chunks in the range.</returns>
+    Task<IReadOnlyList<EvidenceChunk>> GetChunkRangeAsync(
+        string proofRoot,
+        int startIndex,
+        int count,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets the chunk manifest (metadata without blobs).
+    /// </summary>
+    /// <param name="proofRoot">The proof root.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The chunk manifest.</returns>
+    Task<ChunkManifest?> GetManifestAsync(
+        string proofRoot,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Stores multiple chunks for a proof root.
+    /// </summary>
+    /// <param name="proofRoot">The proof root.</param>
+    /// <param name="chunks">The chunks to store.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task StoreChunksAsync(
+        string proofRoot,
+        IEnumerable<EvidenceChunk> chunks,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Deletes all chunks for a proof root.
+    /// </summary>
+    /// <param name="proofRoot">The proof root.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Number of chunks deleted.</returns>
+    Task<int> DeleteChunksAsync(
+        string proofRoot,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets total chunk count for a proof root.
+    /// </summary>
+    /// <param name="proofRoot">The proof root.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Number of chunks.</returns>
+    Task<int> GetChunkCountAsync(
+        string proofRoot,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets total storage size for a proof root.
+    /// </summary>
+    /// <param name="proofRoot">The proof root.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Total bytes stored.</returns>
+    Task<long> GetTotalSizeAsync(
+        string proofRoot,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Represents an evidence chunk.
+/// </summary>
+public sealed record EvidenceChunk
+{
+    /// <summary>
+    /// Unique chunk identifier.
+    /// </summary>
+    public required Guid ChunkId { get; init; }
+
+    /// <summary>
+    /// The proof root this chunk belongs to.
+    /// </summary>
+    public required string ProofRoot { get; init; }
+
+    /// <summary>
+    /// Zero-based index within the proof.
+    /// </summary>
+    public required int ChunkIndex { get; init; }
+
+    /// <summary>
+    /// SHA256 hash of the chunk for verification.
+    /// </summary>
+    public required string ChunkHash { get; init; }
+
+    /// <summary>
+    /// The binary content.
+    /// </summary>
+    public required byte[] Blob { get; init; }
+
+    /// <summary>
+    /// Size of the blob in bytes.
+    /// </summary>
+    public required int BlobSize { get; init; }
+
+    /// <summary>
+    /// MIME type of the content.
+    /// </summary>
+    public required string ContentType { get; init; }
+
+    /// <summary>
+    /// When the chunk was created.
+    /// </summary>
+    public required DateTimeOffset CreatedAt { get; init; }
+}
+
+/// <summary>
+/// Manifest describing all chunks for a proof root (metadata only).
+/// Used for lazy fetching where blobs are retrieved on demand.
+/// </summary>
+public sealed record ChunkManifest
+{
+    /// <summary>
+    /// The proof root (Merkle root of all chunks).
+    /// </summary>
+    public required string ProofRoot { get; init; }
+
+    /// <summary>
+    /// Total number of chunks.
+    /// </summary>
+    public required int TotalChunks { get; init; }
+
+    /// <summary>
+    /// Total size of all chunks in bytes.
+    /// </summary>
+    public required long TotalSize { get; init; }
+
+    /// <summary>
+    /// Ordered list of chunk metadata.
+    /// </summary>
+    public required IReadOnlyList<ChunkMetadata> Chunks { get; init; }
+
+    /// <summary>
+    /// When the manifest was generated.
+    /// </summary>
+    public required DateTimeOffset GeneratedAt { get; init; }
+}
+
+/// <summary>
+/// Metadata for a single chunk (no blob).
+/// </summary>
+public sealed record ChunkMetadata
+{
+    /// <summary>
+    /// Chunk identifier.
+    /// </summary>
+    public required Guid ChunkId { get; init; }
+
+    /// <summary>
+    /// Zero-based index.
+    /// </summary>
+    public required int Index { get; init; }
+
+    /// <summary>
+    /// SHA256 hash for verification.
+    /// </summary>
+    public required string Hash { get; init; }
+
+    /// <summary>
+    /// Size in bytes.
+    /// </summary>
+    public required int Size { get; init; }
+
+    /// <summary>
+    /// Content type.
+    /// </summary>
+    public required string ContentType { get; init; }
+}