# 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`