# AGENTS
## Role
Provide durable catalog and artifact storage for the Scanner plane, spanning Mongo catalog collections and MinIO object storage. Expose repositories and services used by WebService and Worker components to persist job state, image metadata, and exported artefacts deterministically.
## Scope
- Mongo collections: artifacts, images, layers, links, jobs, lifecycle_rules, migrations.
- Metadata documents: enforce majority write/read concerns, UTC timestamps, deterministic identifiers (SHA-256 digests, ULIDs for jobs).
- Bootstrapper: create collections + indexes (unique digests, compound references, TTL on lifecycle rules, sparse lookup helpers) and run schema migrations.
- Object storage (MinIO/S3): manage bucket layout (layers/, images/, indexes/, attest/), immutability policies, deterministic paths, and retention classes.
- Services: coordinate dual-write between Mongo metadata and MinIO blobs, compute digests, manage reference counts, and expose typed repositories for WebService/Worker interactions.
## Participants
- Scanner.WebService binds configuration, runs bootstrapper during startup, and uses repositories to enqueue scans, look up catalog entries, and manage lifecycle policies.
- Scanner.Worker writes job progress, uploads SBOM artefacts, and updates artefact reference counts.
- Policy / Notify consumers resolve artefact metadata for reports via catalog APIs once exposed.
## Interfaces & contracts
- Options configured via `ScannerStorageOptions` (Mongo + object store). `EnsureValid` rejects incomplete/unsafe configuration.
- Mongo access uses `IMongoDatabase` scoped with majority `ReadConcern`/`WriteConcern` and cancellation tokens.
- Object store abstraction (`IArtifactObjectStore`) encapsulates MinIO (S3) operations with server-side checksum validation and optional object-lock retain-until.
- Service APIs follow deterministic naming: digests normalized (`sha256:<hex>`), ULIDs sortable, timestamps ISO-8601 UTC.
## In/Out of scope
In: persistence models, bootstrap/migrations, catalog repositories, object storage client, retention helpers, dual-write coordination, deterministic digests.
Out: HTTP endpoints, queue processing, analyzer logic, SBOM composition, policy decisions, UI contracts.
## Observability & security expectations
- Emit structured logs for catalog/object-store writes including correlation IDs and digests.
- Guard against double writes; idempotent operations keyed by digests.
- Do not log credentials; redact connection strings. Honour cancellation tokens.
- Metrics hooks (pending) must expose duration counters for Mongo and MinIO operations.
## Tests
- Integration tests with ephemeral Mongo/MinIO stubs covering bootstrapper indexes, TTL enforcement, dual-write coordination, digest determinism, and majority read/write concerns.
