# Scanner core contracts

Scanner core provides shared DTOs, identifiers, and observability helpers for the
Scanner web service, workers, and analyzers.

Canonical DTOs
- ScanJob and ScanJobStatus for job metadata and lifecycle.
- ScanProgressEvent for stage-level progress updates.
- ScannerError for structured error taxonomy and retry hints.
- ScanJobId for stable identifiers.

Determinism helpers
- ScannerIdentifiers generates job and correlation ids from normalized inputs.
- ScannerTimestamps normalizes to UTC and fixed precision.
- ScannerJsonOptions enforces consistent serialization.

Observability primitives
- ActivitySource and Meter with deterministic tags.
- Log scopes carry job and stage metadata for consistent tracing.

Security utilities
- Authority token caching for short-lived OpToks.
- DPoP proof validation with replay protection.
- Restart-only plugin guard for sealed deployments.

Testing expectations
- Golden fixtures validate JSON shape and determinism.
- Identifier and timestamp normalization tests run in CI.

Related references
- docs/scanner-core-contracts.md
- docs/modules/scanner/architecture.md