advisory.linkset.updated@1 · Event contract

Purpose: unblock CONCELIER-LNM-21-005 by freezing the platform event shape for linkset changes emitted by Concelier. This is the only supported event for linkset churn; downstreams subscribe for graph overlays, policy evaluations, and replay bundles.

Envelope & transport

Subject: concelier.advisory.linkset.updated.v1
Type/version: advisory.linkset.updated@1
Transport: NATS (primary), Redis Stream concelier:advisory.linkset.updated:v1 (fallback). Both carry the same DSSE envelope.
DSSE payloadType: application/vnd.stellaops.advisory.linkset.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.
`linksetId`	string (ObjectId)	Mongo `_id` of the linkset document.
`advisoryId`	string	Upstream advisory identifier (e.g., CVE, GHSA, vendor id).
`source`	string	Linkset source/adapter identifier (lowercase).
`observationIds`	string[]	Array of observation ObjectIds included in this linkset; sorted ASCII.
`delta`	object	Change description: `{ type, observationsAdded, observationsRemoved, confidenceChanged, conflictsChanged }`.
`confidence`	number (0–1, nullable)	Correlation confidence score; null if not computed.
`conflicts`	object[]	Array of `{ field, reason, sourceIds[] }` conflict summaries; sorted by field then reason.
`provenance`	object	`{ observationHashes[], toolVersion?, policyHash? }` for replay/audit.
`createdAt`	string (ISO-8601 UTC)	Timestamp when linkset was built.
`replayCursor`	string	Monotone cursor for offline bundle ordering (tick from createdAt).
`builtByJobId`	string (optional)	Job ID that built this linkset.
`traceId`	string (optional)	Propagated from ingest job/request; aids join with logs/metrics.

Delta object

Field	Type	Rules
`type`	string	`"created"` or `"updated"`.
`observationsAdded`	string[]	Observation IDs added since previous version.
`observationsRemoved`	string[]	Observation IDs removed since previous version.
`confidenceChanged`	boolean	True if confidence score changed.
`conflictsChanged`	boolean	True if conflicts array changed.

Determinism & ordering

Arrays sorted ASCII; objects field-sorted when hashing.
eventId + replayCursor provide exactly-once consumer handling; duplicates must be ignored when observation hashes unchanged.
No judgments: only raw facts, delta descriptions, and provenance 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 linkset id.

Sample payload

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "urn:tenant:acme-corp",
  "linksetId": "6744abcd1234567890abcdef",
  "advisoryId": "CVE-2024-1234",
  "source": "nvd",
  "observationIds": ["674400001234567890abcdef", "674400001234567890abcde0"],
  "delta": {
    "type": "created",
    "observationsAdded": ["674400001234567890abcdef", "674400001234567890abcde0"],
    "observationsRemoved": [],
    "confidenceChanged": true,
    "conflictsChanged": false
  },
  "confidence": 0.85,
  "conflicts": [],
  "provenance": {
    "observationHashes": ["sha256:abc123", "sha256:def456"],
    "toolVersion": "1.0.0",
    "policyHash": null
  },
  "createdAt": "2025-11-27T12:00:00.000Z",
  "replayCursor": "638688000000000000",
  "builtByJobId": "job-12345",
  "traceId": "trace-67890"
}

Schema

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

Implementation (LNM-21-005)

Event type defined in StellaOps.Concelier.Core.Linksets.AdvisoryLinksetUpdatedEvent.
Publisher interface: IAdvisoryLinksetEventPublisher.
Outbox interface: IAdvisoryLinksetEventOutbox.
Configuration: AdvisoryLinksetEventPublisherOptions.

Change control

Add-only. Adjusting delta types or conflict codes requires new version advisory.linkset.updated@2 and a sprint note.