graph

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

README

Graph Package

The data model and the wire types of SemEngine's entity graph. The package imports no NATS client: a reader of a graph type does not pull in the transport to get it (graph-transport-boundary, "The graph root imports no transport"; TestGraphImportsNoTransport).

What the package holds

  • The data model. EntityState is one entity's stored state: its 6-part ID (org.platform.system.domain.type.instance, the key in the ENTITY_STATES bucket), its statements (message.Triple), an optional StorageRef, the MessageType that last wrote it, and UpdatedAt, the store's write time. It carries no version number of its own: the bucket's key-value revision is the only concurrency fence (graph-entity-writes, "The revision is the only fence"). A stored value written with a version key still decodes.
  • The replace rule, a pure function with no I/O. ReplaceBySource treats the statements of one (subject, predicate, source) as one set: an arriving set replaces only the stored set of its own key, and a set older than the stored one (by Timestamp) is not applied and is reported in ReplaceResult.Stale. Confidence and Context never decide whether a write applies.
  • The single-value reads. A predicate may hold statements from several sources. EntityState.GetTriple and EntityState.GetPropertyValue pick the same statement every time: the latest Timestamp; on equal timestamps, the Source that sorts first; on equal sources, the first stored. A reader that wants another choice reads Triples.
  • The reserved sources. SourceIndexingProfile, SourceHierarchy and SourceLifecycle are the names graph-ingest and pkg/lifecycle write their own statements under; IsReservedSource recognises them.
  • The state contract. MarshalEntityState is the validating encoder for stored entities and UnmarshalEntityState the validating decoder. StateContractError carries the "graph state reset required" failure across a request and its reply, and IsStateContractError recognises it. Entity-ID prefixes and the predicate token codec sit beside them.
  • Bucket names. The Bucket* constants name the graph's buckets. The catalog that describes and acquires them is graph/kvcatalog. A product that needs the full list of framework buckets calls kvcatalog.KVCatalog(): it returns a copy of every descriptor, so editing the result changes nothing the framework resolves.
  • The wire types. The query request and reply types, the mutation requests and responses (ReconcilePredicatesRequest names the one source it reconciles), ExactEntity and ExactEntityReader for the authority read, and IndexStatusResponse, the readiness envelope a producer writes to GRAPH_STATUS. Its state field is an IndexState, one of the four IndexState* constants that IndexStates() lists. The computation that fills the envelope is in graph/readiness.
  • The query reply envelope. Replies on graph.ingest.query.* are not enveloped. Replies on graph.index.query.* are a QueryResponse: the verb's result in data, the ENTITY_STATES revision it reflects in indexed_revision, and the answering component in producer; NewQueryResponse refuses an empty producer. On graph.query.* the shape depends on the verb: entity, batch, prefix, prefixIDs and hierarchyStats are bare, and byName, predicate, entityByAlias, relationships, pathSearch, summary, localSearch, globalSearch, searchGraph, semantic, similar, spatial and temporal are enveloped. A caller decodes by the verb's table row (QueryVerb.Enveloped, and QueryVerb.Reply for the type of the body or of data), never by the reply's content.
  • Reading at a revision. A request on an enveloped verb may carry min_revision (MinRevisionField), the kv_revision of a write the answer must include. An index that has not reached it refuses with transient revision_not_reached (ErrorCodeRevisionNotReached), the revision it reached in the detail, and does not wait. The bare verbs ignore the field.
  • The verb table. QueryVerbs declares the request/reply verbs, each with its subject and responder: graph-ingest's entity, batch, prefix and prefixIDs on graph.ingest.query.*, and graph-index's eight verbs (outgoing, incoming, alias, predicate, predicateList, predicateStats, predicateCompound, byName) on graph.index.query.*, the four verbs of the embedding, spatial and temporal responders (search and similar on graph.embedding.query.*, bounds on graph.spatial.query.*, range on graph.temporal.query.*), graph-lexical's word search on graph.lexical.query.* (processor/graph-lexical), and graph-query's entity, batch, prefix, prefixIDs, byName, predicate, entityByAlias, relationships, pathSearch, hierarchyStats, summary, localSearch, globalSearch, searchGraph, semantic, similar, spatial and temporal on graph.query.*. A name is unique only within its responder: entity is declared for graph-ingest and for graph-query. Each row also marks Enveloped and gives the Reply type. The embedding responder is in the tree (processor/graph-embedding). The spatial and temporal responders are not, so those two rows name a responder that does not exist, and graph-query's spatial and temporal forwards and its globalSearch time-range and area strategies are refused transient internal. A verb a consumer serves under graph.query.* is not in the table. QueryVerbs' doc comment names each verb's request and reply types.
  • Local search. LocalSearchRequest names an entity (entity_id), a level from 0 to 2 and a query of 1 to MaxSearchTerms (32) distinct words, and the search runs in that entity's community: the group of entities that share the first 4, 3 or 2 parts of its ID. LocalSearchData is the reply: the community's record (community_id, level, member_count, community_summary, keywords), the matching entities best first, entities_scanned, entities_truncated and an answer sentence. The matches come from one page of at most 1,000 entities in ID order, so on a larger group they are the best of the lexically smallest IDs. EntitiesTruncated is true when the page had more to read or matches were left out to fit max_payload.
  • Global search. GlobalSearchRequest is a query (required, not blank), a level (0 to 2, omitted means 0, read only by the text strategy) and min_revision; any other key is refused. The verbs globalSearch and searchGraph take it and reply with the same GlobalSearchData: strategy (entity, path, temporal, spatial or text) and exactly one field holding that strategy's result as read: entity (the entity verb's reply bytes), path (a PathSearchData), temporal (a TemporalData), spatial (a SpatialData) or text (a TextSearchData). TextSearchData holds the groups read (TextSearchGroup: community_id, member_count, community_summary, keywords), the matches (TextSearchMatch: id, label, score and the entity as the page sent it), entities_scanned, entities_truncated (true when the matches are a sample), unreadable_groups, unhonoured_hints (the hints the text search could not apply: path, similarity, ranking) and an answer sentence. TemporalRangeRequest (start_time and end_time, RFC 3339, limit, min_revision) and SpatialBoundsRequest (north, south, east, west, limit, min_revision) are what graph-query sends to the time-range and bounds verbs, and so what the responders decode; SemStreams spelled the times startTime and endTime. Which questions each strategy answers, and what is refused, is in processor/graph-query/README.md.
  • Counts. PrefixQueryResponse.Total is the number of distinct keys in the listing before the cursor and any limit, as listed and not a snapshot. HierarchyStatsData and SummaryData build on one prefix page: TotalEntities is the whole group, EntitiesScanned, Truncated and NextCursor say how much of it this page covers, and the type counts or children cover that page and no more. Truncated false says only that it is the last page. When summary leaves predicates out (ExcludePredicates), its indexed_revision is 0, which claims nothing: do not compare it with a kv_revision.
Entity Identification

All entity IDs use the 6-part federated format defined in types.EntityID (pkg/types) (canonical order, ADR-102: org.platform = the minting deployment authority, system = the source, domain.type = a delegated taxonomy):

org.platform.system.domain.type.instance

Example: c360.telemetry.mavlink.robotics.drone.42

To parse entity IDs and extract type information:

eid, err := message.ParseEntityID(state.ID)
if err != nil {
    return fmt.Errorf("invalid entity ID: %w", err)
}

entityType := eid.Type      // "drone"
system := eid.System        // "mavlink"
instance := eid.Instance    // "42"

Graphable Interface

The Graphable interface enables domain payloads to self-declare their entities and relationships:

type Graphable interface {
    EntityID() string                  // Returns 6-part federated ID
    Triples() []message.Triple        // Returns all facts about this entity
}

Why it's here: Components implementing graph integration naturally import graph/ to find contracts. This interface defines how payloads transform into graph-compatible data.

Example Implementation
type PositionPayload struct {
    SystemID  uint8   `json:"system_id"`
    Latitude  float64 `json:"latitude"`
    Longitude float64 `json:"longitude"`
    Altitude  float32 `json:"altitude"`
}

func (p *PositionPayload) EntityID() string {
    return fmt.Sprintf("acme.telemetry.robotics.mavlink.drone.%d", p.SystemID)
}

func (p *PositionPayload) Triples() []message.Triple {
    entityID := p.EntityID()
    return []message.Triple{
        {Subject: entityID, Predicate: "geo.location.latitude", Object: p.Latitude},
        {Subject: entityID, Predicate: "geo.location.longitude", Object: p.Longitude},
        {Subject: entityID, Predicate: "geo.location.altitude", Object: p.Altitude},
    }
}

Design Principles

One-Way Transformation

Graphable → EntityState is a one-way transformation at message ingestion time:

  1. Domain payload implements Graphable interface
  2. Graphable.Triples() generates triples at runtime from payload fields
  3. EntityState persists those triples in NATS KV storage
  4. No reverse transformation (storage → payload) is supported or needed
Triple-Based Storage

Properties, relationships, and domain-specific data are all stored as RDF-like triples:

Triple{
    Subject:   "c360.telemetry.robotics.mavlink.drone.42",
    Predicate: "geo.location.latitude",
    Object:    34.052235,
}

This provides maximum flexibility while maintaining semantic clarity.

What is elsewhere

  • graph/kvcatalog: the bucket catalog, its acquisition, the owned-bucket retention check and the write-guard pair (IsFrameworkOwnedBucket, FrameworkOwnedWriteRefusal) the rule engine reads once the rule engine is ported.
  • natsclient: IsKVTombstone, which reports whether a KV watch entry is a delete or a purge.
  • graph/readiness: the readiness computation and the GRAPH_STATUS publisher.
  • graph/inference: hierarchy inference (its hierarchy slice).

Import

import "github.com/c360studio/semengine/graph"

Documentation

Overview

Package graph holds the data model and the wire types of SemEngine's entity graph. It imports no NATS client, so code that only reads a graph type does not pull in the transport.

The data model is EntityState, one entity's stored state in the ENTITY_STATES bucket, and Graphable, the interface a payload implements to declare its entity and statements. Beside them sit the write rules (ReplaceBySource), the validating encoder and decoder for stored entities (MarshalEntityState, UnmarshalEntityState), StateContractError for state that must be reset, the entity-ID prefix helpers, the predicate codec, and the Bucket* names.

The wire types are the request and reply bodies of the graph's request/reply subjects: the query types (QueryVerbs declares the verbs each responder answers, whether its reply is a QueryResponse, and the reply's type, for graph-ingest, graph-index, graph-query and the embedding, spatial and temporal responders), the mutation requests and responses, ExactEntity with its reader, and IndexStatusResponse, the readiness envelope stored in GRAPH_STATUS. A request/reply body is identified by the subject it travels on, so these types are not registered in the payload registry.

Three sub-packages hold the rest: graph/kvcatalog describes and opens the buckets, graph/readiness computes and publishes the readiness envelope, and graph/inference infers hierarchy statements.

Index

Constants

