advisory.observation.updated@1 · Event contract

Purpose: unblock CONCELIER-GRAPH-21-002 by freezing the platform event shape for observation changes emitted by Concelier. This is the only supported event for observation churn; downstreams subscribe for evidence fan-out and replay bundles.

Envelope & transport

Subject: concelier.advisory.observation.updated.v1
Type/version: advisory.observation.updated@1
Transport: NATS (primary), Redis Stream concelier:advisory.observation.updated:v1 (fallback). Both carry the same DSSE envelope.
DSSE payloadType: application/vnd.stellaops.advisory.observation.updated.v1+json.
Signature: Ed25519 via Platform Events signer; attach Rekor UUID when available. Offline kits treat the envelope as the source of truth.

Payload (JSON)

Field	Type	Rules
`eventId`	string (uuid)	Generated by publisher; idempotency key.
`tenantId`	string	`urn:tenant:{uuid}`; required for multi-tenant routing.
`observationId`	string (ObjectId)	Mongo `_id` of the observation document.
`advisoryId`	string	Upstream advisory identifier (e.g., CVE, GHSA, vendor id).
`source`	object	`{ vendor, stream, api, collectorVersion }`; lowercase vendor, non-empty.
`linksetSummary`	object	`{ aliases: string[], purls: string[], cpes?: string[], scopes?: string[], relationships?: object[] }` all arrays pre-sorted ASCII.
`supersedesId`	string (ObjectId, optional)	Previous observation `_id` if this is a new revision; omitted otherwise.
`documentSha`	string	SHA-256 of raw upstream document.
`observationHash`	string	Stable hash over canonicalized observation JSON (tenant, source, advisoryId, documentSha, fetchedAt).
`ingestedAt`	string (ISO-8601 UTC)	Timestamp when appended.
`traceId`	string (optional)	Propagated from ingest job/request; aids join with logs/metrics.
`replayCursor`	string	Monotone cursor for offline bundle ordering (tick from change stream resume token).

Determinism & ordering

Arrays sorted ASCII; objects field-sorted when hashing.
eventId + replayCursor provide exactly-once consumer handling; duplicates must be ignored when observationHash unchanged.
No judgments: only raw facts and hash pointers; any derived severity/merge content is forbidden.

Error contracts for Scheduler

Retryable NATS/Valkey failures use backoff capped at 30s; after 5 attempts, emit concelier.events.dlq with the same envelope and error field describing transport failure.
Consumers must NACK on schema validation failure; publisher logs ERR_EVENT_SCHEMA and quarantines the offending observation id.

Sample payload

See advisory.observation.updated@1.sample.json (canonical field order, ASCII sorted arrays). Hashes intentionally short for readability; replace with real values in tests.

Schema

advisory.observation.updated@1.schema.json provides a JSON Schema (draft 2020-12) for runtime validation; any additional fields are rejected.

Compatibility note

Sprint tracker referenced sbom.observation.updated; this contract standardises on advisory.observation.updated@1. If a legacy alias is required for interim consumers, mirror the envelope on subject surface.sbom.observation.updated.v1 with identical payload.

3.2 KiB Raw Blame History