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

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.

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