git.stella-ops.org/src/Graph/StellaOps.Graph.Indexer/AGENTS.md

Graph Indexer Guild Charter (Epic 5)

Mission

Project SBOM, advisory, VEX, and policy overlay data into a tenant-scoped property graph powering the SBOM Graph Explorer. Own ingestion pipelines, node/edge storage, aggregates, clustering, and snapshot lineage.

Scope

• Service source under src/Graph/StellaOps.Graph.Indexer (workers, ingestion pipelines, schema builders).
• In-memory graph storage for graph_nodes, graph_edges, graph_snapshots, clustering metadata (Mongo removed; durable store to follow).
• Event consumers: SBOM ingest, Conseiller advisories, Excitor VEX, Policy overlay materials.
• Incremental rebuild, diff, and cache warmers for graph overlays.

Principles

1. Immutability – Graph mirrors SBOM snapshots; new data creates new snapshots rather than mutating historical records.
2. Determinism – Given identical inputs, node/edge ids, hashes, and aggregates remain stable across runs.
3. Tenant isolation – Enforce isolation at ingestion, storage, and job levels; no cross-tenant leakage.
4. AOC alignment – Indexer links facts; it never mutates advisories/VEX/policy outcomes. Conseiller/Excitor/Policy Engine remain authoritative.
5. Performance & telemetry – Every job emits metrics (latency, node/edge counts, queue lag) and structured logs.

Collaboration

• Keep src/Graph/StellaOps.Graph.Indexer/TASKS.md, /docs/implplan/SPRINT_*.md synchronized.
• Coordinate with SBOM Service, Policy Engine, Conseiller, Excitor, Scheduler, Web Gateway, and Console teams.
• Publish schema docs and fixtures for clients; share cost/identity conventions across services.

Tooling

• .NET 10 preview workers (HostedService + channel pipelines).
• In-memory node/edge storage (Mongo removed); S3-compatible buckets for layout tiles/snapshots if needed.
• Scheduler integration (jobs, change streams) to handle incremental updates.
• Analytics: clustering/centrality pipelines with in-memory snapshot provider and overlays; change-stream/backfill worker with in-memory idempotency store and retry/backoff.

Definition of Done

• Pipelines deterministic and tested; fixtures validated.
• Metrics/logs/traces wired with tenant context.
• Schema docs + OpenAPI (where applicable) updated; compliance checklist appended.
• Offline kit includes seed data for air-gapped installs, including analytics overlays (overlays/*.ndjson with manifest) ordered deterministically.

Required Reading

• docs/modules/graph/architecture.md
• docs/modules/platform/architecture-overview.md

Working Agreement

• 1. Update task status to DOING/DONE in both correspoding sprint file /docs/implplan/SPRINT_*.md and the local TASKS.md when you start or finish work.
• 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
• 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
• 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
• 5. Revert to TODO if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.