sprints enhancements

src/__Libraries/StellaOps.Provcache/Events/FeedEpochAdvancedEvent.cs

@@ -0,0 +1,109 @@
+namespace StellaOps.Provcache.Events;
+
+/// <summary>
+/// Event published when an advisory feed advances to a new epoch.
+/// Provcache subscribers use this to invalidate cache entries
+/// that were computed against older feed epochs.
+/// </summary>
+/// <remarks>
+/// Stream name: <c>stellaops:events:feed-epoch-advanced</c>
+/// </remarks>
+public sealed record FeedEpochAdvancedEvent
+{
+    /// <summary>
+    /// Stream name for feed epoch events.
+    /// </summary>
+    public const string StreamName = "stellaops:events:feed-epoch-advanced";
+
+    /// <summary>
+    /// Event type identifier for serialization.
+    /// </summary>
+    public const string EventType = "feed.epoch.advanced.v1";
+
+    /// <summary>
+    /// Unique identifier for this event instance.
+    /// </summary>
+    public required Guid EventId { get; init; }
+
+    /// <summary>
+    /// Timestamp when the event occurred (UTC).
+    /// </summary>
+    public required DateTimeOffset Timestamp { get; init; }
+
+    /// <summary>
+    /// The feed identifier (e.g., "cve", "ghsa", "osv", "redhat-oval").
+    /// </summary>
+    public required string FeedId { get; init; }
+
+    /// <summary>
+    /// The previous epoch identifier.
+    /// Format varies by feed (e.g., "2024-12-24T12:00:00Z", "v2024.52").
+    /// </summary>
+    public required string PreviousEpoch { get; init; }
+
+    /// <summary>
+    /// The new epoch identifier.
+    /// </summary>
+    public required string NewEpoch { get; init; }
+
+    /// <summary>
+    /// When the new epoch became effective.
+    /// Cache entries with feed_epoch older than this should be invalidated.
+    /// </summary>
+    public required DateTimeOffset EffectiveAt { get; init; }
+
+    /// <summary>
+    /// Number of advisories added in this epoch (for metrics).
+    /// </summary>
+    public int? AdvisoriesAdded { get; init; }
+
+    /// <summary>
+    /// Number of advisories modified in this epoch (for metrics).
+    /// </summary>
+    public int? AdvisoriesModified { get; init; }
+
+    /// <summary>
+    /// Number of advisories withdrawn in this epoch (for metrics).
+    /// </summary>
+    public int? AdvisoriesWithdrawn { get; init; }
+
+    /// <summary>
+    /// Tenant ID if multi-tenant (null for global feeds).
+    /// </summary>
+    public string? TenantId { get; init; }
+
+    /// <summary>
+    /// Correlation ID for distributed tracing.
+    /// </summary>
+    public string? CorrelationId { get; init; }
+
+    /// <summary>
+    /// Creates a new FeedEpochAdvancedEvent.
+    /// </summary>
+    public static FeedEpochAdvancedEvent Create(
+        string feedId,
+        string previousEpoch,
+        string newEpoch,
+        DateTimeOffset effectiveAt,
+        int? advisoriesAdded = null,
+        int? advisoriesModified = null,
+        int? advisoriesWithdrawn = null,
+        string? tenantId = null,
+        string? correlationId = null)
+    {
+        return new FeedEpochAdvancedEvent
+        {
+            EventId = Guid.NewGuid(),
+            Timestamp = DateTimeOffset.UtcNow,
+            FeedId = feedId,
+            PreviousEpoch = previousEpoch,
+            NewEpoch = newEpoch,
+            EffectiveAt = effectiveAt,
+            AdvisoriesAdded = advisoriesAdded,
+            AdvisoriesModified = advisoriesModified,
+            AdvisoriesWithdrawn = advisoriesWithdrawn,
+            TenantId = tenantId,
+            CorrelationId = correlationId
+        };
+    }
+}