up

src/Signals/StellaOps.Signals/Options/SignalsOptions.cs

@@ -45,6 +45,11 @@ public sealed class SignalsOptions
     /// </summary>
     public SignalsOpenApiOptions OpenApi { get; } = new();
 
+    /// <summary>
+    /// Retention policy configuration for runtime facts and artifacts.
+    /// </summary>
+    public SignalsRetentionOptions Retention { get; } = new();
+
     /// <summary>
     /// Validates configured options.
     /// </summary>
@@ -57,5 +62,6 @@ public sealed class SignalsOptions
         Cache.Validate();
         Events.Validate();
         OpenApi.Validate();
+        Retention.Validate();
     }
 }

src/Signals/StellaOps.Signals/Options/SignalsRetentionOptions.cs

@@ -0,0 +1,87 @@
+namespace StellaOps.Signals.Options;
+
+/// <summary>
+/// Retention policy configuration for runtime facts.
+/// </summary>
+public sealed class SignalsRetentionOptions
+{
+    /// <summary>
+    /// Configuration section name.
+    /// </summary>
+    public const string SectionName = "Signals:Retention";
+
+    /// <summary>
+    /// Time-to-live for runtime facts in hours. Default is 720 (30 days).
+    /// Set to 0 to disable automatic expiration.
+    /// </summary>
+    public int RuntimeFactsTtlHours { get; set; } = 720;
+
+    /// <summary>
+    /// Time-to-live for callgraph artifacts in hours. Default is 2160 (90 days).
+    /// Set to 0 to disable automatic expiration.
+    /// </summary>
+    public int CallgraphTtlHours { get; set; } = 2160;
+
+    /// <summary>
+    /// Time-to-live for reachability states in hours. Default is 720 (30 days).
+    /// Set to 0 to disable automatic expiration.
+    /// </summary>
+    public int ReachabilityStateTtlHours { get; set; } = 720;
+
+    /// <summary>
+    /// Maximum number of runtime facts per subject. Default is 10000.
+    /// Older facts are evicted when the limit is reached.
+    /// </summary>
+    public int MaxRuntimeFactsPerSubject { get; set; } = 10000;
+
+    /// <summary>
+    /// Enable automatic cleanup of expired facts. Default is true.
+    /// </summary>
+    public bool EnableAutoCleanup { get; set; } = true;
+
+    /// <summary>
+    /// Cleanup interval in minutes. Default is 60.
+    /// </summary>
+    public int CleanupIntervalMinutes { get; set; } = 60;
+
+    /// <summary>
+    /// Archive expired facts to CAS before deletion. Default is true.
+    /// </summary>
+    public bool ArchiveBeforeDelete { get; set; } = true;
+
+    /// <summary>
+    /// CAS path for archived facts.
+    /// </summary>
+    public string ArchiveCasPath { get; set; } = "cas://signals/archive/runtime-facts";
+
+    /// <summary>
+    /// Validates retention options.
+    /// </summary>
+    public void Validate()
+    {
+        if (RuntimeFactsTtlHours < 0)
+        {
+            throw new ArgumentException("RuntimeFactsTtlHours must be >= 0.");
+        }
+
+        if (CallgraphTtlHours < 0)
+        {
+            throw new ArgumentException("CallgraphTtlHours must be >= 0.");
+        }
+
+        if (ReachabilityStateTtlHours < 0)
+        {
+            throw new ArgumentException("ReachabilityStateTtlHours must be >= 0.");
+        }
+
+        if (MaxRuntimeFactsPerSubject <= 0)
+        {
+            throw new ArgumentException("MaxRuntimeFactsPerSubject must be > 0.");
+        }
+
+        if (CleanupIntervalMinutes <= 0)
+        {
+            throw new ArgumentException("CleanupIntervalMinutes must be > 0.");
+        }
+    }
+}

src/Signals/StellaOps.Signals/Persistence/IReachabilityFactRepository.cs

@@ -1,3 +1,5 @@
+using System;
+using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
 using StellaOps.Signals.Models;
