up

src/StellaOps.Scanner.Core/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS
+## Role
+Provide shared scanner contracts, observability primitives, and security utilities consumed by the WebService, Worker, analyzers, and downstream tooling.
+## Scope
+- Canonical DTOs for scan jobs, progress, outcomes, and error taxonomy shared across scanner services.
+- Deterministic ID and timestamp helpers to guarantee reproducible job identifiers and ISO-8601 rendering.
+- Observability helpers (logging scopes, correlation IDs, metric naming, activity sources) with negligible overhead.
+- Authority/OpTok integrations, DPoP validation helpers, and restart-time plug-in guardrails for scanner components.
+## Participants
+- Scanner.WebService and Scanner.Worker depend on these primitives for request handling, queue interactions, and diagnostics.
+- Policy/Signer integrations rely on deterministic identifiers and timestamps emitted here.
+- DevOps/Offline kits bundle plug-in manifests validated via the guardrails defined in this module.
+## Interfaces & contracts
+- DTOs must round-trip via System.Text.Json with `JsonSerializerDefaults.Web` and preserve ordering.
+- Deterministic helpers must not depend on ambient time/randomness; they derive IDs from explicit inputs and normalize timestamps to microsecond precision in UTC.
+- Observability scopes expose `scanId`, `jobId`, `correlationId`, and `imageDigest` fields with `stellaops scanner` metric prefixing.
+- Security helpers expose `IAuthorityTokenSource`, `IDPoPProofValidator`, and `IPluginCatalogGuard` abstractions with DI-friendly implementations.
+## In/Out of scope
+In: shared contracts, telemetry primitives, security utilities, plug-in manifest checks.
+Out: queue implementations, analyzer logic, storage adapters, HTTP endpoints, UI wiring.
+## Observability & security expectations
+- No network calls except via registered Authority clients.
+- Avoid allocations in hot paths; prefer struct enumerables/`ValueTask`.
+- All logs structured, correlation IDs propagated, no secrets persisted.
+- DPoP validation enforces algorithm allowlist (ES256/ES384) and ensures replay cache hooks.
+## Tests
+- `../StellaOps.Scanner.Core.Tests` owns unit coverage with deterministic fixtures.
+- Golden JSON for DTO round-trips stored under `Fixtures/`.
+- Security and observability helpers must include tests proving deterministic outputs and rejecting malformed proofs.