Documentation
¶
Overview ¶
Package federation provides types for cross-service graph exchange in the sem* ecosystem.
Federation types are an exchange format for graph entities between services (semsource, semspec, semdragon, etc.). Each EventPayload carries a single Entity with an ID and triples — implementing graph.Graphable so graph-ingest processes federation entities natively.
Key types:
- Entity: graph entity with ID, triples, and provenance
- Provenance: origin record for an entity or event
- Event: graph mutation event (SEED, DELTA, RETRACT, HEARTBEAT)
- EventPayload: message bus transport wrapper for Event, implements graph.Graphable
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ValidEventTypes = map[EventType]bool{ EventTypeSEED: true, EventTypeDELTA: true, EventTypeRETRACT: true, EventTypeHEARTBEAT: true, }
ValidEventTypes is the set of known event types for validation.
Functions ¶
func RegisterPayloads ¶
func RegisterPayloads(reg *payloadregistry.Registry, domain string) error
RegisterPayloads registers the federation event payload for a specific domain on the supplied registry. Each sem* service calls this with its own domain (e.g., "semsource", "semquery"). NOT included in payloadbuiltins.Register because it's domain-parameterized — callers know their domain at boot time.
Types ¶
type Entity ¶
type Entity struct {
// ID is the deterministic 6-part entity identifier.
ID string `json:"id"`
// Triples are the single source of truth for all semantic properties and relationships.
Triples []message.Triple `json:"triples"`
// Provenance records the origin of this entity.
Provenance Provenance `json:"provenance"`
}
Entity represents a normalized knowledge graph entity for cross-service exchange. It carries an ID and triples — the same data model as graph.Graphable. Relationships are encoded as triples, not as a separate edge structure.
The ID field is the 6-part entity identifier: org.platform.domain.system.type.instance which must be a valid NATS KV key.
type Event ¶
type Event struct {
// Type is the event type enum.
Type EventType `json:"type"`
// SourceID identifies the source that produced this event.
SourceID string `json:"source_id"`
// Namespace is the org namespace for this event (e.g., "acme", "public").
Namespace string `json:"namespace"`
// Timestamp is when the event was generated.
Timestamp time.Time `json:"timestamp"`
// Entity is the graph entity for SEED and DELTA events.
Entity Entity `json:"entity"`
// Retractions contains entity IDs to remove for RETRACT events.
Retractions []string `json:"retractions,omitempty"`
}
Event represents a single graph mutation event carrying one entity. Events flow between services over WebSocket for graph-ingest processing.
type EventPayload ¶
type EventPayload struct {
Event Event `json:"event"`
}
EventPayload implements message.Payload and graph.Graphable for federation graph events. It wraps Event for transport through the semstreams message bus. Because it implements Graphable, graph-ingest processes federation entities natively — no separate federation processor is needed.
func (*EventPayload) EntityID ¶
func (p *EventPayload) EntityID() string
EntityID implements graph.Graphable. Returns the 6-part entity identifier.
func (*EventPayload) MarshalJSON ¶
func (p *EventPayload) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler.
func (*EventPayload) Schema ¶
func (p *EventPayload) Schema() message.Type
Schema returns the message type for the Payload interface. The domain is set to "federation" as a default; consuming services register their own domain via RegisterPayload.
func (*EventPayload) Triples ¶
func (p *EventPayload) Triples() []message.Triple
Triples implements graph.Graphable. Returns the entity's triples.
func (*EventPayload) UnmarshalJSON ¶
func (p *EventPayload) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler.
func (*EventPayload) Validate ¶
func (p *EventPayload) Validate() error
Validate validates the payload for the Payload interface.
type EventType ¶
type EventType string
EventType is the type of a graph event emitted during federation.
const ( // EventTypeSEED is emitted on startup and consumer reconnect with a full graph snapshot. EventTypeSEED EventType = "SEED" // EventTypeDELTA is emitted for incremental upserts from watch events. EventTypeDELTA EventType = "DELTA" // EventTypeRETRACT is emitted when entities are explicitly removed. EventTypeRETRACT EventType = "RETRACT" // EventTypeHEARTBEAT is emitted during quiet periods as a liveness signal. EventTypeHEARTBEAT EventType = "HEARTBEAT" )
type Provenance ¶
type Provenance struct {
// SourceType identifies the class of source (e.g., "git", "ast", "url", "doc", "config").
SourceType string `json:"source_type"`
// SourceID is the unique identifier for the specific source instance.
SourceID string `json:"source_id"`
// Timestamp records when this provenance record was created.
Timestamp time.Time `json:"timestamp"`
// Handler is the name of the handler that produced this entity.
Handler string `json:"handler"`
}
Provenance records the origin of an entity or event.
Source Files