Skip to main content

Crate khive_runtime

Crate khive_runtime 

Source
Expand description

khive-runtime: composable Service API used by daemon, MCP server, and CLI.

Wraps StorageBackend and query compilation into a single Rust API surface.

Re-exports§

pub use actor_identity::actor_is_unattributed;
pub use actor_identity::resolve_actor;
pub use actor_identity::should_warn_unattributed_actor;
pub use agent_lifecycle::apply_transition;
pub use agent_lifecycle::spawn_fingerprint;
pub use agent_lifecycle::IllegalTransition;
pub use agent_lifecycle::Transition;
pub use agent_lifecycle::Trigger;
pub use atomic_message::create_notes_atomic;
pub use atomic_message::create_notes_atomic_with_report;
pub use atomic_message::AtomicNoteSpec;
pub use atomic_plan::AddEntityPlan;
pub use atomic_plan::AddNotePlan;
pub use atomic_plan::AffectedRowGuard;
pub use atomic_plan::DeletePlan;
pub use atomic_plan::GovernanceOp;
pub use atomic_plan::GovernancePlan;
pub use atomic_plan::GtdCompletePlan;
pub use atomic_plan::GtdTransitionPlan;
pub use atomic_plan::LinkPlan;
pub use atomic_plan::MergePlan;
pub use atomic_plan::PlanPredicate;
pub use atomic_plan::PlanStatement;
pub use atomic_plan::PostCommitEffect;
pub use atomic_plan::UpdatePlan;
pub use atomic_runner::run_atomic_unit;
pub use atomic_runner::AtomicOpFailure;
pub use atomic_runner::AtomicOpPlan;
pub use atomic_runner::AtomicRunOutcome;
pub use atomic_runner::AtomicRunnerError;
pub use atomic_runner::CommittedPostCommitEffects;
pub use blob::resolve_blob_store;
pub use blob::resolve_blob_store_for_mode;
pub use blob::BlobHydrator;
pub use blob::GovernedBlobError;
pub use blob::VerifiedBlob;
pub use blob::DEFAULT_BLOB_HYDRATION_BYTES;
pub use build_info::BuildInfo;
pub use build_info::BUILD_INFO;
pub use build_info::BUILD_VERSION;
pub use config::ann_fresh_tail_enabled_from_env;
pub use config::process_ref_from_env;
pub use cost_unit::base_resource_payload;
pub use cost_unit::cost_unit_for_dispatch;
pub use cost_unit::resource_payload;
pub use curation::entity_embedding_text;
pub use curation::entity_fts_document;
pub use curation::entity_merge_guard_error;
pub use curation::note_embedding_text;
pub use curation::note_fts_document;
pub use curation::validate_entity_merge_floor;
pub use curation::ContentMergeStrategy;
pub use curation::EdgeListFilter;
pub use curation::EdgePatch;
pub use curation::EntityDedupMergePolicy;
pub use curation::EntityMergeGuard;
pub use curation::EntityPatch;
pub use curation::MergeEdgeConflictPreimage;
pub use curation::MergeEdgePreimage;
pub use curation::MergeSummary;
pub use curation::MergeTxBudgetReport;
pub use curation::MergeTxLimits;
pub use curation::NotePatch;
pub use daemon::acquire_recovery_lock;
pub use daemon::pid_path;
pub use daemon::run_daemon;
pub use daemon::socket_path;
pub use daemon::DaemonDispatch;
pub use daemon::active_phase_names;
pub use daemon::background_task_count;
pub use daemon::daemon_shutdown_token;
pub use daemon::register_active_phase;
pub use daemon::track_background_task;
pub use daemon::DaemonRequestFrame;
pub use daemon::DaemonResponseFrame;
pub use daemon::PhaseGuard;
pub use daemon::PROTOCOL_VERSION;
pub use embedder_registry::EmbedderProvider;
pub use embedder_registry::EmbedderRegistry;
pub use embedder_registry::LatticeEmbedderProvider;
pub use engine_config::config_from_env;
pub use engine_config::BackendConfig;
pub use engine_config::BackendKind;
pub use engine_config::BlobConfig;
pub use engine_config::ConfigError;
pub use engine_config::EngineConfig;
pub use engine_config::GitWriteEntryConfig;
pub use engine_config::GitWriteSectionConfig;
pub use engine_config::KhiveConfig;
pub use engine_config::PackConfig;
pub use engine_config::StorageSectionConfig;
pub use error::fts_text_leg_or_err;
pub use error::AdmissionFailureContext;
pub use error::ChannelIngestFailureClass;
pub use error::GuardedWriteFailure;
pub use error::RuntimeError;
pub use error::RuntimeResult;
pub use error::WriterPoolCheckoutTimeoutContext;
pub use error::WRITER_ADMISSION_SCOPE;
pub use error::WRITER_POOL_CHECKOUT_TIMEOUT_STAGE;
pub use error::WRITER_QUEUE_SATURATED_STAGE;
pub use graph_traversal::PathNode;
pub use objectives::AmplifiedDecayAwareSalienceObjective;
pub use objectives::DecayAwareSalienceObjective;
pub use objectives::GraphProximityObjective;
pub use objectives::MemoryRecallPipeline;
pub use objectives::NoteCandidate;
pub use objectives::RerankerObjective;
pub use objectives::RetrievalCandidate;
pub use objectives::RrfFusionObjective;
pub use objectives::TemporalRecencyObjective;
pub use objectives::TextRelevanceObjective;
pub use objectives::VectorSimilarityObjective;
pub use operations::base_entity_endpoint_rules;
pub use operations::base_entity_rule_allows;
pub use operations::endpoint_matches;
pub use operations::hex_prefix_to_uuid_pattern;
pub use operations::merge_entry_metadata;
pub use operations::uuid_prefix_bounds;
pub use operations::EdgeEndpointKind;
pub use operations::EntityCreateSpec;
pub use operations::LinkSpec;
pub use operations::NoteSearchHit;
pub use operations::QueryResult;
pub use operations::Resolved;
pub use pack::resolve_explicit_namespace;
pub use pack::ChannelIngestCapability;
pub use pack::DispatchHook;
pub use pack::InterceptedDispatchResult;
pub use pack::KindHook;
pub use pack::PackByIdResolver;
pub use pack::PackFactory;
pub use pack::PackInstall;
pub use pack::PackLoadError;
pub use pack::PackRegistration;
pub use pack::PackRegistry;
pub use pack::PackRuntime;
pub use pack::PackSchemaCollisionError;
pub use pack::RequestIdentity;
pub use pack::SchemaPlan;
pub use pack::VerbRegistry;
pub use pack::VerbRegistryBuilder;
pub use pack::VerifiedActor;
pub use pack::AUDIT_PERSISTENCE_SKIPPED_READ_ONLY;
pub use phase_events::emit_phase_event;
pub use phase_events::is_benign_shutdown_cancellation;
pub use portability::ImportSummary;
pub use portability::KgArchive;
pub use preference_verification::LegacyPreferenceVerifier;
pub use preference_verification::VerifiedModelNetworkAttachment;
pub use presentation::apply_redundancy_drop;
pub use presentation::micros_to_iso;
pub use presentation::present;
pub use presentation::render_format;
pub use presentation::rfc3339_to_utc_micros;
pub use presentation::OutputFormat;
pub use presentation::PresentationMode;
pub use reference_resolution::resolve_reference;
pub use reference_resolution::ReferenceCandidate;
pub use reference_resolution::ReferenceResolution;
pub use reference_ring::ReferenceRing;
pub use reference_ring::RingEntry;
pub use registry::ObjectiveRegistry;
pub use registry::RegisteredObjective;
pub use resource::cpu_delta_us;
pub use resource::process_resource_usage;
pub use resource::ProcessResourceUsage;
pub use retrieval::SearchHit;
pub use retrieval::SearchSource;
pub use runtime::assert_captured_db_anchor_consistent;
pub use runtime::assert_db_anchor_consistent;
pub use runtime::expand_tilde;
pub use runtime::parse_pack_list;
pub use runtime::resolve_db_anchor;
pub use runtime::resolve_project_actor_id;
pub use runtime::runtime_config_from_khive_config;
pub use runtime::BackendId;
pub use runtime::EntityTypeValidatorFn;
pub use runtime::KhiveRuntime;
pub use runtime::NamedVectorIdentity;
pub use runtime::NamespaceToken;
pub use runtime::NoteMutationHookFn;
pub use runtime::NoteWriteValidatorFn;
pub use runtime::RuntimeConfig;
pub use secret_gate::SecretMatch;
pub use validation::GraphPatch;
pub use validation::GraphSnapshot;
pub use validation::RuleFn;
pub use validation::RuleId;
pub use validation::Severity;
pub use validation::ValidationContext;
pub use validation::ValidationReport;
pub use validation::ValidationRule;
pub use validation::Violation;

