Struct KhiveRuntime 

pub struct KhiveRuntime { /* private fields */ }

Composable runtime handle used by the MCP server.

Wraps a StorageBackend and provides namespace-scoped accessor methods for each storage capability, plus a lazily-loaded embedder.

Implementations

impl KhiveRuntime

pub async fn update_entity( &self, namespace: Option<&str>, id: Uuid, patch: EntityPatch, ) -> RuntimeResult<Entity>

Patch-style entity update.

Only fields set to Some(_) are changed. Re-indexes FTS5 (and vectors if configured) when name or description changes; skips re-indexing for property/tag-only patches.

Returns RuntimeError::NotFound if the entity does not exist or belongs to a different namespace. This enforces ADR-007 namespace isolation at the runtime layer.

pub async fn merge_entity( &self, namespace: Option<&str>, into_id: Uuid, from_id: Uuid, strategy: MergeStrategy, ) -> RuntimeResult<MergeSummary>

Merge from_id into into_id.

All edges incident to from_id are rewired to into_id. Self-loops that would result from the rewire are dropped. Properties and tags are merged per strategy. from_id is hard-deleted and removed from indexes. Returns a summary.

Atomic: all SQL (entity reads/writes, edge rewires, FTS updates, vec-index delete) runs on a single pool connection inside one BEGIN IMMEDIATE transaction via merge_entity_sql. If embedding vectors are configured, the vector re-insert for into_id is performed after the transaction (requires async embedding computation).

impl KhiveRuntime

pub async fn hybrid_search_with_strategy( &self, namespace: Option<&str>, query_text: &str, query_vector: Option<Vec<f32>>, strategy: FusionStrategy, limit: u32, ) -> RuntimeResult<Vec<SearchHit>>

Hybrid search with a caller-supplied fusion strategy.

impl KhiveRuntime

pub async fn bfs_traverse( &self, namespace: Option<&str>, start: Uuid, options: TraversalOptions, ) -> RuntimeResult<Vec<PathNode>>

BFS traversal from start, returning nodes in level order.

The first element is always the start node (via_edge = None, depth = 0). Nodes already visited are skipped so the result set is deduplicated.

pub async fn shortest_path( &self, namespace: Option<&str>, from: Uuid, to: Uuid, max_depth: usize, ) -> RuntimeResult<Option<Vec<PathNode>>>

Bidirectional BFS shortest path from from to to.

Returns Some(path) where path[0] is from and path.last() is to, or None if no path exists within max_depth hops. For from == to returns Some with a single-node path immediately.

impl KhiveRuntime

pub async fn create_entity( &self, namespace: Option<&str>, kind: &str, name: &str, description: Option<&str>, properties: Option<Value>, tags: Vec<String>, ) -> RuntimeResult<Entity>

Create and persist a new entity.

pub async fn get_entity( &self, namespace: Option<&str>, id: Uuid, ) -> RuntimeResult<Option<Entity>>

Retrieve an entity by ID.

Returns None if the entity does not exist or belongs to a different namespace. This enforces ADR-007 namespace isolation at the runtime layer.

pub async fn list_entities( &self, namespace: Option<&str>, kind: Option<&str>, limit: u32, offset: u32, ) -> RuntimeResult<Vec<Entity>>

List entities in a namespace, optionally filtered by kind.

pub async fn list_events( &self, namespace: Option<&str>, filter: EventFilter, limit: u32, offset: u32, ) -> RuntimeResult<Page<Event>>

List events in a namespace, optionally filtered.

pub async fn link( &self, namespace: Option<&str>, source_id: Uuid, target_id: Uuid, relation: EdgeRelation, weight: f64, ) -> RuntimeResult<Edge>

Create a directed edge between two substrates.

Enforces the ADR-002/ADR-019/ADR-024 three-case relation contract via validate_edge_relation_endpoints. See that method for the full contract.

A record that exists but belongs to a different namespace is treated as not found (fail-closed; no cross-namespace existence leak).

pub async fn neighbors( &self, namespace: Option<&str>, node_id: Uuid, direction: Direction, limit: Option<u32>, relations: Option<Vec<EdgeRelation>>, ) -> RuntimeResult<Vec<NeighborHit>>

Get immediate neighbors of a node, optionally filtered by relation type.

Pass relations: Some(vec![EdgeRelation::Annotates]) to retrieve only annotation edges, enabling cross-substrate navigation as described in ADR-024.

