Update

docs/events/README.md

@@ -20,12 +20,13 @@ All event envelopes share the same deterministic header. Use the following table
 | `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. |
+| `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. |
+| `attributes` | `object` | Optional metadata bag (`string` keys/values) for downstream correlation (e.g., pipeline identifiers). Omit when unused to keep payloads concise. |
 
 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.
+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 unit tests (`ReportSamplesTests`, `PlatformEventSchemaValidationTests`) guard that payloads stay canonical and continue to satisfy the published schemas.
 
 Run the following loop offline to validate both schemas and samples:
 

docs/events/attestor.logged@1.json

@@ -8,8 +8,8 @@
     "kind": {"const": "attestor.logged"},
     "tenant": {"type": "string"},
     "ts": {"type": "string", "format": "date-time"},
-    "payload": {
-      "type": "object",
+    "payload": {
+      "type": "object",
       "required": ["artifactSha256", "rekor", "subject"],
       "properties": {
         "artifactSha256": {"type": "string"},
@@ -30,9 +30,14 @@
             "name": {"type": "string"}
           }
         }
-      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}
+      },
+      "additionalProperties": true
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional event attributes for downstream correlation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

docs/events/scanner.report.ready@1.json

@@ -17,10 +17,10 @@
         "digest": {"type": "string"}
       }
     },
-    "payload": {
-      "type": "object",
-      "required": ["verdict", "delta", "links"],
-      "properties": {
+    "payload": {
+      "type": "object",
+      "required": ["verdict", "delta", "links"],
+      "properties": {
         "reportId": {"type": "string"},
         "generatedAt": {"type": "string", "format": "date-time"},
         "verdict": {"enum": ["pass", "warn", "fail"]},
@@ -76,9 +76,14 @@
           },
           "additionalProperties": false
         }
-      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}
+      },
+      "additionalProperties": true
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional event attributes for downstream correlation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

docs/events/scanner.scan.completed@1.json

@@ -17,8 +17,8 @@
         "digest": {"type": "string"}
       }
     },
-    "payload": {
-      "type": "object",
+    "payload": {
+      "type": "object",
       "required": ["reportId", "digest", "verdict", "summary"],
       "properties": {
         "reportId": {"type": "string"},
@@ -90,8 +90,13 @@
           "additionalProperties": false
         }
       },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}
+      "additionalProperties": true
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional event attributes for downstream correlation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

docs/events/scheduler.rescan.delta@1.json

@@ -8,8 +8,8 @@
     "kind": {"const": "scheduler.rescan.delta"},
     "tenant": {"type": "string"},
     "ts": {"type": "string", "format": "date-time"},
-    "payload": {
-      "type": "object",
+    "payload": {
+      "type": "object",
       "required": ["scheduleId", "impactedDigests", "summary"],
       "properties": {
         "scheduleId": {"type": "string"},
@@ -26,8 +26,13 @@
           }
         }
       },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}
+      "additionalProperties": true
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional event attributes for downstream correlation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}