View Source
const (
	// Primary entity storage
	BucketEntityStates = "ENTITY_STATES"

	// Graph relationship indexes
	BucketPredicateIndex = "PREDICATE_INDEX"
	BucketIncomingIndex  = "INCOMING_INDEX"
	BucketOutgoingIndex  = "OUTGOING_INDEX"

	// Lookup indexes
	BucketAliasIndex = "ALIAS_INDEX"
	// BucketNameIndex maps a normalized (case-folded) human-readable name/title
	// to the entities carrying it, for deterministic name→ranked-IDs lookup
	// (graph.query.byName). Complements ALIAS_INDEX, which excludes display-name
	// (AliasTypeLabel) predicates.
	BucketNameIndex     = "NAME_INDEX"
	BucketSpatialIndex  = "SPATIAL_INDEX"
	BucketTemporalIndex = "TEMPORAL_INDEX"
	// BucketTemporalIndexReverse maps entityID -> current temporal bucket key.
	// It lets graph-index-temporal remove an entity's stale event from its prior
	// time bucket when the entity is re-indexed (observed-time changed) or deleted,
	// so a range query never returns an entity from a bucket it has since left.
	BucketTemporalIndexReverse = "TEMPORAL_INDEX_REVERSE"

	// Semantic tier buckets
	BucketEmbeddingIndex = "EMBEDDING_INDEX"
	BucketEmbeddingDedup = "EMBEDDING_DEDUP"
	BucketCommunityIndex = "COMMUNITY_INDEX"
	// BucketCommunitySummaries holds LLM-generated community summaries, written
	// ONLY by the graph-clustering enhancement worker and keyed by
	// {level}.{membership_hash} (content-addressed). It is deliberately SEPARATE
	// from COMMUNITY_INDEX: the detector owns the partition (COMMUNITY_INDEX),
	// the worker owns the LLM prose (this bucket), so a lagging worker can never
	// clobber a fresher partition or resurrect a Prune-deleted community (ADR-087).
	BucketCommunitySummaries = "COMMUNITY_SUMMARIES"

	// BucketGraphIngestAppliedSeq is graph-ingest's SemStreams ADR-072 redelivery-guard
	// durable tier: `(entityID/streamName) → (stream generation, last-applied
	// stream sequence)`.
	// Created and owned exclusively by graph-ingest (processor/graph-ingest);
	// a member of FrameworkOwnedBuckets so a generic rule update_kv cannot forge
	// a sequence stamp and silently reopen the redelivery overwrite the guard
	// closes. It is correctness-critical no-eviction state, so the retention sweep
	// covers it.
	BucketGraphIngestAppliedSeq = "GRAPH_INGEST_APPLIED_SEQ"
	// BucketSemEngineConfig is the PREFIX of the runtime configuration bucket
	// family. Each deployment's bucket is named by its declared authority pair,
	// "semengine_config_<org>_<stem>", derived only by config.BucketName; the
	// bare name is not a member. The family is in the catalog because the
	// framework guarantees BOTH its retention and its write-ownership: under
	// ADR-104 each member holds the create-once platform identity record, which
	// must never be evicted and must never be forged.
	//
	// config.Manager is its only acquirer. It is still owner-only, because
	// ownership is about who may NOT write: the rule engine, not in SemEngine
	// yet, is to refuse a generic update_kv into any member through
	// kvcatalog.IsFrameworkOwnedBucket.
	BucketSemEngineConfig = "semengine_config"

	// BucketGraphStatus is the ADR-083 readiness distribution bucket. Producers
	// (graph-index, graph-embedding, graph-ingest, and rule) write their liveness
	// envelope; consumers watch it to answer "(status, fresh|unknown)". It is the
	// single source of truth for the bucket name — graph/readiness re-exports this constant. Its catalog
	// descriptor declares History 3 (readiness replay depth) and no lifecycle
	// retention; the acquisition seam and backstop strip only MaxAge/MaxBytes and
	// leave History untouched.
	BucketGraphStatus = "GRAPH_STATUS"

	// BucketStorageReport is the account storage report
	// (storage-observability): ONE KEY PER INVENTORIED RESOURCE, carrying that
	// resource's attribution, capacity, growth rate, projection, and pressure
	// state, written by the storage collector each collection. Every
	// operator-facing surface reads it rather than recomputing an inventory, so
	// there is one produced truth and no two surfaces can disagree.
	//
	// A resource that disappears from the account has its key DELETED by the
	// collector — a semantic decision, never an expiry — which is why its
	// catalog descriptor declares no-lifecycle retention like the rest of the
	// graph. Its bounded History is the restart-surviving growth series.
	BucketStorageReport = "STORAGE_REPORT"
)

Bucket name constants for NATS KV storage

View Source
const (
	// ErrorCodeRevisionMismatch indicates the request specified an
	// ExpectedRevision that didn't match the entity's current KV
	// revision at the time of write. Callers (notably
	// pkg/lifecycle.Manager.Transition) use this to drive
	// read-validate-retry loops.
	ErrorCodeRevisionMismatch = errs.CodeRevisionMismatch

	// ErrorCodeEntityNotFound indicates the request targeted an
	// entity ID that does not exist in ENTITY_STATES. For
	// update-style requests this means the entity was never created
	// or was deleted concurrently.
	ErrorCodeEntityNotFound = "entity_not_found"

	// ErrorCodeEntityExists indicates a create-style request hit an
	// entity ID that already exists. Used by entity.create to surface
	// strict-create conflicts.
	ErrorCodeEntityExists = "entity_already_exists"

	// ErrorCodeInvalidRequest indicates the request envelope failed
	// pre-write validation (nil entity, malformed JSON, etc.).
	// Callers should not retry without fixing the request.
	ErrorCodeInvalidRequest = "invalid_request"

	// ErrorCodeStructuralInvalid indicates a token in the mutation violated the
	// structural-identity contract — an entity ID that is not exactly 6 parts, or a
	// predicate that is not exactly 3 parts (domain.category.property). The token is
	// malformed at its source; callers must fix the token, not retry. Emitted by the
	// graph-ingest structural gate when enforcement is on.
	ErrorCodeStructuralInvalid = "structural_invalid"

	// ErrorCodeMessageTypeUnregistered indicates an entity.create stamped a
	// message_type the receiving binary's payload registry does not hold
	// (SemStreams ADR-103: the registry is the single type authority). Class invalid; the
	// caller registers the type, it does not retry. Detail carries the key under
	// "message_type". Emitted by graph-ingest's registered-type gate on both
	// create paths (the RPC lane and the in-process CreateEntity).
	ErrorCodeMessageTypeUnregistered = "message_type_unregistered"

	// ErrorCodeInternal is the catch-all for handler-internal
	// failures (KV transport errors, unmarshal failures on stored
	// state, etc.). Callers may retry as appropriate.
	ErrorCodeInternal = "internal"

	// ErrorCodeResourceExhausted indicates a query would exceed a server-side read
	// budget — e.g. a byName lookup on a name shared by more entities than the
	// hydration cap. The caller should narrow the query rather than retry unchanged.
	ErrorCodeResourceExhausted = "resource_exhausted"

	// ErrorCodeIndexNotReady indicates a query arrived while the serving index was not
	// SOUND to read from — the responder or its watcher is unavailable, the index is
	// degraded by an unresolved required write, or it has not finished its initial
	// build. While a keyset is still materialising, serving it would advertise a
	// smaller graph than exists.
	//
	// NOT emitted for ordinary revision lag (ADR-084). A healthy index that is merely
	// behind SERVES, reporting its view age as staleness_ms on the readiness envelope,
	// because coverage is not evidence of soundness and gating on it would make every
	// write burst look like a fault. Probe health with
	// `nats kv get GRAPH_STATUS graph-index` and read `state` + `bootstrap_complete` —
	// NOT the `ready` bit, which answers coverage and is false on any busy index.
	//
	// Callers retrying it should retry with backoff against the health question, and a
	// caller that needs "is MY write visible?" should not use this code at all: compare
	// the kv_revision its mutation returned against the envelope's indexed_revision,
	// which is the one sound per-entity check (ADR-084).
	ErrorCodeIndexNotReady = errs.CodeIndexNotReady

	// ErrorCodeEmbeddingUnavailable indicates a similarity/embedding query targeted
	// a SOURCE entity that has no usable embedding to query FROM — the entity has no
	// embedding record, its embedding is not yet generated (status != generated), or
	// its stored vector is empty. It is a PER-ENTITY miss, NOT a producer-wide index
	// fault: the embedding index itself is sound (contrast ErrorCodeIndexNotReady),
	// this one source entity simply has no vector yet (e.g. an aggregation/group
	// entity never projected through the embedder). Class is ErrorInvalid.
	//
	// Emitted by graph-embedding's similar verb (handleSimilar). A caller may read it
	// as a definitive "this entity has no semantic neighbors" and fail open to an
	// empty set, distinct from a malformed / unknown reply, which it should count as
	// a failure rather than cache as a hollow empty. Consumers classify by this stable
	// code, never by the message text.
	ErrorCodeEmbeddingUnavailable = "embedding_unavailable"

	// ErrorCodeNotEnabled indicates the composition turned the verb off: graph-query
	// was not configured with embedding_enabled true, so it answers no semantic or
	// similar request. Every request is refused alike, unlike embedding_unavailable,
	// which is one source entity with no vector, and index_not_ready, which is an
	// index still catching up. Retrying does not help. Class is ErrorInvalid; the
	// message names the verb.
	//
	// Sent by graph-query's semantic and similar verbs. Consumers classify by this
	// stable code, never by the message text.
	ErrorCodeNotEnabled = "not_enabled"

	// ErrorCodeAliasAmbiguous indicates an alias query named an alias that two or
	// more distinct entities carry, so no one entity answers it. Rows of one entity
	// under several alias predicates are one holder and answer that entity. Class is
	// ErrorInvalid; the message names the alias (ADR-114 §3).
	//
	// Emitted by graph-index's alias verb. The refusal holds while the alias is
	// shared: once all but one holder drops the alias or is deleted, and graph-index
	// has indexed that change, the same request answers the remaining holder.
	// Consumers classify by this stable code, never by the message text.
	ErrorCodeAliasAmbiguous = "alias_ambiguous"

	// ErrorCodeRevisionNotReached indicates a query's min_revision is above the
	// revision its reply would carry, on an index that is otherwise sound to read
	// (contrast ErrorCodeIndexNotReady). Class is ErrorTransient; the detail's
	// indexed_revision names the revision reached, and the caller may retry.
	//
	// Emitted by graph-index's verbs and relayed unchanged by graph-query.
	// Consumers classify by this stable code, never by the message text.
	ErrorCodeRevisionNotReached = "revision_not_reached"
)

Stable failure codes carried by *errs.ClassifiedError.Code (ADR-060). A caller reads one with errors.As(err, &ce) and ce.Code; revision_mismatch also matches errs.ErrRevisionMismatch through errors.Is.

Who emits them in this module: graph-ingest's mutation handlers and query verbs emit revision_mismatch, entity_not_found, entity_already_exists, invalid_request, structural_invalid (its stream lane only), message_type_unregistered and internal; the exact reader emits invalid_request and internal; index_not_ready comes from natsclient's OpenFrameworkBucket and pkg/lifecycle's queries. embedding_unavailable is emitted by processor/graph-embedding's similar verb. not_enabled is sent by processor/graph-query's semantic and similar verbs. resource_exhausted is emitted by processor/graph-index's name verb. graph-ingest counts each refused canonical mutation on graph_mutation_outcomes_total under its code, or internal when it carries none.

View Source
const (
	// MaxPathSearchDepth is the largest max_depth a request may send.
	MaxPathSearchDepth = 10
	// MaxPathSearchNodes is the largest max_nodes a request may send.
	MaxPathSearchNodes = 500
	// DefaultPathSearchNodes is what a max_nodes of 0 means.
	DefaultPathSearchNodes = 100
)

Limits of the pathSearch verb. A request over one is refused, stating the bound, rather than clamped: a clamped depth would be silent and truncated would stop being exact.

