stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
e91cf98f8fb87537bfa92de8ddfb7ba7fc602afe
git.stella-ops.org/src/Graph/AGENTS.md

4.2 KiB
Raw Blame History

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-archived/implplan/SPRINT_0207_0001_0001_graph.md, docs-archived/implplan/SPRINT_0141_0001_0001_graph_indexer.md, and follow-on graph documentation tracked in docs/modules/graph/architecture.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-archived/implplan/SPRINT_0207_0001_0001_graph.md
  • Sprint doc for current work (e.g., docs-archived/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 in .nuget/packages/.

Data & Environment

  • Storage is currently in-memory (MongoDB dependency removed); persistent backing store to be added in a follow-up sprint.
  • Collections (historical naming) graph_nodes, graph_edges, graph_overlays_cache, graph_snapshots, graph_saved_queries map to in-memory structures for now.
  • 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
  • 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.

Service Endpoints