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