inference

package
v0.1.0-alpha.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 13 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func HierarchyContainerMessageType

func HierarchyContainerMessageType() message.Type

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 (SemStreams ADR-103): the framework's own in-process writer passes the same registered-type gate as every other birth. It is transitional: the registration retires with the hierarchy containers.

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

type ContainerEntity struct {
	ID    string           `json:"id"`
	Facts []message.Triple `json:"facts"`
}

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:

  1. creates the container if storage does not hold it (a write);
  2. 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, and membership is read from the forward edges on each member. Nor does it write a sibling edge between entities of one type. 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. 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. 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL