up

docs/policy/ui-integration.md

@@ -0,0 +1,41 @@
+# Policy UI Integration for Graph/Vuln
+
+Status: Draft (2025-11-26) — aligns with POLICY-ENGINE-30-001..003 and Graph API overlays.
+
+## Goals
+- Explain how UI surfaces (Console, Vuln Explorer) consume policy/VEX overlays from Graph.
+- 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: `docs/modules/policy/prep/2025-11-22-policy-engine-30-001-prep.md`
+- Graph API overlays: `docs/api/graph.md`, `docs/modules/graph/architecture-index.md`
+- Concelier/Excititor overlays: `docs/modules/excititor/vex_observations.md`