git.stella-ops.org/src/Policy/StellaOps.Policy.Engine/EffectiveDecisionMap/IEffectiveDecisionMap.cs

namespace StellaOps.Policy.Engine.EffectiveDecisionMap;

/// <summary>
/// Interface for effective decision map storage.
/// Maintains policy decisions per asset/snapshot for Graph overlays.
/// </summary>
public interface IEffectiveDecisionMap
{
    /// <summary>
    /// Sets an effective decision entry.
    /// </summary>
    Task SetAsync(
        string tenantId,
        string snapshotId,
        EffectiveDecisionEntry entry,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Sets multiple effective decision entries.
    /// </summary>
    Task SetBatchAsync(
        string tenantId,
        string snapshotId,
        IEnumerable<EffectiveDecisionEntry> entries,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets an effective decision entry.
    /// </summary>
    Task<EffectiveDecisionEntry?> GetAsync(
        string tenantId,
        string snapshotId,
        string assetId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets multiple effective decision entries.
    /// </summary>
    Task<EffectiveDecisionQueryResult> GetBatchAsync(
        string tenantId,
        string snapshotId,
        IReadOnlyList<string> assetIds,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all effective decisions for a snapshot.
    /// </summary>
    Task<IReadOnlyList<EffectiveDecisionEntry>> GetAllForSnapshotAsync(
        string tenantId,
        string snapshotId,
        EffectiveDecisionFilter? filter = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a summary of effective decisions for a snapshot.
    /// </summary>
    Task<EffectiveDecisionSummary> GetSummaryAsync(
        string tenantId,
        string snapshotId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Invalidates a specific entry.
    /// </summary>
    Task InvalidateAsync(
        string tenantId,
        string snapshotId,
        string assetId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Invalidates all entries for a snapshot.
    /// </summary>
    Task InvalidateSnapshotAsync(
        string tenantId,
        string snapshotId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Invalidates all entries for a tenant.
    /// </summary>
    Task InvalidateTenantAsync(
        string tenantId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the current map version for a snapshot.
    /// </summary>
    Task<long> GetVersionAsync(
        string tenantId,
        string snapshotId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Increments and returns the new map version for a snapshot.
    /// </summary>
    Task<long> IncrementVersionAsync(
        string tenantId,
        string snapshotId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets statistics about the effective decision map.
    /// </summary>
    Task<EffectiveDecisionMapStats> GetStatsAsync(
        string? tenantId = null,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Statistics about the effective decision map.
/// </summary>
public sealed record EffectiveDecisionMapStats
{
    /// <summary>
    /// Total entries across all tenants/snapshots.
    /// </summary>
    public long TotalEntries { get; init; }

    /// <summary>
    /// Total snapshots tracked.
    /// </summary>
    public long TotalSnapshots { get; init; }

    /// <summary>
    /// Memory used in bytes (if available).
    /// </summary>
    public long? MemoryUsedBytes { get; init; }

    /// <summary>
    /// Entries expiring in the next hour.
    /// </summary>
    public long ExpiringWithinHour { get; init; }

    /// <summary>
    /// Last eviction timestamp.
    /// </summary>
    public DateTimeOffset? LastEvictionAt { get; init; }

    /// <summary>
    /// Count of entries evicted in last eviction run.
    /// </summary>
    public long LastEvictionCount { get; init; }
}