up

src/Scanner/StellaOps.Scanner.WebService/Contracts/RuntimePolicyContracts.cs

@@ -89,3 +89,124 @@ public sealed record RuntimePolicyRekorDto
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public bool? Verified { get; init; }
 }
+
+/// <summary>
+/// Request for policy overlays on graph nodes (for Cartographer integration).
+/// </summary>
+public sealed record PolicyOverlayRequestDto
+{
+    [JsonPropertyName("tenant")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Tenant { get; init; }
+
+    [JsonPropertyName("nodes")]
+    public IReadOnlyList<PolicyOverlayNodeDto> Nodes { get; init; } = Array.Empty<PolicyOverlayNodeDto>();
+
+    [JsonPropertyName("overlayKind")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? OverlayKind { get; init; }
+
+    [JsonPropertyName("includeEvidence")]
+    public bool IncludeEvidence { get; init; }
+}
+
+/// <summary>
+/// A graph node for policy overlay evaluation.
+/// </summary>
+public sealed record PolicyOverlayNodeDto
+{
+    [JsonPropertyName("nodeId")]
+    public string NodeId { get; init; } = string.Empty;
+
+    [JsonPropertyName("nodeType")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? NodeType { get; init; }
+
+    [JsonPropertyName("purl")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Purl { get; init; }
+
+    [JsonPropertyName("imageDigest")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? ImageDigest { get; init; }
+
+    [JsonPropertyName("advisoryKey")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? AdvisoryKey { get; init; }
+}
+
+/// <summary>
+/// Response containing policy overlays for graph nodes.
+/// </summary>
+public sealed record PolicyOverlayResponseDto
+{
+    [JsonPropertyName("tenant")]
+    public string Tenant { get; init; } = string.Empty;
+
+    [JsonPropertyName("generatedAt")]
+    public DateTimeOffset GeneratedAt { get; init; }
+
+    [JsonPropertyName("policyRevision")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? PolicyRevision { get; init; }
+
+    [JsonPropertyName("overlays")]
+    public IReadOnlyList<PolicyOverlayDto> Overlays { get; init; } = Array.Empty<PolicyOverlayDto>();
+}
+
+/// <summary>
+/// A single policy overlay for a graph node with deterministic ID.
+/// </summary>
+public sealed record PolicyOverlayDto
+{
+    [JsonPropertyName("overlayId")]
+    public string OverlayId { get; init; } = string.Empty;
+
+    [JsonPropertyName("nodeId")]
+    public string NodeId { get; init; } = string.Empty;
+
+    [JsonPropertyName("overlayKind")]
+    public string OverlayKind { get; init; } = "policy.overlay.v1";
+
+    [JsonPropertyName("verdict")]
+    public string Verdict { get; init; } = "unknown";
+
+    [JsonPropertyName("reasons")]
+    public IReadOnlyList<string> Reasons { get; init; } = Array.Empty<string>();
+
+    [JsonPropertyName("confidence")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public double? Confidence { get; init; }
+
+    [JsonPropertyName("quieted")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public bool? Quieted { get; init; }
+
+    [JsonPropertyName("evidence")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public PolicyOverlayEvidenceDto? Evidence { get; init; }
+}
+
+/// <summary>
+/// Runtime evidence attached to a policy overlay.
+/// </summary>
+public sealed record PolicyOverlayEvidenceDto
+{
+    [JsonPropertyName("signed")]
+    public bool Signed { get; init; }
+
+    [JsonPropertyName("hasSbomReferrers")]
+    public bool HasSbomReferrers { get; init; }
+
+    [JsonPropertyName("rekor")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public RuntimePolicyRekorDto? Rekor { get; init; }
+
+    [JsonPropertyName("buildIds")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IReadOnlyList<string>? BuildIds { get; init; }
+
+    [JsonPropertyName("metadata")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IReadOnlyDictionary<string, string>? Metadata { get; init; }
+}