up

src/Policy/StellaOps.Policy.Engine/ReachabilityFacts/IReachabilityFactsSignalsClient.cs

@@ -0,0 +1,234 @@
+namespace StellaOps.Policy.Engine.ReachabilityFacts;
+
+/// <summary>
+/// HTTP client interface for fetching reachability facts from Signals service.
+/// </summary>
+public interface IReachabilityFactsSignalsClient
+{
+    /// <summary>
+    /// Gets a reachability fact by subject key.
+    /// </summary>
+    /// <param name="subjectKey">Subject key (scan ID or component key).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The reachability fact document, or null if not found.</returns>
+    Task<SignalsReachabilityFactResponse?> GetBySubjectAsync(
+        string subjectKey,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets multiple reachability facts by subject keys.
+    /// </summary>
+    /// <param name="subjectKeys">Subject keys to lookup.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Dictionary of subject key to fact.</returns>
+    Task<IReadOnlyDictionary<string, SignalsReachabilityFactResponse>> GetBatchBySubjectsAsync(
+        IReadOnlyList<string> subjectKeys,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Triggers recomputation of reachability for a subject.
+    /// </summary>
+    /// <param name="request">Recompute request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>True if recompute was triggered.</returns>
+    Task<bool> TriggerRecomputeAsync(
+        SignalsRecomputeRequest request,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Response from Signals /facts/{subjectKey} endpoint.
+/// Maps to ReachabilityFactDocument in Signals module.
+/// </summary>
+public sealed record SignalsReachabilityFactResponse
+{
+    /// <summary>
+    /// Document ID.
+    /// </summary>
+    public string Id { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Callgraph ID.
+    /// </summary>
+    public string CallgraphId { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Subject information.
+    /// </summary>
+    public SignalsSubject? Subject { get; init; }
+
+    /// <summary>
+    /// Entry points.
+    /// </summary>
+    public List<string>? EntryPoints { get; init; }
+
+    /// <summary>
+    /// Reachability states.
+    /// </summary>
+    public List<SignalsReachabilityState>? States { get; init; }
+
+    /// <summary>
+    /// Runtime facts.
+    /// </summary>
+    public List<SignalsRuntimeFact>? RuntimeFacts { get; init; }
+
+    /// <summary>
+    /// CAS URI for runtime-facts batch artifact.
+    /// </summary>
+    public string? RuntimeFactsBatchUri { get; init; }
+
+    /// <summary>
+    /// BLAKE3 hash of runtime-facts batch.
+    /// </summary>
+    public string? RuntimeFactsBatchHash { get; init; }
+
+    /// <summary>
+    /// Additional metadata.
+    /// </summary>
+    public Dictionary<string, string?>? Metadata { get; init; }
+
+    /// <summary>
+    /// Context facts for provenance.
+    /// </summary>
+    public SignalsContextFacts? ContextFacts { get; init; }
+
+    /// <summary>
+    /// Uncertainty information.
+    /// </summary>
+    public SignalsUncertainty? Uncertainty { get; init; }
+
+    /// <summary>
+    /// Edge bundle references.
+    /// </summary>
+    public List<SignalsEdgeBundleReference>? EdgeBundles { get; init; }
+
+    /// <summary>
+    /// Whether quarantined edges exist.
+    /// </summary>
+    public bool HasQuarantinedEdges { get; init; }
+
+    /// <summary>
+    /// Reachability score.
+    /// </summary>
+    public double Score { get; init; }
+
+    /// <summary>
+    /// Risk score.
+    /// </summary>
+    public double RiskScore { get; init; }
+
+    /// <summary>
+    /// Count of unknowns.
+    /// </summary>
+    public int UnknownsCount { get; init; }
+
+    /// <summary>
+    /// Unknowns pressure.
+    /// </summary>
+    public double UnknownsPressure { get; init; }
+
+    /// <summary>
+    /// Computation timestamp.
+    /// </summary>
+    public DateTimeOffset ComputedAt { get; init; }
+
+    /// <summary>
+    /// Subject key.
+    /// </summary>
+    public string SubjectKey { get; init; } = string.Empty;
+}
+
+/// <summary>
+/// Subject information from Signals.
+/// </summary>
+public sealed record SignalsSubject
+{
+    public string? ImageDigest { get; init; }
+    public string? Component { get; init; }
+    public string? Version { get; init; }
+    public string? ScanId { get; init; }
+}
+
+/// <summary>
+/// Reachability state from Signals.
+/// </summary>
+public sealed record SignalsReachabilityState
+{
+    public string Target { get; init; } = string.Empty;
+    public bool Reachable { get; init; }
+    public double Confidence { get; init; }
+    public string Bucket { get; init; } = "unknown";
+    public string? LatticeState { get; init; }
+    public string? PreviousLatticeState { get; init; }
+    public double Weight { get; init; }
+    public double Score { get; init; }
+    public List<string>? Path { get; init; }
+    public SignalsEvidence? Evidence { get; init; }
+    public DateTimeOffset? LatticeTransitionAt { get; init; }
+}
+
+/// <summary>
+/// Evidence from Signals.
+/// </summary>
+public sealed record SignalsEvidence
+{
+    public List<string>? RuntimeHits { get; init; }
+    public List<string>? BlockedEdges { get; init; }
+}
+
+/// <summary>
+/// Runtime fact from Signals.
+/// </summary>
+public sealed record SignalsRuntimeFact
+{
+    public string SymbolId { get; init; } = string.Empty;
+    public string? CodeId { get; init; }
+    public string? SymbolDigest { get; init; }
+    public string? Purl { get; init; }
+    public string? BuildId { get; init; }
+    public int HitCount { get; init; }
+    public DateTimeOffset? ObservedAt { get; init; }
+}
+
+/// <summary>
+/// Context facts from Signals.
+/// </summary>
+public sealed record SignalsContextFacts;
+
+/// <summary>
+/// Uncertainty information from Signals.
+/// </summary>
+public sealed record SignalsUncertainty
+{
+    public string? AggregateTier { get; init; }
+    public double? RiskScore { get; init; }
+}
+
+/// <summary>
+/// Edge bundle reference from Signals.
+/// </summary>
+public sealed record SignalsEdgeBundleReference
+{
+    public string BundleId { get; init; } = string.Empty;
+    public string Reason { get; init; } = string.Empty;
+    public int EdgeCount { get; init; }
+    public string? CasUri { get; init; }
+    public string? DsseDigest { get; init; }
+    public bool HasRevokedEdges { get; init; }
+}
+
+/// <summary>
+/// Request to trigger reachability recomputation.
+/// </summary>
+public sealed record SignalsRecomputeRequest
+{
+    /// <summary>
+    /// Subject key to recompute.
+    /// </summary>
+    public required string SubjectKey { get; init; }
+
+    /// <summary>
+    /// Tenant ID.
+    /// </summary>
+    public required string TenantId { get; init; }
+}