sprints completion. new product advisories prepared

src/Scanner/__Libraries/StellaOps.Scanner.Reachability/RichGraphSemanticExtensions.cs

@@ -49,6 +49,30 @@ public static class RichGraphSemanticAttributes
 
     /// <summary>CWE ID if applicable.</summary>
     public const string CweId = "cwe_id";
+
+    // Sprint: SPRINT_20260112_004_SCANNER_reachability_trace_runtime_evidence
+    // Runtime evidence overlay attributes (do not alter lattice precedence)
+
+    /// <summary>Reachability score (0.0-1.0) - computed from path confidence.</summary>
+    public const string ReachabilityScore = "reachability_score";
+
+    /// <summary>Whether this node/edge was confirmed at runtime ("true"/"false").</summary>
+    public const string RuntimeConfirmed = "runtime_confirmed";
+
+    /// <summary>Number of runtime observations for this node/edge.</summary>
+    public const string RuntimeObservationCount = "runtime_observation_count";
+
+    /// <summary>Timestamp of first runtime observation (ISO 8601).</summary>
+    public const string RuntimeFirstObserved = "runtime_first_observed";
+
+    /// <summary>Timestamp of last runtime observation (ISO 8601).</summary>
+    public const string RuntimeLastObserved = "runtime_last_observed";
+
+    /// <summary>Runtime evidence URI reference.</summary>
+    public const string RuntimeEvidenceUri = "runtime_evidence_uri";
+
+    /// <summary>Runtime confirmation type (confirmed/partial/none).</summary>
+    public const string RuntimeConfirmationType = "runtime_confirmation_type";
 }
 
 /// <summary>
@@ -162,6 +186,88 @@ public static class RichGraphSemanticExtensions
         // Use max risk score as overall
         return riskScores.Max();
     }
