Trait PackRuntime 

pub trait PackRuntime: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn note_kinds(&self) -> &'static [&'static str];
    fn entity_kinds(&self) -> &'static [&'static str];
    fn handlers(&self) -> &'static [HandlerDef];
    fn dispatch<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        verb: &'life1 str,
        params: Value,
        registry: &'life2 VerbRegistry,
        token: &'life3 NamespaceToken,
    ) -> Pin<Box<dyn Future<Output = Result<Value, RuntimeError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait;

    // Provided methods
    fn edge_rules(&self) -> &'static [EdgeEndpointRule] { ... }
    fn entity_types(&self) -> &'static [EntityTypeDef] { ... }
    fn requires(&self) -> &'static [&'static str] { ... }
    fn note_kind_specs(&self) -> &'static [NoteKindSpec] { ... }
    fn kind_hook(&self, _kind: &str) -> Option<Arc<dyn KindHook>> { ... }
    fn schema_plan(&self) -> SchemaPlan { ... }
    fn validation_rules(&self) -> &'static [ValidationRule] { ... }
    fn register_embedders(&self, _runtime: &KhiveRuntime) { ... }
    fn register_entity_type_validator(&self, _runtime: &KhiveRuntime) { ... }
    fn register_entity_type_validator_with_types(
        &self,
        runtime: &KhiveRuntime,
        _pack_entity_types: &[EntityTypeDef],
    ) { ... }
    fn register_note_mutation_hook(&self, _runtime: &KhiveRuntime) { ... }
    fn warm<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn registered_embedding_model_names(&self) -> Vec<String> { ... }
}

Async dispatch trait for packs.

This is the object-safe behavioral counterpart to khive_types::Pack. Pack uses const associated items (not object-safe in Rust); this trait mirrors that metadata as methods and adds async dispatch.

Registration requires P: Pack + PackRuntime — the compiler enforces that every runtime pack also declares its vocabulary via Pack.

Required Methods

fn name(&self) -> &str

Pack name — must equal <Self as Pack>::NAME.

fn note_kinds(&self) -> &'static [&'static str]

Note kinds this pack owns — must equal <Self as Pack>::NOTE_KINDS.

fn entity_kinds(&self) -> &'static [&'static str]

Entity kinds this pack owns — must equal <Self as Pack>::ENTITY_KINDS.

fn handlers(&self) -> &'static [HandlerDef]

Handlers this pack registers — must equal <Self as Pack>::HANDLERS.

fn dispatch<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, verb: &'life1 str, params: Value, registry: &'life2 VerbRegistry, token: &'life3 NamespaceToken, ) -> Pin<Box<dyn Future<Output = Result<Value, RuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Dispatch a verb call. Returns serialized JSON response.

The registry parameter gives the handler access to the merged vocabulary and kind hooks across all loaded packs. The token is an authorized namespace token minted by the dispatch boundary after gate authorization — handlers must use it directly.

Provided Methods

fn edge_rules(&self) -> &'static [EdgeEndpointRule]

Pack-extensible edge endpoint rules — must equal <Self as Pack>::EDGE_RULES. Defaults to empty so existing packs that don’t extend the edge contract can ignore it.

fn entity_types(&self) -> &'static [EntityTypeDef]

Pack-extensible entity-type subtypes — must equal <Self as Pack>::ENTITY_TYPES. Defaults to empty so existing packs that don’t extend the entity_type registry can ignore it.

fn requires(&self) -> &'static [&'static str]

Pack names whose vocabulary this pack references. Defaults to empty so existing packs compile without changes.

fn note_kind_specs(&self) -> &'static [NoteKindSpec]

NoteKindSpec declarations for note kinds this pack owns.

Packs that introduce note kinds with explicit lifecycle semantics declare the spec here. The runtime collects these for introspection and future enforcement. Defaults to empty so existing packs compile without changes.

fn kind_hook(&self, _kind: &str) -> Option<Arc<dyn KindHook>>

Optional per-kind hook for shared CRUD specialization.

When a kind is owned by this pack (declared in note_kinds() or entity_kinds()), returning Some(hook) opts that kind into pack-specific behavior — defaults, derived properties, side-effect edges — through the shared create path. Returning None keeps the kind as plain storage with no specialization.

fn schema_plan(&self) -> SchemaPlan

Pack-auxiliary schema.

Returns DDL statements for pack-owned tables that are NOT part of the core substrate schema. Statements are idempotent (CREATE TABLE IF NOT EXISTS) so callers can apply them safely on every registration. Core substrate tables evolve through versioned migrations; pack schema is strictly pack-auxiliary.

Defaults to an empty plan — packs that store everything in the core substrate tables (entities, notes, edges, events) return this default.

Plans are aggregated via VerbRegistry::all_schema_plans and applied at startup via KhiveMcpServer::with_packs. Packs that need their schema present (e.g. GTD) also self-bootstrap lazily on first call for robustness in test contexts that create fresh in-memory databases.

fn validation_rules(&self) -> &'static [ValidationRule]

Domain-specific validation rules contributed by this pack.

Rule IDs MUST follow the <pack>/<rule-id> namespace convention. Built-in rules (no pack prefix) are reserved for the khive-runtime validation infrastructure.

Defaults to empty — packs with no domain-specific rules return &[].

fn register_embedders(&self, _runtime: &KhiveRuntime)

Register custom embedding providers with the runtime. Called during pack initialisation, before the first verb dispatch, so KhiveRuntime::embedder(name) resolves provider names declared here. Default no-op — packs that only use built-in lattice models do not need to override this. See docs/api/pack.md#register_embedders for a usage example.

fn register_entity_type_validator(&self, _runtime: &KhiveRuntime)

Install a pack-owned entity-type validator on the runtime, called during pack initialisation (after the registry is built, before the first dispatch) so create_many/create_entity reject unregistered entity_type values at the runtime layer. Default no-op leaves the validator absent (skip-when-None). See docs/api/pack.md#register_entity_type_validator for the two-hook compatibility contract.

fn register_entity_type_validator_with_types( &self, runtime: &KhiveRuntime, _pack_entity_types: &[EntityTypeDef], )

Install a pack-owned entity-type validator that also receives the boot-time composed set of every loaded pack’s ENTITY_TYPES (VerbRegistry::all_entity_types). Defaults to calling register_entity_type_validator with just the runtime. call_register_entity_type_validators calls this hook, not the simpler one — override this to receive the composed vocabulary. See docs/api/pack.md#register_entity_type_validator for the two-hook compatibility contract.

fn register_note_mutation_hook(&self, _runtime: &KhiveRuntime)

Install a pack-owned note-mutation hook on the runtime, called during pack initialisation with the same timing as register_entity_type_validator. Packs that cache derived state keyed by note content (e.g. khive-pack-memory’s warm ANN index) override this to install a hook via KhiveRuntime::install_note_mutation_hook. Default no-op leaves the hook absent. See docs/api/pack.md#register_note_mutation_hook for cross-pack notification rationale.

fn warm<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Warm up any in-memory state from persisted snapshots (optional). Called after all packs are registered but before serving the first request. Must be idempotent and infallible — errors are logged internally, never propagated.

fn registered_embedding_model_names(&self) -> Vec<String>

Names of all embedding models registered on this pack’s underlying runtime handle. Defaults to empty — only packs that own embedding-bearing verbs (kg, memory) need to override this. See docs/api/pack.md#registered_embedding_model_names for the ADR-103 consumer.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors