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 host_state(&self) -> Option<Arc<dyn Any + Send + Sync>> { ... }
    fn validate_config(&self) -> Result<(), RuntimeError> { ... }
    fn brain_consumer_kinds(&self) -> &'static [&'static str] { ... }
    fn apply_profile_section_feedback<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _token: &'life1 NamespaceToken,
        _profile_id: &'life2 str,
        _section_signals: Value,
        _target_attribution: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<Value, RuntimeError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn input_schema(&self, _verb: &str) -> Option<Value> { ... }
    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 accept_channel_ingest_capability(
        &self,
        _capability: ChannelIngestCapability,
    ) { ... }
    fn schema_plan(&self) -> SchemaPlan { ... }
    fn schema_column_additions(&self) -> &'static [PackColumnAddition] { ... }
    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 register_note_write_validator(&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> { ... }
    fn mounted_namespace(&self) -> Option<&str> { ... }
    fn mounted_catalog_snapshot(&self) -> Vec<MountedVerb> { ... }
    fn mounted_catalog<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MountedVerb>, RuntimeError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn dispatch_mounted<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
        &'life0 self,
        _definition: &'life1 MountedVerb,
        verb: &'life2 str,
        params: Value,
        registry: &'life3 VerbRegistry,
        token: &'life4 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,
             'life4: 'async_trait { ... }
}

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 host_state(&self) -> Option<Arc<dyn Any + Send + Sync>>

Optional instance-owned state for host work outside verb dispatch. Return the same shared state used by this pack’s handlers. The host owns task startup and shutdown; this accessor must not start work.

fn validate_config(&self) -> Result<(), RuntimeError>

Validate this pack instance’s configuration before it can execute. Metadata-only construction does not activate packs.

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

Brain profile consumer kinds this pack requests — must equal <Self as Pack>::BRAIN_CONSUMER_KINDS.

fn apply_profile_section_feedback<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _token: &'life1 NamespaceToken, _profile_id: &'life2 str, _section_signals: Value, _target_attribution: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<Value, RuntimeError>> + Send + 'async_trait>>

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

Trusted in-process section feedback after the calling pack has validated its own target. This is not a registered handler or a wire entry point.

fn input_schema(&self, _verb: &str) -> Option<Value>

Optional canonical input schema owned by the pack; ParamDefs remain available.

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 accept_channel_ingest_capability(&self, _capability: ChannelIngestCapability)

Accept the trusted channel-ingest capability grant for this specific pack instance.

Called at most once per instance, immediately after this instance is constructed via PackFactory::create_install, and only for packs whose name appears in CHANNEL_INGEST_CAPABLE_PACKS. Storing the grant on self (rather than on the &'static dyn PackFactory, which is a single process-wide singleton shared by every instance the factory ever creates) makes the grant instance-bound: a CommPack built outside PackRegistry::register_packs holds no capability unless something calls this on that specific instance. Defaults to a no-op so packs outside the allowlist compile without changes.

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 schema_column_additions(&self) -> &'static [PackColumnAddition]

Nullable-column upgrades for this pack’s auxiliary tables.

Must equal Pack::SCHEMA_COLUMN_ADDITIONS. The backend validates and adds missing columns on existing tables before applying the full schema plan, then validates every declared column. Both steps share the plan’s transaction. Defaults to empty for packs with no auxiliary upgrades.

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 register_note_write_validator(&self, _runtime: &KhiveRuntime)

Install a note-write validator on the runtime, called at pack initialisation with the same timing as register_note_mutation_hook.

A pack owning a note kind whose properties carry identity that the runtime can derive from the authorization token implements this and calls KhiveRuntime::install_note_write_validator, so the identity is derived at every note-write site rather than trusted from caller input on the write paths that reach no pack verb. Default no-op leaves the slot absent. The slot holds one validator, so an implementation must return properties for kinds it does not own unchanged.

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.

fn mounted_namespace(&self) -> Option<&str>

fn mounted_catalog_snapshot(&self) -> Vec<MountedVerb>

Advisory owned catalog only: no storage, process, gate, or audit work.

fn mounted_catalog<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<MountedVerb>, RuntimeError>> + Send + 'async_trait>>

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

fn dispatch_mounted<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, _definition: &'life1 MountedVerb, verb: &'life2 str, params: Value, registry: &'life3 VerbRegistry, token: &'life4 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, 'life4: 'async_trait,

Dyn Compatibility

This trait is dyn compatible.

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

Implementors