up

docs/ui/sbom-graph-explorer.md

@@ -0,0 +1,47 @@
+# SBOM Graph Explorer
+
+> **Imposed rule:** Saved views and exports must include the overlay + filter set that produced them; do not distribute stripped exports.
+
+The SBOM Graph Explorer lets operators traverse components, dependencies, and reachability overlays with deterministic filters suitable for online and air-gapped consoles.
+
+## Views & overlays
+- **Inventory vs Usage overlays:** toggle to see declared packages (inventory) or runtime-observed packages (usage). Overlays are rendered as chips; colors align with graph legend.
+- **Reachability overlay:** highlights components reachable from entrypoints; respects cached reachability results from Graph API. Disabled when `reachability_source` is stale (>24h) to avoid misleading badges.
+- **Policy overlay:** displays allow/deny/review verdicts from Policy Engine; shows cache epoch and simulator marker when viewing staged policy.
+- **VEX overlay:** marks components covered by active VEX claims (Excititor); conflict states (pending/contested) surface as striped badges.
+
+## Filters
+- **Package facets:** ecosystem, name (supports substring and PURL), version, license, and supplier.
+- **Reachability facets:** entrypoint, call depth, and evidence source (static/runtime/edge bundle).
+- **Risk facets:** severity band, EPSS bucket, KEV flag, exploitability score.
+- **Time facets:** last-seen (usage), last-scan (inventory) to surface staleness.
+- Filters are additive; results are deterministically sorted by component PURL, then version.
+
+## Saved views
+- Saved views capture query, overlays, column set, sort, and tenant. They are stored per tenant and tagged with `graph_cache_epoch` to detect stale caches.
+- Export saved view: downloads NDJSON with `view_id`, `filters`, `overlays`, `results[]`, and SHA-256 manifest. Works offline; includes attestations if available.
+- Restoring a view warns when cache epoch differs; users can refresh overlays before applying.
+
+## Interactions
+- **Graph canvas:** zoom/pan; node tooltip shows PURL, reachability, licenses, and open issues count. Double-click expands neighbors; capped by `ui.graph.maxNodes` to keep performance deterministic.
+- **Table panel:** synchronized with canvas selection; supports column picker and keyboard navigation (arrow keys, Enter to open drawer).
+- **Details drawer:** shows component metadata, provenance (source SBOM digest + Rekor UUID if attested), and outgoing/incoming edges with reachability evidence.
+- **Search bar:** accepts PURL, package name, or CVE; CVE search auto-filters to affected components via vulnerability overlay.
+
+## Accessibility
+- Full keyboard navigation: Tab/Shift+Tab moves between canvas, filters, table, drawer. Canvas focus ring is visible at 3:1 contrast.
+- Screen reader labels include overlay state (e.g., “node: openssl 3.0.12, reachable, vex-contested”).
+- High-contrast mode uses solid fills; motion reduced when `prefers-reduced-motion` is set.
+
+## Air-gap & caching
+- Works with offline Graph API bundles; overlays and filters use cached results when `graph_cache_epoch` matches. Exports include cache epoch to keep audits deterministic.
+- Prefers client-side cache for back/forward navigation; cache invalidates on tenant switch or overlay version change.
+
+## AOC visibility
+- Aggregation-Only Contract surfaces in the header when viewing regulated tenants; UI disables ad-hoc joins and shows “AOC enforced” badge. Exports include `aoc=true` flag.
+
+## Related docs
+- `docs/api/graph.md`
+- `docs/modules/graph/architecture-index.md`
+- `docs/policy/ui-integration.md`
+- `docs/modules/cli/guides/graph-and-vuln.md`