namespace StellaOps.Provcache;

/// <summary>
/// High-level service interface for Provcache operations.
/// Orchestrates cache store and repository with metrics and invalidation logic.
/// </summary>
public interface IProvcacheService
{
    /// <summary>
    /// Gets a cached decision by VeriKey.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="bypassCache">If true, skip cache and force re-evaluation.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The cache result with decision if found.</returns>
    Task<ProvcacheServiceResult> GetAsync(
        string veriKey,
        bool bypassCache = false,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Stores a decision in the cache.
    /// </summary>
    /// <param name="entry">The cache entry to store.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if the entry was stored successfully.</returns>
    Task<bool> SetAsync(ProvcacheEntry entry, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets or computes a decision using a factory function for cache misses.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="factory">Factory function to create the entry on cache miss.</param>
    /// <param name="bypassCache">If true, skip cache and force re-computation.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The cached or newly computed entry.</returns>
    Task<ProvcacheEntry> GetOrComputeAsync(
        string veriKey,
        Func<CancellationToken, Task<ProvcacheEntry>> factory,
        bool bypassCache = false,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Invalidates a cache entry by VeriKey.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="reason">Reason for invalidation (for audit log).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if the entry existed and was invalidated.</returns>
    Task<bool> InvalidateAsync(
        string veriKey,
        string? reason = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Invalidates entries by invalidation criteria.
    /// </summary>
    /// <param name="request">The invalidation request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Invalidation result with count of affected entries.</returns>
    Task<InvalidationResult> InvalidateByAsync(
        InvalidationRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets cache metrics for monitoring.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Cache metrics.</returns>
    Task<ProvcacheMetrics> GetMetricsAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Prunes expired entries from the cache.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Number of entries pruned.</returns>
    Task<long> PruneExpiredAsync(CancellationToken cancellationToken = default);
}