Policy UI Integration for Graph/Vuln

Status: Draft (2025-11-26) — aligns with POLICY-ENGINE-30-001…003 and Graph API overlays.

This guide explains how Stella Ops UI surfaces (Console and Vuln Explorer) consume policy and VEX overlays from the Graph API. It is written for frontend engineers integrating overlay rendering and for backend engineers who own the overlay contracts those surfaces depend on.

Goals

• Explain how UI surfaces (Console, Vuln Explorer) consume policy/VEX overlays from the Graph API.
• Clarify cache usage, simulator contracts, and explain traces.

Data sources

• Policy overlays (policy.overlay.v1) produced by Policy Engine (POLICY-ENGINE-30-001).
• VEX overlays (openvex.v1) from Concelier/Excititor pipelines.
• Graph API emits overlays per node (see docs/api/graph.md) with deterministic IDs and optional explainTrace sampling.

Cache rules

• UI should respect overlay cache TTL (5–10 minutes). Cache key: tenant + nodeId + overlay kind.
• On cache miss, fallback to Graph API which will populate cache; avoid fan-out calls per tile.
• When policy overlay contract version changes, invalidate cache via version tag (e.g., policy.overlay.v1 → v2).

Requests

• Graph API: includeOverlays=true on /graph/query or /graph/paths to receive overlay payloads inline.
• Budget: ensure budget.tiles leaves room for overlays; UI may need to request higher budgets when overlays are critical to UX.
• Simulator: when running policy simulator, attach X-Stella-Simulator: true header (once enabled) to route to simulator instance; cache should be bypassed for simulator runs.

UI rendering guidance

• Show policy status badge (e.g., warn, deny, allow) with ruleId and severity.
• If explainTrace present, render as expandable list; only one sampled node per query may include trace.
• VEX overlays: render status (not_affected, affected) and justification; show issued timestamp and source.
• Overlay provenance: display overlayId, version, and source engine version if present.

Error handling

• If Graph returns GRAPH_BUDGET_EXCEEDED, prompt user to reduce scope or increase budgets; do not silently drop overlays.
• On overlay cache miss + upstream failure, surface a non-blocking warning and proceed with node data.

Events & notifications

• Subscribe to policy.overlay.updated (future) or re-poll every 10 minutes to refresh overlays in UI.
• When VEX status changes, UI should refresh impacted nodes/edges and reflect new status badges.

References

• Policy overlay contract: ../design/policy-overlay-projection.md
• Graph API overlays: ../../../api/graph.md, ../../graph/architecture-index.md
• Concelier/Excititor overlays: ../../excititor/vex_observations.md