# Events and messaging

Platform services emit strongly typed events with JSON schemas. Event files
use the pattern <event-name>@<version>.json and samples mirror the version.

Envelope types
- Orchestrator events: versioned envelopes with idempotency keys and trace context.
- Legacy Redis envelopes: transitional schemas used for older consumers.

Event catalog (examples)
- scanner.event.report.ready@1 and scanner.event.scan.completed@1 (orchestrator envelopes).
- scanner.report.ready@1 and scanner.scan.completed@1 (legacy Redis envelopes).
- scheduler.rescan.delta@1, scheduler.graph.job.completed@1, attestor.logged@1.

Orchestrator envelope fields (v1)
- eventId, kind, version, tenant
- occurredAt, recordedAt
- source, idempotencyKey, correlationId
- traceId, spanId
- scope, payload, attributes

Legacy envelope fields
- eventId, kind, tenant, ts
- scope, payload, attributes

Versioning rules
- Additive changes stay in the same version.
- Breaking changes require a new @<version> schema and matching sample.
- Consumers should pin and log unknown versions.

Validation
- Schemas and samples live under docs/events/ and docs/events/samples/.
- Offline validation uses ajv-cli; keep schema checks deterministic.
- Validate schemas with ajv compile and validate samples against matching schemas.
- Add new samples for each new schema version.

Related references
- docs/events/README.md
- docs/runtime/SCANNER_RUNTIME_READINESS.md