# AGENTS · Graph Module

## Purpose & Scope
- Working directories: `src/Graph/StellaOps.Graph.Api`, `src/Graph/StellaOps.Graph.Indexer`, and `src/Graph/__Tests`.
- Modules covered: Graph API (query/search/paths/diff/overlay/export) and Graph Indexer (ingest, snapshot, overlays).
- Applicable sprints: `docs/implplan/SPRINT_0207_0001_0001_graph.md`, `docs/implplan/SPRINT_0141_0001_0001_graph_indexer.md`, and any follow-on graph docs sprints (`docs/implplan/SPRINT_0321_0001_0001_docs_modules_graph.md`).

## Roles
- Backend engineer (.NET 10) — API, planners, overlays, exports.
- Data/ETL engineer — Indexer ingest, snapshots, overlays.
- QA/Perf engineer — deterministic tests, load/fuzz, offline parity.
- Docs maintainer — graph API/ops runbooks, Offline Kit notes.

## Required Reading (treat as read before DOING)
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/graph/architecture.md`
- `docs/modules/graph/implementation_plan.md`
- Sprint doc for current work (e.g., `docs/implplan/SPRINT_0207_0001_0001_graph.md`).
- Policy overlay contract refs when touching overlays: `POLICY-ENGINE-30-001..003` (see policy module docs).

## Determinism & Offline
- Default to deterministic ordering for streams/exports; manifest checksums required for `graphml/csv/ndjson` exports.
- Timestamps: UTC ISO-8601; avoid wall-clock in tests.
- Snapshot/export roots configurable via `STELLAOPS_GRAPH_SNAPSHOT_DIR` or `SbomIngestOptions.SnapshotRootDirectory`.
- Offline posture: no external calls beyond allowlisted feeds; prefer cached schemas and local nugets in `local-nugets/`.

## Data & Environment
- Canonical store: MongoDB (>=3.0 driver). Tests use `STELLAOPS_TEST_MONGO_URI`; fallback `mongodb://127.0.0.1:27017`, then Mongo2Go.
- Collections: `graph_nodes`, `graph_edges`, `graph_overlays_cache`, `graph_snapshots`, `graph_saved_queries`.
- Tenant isolation mandatory on every query and export.

## Testing Expectations
- Unit: node/edge builders, identifier stability, overlay calculators, planners, diff engine.
- Integration: ingest → snapshot → query/paths/diff/export end-to-end; RBAC + tenant guards.
- Performance: synthetic datasets (~500k nodes / 2M edges) with enforced budgets; capture latency metrics.
- Security: RBAC scopes (`graph:read/query/export`), audit logging, rate limiting.
- Offline: export/import parity for Offline Kit bundles; deterministic manifests verified in tests.

## Observability
- Metrics to emit: `graph_ingest_lag_seconds`, `graph_tile_latency_seconds`, `graph_query_budget_denied_total`, `graph_overlay_cache_hit_ratio`, clustering counters from architecture doc.
- Structured logs with trace IDs; traces for ingest stages and query planner/executor.

## Coding Standards
- Target framework: net10.0 with latest C# preview features.
- Use dependency injection; avoid static singletons.
- Respect module boundaries; shared libs only if declared in sprint or architecture docs.
- Naming: projects `StellaOps.Graph.Api`, `StellaOps.Graph.Indexer`; prefer `Graph*` prefixes for internal components.

## Coordination & Status
- Update sprint Delivery Tracker statuses (TODO → DOING → DONE/BLOCKED) in relevant sprint file.
- If a required contract/doc is missing or stale, mark the affected task BLOCKED in the sprint and log under Decisions & Risks; do not pause work waiting for live answers.

## Run/Test Commands (examples)
- Restore: `dotnet restore src/Graph/StellaOps.Graph.Api/StellaOps.Graph.Api.csproj --source ../local-nugets`
- Build: `dotnet build src/Graph/StellaOps.Graph.Api/StellaOps.Graph.Api.csproj -c Release`
- Tests: `dotnet test src/Graph/__Tests/StellaOps.Graph.Indexer.Tests/StellaOps.Graph.Indexer.Tests.csproj`
- Lint/style: follow repo-wide analyzers in `Directory.Build.props` / `.editorconfig`.

## Evidence
- Keep artefacts deterministic; attach manifest hashes in PR/sprint notes when delivering exports or snapshots.
- Document new metrics/routes/schemas under `docs/modules/graph` and link from sprint Decisions & Risks.