# AGENTS
## Role
Canonical data model for normalized advisories and all downstream serialization. Source of truth for merge/export.
## Scope
- Canonical types: Advisory, AdvisoryReference, CvssMetric, AffectedPackage, AffectedVersionRange, AdvisoryProvenance.
- Invariants: stable ordering, culture-invariant serialization, UTC timestamps, deterministic equality semantics.
- Field semantics: preserve all aliases/references; ranges per ecosystem (NEVRA/EVR/SemVer); provenance on every mapped field.
- Backward/forward compatibility: additive evolution; versioned DTOs where needed; no breaking field renames.
- Detailed field coverage documented in `CANONICAL_RECORDS.md`; update alongside model changes.
## Participants
- Source connectors map external DTOs into these types.
- Merge engine composes/overrides AffectedPackage sets and consolidates references/aliases.
- Exporters serialize canonical documents deterministically.
## Interfaces & contracts
- Null-object statics: Advisory.Empty, AdvisoryReference.Empty, CvssMetric.Empty.
- AffectedPackage.Type describes semantics (e.g., rpm, deb, cpe, semver). Identifier is stable (e.g., NEVRA, PURL, CPE).
- Version ranges list is ordered by introduction then fix; provenance identifies source/kind/value/recordedAt.
- Alias schemes must include CVE, GHSA, OSV, JVN/JVNDB, BDU, VU(CERT/CC), MSRC, CISCO-SA, ORACLE-CPU, APSB/APA, APPLE-HT, CHROMIUM-POST, VMSA, RHSA, USN, DSA, SUSE-SU, ICSA, CWE, CPE, PURL.
## In/Out of scope
In: data shapes, invariants, helpers for canonical serialization and comparison.
Out: fetching/parsing external schemas, storage, HTTP.
## Observability & security expectations
- No secrets; purely in-memory types.
- Provide debug renders for test snapshots (canonical JSON).
- Emit model version identifiers in logs when canonical structures change; keep adapters for older readers until deprecated.
## Tests
- Author and review coverage in `../StellaOps.Feedser.Models.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Feedser.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.

