stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

docs consolidation work

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-25 18:48:11 +02:00
parent 2a06f780cf
commit 82a49f6743
102 changed files with 3550 additions and 1679 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/modules/graph/README.md
View File

@@ -60,3 +60,31 @@ Graph Indexer + Graph API build the tenant-scoped knowledge graph that powers bl
## Epic alignment
- **Epic 5 – SBOM Graph Explorer:** Graph Indexer, Graph API, saved queries, overlays, Console/CLI experiences, Offline Kit parity.
- Cross-epic ties: Policy reasoning (explain overlays), Scheduler recompute, Notify/Task Runner integration for graph incidents.
## Implementation Status
### Delivery Phases
- **Phase 1 – Graph Indexer foundations:** Stand up Graph Indexer service, node/edge schemas, ingestion from SBOM/Concelier/Excititor events, identity stability, snapshot materialisation
- **Phase 2 – Graph API service:** Expose search, query, path, impact, diff, and overlay endpoints with RBAC, cost controls, streaming responses
- **Phase 3 – Console & CLI experiences:** Ship Graph Explorer UI (WebGL canvas, filters, diff mode, overlays) and CLI for automation pipelines
- **Phase 4 – Advanced analytics:** Implement clustering, centrality, saved queries, overlay caching, Policy Engine explain integration
- **Phase 5 – Exports & offline:** Deliver GraphML/CSV/NDJSON exports, Offline Kit bundles with deterministic manifests
- **Phase 6 – Observability & hardening:** Complete dashboards, alerts, runbooks, load/perf testing, a11y review
### Acceptance Criteria
- Graph Indexer ingests SBOM/advisory/VEX events deterministically with tenant isolation and append-only provenance
- Graph API serves endpoints within budgeted latency and enforces cost limits + RBAC
- Console explorer visualises topology, overlays, diffs; CLI commands mirror functionality for automation
- Exports and Offline Kit bundles reproduce snapshots and overlays with signed manifests
- Observability dashboards/alerts detect ingest lag, query failures, cache churn, memory pressure; runbooks guide remediation
- Policy/VEX overlays align with Policy Engine explain traces and VEX suppressions
### Key Risks & Mitigations
- **Graph scale/complexity:** Adopt adjacency compression, cached overlays, streaming pagination, enforced query budgets
- **Tenant bleed:** Strict tenant filters, fuzz tests, data masking, compliance reviews
- **Runaway queries/visualization:** Cost planner, query timeout, UI hints, safe mode renders
- **Cache poisoning:** Input validation, schema versioning, eviction policies
- **Offline parity gaps:** Deterministic export pipeline, integration tests for Offline Kit import
### Current Active Sprint
- Runtime & Signals 140.A: Clustering/centrality jobs, incremental/backfill pipeline, determinism tests, packaging

65
docs/modules/graph/implementation_plan.md
View File

@@ -1,65 +0,0 @@
# Implementation plan — Graph
## Delivery phases
> Current active execution sprint: `docs/implplan/SPRINT_0141_0001_0001_graph_indexer.md` (Runtime & Signals 140.A).
- **Phase 1 – Graph Indexer foundations**
Stand up Graph Indexer service, node/edge schemas, ingestion from SBOM/Concelier/Excititor events, identity stability, and snapshot materialisation.
- **Phase 2 – Graph API service**
Expose search, query, path, impact, diff, and overlay endpoints with RBAC, cost controls, and streaming responses.
- **Phase 3 – Console & CLI experiences**
Ship Graph Explorer UI (WebGL canvas, filters, diff mode, overlays) and CLI (`stella sbom graph ...`) for automation pipelines.
- **Phase 4 – Advanced analytics**
Implement clustering, centrality, saved queries, overlay caching, and Policy Engine explain integration.
- **Phase 5 – Exports & offline**
Deliver GraphML/CSV/NDJSON exports, Offline Kit bundles (`nodes.jsonl`, `edges.jsonl`, overlays), and deterministic manifests.
- **Phase 6 – Observability & hardening**
Complete dashboards, alerts, runbooks, load/perf testing, and a11y/accessibility review.
## Work breakdown
- **Services**
- Graph Indexer: event consumers, node/edge builders, snapshot/version handling, aggregate metrics.
- Graph API: validation, planner/cost guard, streaming tile engine, diff/overlay builder, exports.
- Worker jobs: clustering, diff, overlay materialisation with backpressure awareness.
- **Data model & storage**
- Collections/tables (`graph_nodes`, `graph_edges`, `graph_snapshots`, `graph_saved_queries`, `graph_overlays_cache`), indexes, tenant partitioning, append-only change logs.
- Evaluate document + adjacency vs graph DB abstraction; ensure deterministic serialization for exports.
- **Console**
- Feature module `graph-explorer` with routes, canvas renderer, panels, diff UI, saved queries, export workflows, a11y pass.
- Telemetry instrumentation for user interactions and query budgets.
- **CLI & SDK**
- `stella sbom graph query|diff|impact|export`, with JSON schema and piping support.
- SDK utilities for automation and CI pipelines.
- **Policy & VEX integration**
- Fetch explain traces for policy overlays, integrate VEX suppressions, align with Policy Engine & VEX Lens data models.
- **Observability & Ops**
- Metrics (ingest lag, query latency, cache hit rate), log/traces, dashboards, alerting for runaway queries and OOM.
- Runbooks for incident classes (query denial, cache poisoning, degraded render).
- **Documentation**
- Maintain overview, API, query language, console guide, CLI reference, policy/VEX integration docs with compliance checklists.
## Acceptance criteria
- Graph Indexer ingests SBOM/advisory/VEX events deterministically with tenant isolation and append-only provenance.
- Graph API serves search/query/path/diff/overlay endpoints within budgeted latency and enforces cost limits + RBAC.
- Console explorer visualises topology, overlays, diffs, saved queries; CLI commands mirror functionality for automation.
- Exports (GraphML/CSV/NDJSON) and Offline Kit bundles reproduce snapshots and overlays with signed manifests.
- Observability dashboards/alerts detect ingest lag, query failures, cache churn, and memory pressure; runbooks guide remediation.
- Policy/VEX overlays align with Policy Engine explain traces and VEX suppressions.
## Risks & mitigations
- **Graph scale/complexity:** adopt adjacency compression, cached overlays, streaming pagination, enforced query budgets.
- **Tenant bleed:** strict tenant filters, fuzz tests, data masking, compliance reviews.
- **Runaway queries/visualization:** cost planner, query timeout, UI hints, safe mode renders.
- **Cache poisoning:** input validation, schema versioning, eviction policies.
- **Offline parity gaps:** deterministic export pipeline, integration tests for Offline Kit import.
## Test strategy
- **Unit:** node/edge builders, identifier stability, overlay computations, query planner, diff engine.
- **Integration:** end-to-end ingest + query flows across SBOM/advisory/VEX, saved query execution, diff exports.
- **Performance:** large SBOM datasets, concurrency, memory profiling, WebGL rendering.
- **Security:** tenant isolation tests, RBAC, query cost abuse.
- **Offline:** export/import verification, manifest hashing, CLI replay.
## Definition of done
- All phases delivered with telemetry, documentation, runbooks, and Offline Kit parity.
- Console/CLI parity validated; a11y review complete.
- ./TASKS.md and ../../TASKS.md updated; README/architecture/plan kept current with imposed rule references.