up

docs/modules/excititor/observability/locker-manifest.md

@@ -0,0 +1,39 @@
+# Excititor Locker Manifest (OBS-53-001)
+
+Defines the manifest for evidence snapshots stored in Evidence Locker / sealed-mode bundles.
+
+## Manifest structure
+```json
+{
+  "tenant": "default",
+  "manifestId": "locker:excititor:2025-11-23:0001",
+  "createdAt": "2025-11-23T23:10:00Z",
+  "items": [
+    {
+      "observationId": "vex:obs:sha256:...",
+      "providerId": "ubuntu-csaf",
+      "contentHash": "sha256:...",
+      "linksetId": "CVE-2024-0001:pkg:maven/org.demo/app@1.2.3",
+      "dsseEnvelopeHash": "sha256:...",  
+      "provenance": {
+        "source": "mirror|ingest",
+        "mirrorGeneration": 12,
+        "exportCenterManifest": "sha256:..."
+      }
+    }
+  ],
+  "merkleRoot": "sha256:...",            // over `items[*].contentHash`
+  "signature": null,                       // populated in OBS-54-001 (DSSE)
+  "metadata": {"sealed": true}
+}
+```
+
+## Rules
+- `items` sorted by `observationId`, then `providerId`.
+- `merkleRoot` uses SHA-256 over concatenated item hashes (stable order above).
+- `signature` is a DSSE envelope (hash recorded in `dsseEnvelopeHash`) when OBS-54-001 is enabled; otherwise `null`.
+- Manifests are immutable; version using `manifestId` suffix.
+
+## Storage and replay
+- Store manifests alongside payloads in object storage; key prefix: `locker/excititor/<tenant>/<manifestId>`.
+- Replay tools must verify `merkleRoot` before loading payloads; reject if mismatched.

docs/modules/excititor/observability/timeline-events.md

@@ -0,0 +1,43 @@
+# Excititor Timeline Events (OBS-52-001)
+
+Defines the event envelope for evidence timelines emitted by Excititor. All fields are aggregation-only; no consensus/merge logic.
+
+## Envelope
+
+```json
+{
+  "type": "excititor.timeline.v1",
+  "tenant": "default",
+  "eventId": "urn:uuid:...",
+  "timestamp": "2025-11-23T23:10:00Z",
+  "traceId": "beefcafe...",
+  "spanId": "deadb33f...",
+  "source": "excititor.web",
+  "kind": "observation|linkset",
+  "action": "ingest|update|backfill|replay",
+  "observationId": "vex:obs:sha256:...",
+  "linksetId": "CVE-2024-0001:pkg:maven/org.demo/app@1.2.3",
+  "justifications": ["component_not_present"],
+  "conflicts": [
+    {"providerId": "suse-csaf", "status": "fixed", "justification": null}
+  ],
+  "evidenceHash": "sha256:...",        // content-addressed payload hash
+  "dsseEnvelopeHash": "sha256:...",    // if attested (see OBS-54-001)
+  "metadata": {"connector": "ubuntu-csaf", "mirrorGeneration": 12}
+}
+```
+
+## Semantics
+- `eventId` is stable per write; retries reuse the same ID.
+- `timestamp` must be UTC; derive from TimeProvider.
+- `traceId`/`spanId` propagate ingestion traces; if tracing is disabled, set both to `null`.
+- `kind` + `action` drive downstream storage and alerting.
+- `evidenceHash` is the raw document hash; `dsseEnvelopeHash` appears only when OBS-54-001 is enabled.
+
+## Determinism
+- Sort `justifications` and `conflicts` ascending by providerId/status before emit.
+- Emit at-most-once per storage write; idempotent consumers rely on `(eventId, tenant)`.
+
+## Transport
+- Default topic: `excititor.timeline.v1` (NATS/Redis). Subject includes tenant: `excititor.timeline.v1.<tenant>`.
+- Payload size should stay <32 KiB; truncate conflict arrays with `truncated=true` flag if needed (keep hash counts deterministic).