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

Restructure solution layout by module

Browse Source
This commit is contained in:
master
2025-10-28 15:10:40 +02:00
parent 95daa159c4
commit d870da18ce
4103 changed files with 192899 additions and 187024 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
src/Graph/StellaOps.Graph.Api/AGENTS.md Normal file
View File

@@ -0,0 +1,33 @@
# Graph API Guild Charter (Epic 5)
## Mission
Provide tenant-scoped Graph Explorer APIs for search, query, paths, diffs, overlays, and exports. Deliver cost-aware streaming endpoints that integrate with Policy Engine, Conseiller, Excitator, and the Graph Indexer while honoring AOC and RBAC.
## Scope
- Service under `src/Graph/StellaOps.Graph.Api` (Minimal API + streaming pipeline + query planner).
- Query validation/planning, cost estimation, tile streaming, overlay composition, export serializers.
- Integration with Authority scopes, Web API Gateway, Policy Engine explain endpoints, Graph Indexer storage.
- Saved query management and diff endpoints.
## Principles
1. **Bounded interactivity** – Enforce budgets (nodes, edges, time) per tenant and surface truncation clearly.
2. **Determinism** – Same query + seed yields same streamed content; maintain layout seeds for client.
3. **Security first** – RBAC enforced server-side; input validation, tenant isolation, query sanitization.
4. **AOC alignment** – API surfaces readonly data; overlays annotate Policy Engine outputs; never mutate facts.
5. **Observability** – Every query logs cost, latency, truncation, caching; metrics + traces integrated.
## Collaboration
- Maintain `src/Graph/StellaOps.Graph.Api/TASKS.md`, `../../docs/implplan/SPRINTS.md` alignment.
- Coordinate with Graph Indexer (storage contracts), Web Gateway, Console, CLI, Policy Engine, DevOps, and Docs teams.
- Publish OpenAPI + JSON schema for queries and streaming tiles.
## Tooling
- .NET 10 preview Minimal API with async streaming; pipeline pattern for parsing/planning/fetching.
- Mongo aggregation / adjacency store from Graph Indexer; optional caching layer.
- SSE/WebSockets or chunked NDJSON responses for progressive loading.
## Definition of Done
- APIs shipped with OpenAPI, unit/integration/load tests, budget enforcement.
- Metrics/logs/traces wired; dashboards seeded.
- Documentation updated (API doc, query schema, cost/limit guidance).
- Offline kit instructions include CLI + API usage.

16
src/Graph/StellaOps.Graph.Api/TASKS.md Normal file
View File

@@ -0,0 +1,16 @@
# Graph API Task Board — Epic 5: SBOM Graph Explorer
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| GRAPH-API-28-001 | TODO | Graph API Guild | GRAPH-INDEX-28-001, WEB-GRAPH-21-001 | Define OpenAPI + JSON schema for graph search/query/paths/diff/export endpoints, including cost metadata and streaming tile schema. | OpenAPI committed; schema validated via CI; clients regenerated; docs updated. |
| GRAPH-API-28-002 | TODO | Graph API Guild | GRAPH-API-28-001, GRAPH-INDEX-28-002 | Implement `/graph/search` with multi-type index lookup, prefix/exact match, RBAC enforcement, and result ranking + caching. | Endpoint returns ranked results within budget; tests cover scope errors + caching; metrics logged. |
| GRAPH-API-28-003 | TODO | Graph API Guild | GRAPH-API-28-001, GRAPH-INDEX-28-002..005 | Build query planner + cost estimator for `/graph/query`, stream tiles (nodes/edges/stats) progressively, enforce budgets, provide cursor tokens. | Query endpoint streams tiles deterministically, enforces budgets, surfaces truncation flags; integration tests cover large graphs. |
| GRAPH-API-28-004 | TODO | Graph API Guild | GRAPH-API-28-003 | Implement `/graph/paths` with depth ≤6, constraint filters, heuristic shortest path search, and optional policy overlay rendering. | Paths API returns expected routes; policy overlay applied; guardrails enforced; tests cover over-budget errors. |
| GRAPH-API-28-005 | TODO | Graph API Guild | GRAPH-INDEX-28-006, GRAPH-API-28-003 | Implement `/graph/diff` streaming added/removed/changed nodes/edges between SBOM snapshots; include overlay deltas and policy/VEX/advisory metadata. | Diff endpoint streams deterministic results; tests cover sample diffs; metrics record diff compute time. |
| GRAPH-API-28-006 | TODO | Graph API Guild | GRAPH-INDEX-28-002..005, POLICY-ENGINE-27-001 | Consume Policy Engine overlay contract (`POLICY-ENGINE-30-001..003`) and surface advisory/VEX/policy overlays with caching, partial materialization, and explain trace sampling for focused nodes. | Overlay pipeline delivers heatmap stats + explain samples; caches invalidate on policy/VEX/advisory change; tests cover concurrency. |
| GRAPH-API-28-007 | TODO | Graph API Guild | GRAPH-API-28-003..006 | Implement exports (`graphml`, `csv`, `ndjson`, `png`, `svg`) with async job management, checksum manifests, and streaming downloads. | Export job API returns manifest + download URLs; tests validate formats; docs updated. |
| GRAPH-API-28-008 | TODO | Graph API Guild, Authority Guild | AUTH-GRAPH-26-001, AUTH-GRAPH-21-001 | Integrate RBAC scopes (`graph:read`, `graph:query`, `graph:export`), tenant headers, audit logging, and rate limiting. | Unauthorized access rejected; audit logs include query hash & scope; rate limits enforced; integration tests pass; scope checks use `StellaOpsScopes` constants (no string literals). |
> 2025-10-26 — Waiting on Graph API host scaffolding. When endpoints land, ensure all scope enforcement relies on `StellaOpsScopes` before closing GRAPH-API-28-008.
| GRAPH-API-28-009 | TODO | Graph API Guild, Observability Guild | GRAPH-API-28-002..007 | Instrument metrics (`graph_tile_latency_seconds`, `graph_query_budget_denied_total`, `graph_overlay_cache_hit_ratio`), structured logs, and traces per query stage; publish dashboards. | Metrics exposed; dashboards live; alerts configured; docs updated. |
| GRAPH-API-28-010 | TODO | Graph API Guild, QA Guild | GRAPH-API-28-002..007 | Build unit/integration/load tests with synthetic datasets (500k nodes/2M edges), fuzz query validation, verify determinism across runs. | Test suite green; load test report captured; determinism harness passes with fixed seed. |
| GRAPH-API-28-011 | TODO | Graph API Guild, DevOps Guild | GRAPH-API-28-003..007 | Provide deployment manifests, offline kit support, API gateway integration docs, and smoke tests. | Deployment descriptors merged; gateway routes documented; offline kit instructions updated; smoke tests executed. |