pub async fn neighbors_with_query( &self, namespace: Option<&str>, node_id: Uuid, query: NeighborQuery, ) -> RuntimeResult<Vec<NeighborHit>>

Get neighbors with full query control (includes min_weight).

pub async fn traverse( &self, namespace: Option<&str>, request: TraversalRequest, ) -> RuntimeResult<Vec<GraphPath>>

Traverse the graph from a set of root nodes.

pub async fn create_note( &self, namespace: Option<&str>, kind: &str, name: Option<&str>, content: &str, salience: f64, properties: Option<Value>, annotates: Vec<Uuid>, ) -> RuntimeResult<Note>

Create and persist a note, optionally with properties and annotation targets.

After creating the note:

• Always indexes into FTS5 at the notes_<namespace> key.
• If an embedding model is configured, indexes into the vector store with SubstrateKind::Note.
• For each UUID in annotates, creates an EdgeRelation::Annotates edge from the note to that target.

pub async fn create_note_with_decay( &self, namespace: Option<&str>, kind: &str, name: Option<&str>, content: &str, salience: f64, decay_factor: f64, properties: Option<Value>, annotates: Vec<Uuid>, ) -> RuntimeResult<Note>

Like [create_note] but also sets a non-zero decay factor on the note.

pub async fn list_notes( &self, namespace: Option<&str>, kind: Option<&str>, limit: u32, offset: u32, ) -> RuntimeResult<Vec<Note>>

List notes, optionally filtered by kind.

pub async fn search_notes( &self, namespace: Option<&str>, query_text: &str, query_vector: Option<Vec<f32>>, limit: u32, note_kind: Option<&str>, ) -> RuntimeResult<Vec<NoteSearchHit>>

Search notes using a hybrid FTS5 + vector pipeline with salience weighting.

Pipeline (per ADR-024):

1. FTS5 query against notes_<namespace>.
2. If embedding model is configured: vector search filtered to kind="note".
3. RRF fusion (k=60).
4. Salience-weighted rerank: score *= (0.5 + 0.5 * note.salience).
5. Filter soft-deleted notes (deleted_at IS NOT NULL).
6. Truncate to limit.

pub async fn resolve_prefix( &self, namespace: Option<&str>, prefix: &str, ) -> RuntimeResult<Option<Uuid>>

Resolve a short UUID prefix (8+ hex chars) to a full UUID.

Searches entities, notes, and edges tables for a UUID starting with the given prefix, scoped to the caller’s namespace. Returns Ok(Some(uuid)) if exactly one match is found, Ok(None) if no matches, or an error if ambiguous (multiple matches).

pub async fn resolve( &self, namespace: Option<&str>, id: Uuid, ) -> RuntimeResult<Option<Resolved>>

Resolve a UUID to its substrate kind by trying entity, then note, then event stores.

Returns None if the UUID is not found in any substrate. Cost: at most 3 store lookups per call (cheap for v0.1).

pub async fn delete_note( &self, namespace: Option<&str>, id: Uuid, hard: bool, ) -> RuntimeResult<bool>

Delete a note by ID, enforcing namespace isolation.

On hard delete, cascades to remove all incident edges (both inbound and outbound) and cleans up FTS and vector indexes, preventing dangling references for annotates edges that target this note (ADR-002, ADR-024). Soft delete also cleans FTS and vector indexes; edges are left in place.

Returns false without deleting if the note does not exist or belongs to a different namespace (ADR-007 namespace isolation).

impl KhiveRuntime

pub async fn query( &self, namespace: Option<&str>, query: &str, ) -> RuntimeResult<Vec<SqlRow>>

Execute a GQL or SPARQL query string, returning raw SQL rows.

The query is compiled to SQL with the namespace scope applied. GQL syntax: MATCH (a:concept)-[e:extends]->(b) RETURN a, b LIMIT 10 SPARQL syntax: SELECT ?a WHERE { ?a :kind "concept" . }

pub async fn query_with_metadata( &self, namespace: Option<&str>, query: &str, ) -> RuntimeResult<QueryResult>

Execute a GQL/SPARQL query, returning rows and any validation warnings.

pub async fn delete_entity( &self, namespace: Option<&str>, id: Uuid, hard: bool, ) -> RuntimeResult<bool>

Delete an entity by ID (soft delete by default).

On hard delete, cascades to remove all incident edges (both inbound and outbound) to prevent dangling references. Soft delete also cleans FTS and vector indexes; edges are left in place.