@@ -9,4 +11,24 @@ public interface IReachabilityFactRepository
     Task<ReachabilityFactDocument> UpsertAsync(ReachabilityFactDocument document, CancellationToken cancellationToken);
 
     Task<ReachabilityFactDocument?> GetBySubjectAsync(string subjectKey, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Gets documents with ComputedAt older than the specified cutoff.
+    /// </summary>
+    Task<IReadOnlyList<ReachabilityFactDocument>> GetExpiredAsync(DateTimeOffset cutoff, int limit, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Deletes the document with the specified subject key.
+    /// </summary>
+    Task<bool> DeleteAsync(string subjectKey, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Gets the count of runtime facts for a subject.
+    /// </summary>
+    Task<int> GetRuntimeFactsCountAsync(string subjectKey, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Trims runtime facts for a subject to the specified limit, keeping most recent.
+    /// </summary>
+    Task TrimRuntimeFactsAsync(string subjectKey, int maxCount, CancellationToken cancellationToken);
 }

src/Signals/StellaOps.Signals/Persistence/InMemoryReachabilityFactRepository.cs

@@ -1,4 +1,7 @@
+using System;
 using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using StellaOps.Signals.Models;
@@ -31,6 +34,66 @@ internal sealed class InMemoryReachabilityFactRepository : IReachabilityFactRepo
         return Task.FromResult(_store.TryGetValue(subjectKey, out var doc) ? Clone(doc) : null);
     }
 
+    public Task<IReadOnlyList<ReachabilityFactDocument>> GetExpiredAsync(DateTimeOffset cutoff, int limit, CancellationToken cancellationToken)
+    {
+        var expired = _store.Values
+            .Where(d => d.ComputedAt < cutoff)
+            .OrderBy(d => d.ComputedAt)
+            .Take(limit)
+            .Select(Clone)
+            .ToList();
+
+        return Task.FromResult<IReadOnlyList<ReachabilityFactDocument>>(expired);
+    }
+
+    public Task<bool> DeleteAsync(string subjectKey, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(subjectKey))
+        {
+            throw new ArgumentException("Subject key is required.", nameof(subjectKey));
+        }
+
+        return Task.FromResult(_store.TryRemove(subjectKey, out _));
+    }
+
+    public Task<int> GetRuntimeFactsCountAsync(string subjectKey, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(subjectKey))
+        {
+            throw new ArgumentException("Subject key is required.", nameof(subjectKey));
+        }
+
+        if (_store.TryGetValue(subjectKey, out var doc))
+        {
+            return Task.FromResult(doc.RuntimeFacts?.Count ?? 0);
+        }
+
+        return Task.FromResult(0);
+    }
+
+    public Task TrimRuntimeFactsAsync(string subjectKey, int maxCount, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(subjectKey))
+        {
+            throw new ArgumentException("Subject key is required.", nameof(subjectKey));
+        }
+
+        if (_store.TryGetValue(subjectKey, out var doc) && doc.RuntimeFacts is { Count: > 0 })
+        {
+            if (doc.RuntimeFacts.Count > maxCount)
+            {
+                var trimmed = doc.RuntimeFacts
+                    .OrderByDescending(f => f.ObservedAt ?? DateTimeOffset.MinValue)
+                    .ThenByDescending(f => f.HitCount)
+                    .Take(maxCount)
+                    .ToList();
+                doc.RuntimeFacts = trimmed;
+            }
+        }
+
+        return Task.CompletedTask;
+    }
+
     private static ReachabilityFactDocument Clone(ReachabilityFactDocument source) => new()
     {
         Id = source.Id,

src/Signals/StellaOps.Signals/Services/ReachabilityFactCacheDecorator.cs

@@ -1,3 +1,5 @@
+using System;
+using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
 using StellaOps.Signals.Models;
@@ -42,4 +44,28 @@ internal sealed class ReachabilityFactCacheDecorator : IReachabilityFactReposito
         await cache.SetAsync(result, cancellationToken).ConfigureAwait(false);
         return result;
     }
+
+    public Task<IReadOnlyList<ReachabilityFactDocument>> GetExpiredAsync(DateTimeOffset cutoff, int limit, CancellationToken cancellationToken)
+    {
+        // Cache decorator doesn't cache expired queries - pass through to inner
+        return inner.GetExpiredAsync(cutoff, limit, cancellationToken);
+    }
+
+    public async Task<bool> DeleteAsync(string subjectKey, CancellationToken cancellationToken)
+    {
+        await cache.InvalidateAsync(subjectKey, cancellationToken).ConfigureAwait(false);
+        return await inner.DeleteAsync(subjectKey, cancellationToken).ConfigureAwait(false);
+    }
+
+    public Task<int> GetRuntimeFactsCountAsync(string subjectKey, CancellationToken cancellationToken)
+    {
+        // Pass through to inner - count queries are not cached
+        return inner.GetRuntimeFactsCountAsync(subjectKey, cancellationToken);
+    }
+
+    public async Task TrimRuntimeFactsAsync(string subjectKey, int maxCount, CancellationToken cancellationToken)
+    {
+        await inner.TrimRuntimeFactsAsync(subjectKey, maxCount, cancellationToken).ConfigureAwait(false);
+        await cache.InvalidateAsync(subjectKey, cancellationToken).ConfigureAwait(false);
+    }
 }