+
+    // Sprint: SPRINT_20260112_004_SCANNER_reachability_trace_runtime_evidence
+    // Extension methods for runtime evidence overlay attributes
+
+    /// <summary>Gets the reachability score (0.0-1.0).</summary>
+    public static double? GetReachabilityScore(this RichGraphNode node)
+    {
+        if (node.Attributes?.TryGetValue(RichGraphSemanticAttributes.ReachabilityScore, out var value) != true ||
+            string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        return double.TryParse(value, NumberStyles.Float, CultureInfo.InvariantCulture, out var score) ? score : null;
+    }
+
+    /// <summary>Gets whether this node was confirmed at runtime.</summary>
+    public static bool? GetRuntimeConfirmed(this RichGraphNode node)
+    {
+        if (node.Attributes?.TryGetValue(RichGraphSemanticAttributes.RuntimeConfirmed, out var value) != true ||
+            string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        return bool.TryParse(value, out var result) ? result : null;
+    }
+
+    /// <summary>Gets the runtime observation count.</summary>
+    public static ulong? GetRuntimeObservationCount(this RichGraphNode node)
+    {
+        if (node.Attributes?.TryGetValue(RichGraphSemanticAttributes.RuntimeObservationCount, out var value) != true ||
+            string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        return ulong.TryParse(value, NumberStyles.Integer, CultureInfo.InvariantCulture, out var count) ? count : null;
+    }
+
+    /// <summary>Gets the runtime confirmation type (confirmed/partial/none).</summary>
+    public static string? GetRuntimeConfirmationType(this RichGraphNode node)
+    {
+        return node.Attributes?.TryGetValue(RichGraphSemanticAttributes.RuntimeConfirmationType, out var value) == true ? value : null;
+    }
+
+    /// <summary>Gets the runtime evidence URI.</summary>
+    public static string? GetRuntimeEvidenceUri(this RichGraphNode node)
+    {
+        return node.Attributes?.TryGetValue(RichGraphSemanticAttributes.RuntimeEvidenceUri, out var value) == true ? value : null;
+    }
+
+    /// <summary>Gets nodes with runtime confirmation.</summary>
+    public static IReadOnlyList<RichGraphNode> GetRuntimeConfirmedNodes(this RichGraph graph)
+    {
+        return graph.Nodes.Where(n => n.GetRuntimeConfirmed() == true).ToList();
+    }
+
+    /// <summary>Calculates the graph-level runtime coverage percentage.</summary>
+    public static double CalculateRuntimeCoverage(this RichGraph graph)
+    {
+        if (graph.Nodes.Count == 0)
+            return 0.0;
+
+        var confirmedCount = graph.Nodes.Count(n => n.GetRuntimeConfirmed() == true);
+        return (double)confirmedCount / graph.Nodes.Count * 100.0;
+    }
+
+    /// <summary>Gets the average reachability score for the graph.</summary>
+    public static double? CalculateAverageReachabilityScore(this RichGraph graph)
+    {
+        var scores = graph.Nodes
+            .Select(n => n.GetReachabilityScore())
+            .Where(s => s.HasValue)
+            .Select(s => s!.Value)
+            .ToList();
+
+        if (scores.Count == 0)
+            return null;
+
+        return scores.Average();
+    }
 }
 
 /// <summary>
@@ -230,6 +336,52 @@ public sealed class RichGraphNodeSemanticBuilder
         return this;
     }
 
+    // Sprint: SPRINT_20260112_004_SCANNER_reachability_trace_runtime_evidence
+    // Builder methods for runtime evidence overlay attributes
+
+    /// <summary>Sets the reachability score (0.0-1.0).</summary>
+    public RichGraphNodeSemanticBuilder WithReachabilityScore(double score)
+    {
+        _attributes[RichGraphSemanticAttributes.ReachabilityScore] = Math.Clamp(score, 0.0, 1.0).ToString("F3", CultureInfo.InvariantCulture);
+        return this;
+    }
+
+    /// <summary>Sets the runtime confirmed flag.</summary>
+    public RichGraphNodeSemanticBuilder WithRuntimeConfirmed(bool confirmed)
+    {
+        _attributes[RichGraphSemanticAttributes.RuntimeConfirmed] = confirmed.ToString().ToLowerInvariant();
+        return this;
+    }
+
+    /// <summary>Sets the runtime observation count.</summary>
+    public RichGraphNodeSemanticBuilder WithRuntimeObservationCount(ulong count)
+    {
+        _attributes[RichGraphSemanticAttributes.RuntimeObservationCount] = count.ToString(CultureInfo.InvariantCulture);
+        return this;
+    }
+
+    /// <summary>Sets the runtime observation timestamps.</summary>
+    public RichGraphNodeSemanticBuilder WithRuntimeObservationTimes(DateTimeOffset firstObserved, DateTimeOffset lastObserved)
+    {
+        _attributes[RichGraphSemanticAttributes.RuntimeFirstObserved] = firstObserved.ToString("O", CultureInfo.InvariantCulture);
+        _attributes[RichGraphSemanticAttributes.RuntimeLastObserved] = lastObserved.ToString("O", CultureInfo.InvariantCulture);
+        return this;
+    }
+
+    /// <summary>Sets the runtime evidence URI.</summary>
+    public RichGraphNodeSemanticBuilder WithRuntimeEvidenceUri(string uri)
+    {
+        _attributes[RichGraphSemanticAttributes.RuntimeEvidenceUri] = uri;
+        return this;
+    }
+
+    /// <summary>Sets the runtime confirmation type (confirmed/partial/none).</summary>
+    public RichGraphNodeSemanticBuilder WithRuntimeConfirmationType(string confirmationType)
+    {
+        _attributes[RichGraphSemanticAttributes.RuntimeConfirmationType] = confirmationType;
+        return this;
+    }
+
     /// <summary>Builds the attributes dictionary.</summary>
     public IReadOnlyDictionary<string, string> Build()
     {