git.stella-ops.org/src/Policy/StellaOps.Policy.Engine/ReachabilityFacts/IReachabilityFactsSignalsClient.cs

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>
    /// Gets a reachability fact with its associated subgraph slice.
    /// Fetches from Signals for the fact and ReachGraph Store for the subgraph.
    /// </summary>
    /// <param name="subjectKey">Subject key (scan ID or component key).</param>
    /// <param name="cveId">Optional CVE ID to slice by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The reachability fact with subgraph, or null if not found.</returns>
    Task<ReachabilityFactWithSubgraph?> GetWithSubgraphAsync(
        string subjectKey,
        string? cveId = null,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Response containing both the reachability fact and its subgraph slice.
/// </summary>
public sealed record ReachabilityFactWithSubgraph(
    SignalsReachabilityFactResponse Fact,
    ReachGraphSlice? Subgraph);

/// <summary>
/// Represents a slice of the reachability graph for a specific query.
/// </summary>
public sealed record ReachGraphSlice
{
    /// <summary>
    /// Schema version.
    /// </summary>
    public string? SchemaVersion { get; init; }

    /// <summary>
    /// Slice query information.
    /// </summary>
    public ReachGraphSliceQuery? SliceQuery { get; init; }

    /// <summary>
    /// Parent graph digest.
    /// </summary>
    public string? ParentDigest { get; init; }

    /// <summary>
    /// BLAKE3 digest of this slice.
    /// </summary>
    public string? Digest { get; init; }

    /// <summary>
    /// Nodes in the slice.
    /// </summary>
    public List<ReachGraphSliceNode>? Nodes { get; init; }

    /// <summary>
    /// Edges in the slice.
    /// </summary>
    public List<ReachGraphSliceEdge>? Edges { get; init; }

    /// <summary>
    /// Number of nodes.
    /// </summary>
    public int NodeCount { get; init; }

    /// <summary>
    /// Number of edges.
    /// </summary>
    public int EdgeCount { get; init; }

    /// <summary>
    /// Sink node IDs.
    /// </summary>
    public List<string>? Sinks { get; init; }

    /// <summary>
    /// Paths from entrypoints to sinks.
    /// </summary>
    public List<ReachGraphPath>? Paths { get; init; }
}

/// <summary>
/// Slice query information.
/// </summary>
public sealed record ReachGraphSliceQuery
{
    public string? Type { get; init; }
    public string? Query { get; init; }
    public string? Cve { get; init; }
}

/// <summary>
/// Node in a reachability graph slice.
/// </summary>
public sealed record ReachGraphSliceNode
{
    public string? Id { get; init; }
    public string? Kind { get; init; }
    public string? Ref { get; init; }
    public string? File { get; init; }
    public int? Line { get; init; }
    public bool IsEntrypoint { get; init; }
    public bool IsSink { get; init; }
}

/// <summary>
/// Edge in a reachability graph slice.
/// </summary>
public sealed record ReachGraphSliceEdge
{
    public string? From { get; init; }
    public string? To { get; init; }
    public ReachGraphEdgeExplanation? Why { get; init; }
}

/// <summary>
/// Edge explanation in a reachability graph.
/// </summary>
public sealed record ReachGraphEdgeExplanation
{
    public string? Type { get; init; }
    public string? Loc { get; init; }
    public string? Guard { get; init; }
    public double Confidence { get; init; }
}

/// <summary>
/// Path from entrypoint to sink.
/// </summary>
public sealed record ReachGraphPath
{
    public string? Entrypoint { get; init; }
    public string? Sink { get; init; }
    public List<string>? Hops { get; init; }
    public List<ReachGraphSliceEdge>? Edges { get; init; }
}

/// <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; }
}