Documentation
¶
Overview ¶
Package federation provides types for cross-service graph exchange in the sem* ecosystem.
Federation types are an exchange format for graph events between services (semsource, semspec, semdragon, etc.). They carry explicit entities, edges, and provenance chains for namespace-sovereign merge operations.
This is distinct from graph.EntityState, which is the internal storage format using triple-based representation in NATS KV. Use ToEntityState and FromEntityState for bidirectional conversion between the two representations.
Key types:
- Entity: normalized graph entity with triples, edges, and provenance
- Edge: directed relationship between two entities
- Provenance: origin record for an entity or event
- Event: graph mutation event (SEED, DELTA, RETRACT, HEARTBEAT)
- EventPayload: message bus transport wrapper for Event
- Store: thread-safe in-memory store with content-based change detection
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 NewFederationMessageType ¶
NewFederationMessageType creates a message.Type for federation events. This is a convenience for use with ToEntityState.
func RegisterPayload ¶
RegisterPayload registers the federation event payload for a specific domain. Each sem* service calls this with its own domain (e.g., "semsource", "semquery"). This enables domain-specific message routing while sharing the same payload structure.
func ToEntityState ¶
func ToEntityState(entity Entity, msgType message.Type) *graph.EntityState
ToEntityState converts a federation Entity to a graph.EntityState.
Conversion rules:
- Entity.Triples are copied directly (same message.Triple type)
- Each Edge becomes a relationship triple with predicate "federation.edge.{EdgeType}"
- Non-zero edge weights become a separate triple with predicate "federation.edge.{EdgeType}.weight"
- Primary provenance is stored as a "federation.provenance.source_type" triple
The msgType parameter sets EntityState.MessageType for downstream consumers.
Types ¶
type Edge ¶
type Edge struct {
// FromID is the source entity's 6-part ID.
FromID string `json:"from_id"`
// ToID is the target entity's 6-part ID.
ToID string `json:"to_id"`
// EdgeType describes the semantic relationship (e.g., "authored_by", "imports", "calls").
EdgeType string `json:"edge_type"`
// Weight is an optional edge weight (0.0 = unweighted, positive = weighted).
Weight float64 `json:"weight,omitempty"`
// Properties holds any additional edge metadata.
Properties map[string]any `json:"properties,omitempty"`
}
Edge represents a directed relationship between two graph entities.
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.
Triples []message.Triple `json:"triples"`
// Edges represent explicit relationships to other entities.
Edges []Edge `json:"edges,omitempty"`
// Provenance records the primary (most recent) origin of this entity.
Provenance Provenance `json:"provenance"`
// AdditionalProvenance accumulates provenance records from prior merges.
// The federation processor appends previous Provenance here on each merge.
// This field is always appended, never replaced.
AdditionalProvenance []Provenance `json:"additional_provenance,omitempty"`
}
Entity represents a normalized knowledge graph entity for cross-service exchange. It carries triples, explicit edges, and provenance for federation merge operations.
The ID field is the 6-part entity identifier: org.platform.domain.system.type.instance which must be a valid NATS KV key.
func FromEntityState ¶
func FromEntityState(state *graph.EntityState, provenance Provenance) Entity
FromEntityState converts a graph.EntityState back to a federation Entity.
Conversion rules:
- Triples with "federation.edge.{EdgeType}" predicate are extracted as Edges
- Triples with "federation.edge.{EdgeType}.weight" predicate set edge weights
- All other triples are preserved as-is
- The provenance parameter becomes the Entity's primary provenance
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"`
// Entities contains graph entities for SEED and DELTA events.
Entities []Entity `json:"entities,omitempty"`
// Retractions contains entity IDs to remove for RETRACT events.
Retractions []string `json:"retractions,omitempty"`
// Provenance records the event origin.
Provenance Provenance `json:"provenance"`
}
Event represents a single graph mutation event. Events flow between services through NATS JetStream for federation merge operations.
type EventPayload ¶
type EventPayload struct {
Event Event `json:"event"`
}
EventPayload implements message.Payload for federation graph events. It wraps Event for transport through the semstreams message bus.
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) 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.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a goroutine-safe in-memory store for Entity values. It uses content-based change detection to avoid spurious DELTA events.
func (*Store) Get ¶
Get returns the entity with the given ID, or nil if not found. The returned entity is a deep copy — mutations do not affect the store.
func (*Store) Remove ¶
Remove deletes the entity with the given ID from the store. Returns true if the entity existed and was removed; false if not found.
func (*Store) Snapshot ¶
Snapshot returns a copy of all entities currently in the store. The returned slice is independent of the store — mutations do not affect the store.
func (*Store) SnapshotMap ¶
SnapshotMap returns a map of entity ID → *Entity for all stored entities. Useful for passing to Merger.ApplyEvent as the existing store. The returned map and entities are deep copies.
Source Files