Returns false without deleting if the entity exists but belongs to a different namespace (ADR-007 namespace isolation).

pub async fn count_entities( &self, namespace: Option<&str>, kind: Option<&str>, ) -> RuntimeResult<u64>

Count entities in a namespace, optionally filtered.

pub async fn get_edge( &self, namespace: Option<&str>, edge_id: Uuid, ) -> RuntimeResult<Option<Edge>>

Fetch a single edge by id. Returns None if the edge does not exist.

pub async fn list_edges( &self, namespace: Option<&str>, filter: EdgeListFilter, limit: u32, ) -> RuntimeResult<Vec<Edge>>

List edges matching filter. limit is capped at 1000; defaults to 100.

pub async fn update_edge( &self, namespace: Option<&str>, edge_id: Uuid, relation: Option<EdgeRelation>, weight: Option<f64>, ) -> RuntimeResult<Edge>

Patch-style edge update. Only Some(_) fields are applied.

When relation is Some(new_rel), validates that the edge’s existing endpoints are legal for new_rel before persisting. Weight-only updates (relation = None) skip validation. Returns InvalidInput if the new relation would violate the ADR-002/ADR-019/ADR-024 three-case contract; the edge is NOT mutated on error.

pub async fn delete_edge( &self, namespace: Option<&str>, edge_id: Uuid, ) -> RuntimeResult<bool>

Hard-delete an edge by id.

Cascades to remove any annotates edges whose target is the deleted edge (ADR-002: annotates is note → anything; deleting an edge target leaves annotation edges dangling if not cleaned up). Returns true if the primary edge was removed.

If edge_id does not refer to an edge (e.g. the caller passes an entity or note UUID by mistake), this method returns Ok(false) immediately with no side effects — it does not cascade inbound edges of the non-edge record.

pub async fn count_edges( &self, namespace: Option<&str>, filter: EdgeListFilter, ) -> RuntimeResult<u64>

Count edges matching filter.

impl KhiveRuntime

pub async fn export_kg( &self, namespace: Option<&str>, ) -> RuntimeResult<KgArchive>

Export all entities and edges in a namespace to a portable JSON archive.

Edge collection: all entity IDs in the namespace are gathered first; query_edges is then called with those IDs as source_ids. This captures every edge whose source entity belongs to the namespace.

pub async fn export_kg_json( &self, namespace: Option<&str>, ) -> RuntimeResult<String>

Export to a JSON string (convenience wrapper around export_kg).

pub async fn import_kg( &self, archive: &KgArchive, target_namespace: Option<&str>, ) -> RuntimeResult<ImportSummary>

Import an archive into target_namespace.

If target_namespace is None, the archive’s own namespace is used.

• Entities: upserted by ID; existing records are overwritten.
• Edges: upserted; existing records are overwritten.
• Validation: format != "khive-kg" or unsupported version → InvalidInput. Invalid edge relations are caught at JSON deserialization time.

pub async fn import_kg_json( &self, json: &str, target_namespace: Option<&str>, ) -> RuntimeResult<ImportSummary>

Import from a JSON string (convenience wrapper around import_kg).

impl KhiveRuntime

pub async fn embed(&self, text: &str) -> RuntimeResult<Vec<f32>>

Generate an embedding vector for text using the configured local model.

First call lazily loads model weights (cold start cost). Subsequent calls reuse them. Returns Unconfigured("embedding_model") if no model is configured.

pub async fn embed_batch( &self, texts: &[String], ) -> RuntimeResult<Vec<Vec<f32>>>

Generate embeddings for multiple texts in one call.

Delegates to the cached EmbeddingService::embed, so repeated texts within and across calls benefit from the runtime-level LRU cache.

Returns an empty vec for empty input without hitting the embedding service. Returns Unconfigured("embedding_model") if no model is configured.

pub async fn vector_search( &self, namespace: Option<&str>, query_embedding: Option<Vec<f32>>, query_text: Option<&str>, top_k: u32, kind: Option<SubstrateKind>, ) -> RuntimeResult<Vec<VectorSearchHit>>

Search vectors using either a caller-provided embedding or query text.

Existing callers pass query_embedding: Some(vec) to avoid re-embedding. Text callers pass query_embedding: None, query_text: Some(...) and the runtime embeds internally.

pub async fn hybrid_search( &self, namespace: Option<&str>, query_text: &str, query_vector: Option<Vec<f32>>, limit: u32, entity_kind: Option<&str>, ) -> RuntimeResult<Vec<SearchHit>>

