Documentation
¶
Overview ¶
Package inference derives an entity's hierarchy statements from its 6-part ID (org.platform.system.domain.type.instance, ADR-102).
HierarchyInference is called by graph-ingest when an entity is born, and built only when graph-ingest's enable_hierarchy is set. For each of the three levels (type, taxonomy, source) AddToContainers makes sure the level's container entity exists, creating it through an EntityStore when it does not, and returns the entity's membership statement for the caller to write with the entity. A container that exists is not written: its stored value does not change when a member is born. Every statement names graph-ingest's hierarchy producer (graph.SourceHierarchy) as its source and carries the time of the write that triggered it. If any part fails, AddToContainers returns an error and no statements, so the caller can refuse the birth. An entity of another deployment, and a container, get no hierarchy.
ContainerEntity is the payload a container entity is born with; its type, graph.hierarchy_container.v1, is registered by RegisterPayloads.
Index ¶
- func HierarchyContainerMessageType() message.Type
- func RegisterPayloads(reg *payloadregistry.Registry) error
- type ContainerEntity
- func (e *ContainerEntity) EntityID() string
- func (e *ContainerEntity) MarshalJSON() ([]byte, error)
- func (e *ContainerEntity) Schema() message.Type
- func (e *ContainerEntity) Triples() []message.Triple
- func (e *ContainerEntity) UnmarshalJSON(data []byte) error
- func (e *ContainerEntity) Validate() error
- type EntityStore
- type HierarchyInference
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HierarchyContainerMessageType ¶
HierarchyContainerMessageType returns the message.Type graph-ingest stamps on the hierarchy container entities it births — key "graph.hierarchy_container.v1". Registered by RegisterPayloads, which a consumer or test calls on its payload registry, with floor control (ADR-103, O-16 (a)): the framework's own in-process writer passes the same registered-type gate as every other birth. Transitional until gh606 retires containers; the registration retires with them.
func RegisterPayloads ¶
func RegisterPayloads(reg *payloadregistry.Registry) error
RegisterPayloads registers graph.hierarchy_container.v1 with the supplied registry. A consumer calls it on the registry it gives graph-ingest, at process bootstrap, and a test on the registry it builds; graph-ingest refuses to construct with hierarchy enabled unless its registry holds this type.
Types ¶
type ContainerEntity ¶
ContainerEntity is the verbatim Graphable carrier for a hierarchy container: EntityID() is the field and Triples() returns the facts unchanged.
func (*ContainerEntity) EntityID ¶
func (e *ContainerEntity) EntityID() string
EntityID implements graph.Graphable.
func (*ContainerEntity) MarshalJSON ¶
func (e *ContainerEntity) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler with the alias idiom.
func (*ContainerEntity) Schema ¶
func (e *ContainerEntity) Schema() message.Type
Schema implements message.Payload.
func (*ContainerEntity) Triples ¶
func (e *ContainerEntity) Triples() []message.Triple
Triples implements graph.Graphable: the facts, verbatim.
func (*ContainerEntity) UnmarshalJSON ¶
func (e *ContainerEntity) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler with the alias idiom.
func (*ContainerEntity) Validate ¶
func (e *ContainerEntity) Validate() error
Validate implements message.Payload: the carried ID must be a well-formed entity ID.
type EntityStore ¶
type EntityStore interface {
// CreateEntity writes entity under its ID, refusing an ID the store holds
// with natsclient.ErrKVKeyExists. The inference reads that refusal as the
// container existing.
CreateEntity(ctx context.Context, entity *gtypes.EntityState) error
}
EntityStore is the entity storage the inference creates containers in. graph-ingest implements it.
type HierarchyInference ¶
type HierarchyInference struct {
// contains filtered or unexported fields
}
HierarchyInference creates membership edges to container entities based on the 6-part entity ID structure. It operates synchronously - hierarchy triples are computed and returned before the entity is written to storage.
Entity ID format: org.platform.system.domain.type.instance (ADR-102). Example: acme.iot.hvac.sensors.temperature.001
Containers are built from the NAMED prefix levels, not fixed indexes:
- Type container: <TypePrefix>.group (level 5 + padding)
- Taxonomy container: <TaxonomyPrefix>.group.container (level 4 + padding)
- Source container: <SourcePrefix>.group.container.level (level 3 + padding)
Graph distances via containers:
- Same type: 2 hops (entity → type.group ← entity)
- Same taxonomy, different type: 4 hops
- Same source, different taxonomy: 6 hops
A caller with hierarchy off builds none: there is no disabled inference. This is a stateless utility - no lifecycle methods (Start/Stop).
func NewHierarchyInference ¶
func NewHierarchyInference(store EntityStore, platform types.PlatformMeta, logger *slog.Logger) (*HierarchyInference, error)
NewHierarchyInference builds the inference over store for the deployment whose authority is platform, graph-ingest's deps.Platform. An entity whose positions 1-2 differ is an imported mirror, and AddToContainers mints NOTHING for it (no container, no membership triple), because the framework never mints under a foreign authority (ADR-102). An empty pair could only read every entity as foreign and mint nothing, forever, so it is refused here rather than on every call. A nil logger is slog.Default.
func (*HierarchyInference) AddToContainers ¶
func (h *HierarchyInference) AddToContainers(ctx context.Context, entityID string, at time.Time) ([]message.Triple, error)
AddToContainers adds an entity being born to its three containers (type, taxonomy, source). For each one it:
- creates the container if storage does not hold it (a write);
- returns the entity's membership statement, entity → member → container, which it does not write: the caller writes the returned statements with the entity.
It writes nothing to a container that exists, so a container's stored value does not change when a member is born: there is no inverse contains edge (ruling M, #91 comment 6080973822; #145), and membership is read from the forward edges on each member. Nor does it write a sibling edge between entities of one type (ruling G, #91 comment 6062681355). The hierarchy.*.contains predicates and vocabulary.HierarchyTypeSibling stay registered in vocabulary.
Every statement it returns or writes, a new container's type statement included, names graph.SourceHierarchy as its source and carries at, the time of the write that triggered the inference, never the clock (design D15). A zero at is refused.
If any part fails (a container's birth), it returns every failure joined and no statements, so the caller refuses the birth (design D21). Containers born before the failure are found by the next attempt, which births only those still absent.
It returns no statements, and writes nothing, for an invalid entity ID, a container, or an entity carrying a FOREIGN authority (an imported mirror, ADR-102). A nil context is refused as invalid before the ID is read.