View Source
const (
	// DefaultSimilarityLimit is what a semantic, similar or word search request's limit of 0 means.
	DefaultSimilarityLimit = 10
	// MaxSimilarityLimit is the largest limit a semantic, similar or word search request may send; a
	// larger or negative one is refused, never clamped.
	MaxSimilarityLimit = 100
)
View Source
const (
	// SourceIndexingProfile names the indexing-profile statement graph-ingest
	// stamps at an entity's birth (SemStreams ADR-054).
	SourceIndexingProfile = "graph-ingest-indexing-profile"
	// SourceHierarchy names the hierarchy statements graph-ingest derives, and
	// the statements of the containers it creates for them.
	SourceHierarchy = "graph-ingest-hierarchy"
	// SourceLifecycle names every statement pkg/lifecycle's manager writes.
	SourceLifecycle = "semengine-lifecycle"
)

The reserved sources: the names graph-ingest and pkg/lifecycle write their own statements under. A stream message may not carry a statement under one of them (graph-entity-writes, "Statement metadata is required"), so no producer on the stream can replace their sets; the mutation lane accepts them, since pkg/lifecycle writes there under its own.

View Source
const ErrorCodeGraphStateResetRequired = "graph_state_reset_required"

ErrorCodeGraphStateResetRequired is the cross-component code for authoritative ENTITY_STATES that cannot be interpreted by the running graph contract.

View Source
const MaxPrefixQueryLimit = 1000

MaxPrefixQueryLimit is the maximum number of entities returned per page. A limit of zero or less, or over 1000, means 1000. The active NATS max_payload ceiling is the binding byte constraint: graph-ingest fits the complete encoded response, including continuation, against the observed connection limit.

View Source
const MaxSearchTerms = 32

