Resolve Concelier/Excititor merge conflicts

docs/events/README.md

@@ -0,0 +1,65 @@
+# Event Envelope Schemas
+
+Platform services publish strongly typed events; the JSON Schemas in this directory define those envelopes. File names follow `<event-name>@<version>.json` so producers and consumers can negotiate contracts explicitly.
+
+## Catalog
+- `scanner.report.ready@1.json` — emitted by Scanner.WebService once a signed report is persisted (payload embeds the canonical report plus DSSE envelope). Consumers: Notify, UI timeline.
+- `scanner.scan.completed@1.json` — emitted alongside the signed report to capture scan outcomes/summary data for downstream automation. Consumers: Notify, Scheduler backfills, UI timelines.
+- `scheduler.rescan.delta@1.json` — emitted by Scheduler when BOM-Index diffs require fresh scans. Consumers: Notify, Policy Engine.
+- `attestor.logged@1.json` — emitted by Attestor after storing the Rekor inclusion proof. Consumers: UI attestation panel, Governance exports.
+
+Additive payload changes (new optional fields) can stay within the same version. Any breaking change (removing a field, tightening validation, altering semantics) must increment the `@<version>` suffix and update downstream consumers.
+
+## Envelope structure
+All event envelopes share the same deterministic header. Use the following table as the quick reference when emitting or parsing events:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `eventId` | `uuid` | Must be globally unique per occurrence; producers log duplicates as fatal. |
+| `kind` | `string` | Fixed per schema (e.g., `scanner.report.ready`). Downstream services reject unknown kinds or versions. |
+| `tenant` | `string` | Multi‑tenant isolation key; mirror the value recorded in queue/Mongo metadata. |
+| `ts` | `date-time` | RFC 3339 UTC timestamp. Use monotonic clocks or atomic offsets so ordering survives retries. |
+| `scope` | `object` | Optional block used when the event concerns a specific image or repository. See schema for required fields (e.g., `repo`, `digest`). |
+| `payload` | `object` | Event-specific body. Schemas allow additional properties so producers can add optional hints (e.g., `reportId`, `quietedFindingCount`) without breaking consumers. For scanner events, payloads embed both the canonical report document and the DSSE envelope so consumers can reuse signatures without recomputing them. See `docs/runtime/SCANNER_RUNTIME_READINESS.md` for the runtime consumer checklist covering these hints. |
+
+When adding new optional fields, document the behaviour in the schema’s `description` block and update the consumer checklist in the next sprint sync.
+
+## Canonical samples & validation
+Reference payloads live under `docs/events/samples/`, mirroring the schema version (`<event-name>@<version>.sample.json`). They illustrate common field combinations, including the optional attributes that downstream teams rely on for UI affordances and audit trails. Scanner samples reuse the exact DSSE envelope checked into `samples/api/reports/report-sample.dsse.json`, and a unit test (`ReportSamplesTests`) guards that the payload/base64 remain canonical.
+
+Run the following loop offline to validate both schemas and samples:
+
+```bash
+# Validate schemas (same check as CI)
+for schema in docs/events/*.json; do
+  npx ajv compile -c ajv-formats -s "$schema"
+done
+
+# Validate canonical samples against their schemas
+for sample in docs/events/samples/*.sample.json; do
+  schema="docs/events/$(basename "${sample%.sample.json}").json"
+  npx ajv validate -c ajv-formats -s "$schema" -d "$sample"
+done
+```
+
+Consumers can copy the samples into integration tests to guarantee backwards compatibility. When emitting new event versions, include a matching sample and update this README so air-gapped operators stay in sync.
+
+## CI validation
+The Docs CI workflow (`.gitea/workflows/docs.yml`) installs `ajv-cli` and compiles every schema on pull requests. Run the same check locally before opening a PR:
+
+```bash
+for schema in docs/events/*.json; do
+  npx ajv compile -c ajv-formats -s "$schema"
+done
+```
+
+Tip: run `npm install --no-save ajv ajv-cli ajv-formats` once per clone so `npx` can resolve the tooling offline.
+
+If a schema references additional files, include `-r` flags so CI and local runs stay consistent.
+
+## Working with schemas
+- Producers should validate outbound payloads using the matching schema during unit tests.
+- Consumers should pin to a specific version and log when encountering unknown versions to catch missing migrations early.
+- Store real payload samples under `docs/events/samples/` (mirrors the schema version) and mirror them into `samples/events/` when you need fixtures in integration repositories.
+
+Contact the Platform Events group in Docs Guild if you need help shaping a new event or version strategy.