# 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.