stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 14 Releases Wiki Activity
Files
f43e828b4e21957636ce35cdaf50bb29da5d4e1d
git.stella-ops.org/src/Concelier/AGENTS.md
StellaOps Bot f43e828b4e
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat: Implement MongoDB orchestrator storage with registry, commands, and heartbeats 
- Added NullAdvisoryObservationEventTransport for handling advisory observation events.
- Created IOrchestratorRegistryStore interface for orchestrator registry operations.
- Implemented MongoOrchestratorRegistryStore for MongoDB interactions with orchestrator data.
- Defined OrchestratorCommandDocument and OrchestratorCommandRecord for command handling.
- Added OrchestratorHeartbeatDocument and OrchestratorHeartbeatRecord for heartbeat tracking.
- Created OrchestratorRegistryDocument and OrchestratorRegistryRecord for registry management.
- Developed tests for orchestrator collections migration and MongoOrchestratorRegistryStore functionality.
- Introduced AirgapImportRequest and AirgapImportValidator for air-gapped VEX bundle imports.
- Added incident mode rules sample JSON for notifier configuration.
2025-11-22 12:35:38 +02:00

4.1 KiB
Raw Blame History

Concelier · AGENTS Charter (Sprint 0112–0114)

Module Scope & Working Directory

  • Working directory: src/Concelier/** (WebService, __Libraries, Storage.Mongo, analyzers, tests, seed-data). Do not edit other modules unless explicitly referenced by this sprint.
  • Mission: Link-Not-Merge (LNM) ingestion of advisory observations, correlation into linksets, evidence/export APIs, and deterministic telemetry.

Roles

  • Backend engineer (ASP.NET Core / Mongo): connectors, ingestion guards, linkset builder, WebService APIs, storage migrations.
  • Observability/Platform engineer: OTEL metrics/logs, health/readiness, distributed locks, scheduler safety.
  • QA automation: Mongo2Go + WebApplicationFactory tests for handlers/jobs; determinism and guardrail regression harnesses.
  • Docs/Schema steward: keep LNM schemas, API references, and inline provenance docs aligned with behavior.

Required Reading (must be treated as read before setting DOING)

  • docs/README.md
  • docs/07_HIGH_LEVEL_ARCHITECTURE.md
  • docs/modules/platform/architecture-overview.md
  • docs/modules/concelier/architecture.md
  • docs/modules/concelier/link-not-merge-schema.md
  • docs/provenance/inline-dsse.md (for provenance anchors/DSSE notes)
  • docs/modules/concelier/prep/2025-11-22-oas-obs-prep.md (OAS + observability prep)
  • docs/modules/concelier/prep/2025-11-20-orchestrator-registry-prep.md (orchestrator registry/control contracts)
  • Any sprint-specific ADRs/notes linked from docs/implplan/SPRINT_0112_0001_0001_concelier_i.md, SPRINT_0113_0001_0002_concelier_ii.md, or SPRINT_0114_0001_0003_concelier_iii.md.

Working Agreements

  • Aggregation-Only Contract (AOC): no derived semantics in ingestion; enforce via AOCWriteGuard and analyzers. Raw observations are append-only; linksets carry correlations/conflicts only.
  • Determinism: use canonical JSON writer; sort collections (fieldType, observationPath, sourceId) for cache keys; UTC ISO-8601 timestamps; stable ordering in exports/events.
  • Offline-first: avoid new external calls outside allowlisted connectors; feature flags must default safe for air-gapped deployments (concelier:features:*).
  • Tenant safety: every API/job must enforce tenant headers/guards; no cross-tenant leaks.
  • Schema gates: LNM schema changes require docs + tests; update link-not-merge-schema.md and samples together.
  • Cross-module edits: none without sprint note; if needed, log in sprint Execution Log and Decisions & Risks.

Coding & Observability Standards

  • Target .NET 10; prefer latest C# preview features already enabled in repo.
  • Mongo driver ≥ 3.x; canonical BSON/JSON mapping lives in Storage.Mongo.
  • Metrics: use Meter names under StellaOps.Concelier.*; tag tenant, source, result as applicable. Counters/histograms must be documented.
  • Logging: structured, no PII; include tenant, source, job, correlationId when available.
  • Scheduler/locks: one lock per connector/export job; no duplicate runs; honor CancellationToken.

Testing Rules

  • Write/maintain tests alongside code:
    • Web/API: StellaOps.Concelier.WebService.Tests with WebApplicationFactory + Mongo2Go fixtures.
    • Core/Linkset/Guards: StellaOps.Concelier.Core.Tests.
    • Storage: StellaOps.Concelier.Storage.Mongo.Tests (use in-memory or Mongo2Go; determinism on ordering/hashes).
    • Observability/analyzers: tests in __Analyzers or respective test projects.
  • Tests must assert determinism (stable ordering/hashes), tenant guards, AOC invariants, and no derived fields in ingestion.
  • Prefer seeded fixtures under seed-data/ for repeatability; avoid network in tests.

Delivery Discipline

  • Update sprint tracker status (TODO → DOING → DONE/BLOCKED) when you start/finish/block work; mirror decisions in Execution Log and Decisions & Risks.
  • If a design decision is needed, mark the task BLOCKED in the sprint doc and record the decision ask—do not pause the codebase.
  • When changing contracts (APIs, schemas, telemetry, exports), update corresponding docs and link them from the sprint Decisions & Risks section.