MaxSearchTerms is the most distinct words a search query may hold, counted by the word index (graph/lexical's ParseQuery) after tokenizing, plain, phrase and excluded words together. A longer query is refused, never cut. 32 takes a pasted error line, which runs to about 20 words, while bounding the work one search does.

View Source
const ResponderGraphEmbedding = "graph-embedding"

ResponderGraphEmbedding is the Responder of the embedding verbs, answered by processor/graph-embedding.

View Source
const ResponderGraphIndex = "graph-index"

ResponderGraphIndex is the Responder of the verbs graph-index answers.

View Source
const ResponderGraphIndexSpatial = "graph-index-spatial"

ResponderGraphIndexSpatial is the Responder of the spatial verb, whose component arrives with a later change.

View Source
const ResponderGraphIndexTemporal = "graph-index-temporal"

ResponderGraphIndexTemporal is the Responder of the temporal verb, whose component arrives with a later change.

View Source
const ResponderGraphIngest = "graph-ingest"

ResponderGraphIngest is the Responder of the verbs graph-ingest answers.

View Source
const ResponderGraphLexical = "graph-lexical"

ResponderGraphLexical is the Responder of the word search verb, answered by processor/graph-lexical.

View Source
const ResponderGraphQuery = "graph-query"

ResponderGraphQuery is the Responder of the verbs graph-query answers.

Variables

This section is empty.

Functions

func DecodePredicateToken

func DecodePredicateToken(token string) (string, bool)

DecodePredicateToken reverses EncodePredicateToken. Returns (predicate, true) on success, ("", false) when the token is not valid hex (a malformed key token the caller should skip rather than surface as data).

func EncodePredicateToken

func EncodePredicateToken(predicate string) string

EncodePredicateToken hex-encodes a predicate for use as a single key token in the INCOMING / NAME / CONTEXT composite-key reverse indexes.

Canonical predicates are validated before persistence and are NATS-key-safe, but their three semantic segments contain two dots. Encoding the raw predicate in a composite key would consume three physical tokens and change the fixed token positions and arity used by INCOMING / NAME / CONTEXT filters.

Hex (not a hash) is deliberate: it is reversible, so a reader reconstructs the exact predicate from the key with no per-row value lookup — keeping INCOMING a pure prefix key-scan on its hot path. Hex is a fixed-alphabet ([0-9a-f]), dot-free encoding, so an encoded predicate is always exactly one KV-safe token. This is only a physical codec; it provides no compatibility path and does not weaken canonical predicate validation.

Shared here (not in the graph-index package) because graph-clustering and other reverse-index readers reconstruct these keys and must decode with the identical codec.

func IsReservedSource

func IsReservedSource(source string) bool

IsReservedSource reports whether source is one of the reserved sources, compared exactly.

func IsStateContractError

func IsStateContractError(err error) bool

IsStateContractError reports whether err carries the shared authoritative graph-reset contract, either as the in-process typed cause or as the stable classified code reconstructed across request/reply.

func MarshalEntityState

func MarshalEntityState(entity *EntityState) ([]byte, error)

MarshalEntityState is the authoritative in-process ENTITY_STATES persistence seam. It validates the complete final candidate before serialization.

func MatchesAnyIDPrefix

func MatchesAnyIDPrefix(id string, prefixes []string) bool

MatchesAnyIDPrefix reports whether a dot-delimited entity ID falls under any of the given ID prefixes (OR-matched). An empty/nil prefixes slice means "no filter" and matches every ID, the convention of the []string type-filter surfaces (ADR-071).

Matching is on a dot boundary: id matches prefix p iff id == p or id has the literal prefix p+"." So prefix "c360.semspec.source.doc" matches "c360.semspec.source.doc" and "c360.semspec.source.doc.readme" but NOT "c360.semspec.source.docker.compose" — a prefix must end on a segment boundary, never mid-segment. This mirrors the dot-prefix convention on PrefixQueryRequest (the server appends the trailing dot when it filters), so the deterministic prefix query and the NL scope filter share ONE matcher and their semantics cannot drift.

An empty string element inside a non-empty slice is treated as an explicit match-all (consistent with empty=no-filter), not as "matches only the empty ID".

func UnmarshalEntityState

func UnmarshalEntityState(key string, data []byte, entity *EntityState) error

UnmarshalEntityState is the one decoder for the bytes stored under key in ENTITY_STATES, for graph-ingest and every reader of the bucket or of one entity's reply. It refuses, in this order: bytes that do not decode (unreadable_entity_state, so an empty value is poison, never absence); an entity that violates the canonical contract; an entity that is not the one key names (noncanonical_entity_id); and a statement with no Source or no Timestamp (missing_statement_metadata). Each refusal is one fatal graph_state_reset_required classification over a *StateContractError whose EntityID is key.

func ValidateDecodedEntityIDs

func ValidateDecodedEntityIDs(entityIDs []string) error

ValidateDecodedEntityIDs validates identity-only authoritative query replies (semantic hits, name matches, and relationship endpoints) as one unit.

func ValidateDecodedEntityState

func ValidateDecodedEntityState(entity *EntityState) error

ValidateDecodedEntityState applies the stored-value rule to an EntityState that was decoded as part of a larger query reply: the canonical contract and statement metadata, the steps of UnmarshalEntityState that need no key. Aggregate decoders must call this before exposing any candidate downstream. A refusal has UnmarshalEntityState's shape, with no entity ID.

func ValidateDecodedEntityStatePointers

func ValidateDecodedEntityStatePointers(entities []*EntityState) error

ValidateDecodedEntityStatePointers is the pointer-slice counterpart used by GraphRAG hydration replies. Nil entries are contract violations, not absence: the batch protocol represents absence by omitting an entity.

func ValidateDecodedEntityStates

func ValidateDecodedEntityStates(entities []EntityState) error

ValidateDecodedEntityStates validates an entire value collection before its caller performs any downstream work. The indexed wrapper preserves the contract error for errors.As while identifying which candidate poisoned the reply.

func ValidateEntityStateContract

func ValidateEntityStateContract(entity *EntityState) error

ValidateEntityStateContract validates one complete final EntityState candidate. It never fills or rewrites fields; the Graphable fact lane owns its one allowed empty-subject projection convenience before this seam.

func ValidateStatementMetadata

func ValidateStatementMetadata(triples []message.Triple) error

ValidateStatementMetadata is the statement-metadata rule: every stored statement carries a Source and a Timestamp (ADR-110 Decision 5). It names the first of triples with neither, by its index and the missing field, or returns nil. Callers classify it: UnmarshalEntityState as stored graph state (missing_statement_metadata), graph-ingest's write lanes as the request's invalid_request.

Types

type AliasData

type AliasData struct {
	CanonicalID *string `json:"canonical_id"` // nil if not found
}

AliasData contains the canonical entity ID for an alias lookup.

type AppendSubjectResult

type AppendSubjectResult struct {
	EntityID   string           `json:"entity_id"`
	Outcome    MutationOutcome  `json:"outcome"`
	KVRevision uint64           `json:"kv_revision,omitempty"`
	Error      *MutationFailure `json:"error,omitempty"`
}

AppendSubjectResult reports one subject's independent append result. Outcome is the discriminator: failed requires Error; every other outcome forbids it. A failed result is definite; transport ambiguity is never encoded here.

type AppendTriplesRequest

type AppendTriplesRequest struct {
	Triples   []message.Triple `json:"triples"`
	TraceID   string           `json:"trace_id,omitempty"`
	RequestID string           `json:"request_id,omitempty"`
}

AppendTriplesRequest appends canonical tuples independently per subject.

type AppendTriplesResponse

type AppendTriplesResponse struct {
	Results   []AppendSubjectResult `json:"results"`
	TraceID   string                `json:"trace_id,omitempty"`
	RequestID string                `json:"request_id,omitempty"`
}

AppendTriplesResponse reports explicit partial results by distinct subject.

type CompoundPredicateData

type CompoundPredicateData struct {
	Entities []string `json:"entities"`
	Operator string   `json:"operator"`
	Matched  int      `json:"matched"`
}

CompoundPredicateData contains entities matching a compound predicate query.

type CompoundPredicateQuery

type CompoundPredicateQuery struct {
	Predicates []string `json:"predicates"`
	Operator   string   `json:"operator"` // "AND" or "OR"
	Limit      int      `json:"limit,omitempty"`
	MinRevisionField
}

CompoundPredicateQuery represents a query combining multiple predicates.

type CreateEntityRequest

type CreateEntityRequest struct {
	Entity          *EntityState     `json:"entity"`
	Triples         []message.Triple `json:"triples"`
	IndexingProfile string           `json:"indexing_profile,omitempty"`
	TraceID         string           `json:"trace_id,omitempty"`
	RequestID       string           `json:"request_id,omitempty"`
}

CreateEntityRequest atomically creates one entity with its initial facts.

type DeleteEntityRequest

type DeleteEntityRequest struct {
	EntityID         string `json:"entity_id"`
	ExpectedRevision uint64 `json:"expected_revision"`
	TraceID          string `json:"trace_id,omitempty"`
	RequestID        string `json:"request_id,omitempty"`
}

DeleteEntityRequest conditionally deletes one entity.

type DeleteEntityResponse

type DeleteEntityResponse struct {
	EntityID         string          `json:"entity_id"`
	Outcome          MutationOutcome `json:"outcome"`
	ExpectedRevision uint64          `json:"expected_revision"`
	TraceID          string          `json:"trace_id,omitempty"`
	RequestID        string          `json:"request_id,omitempty"`
}

DeleteEntityResponse response for entity deletion

type EntityBatchRequest

type EntityBatchRequest struct {
	IDs []string `json:"ids"`
}

EntityBatchRequest is the batch-query request: the entity IDs to read.

type EntityBatchResponse

type EntityBatchResponse struct {
	Entities []EntityState `json:"entities"`
	// Missing names the requested IDs not present in Entities, with a reason each.
	// Omitted entirely when nothing was missing.
	Missing []MissingEntity `json:"missing,omitempty"`
}

EntityBatchResponse is the batch-query reply. Entities keeps its field name and shape, so a consumer reading only `entities` is unaffected; `missing` is additive and omitempty, so a fully-hydrated batch is the bare `{"entities":[…]}` object.

type EntityMutationResponse

type EntityMutationResponse struct {
	Outcome    MutationOutcome `json:"outcome"`
	Entity     *EntityState    `json:"entity"`
	KVRevision uint64          `json:"kv_revision"`
	TraceID    string          `json:"trace_id,omitempty"`
	RequestID  string          `json:"request_id,omitempty"`
}

EntityMutationResponse is the reply to a create or a reconcile: the outcome, and the entity as committed (create, or a reconcile that applied) or as it stands (a reconcile that changed nothing), with its KV revision.

type EntityPredicateContractError

type EntityPredicateContractError struct {
	Violations []InvalidEntityPredicate `json:"violations"`
}

EntityPredicateContractError reports every unique invalid predicate in one candidate. Writers must reject the whole candidate when this error is returned.

func (*EntityPredicateContractError) Error

Error implements error with deterministic ordering for logs and tests.

type EntityRequest

type EntityRequest struct {
	ID string `json:"id"`
}

EntityRequest is the entity verb's request: the ID of the one entity to read.

type EntityState

type EntityState struct {
	// ID is the 6-part entity identifier: org.platform.system.domain.type.instance
	// Used as NATS KV key for storage and retrieval.
	ID string `json:"id"`

	// Triples contains all semantic facts about this entity.
	// Properties, relationships, and domain-specific data are all stored as triples.
	Triples []message.Triple `json:"triples"`

	// StorageRef optionally points to where the full original message is stored.
	// Supports "store once, reference anywhere" pattern for large payloads.
	// Nil if message was not stored or storage reference not available.
	StorageRef *message.StorageReference `json:"storage_ref,omitempty"`

	// MessageType records the original message type that created/updated this entity.
	// Provides provenance and enables filtering by message source.
	MessageType message.Type `json:"message_type"`

	// UpdatedAt records when this entity state was last modified.
	UpdatedAt time.Time `json:"updated_at"`
}

EntityState represents complete local graph state for an entity. Triples are the single source of truth for all semantic properties.

The ID field is the 6-part entity identifier (org.platform.system.domain.type.instance) which serves as the NATS KV key for storage and retrieval.

To extract type information from the ID, use message.ParseEntityID():

eid, err := message.ParseEntityID(state.ID)
if err != nil {
    return fmt.Errorf("invalid entity ID: %w", err)
}
entityType := eid.Type

func (*EntityState) Clone

func (es *EntityState) Clone() *EntityState

Clone returns a copy of the EntityState with its own Triples slice and its own StorageRef. Each triple is copied by value, so two fields stay shared with the original: Object, when it holds a map, a slice or a pointer, and the ExpiresAt pointer. A caller that changes either replaces it rather than writing through it.

func (*EntityState) GetPropertyValue

func (es *EntityState) GetPropertyValue(predicate string) (any, bool)

GetPropertyValue returns the value for a property by predicate. It checks Triples for a matching predicate and returns the Object value. Returns (value, true) if found, (nil, false) if not found.

func (*EntityState) GetTriple

func (es *EntityState) GetTriple(predicate string) *message.Triple

GetTriple returns one statement of the given predicate, or nil when the entity holds none. A predicate may hold statements from several sources (each source replaces only its own), so the read picks the same way every time: the latest Timestamp; on equal timestamps, the Source that sorts first; on equal sources, the first stored. A reader that wants another choice reads Triples and picks.

type EntityStateContractError

type EntityStateContractError struct {
	Field       EntityStateContractField
	TripleIndex int
	Err         error
}

EntityStateContractError reports the first noncanonical identity-bearing field in a complete EntityState. TripleIndex is -1 for the root ID.

Precedence is root ID, subjects in slice order, explicit references in slice order, then the existing deterministic predicate contract. This keeps error classification stable without echoing rejected identity bytes.

func (*EntityStateContractError) Error

func (e *EntityStateContractError) Error() string

Error implements error without exposing the rejected identity.

func (*EntityStateContractError) Unwrap

func (e *EntityStateContractError) Unwrap() error

Unwrap exposes the canonical entity-ID or object-type cause.

type EntityStateContractField

type EntityStateContractField string

EntityStateContractField identifies the first identity-bearing field that makes a complete EntityState candidate noncanonical.

const (
	// EntityStateContractFieldID is the EntityState.ID root key.
	EntityStateContractFieldID EntityStateContractField = "id"
	// EntityStateContractFieldSubject is a persisted Triple.Subject.
	EntityStateContractFieldSubject EntityStateContractField = "subject"
	// EntityStateContractFieldReference is an explicitly marked @id object.
	EntityStateContractFieldReference EntityStateContractField = "reference"
)

type EntityTypeSummary

type EntityTypeSummary struct {
	// Type is the system.domain.type triple (positions 3-5 of the canonical
	// entity ID, by named field) — the bucket name.
	Type string `json:"type"`

	// Count is how many rows of the page read fall in this bucket: a
	// sample when Truncated is set on the parent SummaryData.
	Count int `json:"count"`

	// Examples is up to ExamplesPerType real entity IDs from this
	// bucket. The caller uses these as starting points for
	// query_entity / query_relationships without having to invent IDs.
	Examples []string `json:"examples"`
}

EntityTypeSummary represents one entity-type bucket — entities grouped by their 6-part ID's system.domain.type segments (parts 3.4.5 in 1-indexed terms; parts 2-4 in 0-indexed slice terms; ADR-102).

Examples in this codebase:

acme.platform1.agentic-loop.agent.execution.<loopID>
→ type "agentic-loop.agent.execution"

acme.platform1.web.agent.observation.<hash>
→ type "web.agent.observation"

type ExactEntity

type ExactEntity struct {
	Entity     *EntityState `json:"entity"`
	KVRevision uint64       `json:"kv_revision"`
}

ExactEntity is one validated authority value and the revision of the same ENTITY_STATES entry. KVRevision is the entry's only revision: the stored value carries none of its own.

type ExactEntityReader

type ExactEntityReader struct {
	// contains filtered or unexported fields
}

ExactEntityReader is the operation-specific embedded authority read: one entity by its ID, through graph-ingest's entity verb, refused under the stored-value rule (UnmarshalEntityState). It exposes no raw subject, KV handle, or aggregate graph-client capability. Build it with NewExactEntityReader; the zero value refuses every read.

func NewExactEntityReader

func NewExactEntityReader(requester classifiedRequester, timeout time.Duration) (*ExactEntityReader, error)

NewExactEntityReader constructs the exact reader over requester. It refuses a nil requester and a negative timeout; a zero timeout means the requester's default. A typed-nil pointer is not detected.

func (*ExactEntityReader) ReadExactEntity

func (r *ExactEntityReader) ReadExactEntity(ctx context.Context, entityID string) (*ExactEntity, error)

ReadExactEntity reads entityID and the KV revision of its stored value. A stored value the stored-value rule refuses is returned as that refusal.

type GlobalSearchData

type GlobalSearchData struct {
	Text   *TextSearchData    `json:"text"`
	Entity json.RawMessage    `json:"entity,omitempty"`
	Path   *PathSearchData    `json:"path,omitempty"`
	Hints  []GlobalSearchHint `json:"hints"`
}

GlobalSearchData is the reply to a global search. Text, the word search's matches, is always there. Entity, the entity verb's reply data as its bytes came, is there only beside an honoured "entity" hint, and Path, the path search from the question's start, only beside an honoured "path" hint. Hints lists what the question asked for beyond its words, honoured or not, empty when nothing.

type GlobalSearchHint

type GlobalSearchHint struct {
	Hint     string `json:"hint"`
	Detail   string `json:"detail,omitempty"`
	Honoured bool   `json:"honoured"`
	Reason   string `json:"reason,omitempty"`
	Code     string `json:"code,omitempty"`
}

GlobalSearchHint is one thing a question asked for beyond its words. Hint is its kind: "entity" (a one-word question, read as a reference), "path" (a walk from a start), "time_range", "area", "aggregation", "similarity", "ranking", or "classification" (the question classifier refused the question). Detail is what the question named for it, such as the reference, the start or the operation, omitted when it named nothing. Honoured is true only when the reply holds its answer. Reason says why it was not honoured, and Code is the refusal's code when a refusal caused it.

type GlobalSearchRequest

type GlobalSearchRequest struct {
	Query string `json:"query"`
	Level int    `json:"level,omitempty"`
	Limit int    `json:"limit,omitempty"`
	MinRevisionField
}

GlobalSearchRequest is the globalSearch verb's request, decoded strictly: an unknown key is refused, naming it. Query is the question, required and not blank; every question is searched for its words, and no other key steers the answer. Level is the community level the matches are grouped at, 0 to 2, omitted 0. Limit is the most matches answered, 0 meaning DefaultSimilarityLimit, else 1 to MaxSimilarityLimit.

type Graphable

type Graphable interface {
	// EntityID returns deterministic 6-part ID: org.platform.system.domain.type.instance
	EntityID() string

	// Triples returns all facts about this entity
	Triples() []message.Triple
}

Graphable enables messages to self-declare their domain entities and relationships. This interface eliminates the need for brittle string matching in entity extraction by allowing payloads to explicitly state what entities they contain and how those entities relate to each other.

The Graphable pattern addresses a core architectural requirement: messages should contain domain expertise about the entities they represent. Rather than having infrastructure code guess what entities exist based on message types or field names, the message payload itself declares this information.

Design Benefits:

  • Domain Expertise: Payloads contain knowledge about their entities
  • Type Safety: No string matching or reflection-based entity detection
  • Extensibility: New domains simply implement the interface
  • Relationships: Explicit declaration of entity relationships
  • Performance: No need for complex entity detection algorithms
  • Resolution Guidance: Provides hints for entity resolution and merging

Triple-Based Design:

The Graphable interface uses a Triple-based approach where payloads return RDF-like triples (subject, predicate, object) to describe entity properties and relationships. This provides maximum flexibility while remaining simple.

Example Implementation:

type PositionPayload struct {
    SystemID  uint8   `json:"system_id"`
    Latitude  float64 `json:"latitude"`
    Longitude float64 `json:"longitude"`
    Altitude  float32 `json:"altitude"`
}

func (p *PositionPayload) EntityID() string {
    // Return deterministic 6-part ID
    return fmt.Sprintf("acme.telemetry.mavlink.robotics.drone.%d", p.SystemID)
}

func (p *PositionPayload) Triples() []message.Triple {
    entityID := p.EntityID()
    return []message.Triple{
        {Subject: entityID, Predicate: "geo.location.latitude", Object: p.Latitude},
        {Subject: entityID, Predicate: "geo.location.longitude", Object: p.Longitude},
        {Subject: entityID, Predicate: "geo.location.altitude", Object: p.Altitude},
    }
}

Graphable provides entity identification and semantic triples

type HierarchyChild

type HierarchyChild struct {
	Prefix string `json:"prefix"`
	Count  int    `json:"count"`
}

HierarchyChild is one prefix one segment longer than the request's, with how many entities on the page sit under it.

type HierarchyStatsData

type HierarchyStatsData struct {
	Prefix          string           `json:"prefix"`
	TotalEntities   int              `json:"total_entities"`
	EntitiesScanned int              `json:"entities_scanned"`
	Truncated       bool             `json:"truncated"`
	NextCursor      string           `json:"next_cursor,omitempty"`
	Children        []HierarchyChild `json:"children"`
}

HierarchyStatsData is the reply to hierarchyStats, read from one prefix page, live and as listed, not a snapshot. It is bare, since no index is read.

TotalEntities is the length of the key listing: the whole group as listed, before the cursor and any limit. EntitiesScanned is the rows on this page. Children, by count descending then prefix, count those rows alone, so they cover this page and no more: on a first page with Truncated true, a sample of the lexically smallest IDs; on a page read with a cursor, that page. An entity whose ID is the prefix is scanned and in no child. Truncated is true exactly when NextCursor is set, so false says only that this is the last page; a caller wanting the rest sends NextCursor as Cursor, paying one key scan per page.

type HierarchyStatsRequest

type HierarchyStatsRequest struct {
	Prefix string `json:"prefix,omitempty"`
	Cursor string `json:"cursor,omitempty"`
	MinRevisionField
}

HierarchyStatsRequest is the hierarchyStats verb's request, decoded strictly: an unknown key is refused. Prefix, when not empty, is a dot-delimited entity-ID prefix with no trailing dot; empty counts the whole graph. Cursor is a NextCursor from an earlier reply; empty reads the first page.

The verb reads no index, so it has no revision to compare: MinRevision is accepted and ignored.

type IncomingEntry

type IncomingEntry struct {
	FromEntityID string `json:"from_entity_id"`
	Predicate    string `json:"predicate"`
}

IncomingEntry represents a single incoming relationship in the graph.

type IncomingRelationshipsData

type IncomingRelationshipsData struct {
	Relationships []IncomingEntry `json:"relationships"`
}

IncomingRelationshipsData contains incoming relationships for an entity.

type IndexState

type IndexState string

IndexState is the readiness envelope's state field. Its wire values are the four constants below; a value outside them is a state this reader does not know, and the readiness gate defers on it.

const (
	IndexStateBuilding      IndexState = "building"
	IndexStateReady         IndexState = "ready"
	IndexStateDegraded      IndexState = "degraded"
	IndexStateResetRequired IndexState = "reset_required"
)

Index readiness states. Fusion keeps no copy of them: it reads no envelope (ADR-109 decision 1).

func IndexStates

func IndexStates() []IndexState

IndexStates returns the closed set of readiness states, in a new slice on every call. It is the iteration domain for the one-hot readiness `state` metric and the readiness gate's allow-list: adding a state means adding it here, and every one-hot state gauge picks it up, so a new state never renders as all zeros (a silent "no data" rather than an alertable signal).

type IndexStatusResponse

type IndexStatusResponse struct {
	Ready bool       `json:"ready"` // target>0 && indexed_revision>=target_revision
	State IndexState `json:"state"` // one of IndexStates()
	// Code and Reason carry bounded operator-actionable fatal readiness state.
	// They are empty during ordinary building/ready/degraded operation.
	Code   string `json:"code,omitempty"`
	Reason string `json:"reason,omitempty"`
	// BootstrapComplete reports whether this producer has finished its INITIAL BUILD
	// in the current process lifetime: enumeration of ENTITY_STATES plus replay up to
	// the enumeration-time target, including the authoritatively-empty 0/0 outcome. It
	// stays true once set and resets to false on restart, so a restart into a format
	// cutover re-gates (ADR-084 decision 2).
	//
	// For a backlog producer it means its boot work finished, not that the backlog it
	// bound onto (BootstrapScope) was worked off: graph-ingest's boot work is its
	// ENTITY_STATES sweep, which Start finishes, so it publishes true on every envelope
	// (ADR-109 Decision 3). Whether a backlog stands is Ready's and Lag's to say.
	//
	// It exists because health is otherwise not evaluable from the wire: an index
	// halfway through a format cutover reports State=building with a plausible Lag,
	// indistinguishable from an index that is merely behind. Ready cannot answer it
	// (a caught-up index is bootstrapped, but a bootstrapped index under write is not
	// caught up) and TargetRevision==0 cannot either (it is false during a cutover and
	// would defer the empty graph).
	//
	// NOT omitempty, and absent reads FALSE — fail closed. An envelope from a
	// producer that does not send the field therefore defers every health gate, and
	// the explicit `false` on the wire keeps that producer distinguishable from "not
	// yet bootstrapped" in a `nats kv get GRAPH_STATUS <producer>` dump.
	BootstrapComplete bool `json:"bootstrap_complete"`
	// IndexedRevision is the low-water-of-pending watermark: every delivered
	// ENTITY_STATES revision <= this has been applied and nothing <= it is still
	// in flight. What "applied" means is the producer's: for graph-index it is
	// indexed, so a consumer that knows its own target revision can gate on
	// IndexedRevision >= myRev instead of the coarse global Ready bool. For
	// graph-clustering it means held by its community maintainer, not yet
	// published: a reader of communities gates on a community record's own
	// entity_revision, never on this.
	IndexedRevision uint64 `json:"indexed_revision,omitempty"`
	// TargetRevision is the ENTITY_STATES stream LastSeq read at query time — the
	// latest committed write the index must catch up to.
	TargetRevision uint64 `json:"target_revision,omitempty"`
	// Lag is TargetRevision - IndexedRevision; 0 means caught up.
	Lag uint64 `json:"lag,omitempty"`
	// FailedCount / FailedReasons are the bounded failure detail a producer that
	// tracks per-entity failures carries on a DEGRADED envelope so an operator can
	// tell a whole-dependency outage from a few persistently-failing entities
	// WITHOUT any unbounded per-entity list on the watched key.
	//
	// Both are additive and omitempty: a producer with no failures emits neither,
	// and graph-index, which counts failures without reasons, emits FailedCount
	// only. FailedReasons is bounded to a fixed reason enum (a handful of keys),
	// keeping the watched key compact on the hot KV path. FailedCount is echoed from
	// the projection input (it also drives State=degraded); FailedReasons is set by
	// the producer after the projection. There is no first-failure time.
	FailedCount   uint64            `json:"failed_count,omitempty"`
	FailedReasons map[string]uint64 `json:"failed_reasons,omitempty"`
	// StalenessMs is the AGE OF THE VIEW in milliseconds (ADR-083): now minus the
	// KV commit time of the oldest delivered ENTITY_STATES revision the index has
	// not yet applied, or of the newest delivered one when none is in flight. It is
	// the view-rate consumer's tolerance unit because it is invariant to write rate
	// and coalesce_ms, where a revision count is not (a correct revision bound shifts
	// 2-4x with the coalesce dial alone).
	//
	// PRESENCE ENCODING — 0 does NOT mean "zero staleness". It means the value
	// carries no information: either Ready is true (no staleness to report) or the
	// producer could not compute it (nothing observed yet / an early-return hard
	// stop). Any COMPUTED staleness is reported as at least 1ms, so a consumer can
	// treat `StalenessMs > 0` as the presence bit and never read an absent age as
	// "0ms fresh".
	//
	// It is REPORTED, never gating. readiness.EvaluateReadinessGate does not look at
	// this field: readiness withholds an answer only for index health, and how far
	// behind the view is rides on the answer instead (community detection stamps it on
	// staleness_at_detection_ms). A consumer that surfaces it must carry the presence
	// encoding with it — publishing a bare 0 as "caught up" is the one way to turn an
	// unknown age back into a false claim.
	//
	// It is a FLOOR, not an oracle: it is exact for delivered writes, but a revision
	// still undelivered server-side cannot age it. Total stalls surface through the
	// wall-clock stuck detector (State=degraded), not through this field.
	StalenessMs uint64 `json:"staleness_ms,omitempty"`
	// BootstrapScope is the SIZE OF THE INITIAL BUILD this producer started with,
	// expressed in THE PRODUCER'S OWN UNIT — entities for an enumerating producer,
	// messages for a backlog producer (the backlog read when it bound, which its
	// BootstrapComplete does not claim was worked off), replayed values for a
	// watcher producer. It is deliberately not normalized across producers; a shared
	// unit would be a fiction, and every consumer reads it alongside the key it asked
	// for, so it already knows whose unit it is.
	//
	// It exists for exactly one distinction, which no other field carries for any
	// producer: `BootstrapComplete && BootstrapScope == 0` is "authoritatively
	// nothing to do" — the producer finished its initial build and the build was
	// empty — as opposed to "finished a build that had work in it". A consumer
	// waiting for a bootstrap replay cannot otherwise tell an empty-by-truth replay
	// from one it observed too early.
	//
	// THE GATE MUST NOT READ IT. readiness.EvaluateReadinessGate does not look at this
	// field and must never start: the moment a verdict depends on a magnitude, this
	// becomes a threshold knob and readiness stops being a health question (ADR-085
	// refuses a max_staleness knob for the same reason). A test pins the gate's verdict as identical
	// across two envelopes differing only in this field.
	//
	// IT LICENSES NOTHING ABOUT ABSENCE. Scope 0 says the initial build found nothing
	// to do at the instant it was captured — not that the underlying collection is empty,
	// and not that anything published later has been seen.
	BootstrapScope uint64 `json:"bootstrap_scope,omitempty"`
}

IndexStatusResponse is the wire shape of the readiness envelope (ADR-066), distributed as GRAPH_STATUS KV state (ADR-083). Fusion decodes no envelope: it reads not-ready from each query reply instead (ADR-109 decision 1).

Ready reports COVERAGE: every committed ENTITY_STATES revision <= the query-time target has been applied (revision-lag, ADR-066), not merely "indexing started" (a NAME_INDEX-non-empty signal fires minutes before the index is populated). It guarantees revision coverage, not last-writer-wins freshness under same-key churn (ADR-066 §1 Scope boundary).

Ready LICENSES NOTHING ABOUT ABSENCE (ADR-084). It never permits an authoritative not-found, because coverage cannot answer the question — an index caught up to every revision ever committed still knows nothing about a source that never published. No consumer may treat an empty result as an authoritative not-found under ANY envelope state.

Nor does Ready == false withhold a response: reads gate on HEALTH (State plus BootstrapComplete), and a healthy index that is merely behind serves while reporting StalenessMs. Under continuous write Ready is false essentially always, which makes it a poor proxy for soundness. Its remaining jobs are a caught-up fast path for the freshness question, and being the value a caller compares its own revision against via IndexedRevision — the one sound per-entity check.

IndexedRevision is the one spelling of the revision; the envelope has no phase, revision or last_synced field. The readiness computation that fills this envelope is in graph/readiness, so a reader of GRAPH_STATUS needs no NATS import.

type InvalidEntityPredicate

type InvalidEntityPredicate struct {
	Predicate string                               `json:"predicate"`
	Reason    vocabulary.PredicateValidationReason `json:"reason"`
}

InvalidEntityPredicate identifies one unique noncanonical predicate in an EntityState candidate. Predicate values are included for diagnostics; Reason is bounded and safe for metric labels.

type LexicalHit

type LexicalHit struct {
	EntityID string  `json:"entity_id"`
	Score    float64 `json:"score"`
}

LexicalHit is one entity a word search found. Score is the word index's BM25F score: higher is a better match, on no fixed scale, and comparable only within one reply.

type LexicalSearchData

type LexicalSearchData struct {
	Results          []LexicalHit `json:"results"`
	Matched          int          `json:"matched"`
	Excluded         []string     `json:"excluded,omitempty"`
	BodiesNotIndexed int          `json:"bodies_not_indexed"`
}

LexicalSearchData is the reply to a word search. Results holds the best hits, ordered by score and then by entity ID. Matched is the number of entities that matched within the scope, before the limit, so Matched above len(Results) says the limit cut the answer. Excluded is the query's excluded terms, each term's words joined by a space, omitted when there are none: every entity holding one was removed, so a caller can say why an entity it expected is absent. BodiesNotIndexed is the number of entities in the whole index, not the scope or the hits, whose offloaded body the index did not hold when the reply was built: such an entity is found only by its inline text.

type LexicalSearchRequest

type LexicalSearchRequest struct {
	Query string   `json:"query"`
	Limit int      `json:"limit"`
	Scope []string `json:"scope,omitempty"`
	MinRevisionField
}

LexicalSearchRequest is the word search verb's request (graph.lexical.query.search): the entities whose words best match Query, at most Limit of them (0 means DefaultSimilarityLimit, else 1 to MaxSimilarityLimit; any other value is refused, never clamped). Query is read by graph/lexical's ParseQuery, and a query it refuses is refused. Scope, when not empty, keeps only entities whose ID matches one of its entity-ID prefixes, before the limit; "" matches every entity. A responder decodes it strictly, refusing an unknown key by name, and reads min_revision as graph-index's verbs do.

type LocalSearchData

type LocalSearchData struct {
	CommunityID      string             `json:"community_id"`
	Level            int                `json:"level"`
	Record           *LocalSearchRecord `json:"record,omitempty"`
	RecordState      RecordState        `json:"record_state"`
	Matches          []TextSearchMatch  `json:"matches"`
	Matched          int                `json:"matched"`
	Excluded         []string           `json:"excluded,omitempty"`
	Missing          int                `json:"missing"`
	BodiesNotIndexed int                `json:"bodies_not_indexed"`
	Truncated        bool               `json:"truncated"`
	Answer           string             `json:"answer"`
}

LocalSearchData is the reply to a local search: the word index's matches within one group, the group's record when there is one, and an answer text.

CommunityID and Level name the group searched. Record is its record, present exactly when RecordState is RecordRead. Matches are the word index's hits in its order, each read back as stored. Matched is the word index's count of matches in the group before the limit. Excluded is the query's excluded words, omitted when there are none. Missing counts hits that were gone when they were read back, and were left out. BodiesNotIndexed is the word index's count of entities whose offloaded body it did not hold. Truncated is true exactly when Matched is above the hits returned, a hit was missing, or matches were left out for the reply to fit the connection's max_payload.

type LocalSearchRecord

type LocalSearchRecord struct {
	MemberCount      int      `json:"member_count"`
	CommunitySummary string   `json:"community_summary,omitempty"`
	Keywords         []string `json:"keywords,omitempty"`
}

LocalSearchRecord is a group's COMMUNITY_INDEX record as a search attaches it: its member count, its statistical summary and its keywords.

type LocalSearchRequest

type LocalSearchRequest struct {
	EntityID string `json:"entity_id"`
	Query    string `json:"query"`
	Level    int    `json:"level,omitempty"`
	Limit    int    `json:"limit,omitempty"`
	MinRevisionField
}

LocalSearchRequest is the localSearch verb's request, decoded strictly: an unknown key is refused.

EntityID is a literal entity ID; the search runs in its group at Level, 0 to 2, omitted 0. Query is the word index's query: it must not be blank, and the word index refuses what it cannot parse. Limit is the most matches, 0 meaning DefaultSimilarityLimit, else 1 to MaxSimilarityLimit.

type MinRevisionField

type MinRevisionField struct {
	MinRevision uint64 `json:"min_revision,omitempty"`
}

MinRevisionField is the part of a query request that names the ENTITY_STATES revision the reply must reflect. A request embeds it. MinRevision is a kv_revision the caller holds; zero means none. graph-index refuses a request above the revision it would reply with, ErrorCodeRevisionNotReached, and never waits for it.

type MissingEntity

type MissingEntity struct {
	ID     string        `json:"id"`
	Reason MissingReason `json:"reason"`
}

MissingEntity names one requested ID that is not in the response's entity list.

type MissingReason

type MissingReason string

MissingReason is why one requested ID is absent from a batch response. The set is CLOSED so a consumer can switch on it exhaustively.

const (
	// MissingNotFound is a KV read that returned not-found for the key — the
	// overwhelmingly common case.
	MissingNotFound MissingReason = "not_found"
	// MissingError is a per-ID fault that did not fail the whole call. The first-error
	// contract still stands for READ faults — a non-not-found backend error fails the
	// batch — so the only current emitter is a malformed requested ID (the empty
	// string), which is never looked up at all and therefore cannot honestly be called
	// not_found.
	MissingError MissingReason = "error"
)

The closed missing-reason set.

type MutationFailure

type MutationFailure struct {
	Class string `json:"class"`
	Code  string `json:"code"`
}

MutationFailure carries a definite classified subject-local failure without erasing receipts for other subjects that already committed.

type MutationOutcome

type MutationOutcome string

MutationOutcome is the outcome a graph-mutation reply carries. Every other failure travels as a classified error, never as an outcome. Transport uncertainty is classified by the typed requester and is never asserted by a server response.

const (
	// MutationApplied reports that the authority entry changed.
	MutationApplied MutationOutcome = "applied"
	// MutationUnchanged reports convergence without a new authority revision.
	MutationUnchanged MutationOutcome = "unchanged"
	// MutationEntityNotFound reports a missing required authority entry.
	MutationEntityNotFound MutationOutcome = "entity_not_found"
	// MutationFailed reports a classified per-subject append failure.
	MutationFailed MutationOutcome = "failed"
)

type NameData

type NameData struct {
	Matches []NameMatch `json:"matches"`
}

NameData contains the ranked entities for a name lookup. Order IS the ranking: exact-case matches first, then by label-predicate salience, then entity ID.

type NameIndexItem

type NameIndexItem struct {
	EntityID  string `json:"entity_id"`
	Name      string `json:"name"`      // original-case name as stored on the entity
	Predicate string `json:"predicate"` // the label predicate carrying it
	Priority  int    `json:"priority"`  // label-predicate salience (lower = higher)
}

NameIndexItem is one entity's claim on a name, stored in NAME_INDEX.

type NameMatch

type NameMatch struct {
	// EntityID is the matched entity (an opaque handle for the caller).
	EntityID string `json:"entity_id"`
	// MatchedName is the name as stored on the entity (original case).
	MatchedName string `json:"matched_name"`
	// Predicate is the label predicate that carried the name (e.g. dc.terms.title).
	Predicate string `json:"predicate"`
	// ExactCase is true when MatchedName equals the query verbatim (case included);
	// such matches rank above case-folded-only matches.
	ExactCase bool `json:"exact_case"`
}

NameMatch is one entity whose name/title matched a graph.query.byName lookup, carrying the signals a deterministic caller needs to calibrate trust.

type OutgoingEntry

type OutgoingEntry struct {
	ToEntityID string `json:"to_entity_id"`
	Predicate  string `json:"predicate"`
}

OutgoingEntry represents a single outgoing relationship in the graph.

type OutgoingRelationshipsData

type OutgoingRelationshipsData struct {
	Relationships []OutgoingEntry `json:"relationships"`
}

OutgoingRelationshipsData contains outgoing relationships for an entity.

type PathEntity

type PathEntity struct {
	EntityID string `json:"entity_id"`
	Depth    int    `json:"depth"`
}

PathEntity is one entity a path search reached. Depth is its shortest distance from the start under the request's direction and predicates; the start is at 0.

type PathSearchData

type PathSearchData struct {
	Entities  []PathEntity       `json:"entities"`
	Edges     []RelationshipEdge `json:"edges"`
	Truncated bool               `json:"truncated"`
}

PathSearchData is the reply to a path search, each entity and edge once. Entities are in visit order, the start first. Edges[i] first reached Entities[i+1], and names the edge in the direction the graph holds it, whichever way the walk crossed it; a path is the edges followed back. An edge may name an entity with no record.

Truncated is true exactly when the walk found an unseen entity and left it out, as read at the hops. When it is false, Entities is every entity within the request's reach.

type PathSearchRequest

type PathSearchRequest struct {
	StartEntity string   `json:"start_entity"`
	Direction   string   `json:"direction"`
	MaxDepth    int      `json:"max_depth"`
	MaxNodes    int      `json:"max_nodes,omitempty"`
	Predicates  []string `json:"predicates,omitempty"`
	MinRevisionField
}

PathSearchRequest is the pathSearch verb's request, decoded strictly: an unknown key is refused, since a typo in Predicates would widen the answer.

Direction is required: outgoing, incoming or both. MaxDepth is required, 1 to MaxPathSearchDepth. MaxNodes is the most entities in the reply, the start included: 0 means DefaultPathSearchNodes, else 1 to MaxPathSearchNodes. Predicates, when not empty, keeps only edges holding one of them.

type PredicateData

type PredicateData struct {
	Entities []string `json:"entities"`
}

PredicateData contains entities that have a specific predicate.

type PredicateListData

type PredicateListData struct {
	Predicates []PredicateSummary `json:"predicates"`
	Total      int                `json:"total"`
}

PredicateListData contains all predicates with their entity counts.

type PredicateListQuery

type PredicateListQuery struct {
	Namespace string `json:"namespace,omitempty"`
	MinRevisionField
}

PredicateListQuery is the request for graph.index.query.predicateList. Namespace, when set, scopes the listing to one exact domain or domain.category namespace (for example, "inferred.semantic" matches "inferred.semantic.high"). Omitted or empty means "list every predicate" (SemStreams ADR-065).

type PredicateRequest

type PredicateRequest struct {
	Predicate string  `json:"predicate"`
	Value     *string `json:"value,omitempty"`
	Limit     int     `json:"limit,omitempty"`
	MinRevisionField
}

PredicateRequest is the request for graph.index.query.predicate, and for graph.query.predicate, which forwards it unchanged: the entities carrying Predicate, with Value set, only those whose current state holds it with that value (an empty Value is a value), at most Limit of them when Limit is above zero.

type PredicateStatsData

type PredicateStatsData struct {
	Predicate      string   `json:"predicate"`
	EntityCount    int      `json:"entity_count"`
	SampleEntities []string `json:"sample_entities"`
}

PredicateStatsData contains detailed statistics for a single predicate.

type PredicateSummary

type PredicateSummary struct {
	Predicate   string `json:"predicate"`
	EntityCount int    `json:"entity_count"`
}

PredicateSummary represents a predicate with its entity count.

type PrefixIDsResponse

type PrefixIDsResponse struct {
	IDs        []string `json:"ids"`
	Total      int      `json:"total"`
	NextCursor string   `json:"next_cursor,omitempty"`
}

PrefixIDsResponse is the reply of the prefixIDs verb: the IDs a PrefixQueryRequest selects, paged as the prefix verb pages, with no stored value read. A damaged entity is listed like any other, so a caller can find it and read the rest around it.

IDs is the page's keys in lexicographic order, never null: an empty page is []. Total is counted as PrefixQueryResponse.Total is. NextCursor continues the listing on the next prefixIDs request and is omitted when no key follows the page; a cursor is promised only on the verb that gave it.

type PrefixQueryRequest

type PrefixQueryRequest struct {
	// Prefix is a dot-delimited entity-ID prefix (e.g. "acme.ops.robotics").
	// Empty string matches all entities when Pattern is also empty. Do NOT
	// include a trailing dot — the server appends it automatically when
	// filtering. Mutually exclusive with Pattern.
	Prefix string `json:"prefix"`

	// Pattern is an optional exact six-position entity-ID pattern in ADR-102
	// canonical order where any position may be "*". Mutually exclusive with
	// Prefix. Example: "acme.ops.*.intel.platform.*".
	Pattern string `json:"pattern,omitempty"`

	// Limit is the maximum number of entities to return on this page.
	// <=0, or above MaxPrefixQueryLimit, means MaxPrefixQueryLimit.
	Limit int `json:"limit,omitempty"`

	// Cursor is the opaque page-continuation token from a previous response.
	// Leave empty to request the first page.
	Cursor string `json:"cursor,omitempty"`
}

PrefixQueryRequest is the typed request envelope for graph.query.prefix and graph.query.prefixIDs, and for the graph.ingest.query verbs of the same names.

Cursor contract (OPAQUE):

  • First page: leave Cursor empty.
  • Subsequent pages: pass back the NextCursor value VERBATIM from the previous reply of the same verb (a PrefixQueryResponse for prefix, a PrefixIDsResponse for prefixIDs); a cursor is promised only on the verb that gave it. Consumers MUST NOT parse, construct, or modify cursor values — the encoding may change between server versions.
  • Empty NextCursor in the response means the result set is exhausted.

Limit semantics:

  • <=0, or above MaxPrefixQueryLimit, means MaxPrefixQueryLimit.
  • Even within the limit, the server may return fewer entities (or IDs) when the complete encoded response reaches the active NATS max_payload ceiling. In that case NextCursor is set so the caller can fetch the remainder.

V1 pagination caveat (keyset semantics):

  • The server sorts matching keys lexicographically and uses the last returned key as the page boundary. Entities whose IDs sort before the cursor position and that are inserted between page fetches will not appear on later pages — standard keyset behaviour.

Backend note (informational, subject to change):

  • NATS KV has no ranged scan; the server fetches ALL keys matching the prefix, sorts them, then slices the requested page. Large namespaces therefore incur a full key scan on every request.

type PrefixQueryResponse

type PrefixQueryResponse struct {
	// Entities is the full EntityState slice for this page.
	Entities []EntityState `json:"entities"`

	// Total is the length of the key listing; always present, 0 for an empty group.
	Total int `json:"total"`

	// NextCursor is the opaque continuation token; empty = exhausted.
	NextCursor string `json:"next_cursor,omitempty"`
}

PrefixQueryResponse is the typed response envelope for graph.query.prefix.

Entities contains the full EntityState values for this page, triples included. SemOps depends on full values being present so that downstream consumers do not need additional N+1 fetches.

Total is the number of distinct keys in the request's key listing, before the cursor and before any limit, so a later or byte-trimmed page names the same group size as the first. A key the listing repeats is counted and served once. It is true as listed, not a snapshot: under concurrent overwrites a listing can omit keys (seen at nats.go v1.55.0; nats.go does not promise a snapshot), so Total and the pages can miss an entity.

NextCursor is the opaque token to pass as PrefixQueryRequest.Cursor on the next call. An empty NextCursor means the result set is exhausted, and the field is omitted from the JSON output.

type Provider

type Provider interface {
	// GetAllEntityIDs returns all entity IDs in the graph.
	GetAllEntityIDs(ctx context.Context) ([]string, error)

	// GetNeighbors returns the entity IDs connected to the given entity.
	// direction: "outgoing", "incoming", or "both"
	GetNeighbors(ctx context.Context, entityID string, direction string) ([]string, error)

	// GetEdgeWeight returns the weight of the edge between two entities.
	// Returns 1.0 if edge exists but has no weight, 0.0 if no edge exists.
	GetEdgeWeight(ctx context.Context, fromID, toID string) (float64, error)
}

Provider abstracts the graph data source for algorithms. Used by clustering, structural indexing, and other graph operations.

type QueryResponse

type QueryResponse[T any] struct {
	Data            T         `json:"data"`
	IndexedRevision uint64    `json:"indexed_revision"`
	Producer        string    `json:"producer"`
	Timestamp       time.Time `json:"timestamp"`
}

QueryResponse is the success envelope of an enveloped query verb's reply (QueryVerb.Enveloped). A reply is either this body or a classified error (ADR-060); a refusal carries no envelope.

IndexedRevision is the ENTITY_STATES revision the reply reflects: every write at or below it is reflected in Data, on an alias reply too. A caller holding a write's kv_revision compares it here. 0 claims nothing: a reply that read no index (summary with predicates left out) reports it, and a caller must not compare on it, since it never reaches a write's revision. The embedding verbs (graph.embedding.query.search and similar) report it too: they read a view of EMBEDDING_INDEX, whose position is no ENTITY_STATES revision. Producer names the component that answered, so a reply relayed through another component can still be attributed.

func NewQueryResponse

func NewQueryResponse[T any](producer string, indexedRevision uint64, data T) (QueryResponse[T], error)

NewQueryResponse builds a reply from producer, the revision its data reflects and the data, stamped with the current time. It refuses an empty producer: a reply that does not name who answered cannot be attributed.

type QueryVerb

type QueryVerb struct {
	// Name is the verb, the last token of its subject.
	Name    string
	Subject string
	// Responder is the component type that answers on Subject.
	Responder string
	// Enveloped says the reply is a QueryResponse rather than a bare body: true
	// when any answer of the verb can use a graph-index or other derived-index
	// reply. A caller decodes by verb; nothing decides a reply's shape from its
	// content.
	Enveloped bool
	// Reply is the type of the reply body, or of the envelope's Data when
	// Enveloped.
	Reply reflect.Type
}

QueryVerb declares one request/reply verb: the subject it is served on and the component that answers it.

func QueryVerbs

func QueryVerbs() []QueryVerb

QueryVerbs returns the declared request/reply verbs. Each call returns a new slice, so a caller cannot change the declaration. The entity verb takes an EntityRequest, batch an EntityBatchRequest, prefix and prefixIDs a PrefixQueryRequest, and predicate a PredicateRequest. prefix answers the full entities of a page; prefixIDs answers only their IDs and reads no stored value, so a damaged entity is listed where prefix refuses the page. Each entry declares its reply: graph-ingest's are bare, and graph-index's are a QueryResponse whose Data is the entry's Reply, as are the derived-index verbs' (search, similar, bounds, range), of which only search and similar have a responder in the tree, and graph-lexical's search, which takes a LexicalSearchRequest. On graph.query.*, graph-query's forwards answer as the verb they forward to does, and entityByAlias, relationships, pathSearch, summary, localSearch and globalSearch, which read index replies or a community record, are enveloped from graph-query, and hierarchyStats, which reads graph-ingest alone, is bare; a verb a consumer serves under graph.query.* is not in this table. A Name is unique only within its Responder. pathSearch takes a PathSearchRequest, hierarchyStats a HierarchyStatsRequest, summary a SummaryRequest, localSearch a LocalSearchRequest, and globalSearch and searchGraph a GlobalSearchRequest; bounds takes a SpatialBoundsRequest and range a TemporalRangeRequest.

type ReconcilePredicatesRequest

type ReconcilePredicatesRequest struct {
	EntityID         string           `json:"entity_id"`
	ExpectedRevision uint64           `json:"expected_revision"`
	Source           string           `json:"source"`
	Predicates       []string         `json:"predicates"`
	Desired          []message.Triple `json:"desired"`
	TraceID          string           `json:"trace_id,omitempty"`
	RequestID        string           `json:"request_id,omitempty"`
}

ReconcilePredicatesRequest makes the statements of the named predicates from Source equal Desired on one existing entity at ExpectedRevision; the same predicates' statements from other sources stay. Desired may be empty, which clears Source's statements of them. Source is required, and every desired statement's Source must equal it (graph-entity-writes, "One rule per write mode"); graph-ingest refuses the request as invalid_request otherwise.

type RecordState

type RecordState string

RecordState says whether a search could attach a group's COMMUNITY_INDEX record. A record only describes its group, so no state refuses a search.

const (
	// RecordRead is a record read and attached.
	RecordRead RecordState = "read"
	// RecordNone is a community view that holds no record for the group.
	RecordNone RecordState = "none"
	// RecordNotReady is no community view, or one that is catching up, lost or stopped.
	RecordNotReady RecordState = "not_ready"
	// RecordUnreadable is a record the view holds but cannot decode.
	RecordUnreadable RecordState = "unreadable"
)

The record states.

type RelationshipEdge

type RelationshipEdge struct {
	Predicate    string `json:"predicate"`
	FromEntityID string `json:"from_entity_id"`
	ToEntityID   string `json:"to_entity_id"`
}

RelationshipEdge is one row of the graph-query relationships verb's reply, in either direction.

type ReplaceResult

type ReplaceResult struct {
	Triples []message.Triple
	Stale   []StaleSet
}

ReplaceResult is what ReplaceBySource leaves: the statements to store, and each arriving set it did not apply.

func ReplaceBySource

func ReplaceBySource(stored, arrival []message.Triple) ReplaceResult

ReplaceBySource is the replace write mode (graph-entity-writes, "One rule per write mode" and "Timestamp orders a replace"). The statements of one (subject, predicate, source) are one set: each set the arrival carries replaces the stored set of the same key whole, and the statements of the same predicate from every other source stay. A set whose latest Timestamp is older than the latest Timestamp of the stored set of its key is not applied and is named in Stale; equal timestamps apply. Confidence and Context never decide. Stored statements of keys the arrival does not carry are kept in their order, ahead of the arrival's applied sets. An applied set keeps a statement the arrival repeats equal in every field once, the first in arrival order (see keyOfStatement for what equal means).

type SemanticData

type SemanticData struct {
	Results           []SimilarityHit `json:"results"`
	EmbedderType      string          `json:"embedder_type,omitempty"`
	UnreadableRecords int             `json:"unreadable_records"`
	FailedRecords     int             `json:"failed_records"`
}

SemanticData is the reply to a text search over the embeddings. EmbedderType is the name the product registered the answering embedder under. UnreadableRecords is the number of EMBEDDING_INDEX records the responder could not decode, and FailedRecords the number of entities whose latest embedding failed; neither entity can be a hit. A 0 in both says no record was left out for either reason; an entity whose embedding is still pending is left out too and counted in neither, so the counts never prove completeness.

type SemanticRequest

type SemanticRequest struct {
	Query string   `json:"query"`
	Limit int      `json:"limit"`
	Scope []string `json:"scope,omitempty"`
	MinRevisionField
}

SemanticRequest is the text search verb's request (graph.embedding.query.search): the entities whose embeddings best match Query, at most Limit of them (0 means DefaultSimilarityLimit, else 1 to MaxSimilarityLimit). Query is required and not blank. Scope, when not empty, keeps only entities whose ID matches one of its dot-delimited prefixes; "" matches every entity. A responder decodes it strictly, refusing an unknown key by name. The embedding verbs claim no ENTITY_STATES revision, so a min_revision above 0 is refused, never answered.

type SimilarData

type SimilarData struct {
	Results           []SimilarityHit `json:"results"`
	UnreadableRecords int             `json:"unreadable_records"`
	FailedRecords     int             `json:"failed_records"`
}

SimilarData is the reply to a lookup of the entities most like a given one. UnreadableRecords and FailedRecords count what SemanticData's do.

type SimilarRequest

type SimilarRequest struct {
	EntityID string `json:"entity_id"`
	Limit    int    `json:"limit"`
	MinRevisionField
}

SimilarRequest is the similar verb's request (graph.embedding.query.similar): the entities whose embeddings are most like EntityID's, at most Limit of them, bounded as SemanticRequest's. EntityID is a literal entity ID and is never its own hit. A responder decodes it strictly, refusing an unknown key by name, and refuses a min_revision above 0 as SemanticRequest's does.

type SimilarityHit

type SimilarityHit struct {
	EntityID   string  `json:"entity_id"`
	Similarity float64 `json:"similarity"`
}

SimilarityHit is one entity a semantic or similar lookup found.

type SpatialBoundsRequest

type SpatialBoundsRequest struct {
	North float64 `json:"north"`
	South float64 `json:"south"`
	East  float64 `json:"east"`
	West  float64 `json:"west"`
	Limit int     `json:"limit"`
	MinRevisionField
}

SpatialBoundsRequest is the bounds verb's request (graph.spatial.query.bounds): the entities inside the box from South to North in latitude and West to East in longitude, in degrees, at most Limit of them. A responder decodes it strictly, refusing an unknown key by name, and reads min_revision as every derived-index verb does. The keyword classifier does not wrap a box across the antimeridian (graph/query/classifier.go:455-457, 520-522), so East can exceed 180 and West fall below -180; a responder must accept such a box, not refuse it.

type SpatialData

type SpatialData struct {
	Results   []SpatialHit `json:"results"`
	Truncated bool         `json:"truncated"`
}

SpatialData is the reply to a bounds lookup. Truncated says more entities matched than Results holds.

type SpatialHit

type SpatialHit struct {
	EntityID string  `json:"entity_id"`
	Lat      float64 `json:"lat"`
	Lon      float64 `json:"lon"`
	Alt      float64 `json:"alt,omitempty"`
}

SpatialHit is one entity a bounds lookup found, at its indexed position, so a caller gets geometry without reading each entity. Alt is 0 when the entity has no vertical component.

type StaleSet

type StaleSet struct {
	Subject   string
	Predicate string
	Source    string
}

StaleSet names one (subject, predicate, source) set of an arrival that ReplaceBySource did not apply because it was older than the stored set.

type StateContractError

type StateContractError struct {
	Reason   StateResetReason `json:"reason"`
	EntityID string           `json:"entity_id,omitempty"`
	Err      error            `json:"-"`
}

StateContractError means the authoritative graph cannot be safely read or projected. Recovery is reader-class-conditional: the authoritative read surface (graph-ingest's query lanes) scopes refusal to the poisoned entity and recovers as soon as operators repair the stored bytes (delete + recreate through canonical writes) — no restart required. Projection owners (derived views built from watched or replayed entity state) stay in sticky reset-required state and recover only by operator reset and process restart.

EntityID names the poisoned entity when the classification site knows it (snapshot sweep entry key, queried entity ID, RMW target, mutation read seam). It is additive and in-process only: the wire carries just the error class and code, so consumers reconstructing the classification from headers never see it. Err is excluded from JSON on purpose (error values do not marshal usefully); the rendered Error() string is the transport for detail.

func (*StateContractError) Error

func (e *StateContractError) Error() string

Error implements error.

func (*StateContractError) Unwrap

func (e *StateContractError) Unwrap() error

Unwrap exposes the structural or JSON cause.

type StateResetReason

type StateResetReason string

StateResetReason is a bounded machine-readable reset cause.

const (
	// GraphStateReasonUnreadableEntity means authoritative JSON cannot decode.
	GraphStateReasonUnreadableEntity StateResetReason = "unreadable_entity_state"
	// GraphStateReasonNoncanonicalPredicate means stored state violates the predicate grammar.
	GraphStateReasonNoncanonicalPredicate StateResetReason = "noncanonical_predicate"
	// GraphStateReasonNoncanonicalEntityID means the stored entity ID, a triple
	// subject, or an explicitly marked entity reference violates the canonical
	// entity identity contract.
	GraphStateReasonNoncanonicalEntityID StateResetReason = "noncanonical_entity_id"
	// GraphStateReasonMissingStatementMetadata means a stored statement has no Source or no Timestamp, which every
	// stored statement carries (ADR-110 Decision 5).
	GraphStateReasonMissingStatementMetadata StateResetReason = "missing_statement_metadata"
)

type SummaryData

type SummaryData struct {
	// TotalEntities is the number of distinct keys in the listing: the whole group as listed, before
	// the cursor and any limit. A listing under concurrent overwrites can omit keys (seen at nats.go
	// v1.55.0; nats.go does not promise a snapshot), so it is not a snapshot count.
	TotalEntities int `json:"total_entities"`

	// EntitiesScanned is the rows on this page. The type counts count those rows alone.
	EntitiesScanned int `json:"entities_scanned"`

	// Truncated is true exactly when NextCursor is set, so false says only that this is the last page.
	// EntityTypes covers this page and no more: on a first page with Truncated true, a sample of the
	// lexically smallest IDs. A caller wanting the rest sends NextCursor as Cursor, paying one key scan
	// per page.
	Truncated bool `json:"truncated"`

	// NextCursor is the page's cursor, opaque, absent on the last page.
	NextCursor string `json:"next_cursor,omitempty"`

	// EntityTypes lists the type buckets on this page, by count descending then type. Never null.
	EntityTypes []EntityTypeSummary `json:"entity_types"`

	// Predicates is each predicate as listed, with its entity count from the predicate index, whole-graph and
	// unaffected by the page: null when the request excluded them, [] when there are none. Each
	// request for it reads it again, whatever the cursor.
	Predicates []PredicateSummary `json:"predicates"`
}

SummaryData is the summary verb's reply, in a QueryResponse from graph-query: one prefix page and, unless excluded, the predicate list read before it, live and as listed, not a snapshot of the two. Caller-friendly text formatting happens at the tool-wrapper layer; this shape stays structured for non-LLM consumers (dashboards, audit, programmatic clients).

With predicates excluded the reply's IndexedRevision is 0, which claims nothing: no index was read. Do not compare it against a kv_revision on that answer, since it never catches up and a retry loop would spin for ever.

type SummaryRequest

type SummaryRequest struct {
	// Prefix, when not empty, narrows the entity types to one group: a dot-delimited entity-ID prefix
	// with no trailing dot. It needs ExcludePredicates, and is refused without it: predicateList takes
	// no entity prefix, so the answer would set one group's types beside the whole graph's predicates,
	// at the cost of scanning the whole predicate index.
	Prefix string `json:"prefix,omitempty"`

	// ExcludePredicates leaves the predicate counts out, so the answer does not depend on graph-index,
	// which otherwise refuses for the whole request when it cannot answer. Predicates is then null and
	// IndexedRevision 0.
	ExcludePredicates bool `json:"exclude_predicates,omitempty"`

	// ExamplesPerType caps how many sample entity IDs to retain per type. 0 means 2; a negative count
	// is refused. Example IDs are load-bearing for the discovery use case: models invent IDs when no
	// examples are provided.
	ExamplesPerType int `json:"examples_per_type,omitempty"`

	// Cursor is a NextCursor from an earlier reply; empty reads the first page.
	Cursor string `json:"cursor,omitempty"`

	// MinRevision reaches predicateList. With ExcludePredicates no index is read, so it is accepted
	// and ignored.
	MinRevisionField
}

SummaryRequest is the summary verb's request, decoded strictly: an unknown key is refused. The zero value asks for the first page of the whole graph with its predicates.

type TemporalData

type TemporalData struct {
	Results   []TemporalHit `json:"results"`
	Truncated bool          `json:"truncated"`
}

TemporalData is the reply to a time-range lookup. Truncated says more entities matched than Results holds.

type TemporalHit

type TemporalHit struct {
	EntityID string `json:"entity_id"`
}

TemporalHit is one entity a time-range lookup found.

type TemporalRangeRequest

type TemporalRangeRequest struct {
	StartTime time.Time `json:"start_time"`
	EndTime   time.Time `json:"end_time"`
	Limit     int       `json:"limit"`
	MinRevisionField
}

TemporalRangeRequest is the time-range verb's request (graph.temporal.query.range): the entities that changed from StartTime to EndTime, at most Limit of them. The times are RFC 3339 on the wire, under start_time and end_time, never startTime and endTime. A responder decodes it strictly, refusing an unknown key by name, and reads min_revision as every derived-index verb does.

type TextSearchData

type TextSearchData struct {
	Level            int               `json:"level"`
	Groups           []TextSearchGroup `json:"groups"`
	Matches          []TextSearchMatch `json:"matches"`
	Matched          int               `json:"matched"`
	Excluded         []string          `json:"excluded,omitempty"`
	Missing          int               `json:"missing"`
	BodiesNotIndexed int               `json:"bodies_not_indexed"`
	Truncated        bool              `json:"truncated"`
	UnreadableGroups int               `json:"unreadable_groups"`
	Answer           string            `json:"answer"`
}

TextSearchData is the word search's result: the word index's matches over every entity, each read back as stored, and the community groups at Level that hold them.

Matches are the word index's hits in its order, best first. Groups lists each group holding a match once, in the order of its best match. Matched is the word index's count of matches before the limit. Excluded is the query's excluded words, omitted when there are none. Missing counts hits that were gone when they were read back, and were left out. BodiesNotIndexed is the word index's count of entities whose offloaded body it did not hold. Truncated is true exactly when Matched is above the hits returned, a hit was missing, or matches were left out for the reply to fit the connection's max_payload. UnreadableGroups is the number of Groups whose record could not be read. Answer is a plain text built from these fields.

type TextSearchGroup

type TextSearchGroup struct {
	CommunityID string             `json:"community_id"`
	Matches     int                `json:"matches"`
	RecordState RecordState        `json:"record_state"`
	Record      *LocalSearchRecord `json:"record,omitempty"`
}

TextSearchGroup is one community group holding matches: the group's entity-ID prefix, how many of the reply's matches it holds, and its COMMUNITY_INDEX record, present exactly when RecordState is RecordRead.

type TextSearchMatch

type TextSearchMatch struct {
	ID     string          `json:"id"`
	Label  string          `json:"label,omitempty"`
	Score  float64         `json:"score"`
	Entity json.RawMessage `json:"entity"`
}

TextSearchMatch is one matching entity, in a global or a local search: its ID; its label, the first non-empty string value of its most salient label predicate (vocabulary.DiscoverLabelPredicates), omitted when it has none; the word index's score for the question; and the entity as it was read, its bytes unchanged.

Directories

Path Synopsis
Package clustering groups entities by entity-ID prefix and publishes one bounded record per group to the COMMUNITY_INDEX bucket.
Package clustering groups entities by entity-ID prefix and publishes one bounded record per group to the COMMUNITY_INDEX bucket.
Package embedding turns the text of graph entities into vectors, stores them, and finds the nearest ones.
Package embedding turns the text of graph entities into vectors, stores them, and finds the nearest ones.
Package entitytext says which of an entity's values are its text, for every component that reads text from the graph: graph-embedding embeds it, and a word index splits it into a name and a body.
Package entitytext says which of an entity's values are its text, for every component that reads text from the graph: graph-embedding embeds it, and a word index splits it into a name and a body.
Package follower follows ENTITY_STATES for a projection owner: it waits for the bucket, holds the one watch on it, replays the stored entities and then the live writes in delivery order, and keeps the owner's readiness: the watermark of applied revisions, the bootstrap latch, the reset latch, the lost-feed state, and the envelope it publishes to GRAPH_STATUS on every heartbeat (ADR-108 Decision 4).
Package follower follows ENTITY_STATES for a projection owner: it waits for the bucket, holds the one watch on it, replays the stored entities and then the live writes in delivery order, and keeps the owner's readiness: the watermark of applied revisions, the bootstrap latch, the reset latch, the lost-feed state, and the envelope it publishes to GRAPH_STATUS on every heartbeat (ADR-108 Decision 4).
Package inference derives an entity's hierarchy statements from its 6-part ID (org.platform.system.domain.type.instance, ADR-102).
Package inference derives an entity's hierarchy statements from its 6-part ID (org.platform.system.domain.type.instance, ADR-102).
Package kvcatalog holds the framework KV bucket catalog: the ONE literal table of every KV bucket whose write-ownership or retention the framework guarantees.
Package kvcatalog holds the framework KV bucket catalog: the ONE literal table of every KV bucket whose write-ownership or retention the framework guarantees.
Package lexical is tier 0 word search: an in-memory index that ranks entities by field-weighted BM25 over the words of their text.
Package lexical is tier 0 word search: an in-memory index that ranks entities by field-weighted BM25 over the words of their text.
Package query classifies a natural-language question into search hints: the time range, area, path start, aggregation or ranking it asks for.
Package query classifies a natural-language question into search hints: the time range, area, path start, aggregation or ranking it asks for.
Package readiness writes and reads the readiness envelope a producer keeps in the GRAPH_STATUS KV bucket, and holds the gate that judges one.
Package readiness writes and reads the readiness envelope a producer keeps in the GRAPH_STATUS KV bucket, and holds the gate that judges one.

Jump to

Keyboard shortcuts

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