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);
}