Modules§

actor_identity
Shared actor-identity resolution (issue #567).
agent_lifecycle
Pure lifecycle logic for the runtime-owned agent process record (ADR-142 §1).
ann_registry
Durable ANN-consumer registration lifecycle and compaction.
atomic_message
Atomic multi-note write primitive: commits a set of notes — each with its FTS document and every registered embedding model’s vector row — in ONE writer transaction, instead of one create_note call per note.
atomic_plan
ADR-099 (cross-op atomicity for bulk apply) — prepared write-plan types.
atomic_prepare
ADR-099: the per-verb async prepare pass for the KG-substrate v1 admissible verbs (update, delete, link, merge), plus prepare_add_entity/prepare_add_note for the ADR-046 proposal changeset AddEntity/AddNote arms. Each prepare_* function reads current state (async, outside any transaction) and returns a plain-data crate::atomic_runner::AtomicOpPlan (crate::atomic_plan) for the synchronous commit pass (crate::atomic_runner::run_atomic_unit) to apply.
atomic_runner
ADR-099 migration step 3 (sub-slice B2) — the atomic runner: the synchronous commit-pass mechanism that applies a caller-supplied sequence of prepared write plans (crate::atomic_plan) as ONE SqlAccess::atomic_unit, under a per-op SAVEPOINT, committing every plan or rolling back the whole unit.
audit_batch
ADR-133 Slice 1: the audit-batch seam.
blob
Config-driven BlobStore selection (ADR-111 Amendment 2).
build_info
Compile-time identity for the source and build that produced this runtime.
config
RuntimeConfig, BackendId, NamespaceToken, and embedding model helpers.
config_ledger
ADR-094 process-lifetime config lock ledger.
cost_unit
ADR-103 Amendment 1: deterministic cost_unit for the per-dispatch audit-row resource payload enrichment.
curation
Curation operations: entity update/merge and edge-list filter type.
daemon
khived daemon server — persistent warm runtime over a Unix socket.
embedder_registry
EmbedderRegistry — pack-extensible embedding provider surface.
engine_config
TOML-based embedding engine configuration for khive.
error
Runtime error types.
events_split
Events-daemon split (ADR-170): the audit lane leaves the domain store.
fusion
Fusion strategies for combining ranked result lists.
graph_traversal
objectives
Retrieval Objective implementations for khive-runtime.
operations
High-level operations composing storage capabilities into user-facing verbs.
pack
Pack runtime trait and verb registry.
phase_events
Shared helpers for ADR-103 phase-span event emission.
portability
KG export / import — portable JSON archive for namespace-scoped knowledge graphs.
preference_verification
Legacy moodboard preference-model verification, inverted behind a trait.
presentation
Verb response presentation modes and transformation.
reference_resolution
resolve_reference: the Layer-0 deterministic reference resolver from the “unified-verb” draft ADR (Slice 1 — resolver + ring).
reference_ring
Recently-referenced ring: a bounded, per-(namespace, actor) cache of ids this actor recently touched by name, held in daemon-warm memory only.
registry
Objective registry for dynamic dispatch.
resource
Process-level resource reads (ADR-103 Stage 1).
retrieval
Retrieval operations: local embedding generation and hybrid search with RRF fusion.
runtime
KhiveRuntime — composable handle to all storage capabilities.
secret_gate
Write-time secret detection gate.
time_anchor
Calendar-date → earliest-instant anchoring (ADR-169 D1), shared by every surface that accepts a date-only value against the configured display timezone. Moved verbatim from khive-pack-gtd’s handlers when brain.event_counts gained the same date-only semantics — packs do not depend on packs, so the shared rule lives here beside the display_timezone config it interprets.
usage
ADR-103 Amendment 2: dispatch-scoped executed-usage counters.
validation
Validation pipeline types for pack-contributed KG rules.

Structs§

ActorRef
Caller identity with non-empty kind and id, validated on construction and deserialization.
AgentRecord
The runtime-owned agent process record (ADR-142 §1, “Persistent process record”).
AllowAllGate
Permissive gate — every request is allowed with no obligations.
AuditEvent
Structured audit record emitted once per gate consultation.
CheckpointConfig
Configuration for the WAL checkpoint background task.
CheckpointLifecycleOwner
The event sink and namespace owned by one checkpoint task in a fan-out.
ConnectionPool
A read-write connection pool for SQLite.
EventObservation
A single entity observation recorded alongside an event.
EventView
An event together with its associated observations.
GateContext
Per-request context — session, timing, transport source.
GateRequest
What the gate sees on every verb invocation.
HandlerDef
Handler metadata for discovery and documentation.
Namespace
A validated, opaque namespace identifier.
NoteKindSpec
Kind-level schema specification for a note kind.
NoteLifecycleSpec
Lifecycle specification for a note kind.
PackSchemaPlan
DDL statements the pack needs applied to the auxiliary schema.
ParamDef
Parameter type for help=true schema envelopes.
StorageBackend
Concrete storage backend providing capability traits.
TraversalOptions
BFS traversal configuration controlling depth, direction, and edge filters. Deserialization rejects non-finite min_weight.

Enums§

AgentState
One of the four lifecycle states an agent process record can occupy.
AuditDecision
The outcome field of an AuditEvent.
CheckpointTick
Outcome of a single checkpoint attempt.
FusionStrategy
Validated selection for combining ranked result lists.
GateDecision
Gate decision: allow (with optional obligations) or deny (with reason).
GateError
Errors returned by crate::Gate::check.
Obligation
Policy instructions attached to an allow; only Audit has v0 runtime handling.
ObservationRole
Role of a referent in a brain observation (candidate, selected, target, signal).
ReferentKind
Which substrate (entity or note) the referent record lives in.
TerminalReason
Why a record reached Terminal. Set exactly once, at the transition into Terminal.
VerbCategory
Illocutionary force classification for a verb handler.
VerbPresentationPolicy
Presentation override for a verb handler.
Visibility
Visibility tier for a handler.

Traits§

Gate
Authorization gate consulted before each verb dispatch.

Functions§

checkpoint_once
Issue one checkpoint cycle against the task’s dedicated checkpoint connection (conn — see CheckpointConnection; NEVER the pool’s writer mutex).
run_checkpoint_task
Run the WAL checkpoint background task.
run_migrations

Type Aliases§

GateRef
Shareable handle to a Gate impl.