src/Signals/StellaOps.Signals/Services/RuntimeFactsRetentionService.cs

@@ -0,0 +1,140 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using StellaOps.Signals.Options;
+using StellaOps.Signals.Persistence;
+
+namespace StellaOps.Signals.Services;
+
+/// <summary>
+/// Background service that periodically cleans up expired runtime facts
+/// based on the configured retention policy.
+/// </summary>
+public sealed class RuntimeFactsRetentionService : BackgroundService
+{
+    private readonly IReachabilityFactRepository _factRepository;
+    private readonly IOptions<SignalsOptions> _options;
+    private readonly TimeProvider _timeProvider;
+    private readonly ILogger<RuntimeFactsRetentionService> _logger;
+
+    public RuntimeFactsRetentionService(
+        IReachabilityFactRepository factRepository,
+        IOptions<SignalsOptions> options,
+        TimeProvider timeProvider,
+        ILogger<RuntimeFactsRetentionService> logger)
+    {
+        _factRepository = factRepository ?? throw new ArgumentNullException(nameof(factRepository));
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+        _timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        var retention = _options.Value.Retention;
+
+        if (!retention.EnableAutoCleanup)
+        {
+            _logger.LogInformation("Runtime facts auto-cleanup is disabled.");
+            return;
+        }
+
+        _logger.LogInformation(
+            "Runtime facts retention service started. TTL={TtlHours}h, Interval={IntervalMinutes}m, MaxPerSubject={MaxPerSubject}",
+            retention.RuntimeFactsTtlHours,
+            retention.CleanupIntervalMinutes,
+            retention.MaxRuntimeFactsPerSubject);
+
+        var interval = TimeSpan.FromMinutes(retention.CleanupIntervalMinutes);
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            try
+            {
+                await Task.Delay(interval, _timeProvider, stoppingToken).ConfigureAwait(false);
+                await CleanupExpiredFactsAsync(retention, stoppingToken).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+            {
+                // Normal shutdown
+                break;
+            }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex, "Error during runtime facts cleanup cycle.");
+                // Continue to next cycle
+            }
+        }
+
+        _logger.LogInformation("Runtime facts retention service stopped.");
+    }
+
+    private async Task CleanupExpiredFactsAsync(SignalsRetentionOptions retention, CancellationToken cancellationToken)
+    {
+        if (retention.RuntimeFactsTtlHours <= 0)
+        {
+            _logger.LogDebug("RuntimeFactsTtlHours is 0, skipping expiration cleanup.");
+            return;
+        }
+
+        var cutoff = _timeProvider.GetUtcNow().AddHours(-retention.RuntimeFactsTtlHours);
+        var expiredDocs = await _factRepository.GetExpiredAsync(cutoff, 100, cancellationToken).ConfigureAwait(false);
+
+        if (expiredDocs.Count == 0)
+        {
+            _logger.LogDebug("No expired runtime facts documents found.");
+            return;
+        }
+
+        _logger.LogInformation("Found {Count} expired runtime facts documents to clean up.", expiredDocs.Count);
+
+        var deletedCount = 0;
+        var archivedCount = 0;
+
+        foreach (var doc in expiredDocs)
+        {
+            try
+            {
+                if (retention.ArchiveBeforeDelete)
+                {
+                    await ArchiveDocumentAsync(doc, retention, cancellationToken).ConfigureAwait(false);
+                    archivedCount++;
+                }
+
+                var deleted = await _factRepository.DeleteAsync(doc.SubjectKey, cancellationToken).ConfigureAwait(false);
+                if (deleted)
+                {
+                    deletedCount++;
+                }
+            }
+            catch (Exception ex)
+            {
+                _logger.LogWarning(ex, "Failed to cleanup expired document for subject {SubjectKey}.", doc.SubjectKey);
+            }
+        }
+
+        _logger.LogInformation(
+            "Cleanup complete: deleted={DeletedCount}, archived={ArchivedCount}",
+            deletedCount,
+            archivedCount);
+    }
+
+    private Task ArchiveDocumentAsync(
+        StellaOps.Signals.Models.ReachabilityFactDocument document,
+        SignalsRetentionOptions retention,
+        CancellationToken cancellationToken)
+    {
+        // Archive to CAS is a placeholder - actual implementation would write to CAS storage
+        // using the configured ArchiveCasPath
+        _logger.LogDebug(
+            "Archiving document for subject {SubjectKey} to {CasPath}",
+            document.SubjectKey,
+            retention.ArchiveCasPath);
+
+        // TODO: Implement actual CAS archival via ICasStore when available
+        return Task.CompletedTask;
+    }
+}