sprints work

src/__Libraries/StellaOps.Provcache/IProvcacheStore.cs

@@ -0,0 +1,150 @@
+namespace StellaOps.Provcache;
+
+/// <summary>
+/// Cache store interface for Provcache with read-through semantics.
+/// Abstracts the caching layer (Valkey, in-memory, etc.).
+/// </summary>
+public interface IProvcacheStore
+{
+    /// <summary>
+    /// Gets the store provider name for diagnostics.
+    /// </summary>
+    string ProviderName { get; }
+
+    /// <summary>
+    /// Gets a cache entry by VeriKey.
+    /// </summary>
+    /// <param name="veriKey">The cache key.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Cache result indicating hit/miss with the entry if found.</returns>
+    ValueTask<ProvcacheLookupResult> GetAsync(string veriKey, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets multiple cache entries by VeriKeys.
+    /// </summary>
+    /// <param name="veriKeys">The cache keys.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Dictionary of found entries and list of misses.</returns>
+    ValueTask<ProvcacheBatchLookupResult> GetManyAsync(
+        IEnumerable<string> veriKeys,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Sets a cache entry.
+    /// </summary>
+    /// <param name="entry">The cache entry to set.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    ValueTask SetAsync(ProvcacheEntry entry, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Sets multiple cache entries in a batch.
+    /// </summary>
+    /// <param name="entries">The cache entries to set.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    ValueTask SetManyAsync(IEnumerable<ProvcacheEntry> entries, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Invalidates a cache entry by VeriKey.
+    /// </summary>
+    /// <param name="veriKey">The cache key.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>True if the entry existed and was invalidated.</returns>
+    ValueTask<bool> InvalidateAsync(string veriKey, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Invalidates entries matching a key pattern.
+    /// </summary>
+    /// <param name="pattern">The key pattern (supports wildcards).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Number of entries invalidated.</returns>
+    ValueTask<long> InvalidateByPatternAsync(string pattern, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets or sets a cache entry 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="cancellationToken">Cancellation token.</param>
+    /// <returns>The cached or newly created entry.</returns>
+    ValueTask<ProvcacheEntry> GetOrSetAsync(
+        string veriKey,
+        Func<CancellationToken, ValueTask<ProvcacheEntry>> factory,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Result of a single cache lookup.
+/// </summary>
+public sealed record ProvcacheLookupResult
+{
+    /// <summary>
+    /// Whether the entry was found in cache.
+    /// </summary>
+    public required bool IsHit { get; init; }
+
+    /// <summary>
+    /// The cache entry if found.
+    /// </summary>
+    public ProvcacheEntry? Entry { get; init; }
+
+    /// <summary>
+    /// Source of the cache hit (e.g., "valkey", "postgres").
+    /// Null for cache misses.
+    /// </summary>
+    public string? Source { get; init; }
+
+    /// <summary>
+    /// Time taken for the lookup in milliseconds.
+    /// </summary>
+    public double ElapsedMs { get; init; }
+
+    /// <summary>
+    /// Creates a cache hit result.
+    /// </summary>
+    public static ProvcacheLookupResult Hit(ProvcacheEntry entry, string source, double elapsedMs) => new()
+    {
+        IsHit = true,
+        Entry = entry,
+        Source = source,
+        ElapsedMs = elapsedMs
+    };
+
+    /// <summary>
+    /// Creates a cache miss result.
+    /// </summary>
+    public static ProvcacheLookupResult Miss(double elapsedMs) => new()
+    {
+        IsHit = false,
+        Entry = null,
+        Source = null,
+        ElapsedMs = elapsedMs
+    };
+}
+
+/// <summary>
+/// Result of a batch cache lookup.
+/// </summary>
+public sealed record ProvcacheBatchLookupResult
+{
+    /// <summary>
+    /// Entries found in cache, keyed by VeriKey.
+    /// </summary>
+    public required IReadOnlyDictionary<string, ProvcacheEntry> Hits { get; init; }
+
+    /// <summary>
+    /// VeriKeys that were not found in cache.
+    /// </summary>
+    public required IReadOnlyList<string> Misses { get; init; }
+
+    /// <summary>
+    /// Time taken for the lookup in milliseconds.
+    /// </summary>
+    public double ElapsedMs { get; init; }
+
+    /// <summary>
+    /// Cache hit rate for this batch (0.0 - 1.0).
+    /// </summary>
+    public double HitRate => Hits.Count == 0 && Misses.Count == 0
+        ? 0.0
+        : (double)Hits.Count / (Hits.Count + Misses.Count);
+}