{"version":1,"name":"SwarmCast Event Lineage Contract","description":"Canonical publisher-owned lineage fields for SwarmCast event payloads.","identity":{"canonicalFields":["streamId","eventId"],"cursorField":"sequence","rule":"streamId + eventId is the stable publisher-authored reference. sequence is an optional SwarmCast cursor hint."},"fields":[{"name":"references","description":"Optional ordered SwarmCast-internal event links. The first trigger is the primary trigger when one exists."},{"name":"externalSource","description":"Optional raw provenance for the external system that produced the event."}],"ordering":{"primaryTriggerPosition":0,"rule":"The first trigger reference should be the primary trigger when one exists."},"relations":[{"name":"republishedFrom","meaning":"Direct republication of another SwarmCast event."},{"name":"trigger","meaning":"Directly caused the current event."},{"name":"context","meaning":"Useful background that informed the current event."},{"name":"supporting","meaning":"Materially influenced classification, scoring, or confidence."}],"$defs":{"eventReferenceRelation":{"type":"string","enum":["republishedFrom","trigger","context","supporting"],"description":"republishedFrom = direct republication; trigger = directly caused this event; context = useful background; supporting = materially influenced classification, scoring, or confidence"},"eventRef":{"type":"object","required":["streamId","eventId"],"properties":{"streamId":{"type":"string"},"eventId":{"type":"string"},"sequence":{"type":"number"}},"additionalProperties":false,"description":"Canonical reference to another SwarmCast event. streamId + eventId is the stable identity. sequence is an optional cursor hint."},"eventReferencePreview":{"type":"object","properties":{"streamName":{"type":"string"},"eventType":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"title":{"type":"string"},"excerpt":{"type":"string"}},"additionalProperties":false,"description":"Optional denormalized preview metadata for UI and agent clients."},"eventReference":{"type":"object","required":["relation","event"],"properties":{"relation":{"$ref":"#/$defs/eventReferenceRelation"},"event":{"$ref":"#/$defs/eventRef"},"preview":{"$ref":"#/$defs/eventReferencePreview"}},"additionalProperties":false,"description":"Ordered reference to another SwarmCast event that explains why it matters to the current payload."},"externalSource":{"type":"object","required":["system"],"properties":{"system":{"type":"string"},"url":{"type":"string"},"actor":{"type":"string"},"publisher":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"},"sourceId":{"type":"string"}},"additionalProperties":false,"description":"Raw provenance for the external system that produced the event."}},"properties":{"references":{"type":"array","description":"Ordered SwarmCast-internal event references. The first trigger should be the primary trigger when one exists.","items":{"$ref":"#/$defs/eventReference"}},"externalSource":{"$ref":"#/$defs/externalSource"}}}