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
- func DecodePredicateToken(token string) (string, bool)
- func EncodePredicateToken(predicate string) string
- func IsReservedSource(source string) bool
- func IsStateContractError(err error) bool
- func MarshalEntityState(entity *EntityState) ([]byte, error)
- func MatchesAnyIDPrefix(id string, prefixes []string) bool
- func UnmarshalEntityState(key string, data []byte, entity *EntityState) error
- func ValidateDecodedEntityIDs(entityIDs []string) error
- func ValidateDecodedEntityState(entity *EntityState) error
- func ValidateDecodedEntityStatePointers(entities []*EntityState) error
- func ValidateDecodedEntityStates(entities []EntityState) error
- func ValidateEntityStateContract(entity *EntityState) error
- func ValidateStatementMetadata(triples []message.Triple) error
- type AliasData
- type AppendSubjectResult
- type AppendTriplesRequest
- type AppendTriplesResponse
- type CompoundPredicateData
- type CompoundPredicateQuery
- type CreateEntityRequest
- type DeleteEntityRequest
- type DeleteEntityResponse
- type EntityBatchRequest
- type EntityBatchResponse
- type EntityMutationResponse
- type EntityPredicateContractError
- type EntityRequest
- type EntityState
- type EntityStateContractError
- type EntityStateContractField
- type EntityTypeSummary
- type ExactEntity
- type ExactEntityReader
- type GlobalSearchData
- type GlobalSearchHint
- type GlobalSearchRequest
- type Graphable
- type HierarchyChild
- type HierarchyStatsData
- type HierarchyStatsRequest
- type IncomingEntry
- type IncomingRelationshipsData
- type IndexState
- type IndexStatusResponse
- type InvalidEntityPredicate
- type LexicalHit
- type LexicalSearchData
- type LexicalSearchRequest
- type LocalSearchData
- type LocalSearchRecord
- type LocalSearchRequest
- type MinRevisionField
- type MissingEntity
- type MissingReason
- type MutationFailure
- type MutationOutcome
- type NameData
- type NameIndexItem
- type NameMatch
- type OutgoingEntry
- type OutgoingRelationshipsData
- type PathEntity
- type PathSearchData
- type PathSearchRequest
- type PredicateData
- type PredicateListData
- type PredicateListQuery
- type PredicateRequest
- type PredicateStatsData
- type PredicateSummary
- type PrefixIDsResponse
- type PrefixQueryRequest
- type PrefixQueryResponse
- type Provider
- type QueryResponse
- type QueryVerb
- type ReconcilePredicatesRequest
- type RecordState
- type RelationshipEdge
- type ReplaceResult
- type SemanticData
- type SemanticRequest
- type SimilarData
- type SimilarRequest
- type SimilarityHit
- type SpatialBoundsRequest
- type SpatialData
- type SpatialHit
- type StaleSet
- type StateContractError
- type StateResetReason
- type SummaryData
- type SummaryRequest
- type TemporalData
- type TemporalHit
- type TemporalRangeRequest
- type TextSearchData
- type TextSearchGroup
- type TextSearchMatch
Constants ¶
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
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 // 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.
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.
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 )
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.
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.
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.
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.
const ResponderGraphEmbedding = "graph-embedding"
ResponderGraphEmbedding is the Responder of the embedding verbs, answered by processor/graph-embedding.
const ResponderGraphIndex = "graph-index"
ResponderGraphIndex is the Responder of the verbs graph-index answers.
const ResponderGraphIndexSpatial = "graph-index-spatial"
ResponderGraphIndexSpatial is the Responder of the spatial verb, whose component arrives with a later change.
const ResponderGraphIndexTemporal = "graph-index-temporal"
ResponderGraphIndexTemporal is the Responder of the temporal verb, whose component arrives with a later change.
const ResponderGraphIngest = "graph-ingest"
ResponderGraphIngest is the Responder of the verbs graph-ingest answers.
const ResponderGraphLexical = "graph-lexical"
ResponderGraphLexical is the Responder of the word search verb, answered by processor/graph-lexical.
const ResponderGraphQuery = "graph-query"
ResponderGraphQuery is the Responder of the verbs graph-query answers.
Variables ¶
This section is empty.
Functions ¶
func DecodePredicateToken ¶
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 ¶
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 ¶
IsReservedSource reports whether source is one of the reserved sources, compared exactly.
func IsStateContractError ¶
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 ¶
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 ¶
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 ¶
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 ¶
func (e *EntityPredicateContractError) Error() string
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files
¶
- constants.go
- doc.go
- entity_predicate_contract.go
- exact_entity.go
- graphable.go
- helpers.go
- id_prefix.go
- index_status.go
- mutation_requests.go
- mutation_responses.go
- predicate_codec.go
- query_batch_types.go
- query_global_search_types.go
- query_hierarchy_types.go
- query_index_types.go
- query_lexical_types.go
- query_local_search_types.go
- query_name_types.go
- query_path_types.go
- query_predicate_types.go
- query_prefix_types.go
- query_response.go
- query_search_types.go
- query_summary_types.go
- query_verbs.go
- sources.go
- state_contract.go
- types.go
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. |