sprints enhancements

src/__Libraries/StellaOps.Provcache/LazyFetch/ILazyEvidenceFetcher.cs

@@ -0,0 +1,131 @@
+namespace StellaOps.Provcache;
+
+/// <summary>
+/// Interface for lazy evidence chunk fetching from various sources.
+/// Enables on-demand evidence retrieval for air-gapped auditors.
+/// </summary>
+public interface ILazyEvidenceFetcher
+{
+    /// <summary>
+    /// Gets the fetcher type (e.g., "http", "file").
+    /// </summary>
+    string FetcherType { get; }
+
+    /// <summary>
+    /// Fetches a single chunk by index.
+    /// </summary>
+    /// <param name="proofRoot">The proof root identifying the evidence.</param>
+    /// <param name="chunkIndex">The chunk index to fetch.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The fetched chunk or null if not found.</returns>
+    Task<FetchedChunk?> FetchChunkAsync(
+        string proofRoot,
+        int chunkIndex,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Fetches multiple chunks by index.
+    /// </summary>
+    /// <param name="proofRoot">The proof root identifying the evidence.</param>
+    /// <param name="chunkIndices">The chunk indices to fetch.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Async enumerable of fetched chunks.</returns>
+    IAsyncEnumerable<FetchedChunk> FetchChunksAsync(
+        string proofRoot,
+        IEnumerable<int> chunkIndices,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Fetches all remaining chunks for a proof root.
+    /// </summary>
+    /// <param name="proofRoot">The proof root identifying the evidence.</param>
+    /// <param name="manifest">The chunk manifest for reference.</param>
+    /// <param name="existingIndices">Indices of chunks already present locally.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Async enumerable of fetched chunks.</returns>
+    IAsyncEnumerable<FetchedChunk> FetchRemainingChunksAsync(
+        string proofRoot,
+        ChunkManifest manifest,
+        IReadOnlySet<int> existingIndices,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Checks if the source is available for fetching.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>True if the source is available.</returns>
+    Task<bool> IsAvailableAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets the manifest from the source.
+    /// </summary>
+    /// <param name="proofRoot">The proof root to get manifest for.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The chunk manifest or null if not available.</returns>
+    Task<ChunkManifest?> FetchManifestAsync(
+        string proofRoot,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Simplified chunk representation for lazy fetch interface.
+/// Contains only the index and data for transport.
+/// </summary>
+public sealed record FetchedChunk
+{
+    /// <summary>
+    /// Zero-based chunk index.
+    /// </summary>
+    public required int Index { get; init; }
+
+    /// <summary>
+    /// The chunk data.
+    /// </summary>
+    public required byte[] Data { get; init; }
+
+    /// <summary>
+    /// SHA256 hash of the data for verification.
+    /// </summary>
+    public required string Hash { get; init; }
+}
+
+/// <summary>
+/// Result of a lazy fetch operation.
+/// </summary>
+public sealed record LazyFetchResult
+{
+    /// <summary>
+    /// Whether the fetch was successful.
+    /// </summary>
+    public required bool Success { get; init; }
+
+    /// <summary>
+    /// Number of chunks fetched.
+    /// </summary>
+    public required int ChunksFetched { get; init; }
+
+    /// <summary>
+    /// Total bytes fetched.
+    /// </summary>
+    public required long BytesFetched { get; init; }
+
+    /// <summary>
+    /// Number of chunks that failed verification.
+    /// </summary>
+    public required int ChunksFailedVerification { get; init; }
+
+    /// <summary>
+    /// Indices of failed chunks.
+    /// </summary>
+    public IReadOnlyList<int> FailedIndices { get; init; } = [];
+
+    /// <summary>
+    /// Any errors encountered.
+    /// </summary>
+    public IReadOnlyList<string> Errors { get; init; } = [];
+
+    /// <summary>
+    /// Time taken for the fetch operation.
+    /// </summary>
+    public TimeSpan Duration { get; init; }
+}