Hybrid search: text (FTS5) + vector retrieval fused via Reciprocal Rank Fusion.

• Always performs text search over query_text.
• If query_vector is Some, also performs vector search and fuses both lists.
• If None, returns text-only results — no vector store needed.
• If entity_kind is Some, the alive-set query filters to that kind. The text/vector candidate pools are unfiltered up front; the kind filter applies at the alive-check stage where we already fetch each candidate to confirm it isn’t soft-deleted.

limit caps the final returned list; internally pulls limit * 4 candidates per path. The fused candidate set is kept untruncated until after the alive + kind filter so that right-kind hits ranked below limit in the raw fusion still surface when higher-ranked candidates are wrong-kind or soft-deleted.

pub async fn knn( &self, namespace: Option<&str>, query_vector: Vec<f32>, top_k: u32, ) -> RuntimeResult<Vec<VectorSearchHit>>

Exact KNN over the full namespace’s vector store.

sqlite-vec uses brute-force cosine — results are exact, not approximate. Cost is O(N · D) per query. For small-to-medium namespaces (~hundreds of thousands of vectors) this is well within latency budgets.

pub async fn rerank( &self, namespace: Option<&str>, query_vector: &[f32], candidate_ids: &[Uuid], top_k: u32, ) -> RuntimeResult<Vec<VectorSearchHit>>

Exact KNN restricted to a candidate set.

Useful for reranking the top-N results from hybrid_search (or any other retrieval path) with exact cosine similarity against a query vector. Returns hits sorted by similarity (highest first), truncated to top_k.

impl KhiveRuntime

pub fn new(config: RuntimeConfig) -> RuntimeResult<Self>

Create a new runtime with the given config.

pub fn memory() -> RuntimeResult<Self>

Create an in-memory runtime (for tests and ephemeral use).

pub fn config(&self) -> &RuntimeConfig

Return a reference to the runtime config.

pub fn backend(&self) -> &StorageBackend

Return a reference to the underlying storage backend.

pub fn ns<'a>(&'a self, namespace: Option<&'a str>) -> &'a str

Resolve namespace: use provided value or fall back to default_namespace.

pub fn entities( &self, namespace: Option<&str>, ) -> RuntimeResult<Arc<dyn EntityStore>>

Get an EntityStore scoped to the given namespace (or default).

pub fn graph( &self, namespace: Option<&str>, ) -> RuntimeResult<Arc<dyn GraphStore>>

Get a GraphStore scoped to the given namespace (or default).

pub fn notes( &self, namespace: Option<&str>, ) -> RuntimeResult<Arc<dyn NoteStore>>

Get a NoteStore scoped to the given namespace (or default).

pub fn events( &self, namespace: Option<&str>, ) -> RuntimeResult<Arc<dyn EventStore>>

Get an EventStore scoped to the given namespace (or default).

pub fn sql(&self) -> Arc<dyn SqlAccess>

Get the raw SQL access capability (for ad-hoc queries).

pub fn vectors( &self, namespace: Option<&str>, ) -> RuntimeResult<Arc<dyn VectorStore>>

Get a VectorStore for the configured embedding model, scoped to the namespace.

Returns Unconfigured("embedding_model") if no model is set.

pub fn text( &self, namespace: Option<&str>, ) -> RuntimeResult<Arc<dyn TextSearch>>

Get a TextSearch index for the namespace’s entity corpus.

pub fn text_for_notes( &self, namespace: Option<&str>, ) -> RuntimeResult<Arc<dyn TextSearch>>

Get a TextSearch index for the namespace’s notes corpus.

pub fn install_edge_rules(&self, rules: Vec<EdgeEndpointRule>)

Install the pack-aggregated edge endpoint rules (ADR-031).

Called by the transport layer after the VerbRegistry is built so that runtime-layer edge validation (in validate_edge_relation_endpoints) can consult pack rules in addition to the ADR-002 base contract. Idempotent: later calls overwrite the previous rule set.

pub async fn embedder(&self) -> RuntimeResult<Arc<dyn EmbeddingService>>

Get the lazily-initialized embedding service.

Returns a CachedEmbeddingService wrapping a NativeEmbeddingService. First call loads the model (cold start cost); subsequent calls are cheap and benefit from LRU caching of repeated inputs.

Returns Unconfigured("embedding_model") if no model is set.

Trait Implementations

impl Clone for KhiveRuntime

fn clone(&self) -> KhiveRuntime

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.