Skip to main content

khive_runtime/pack/
loading.rs

1use super::{
2    Arc, DispatchHook, HashMap, KhiveRuntime, PackByIdResolver, PackRuntime, RuntimeError,
3    VerbRegistry, VerbRegistryBuilder, Visibility, CHANNEL_INGEST_CAPABLE_PACKS,
4};
5
6// ── Inventory-based dynamic pack loading ────────────────────────────────────
7
8/// Output of [`PackFactory::create_install`] — bundles the pack runtime with
9/// its optional by-ID resolver and dispatch hook so a factory can hand back
10/// all three built from one shared instance (see `BrainPackFactory` for why
11/// this matters: the dispatch hook must observe the same state the runtime
12/// mutates, not a second unrelated instance).
13pub struct PackInstall {
14    /// The pack runtime, registered into the builder's pack list.
15    pub runtime: Box<dyn PackRuntime>,
16    /// Optional by-ID resolver, registered when present.
17    pub resolver: Option<Box<dyn PackByIdResolver>>,
18    /// Optional post-dispatch observer, wired via `VerbRegistryBuilder::with_dispatch_hook`.
19    pub dispatch_hook: Option<Arc<dyn DispatchHook>>,
20}
21
22/// Factory for creating pack instances registered via `inventory` at link time.
23/// Each pack crate submits a `&'static dyn PackFactory` wrapped in a
24/// [`PackRegistration`]; the binary's linker collects them all into a single
25/// slice iterable at runtime.
26///
27/// Implementors must be `Send + Sync + 'static` because the registry is built
28/// once and shared across async tasks.
29/// Possession-bounded capability for the trusted channel-ingest note path.
30///
31/// Constructible only inside `khive-runtime` (the field is private), and
32/// granted during pack registration exclusively to factories named in
33/// `CHANNEL_INGEST_CAPABLE_PACKS`. Every call to
34/// [`crate::KhiveRuntime::try_create_note_as_trusted_ingest`] must present a
35/// reference to one, so the set of callers able to establish transport-owned
36/// message properties is bounded by possession at the composition root, not
37/// by a documentation prohibition. Two ways to obtain one: registering
38/// through [`PackRegistry::register_packs`]/`register_packs_with_runtimes`
39/// under the `comm` name (the allowlisted, automatic path), or a composition
40/// root that builds packs directly calling
41/// [`ChannelIngestCapability::grant_for_direct_composition`] and passing the
42/// result to [`crate::PackRuntime::accept_channel_ingest_capability`] (or a
43/// pack's constructor variant that does so) itself. The residual trust
44/// assumption is unchanged either way: whoever assembles the
45/// `VerbRegistryBuilder` already decides which packs are wired in and already
46/// holds a `KhiveRuntime`, so minting the grant explicitly carries no more
47/// privilege than that composition already had by choosing to register `comm`
48/// at all.
49pub struct ChannelIngestCapability {
50    pub(crate) _sealed: (),
51}
52
53impl ChannelIngestCapability {
54    /// Mint a capability for a composition root that constructs
55    /// channel-transport packs directly, bypassing
56    /// [`PackRegistry::register_packs`] (which grants this automatically).
57    ///
58    /// See the type-level doc for the trust argument: this carries no more
59    /// privilege than the caller already has by virtue of holding a
60    /// `KhiveRuntime` and choosing to wire the pack in.
61    pub fn grant_for_direct_composition() -> Self {
62        Self { _sealed: () }
63    }
64}
65
66pub trait PackFactory: Send + Sync + 'static {
67    /// Canonical lowercase name for this pack (e.g. `"kg"`, `"gtd"`).
68    fn name(&self) -> &'static str;
69
70    /// Version reported by this factory for introspection.
71    ///
72    /// The compatibility default is the version of `khive-runtime`, where
73    /// this trait is defined. Independently versioned pack crates should
74    /// override this method with their own `env!("CARGO_PKG_VERSION")`.
75    fn version(&self) -> &'static str {
76        env!("CARGO_PKG_VERSION")
77    }
78
79    /// Names of packs that must be loaded before this one.
80    ///
81    /// Defaults to empty so pack crates that have no dependencies compile
82    /// without changes. [`PackRegistry::register_packs`] validates that every
83    /// name listed here is present in the caller's explicit pack list — absent
84    /// dependencies are a boot error, not silently auto-added.
85    fn requires(&self) -> &'static [&'static str] {
86        &[]
87    }
88
89    /// Whether this pack intentionally exposes no top-level MCP verbs.
90    ///
91    /// Defaults to `false` so a declared pack whose runtime contributes no
92    /// [`Visibility::Verb`] handlers fails at registration instead of silently
93    /// disappearing from the served surface. Vocabulary- or ontology-only
94    /// packs must opt in explicitly.
95    fn intentionally_verbless(&self) -> bool {
96        false
97    }
98
99    /// Create a new pack instance for the given runtime.
100    fn create(&self, runtime: KhiveRuntime) -> Box<dyn PackRuntime>;
101
102    /// Build the full installation bundle for this pack: runtime, optional
103    /// resolver, optional dispatch hook.
104    ///
105    /// Defaults to composing `create` and `create_resolver` with no dispatch
106    /// hook, so existing factories compile unchanged. Packs whose dispatch
107    /// hook must observe the same instance as the runtime (e.g. `brain`)
108    /// override this method instead of `create`, since the default would
109    /// otherwise require two independent instances to share state.
110    fn create_install(&self, runtime: KhiveRuntime) -> PackInstall {
111        let resolver = self.create_resolver(runtime.clone());
112        PackInstall {
113            runtime: self.create(runtime),
114            resolver,
115            dispatch_hook: None,
116        }
117    }
118
119    /// Optionally create a `PackByIdResolver` for this pack.
120    ///
121    /// Packs that own private SQL tables implement this to hook into
122    /// `get(id)` and `delete(id)`. Defaults to `None` so existing packs
123    /// compile without changes.
124    fn create_resolver(&self, _runtime: KhiveRuntime) -> Option<Box<dyn PackByIdResolver>> {
125        None
126    }
127}
128
129/// Newtype wrapper collected by `inventory` so pack crates can submit
130/// `&'static dyn PackFactory` references without the type-ascription syntax
131/// that `inventory::submit!` does not support for bare trait-object references.
132pub struct PackRegistration(pub &'static dyn PackFactory);
133
134inventory::collect!(PackRegistration);
135
136/// Error returned by [`PackRegistry::register_packs`] when boot validation fails.
137#[derive(Debug)]
138pub enum PackLoadError {
139    /// The requested pack name was not found in the inventory.
140    UnknownPack(String),
141    /// The requested pack name occurs more than once.
142    DuplicatePack(String),
143    /// A pack was requested but a declared dependency is absent from the list.
144    MissingDependency {
145        /// The pack that declared the dependency.
146        pack: String,
147        /// The dependency that is missing from the requested pack list.
148        dep: String,
149    },
150    /// Multiple declared dependencies are absent from the requested pack list.
151    MissingDependencies {
152        /// Missing `(requiring pack, required pack)` pairs in selection/declaration order.
153        missing: Vec<(String, String)>,
154    },
155    /// A declared pack contributed no top-level verbs without explicitly
156    /// declaring itself vocabulary/ontology-only.
157    NoPublicVerbs {
158        /// The declared pack name.
159        pack: String,
160    },
161}
162
163impl std::fmt::Display for PackLoadError {
164    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
165        match self {
166            PackLoadError::UnknownPack(name) => write!(f, "unknown pack {name:?}"),
167            PackLoadError::DuplicatePack(name) => write!(f, "duplicate pack {name:?}"),
168            PackLoadError::MissingDependency { pack, dep } => write!(
169                f,
170                "pack {pack:?} requires {dep:?}, which is not in the requested pack list; \
171                 add --pack {dep} before --pack {pack}"
172            ),
173            PackLoadError::MissingDependencies { missing } => {
174                write!(f, "missing pack dependencies: ")?;
175                for (index, (pack, dep)) in missing.iter().enumerate() {
176                    if index > 0 {
177                        write!(f, "; ")?;
178                    }
179                    write!(f, "pack {pack:?} requires {dep:?}")?;
180                }
181                write!(f, "; add all missing packs to the requested pack list")
182            }
183            PackLoadError::NoPublicVerbs { pack } => write!(
184                f,
185                "declared pack {pack:?} registers no public verbs; if this pack is \
186                 intentionally vocabulary- or ontology-only, its factory must declare \
187                 intentionally_verbless() = true"
188            ),
189        }
190    }
191}
192
193impl std::error::Error for PackLoadError {}
194
195/// Reject a declared pack whose runtime contributes no [`Visibility::Verb`]
196/// handlers unless its factory explicitly opts out via
197/// [`PackFactory::intentionally_verbless`].
198fn check_pack_has_public_verbs(
199    factory: &dyn PackFactory,
200    install: &PackInstall,
201    name: &str,
202) -> Result<(), PackLoadError> {
203    if !factory.intentionally_verbless()
204        && !install
205            .runtime
206            .handlers()
207            .iter()
208            .any(|handler| matches!(handler.visibility, Visibility::Verb))
209    {
210        return Err(PackLoadError::NoPublicVerbs {
211            pack: name.to_string(),
212        });
213    }
214    Ok(())
215}
216
217/// Registry of pack factories discovered via `inventory` at link time.
218///
219/// No instance is needed — all methods are associated functions that walk the
220/// globally-collected [`PackRegistration`] slice.
221pub struct PackRegistry;
222
223/// Whether [`PackRegistry::build_ingest_registry`] attaches the runtime's
224/// event store to the registry it builds.
225#[derive(Debug, Clone, Copy, PartialEq, Eq)]
226pub enum IngestAuditStore {
227    /// Mirror `KhiveMcpServer::with_packs` (`khive-mcp/src/server.rs`): a
228    /// writable runtime attaches its own event store and refuses to build if
229    /// sink initialization fails; a read-only runtime retains no `EventStore`
230    /// handle and an advisory travels beside each result instead.
231    Attach,
232    /// Build the registry with no audit event store, for a caller with no use
233    /// for persisted audit rows.
234    Detach,
235}
236
237impl PackRegistry {
238    /// Names of all pack factories discovered via `inventory`.
239    pub fn discovered_names() -> Vec<&'static str> {
240        inventory::iter::<PackRegistration>
241            .into_iter()
242            .map(|r| r.0.name())
243            .collect()
244    }
245
246    /// Validate linked pack names and explicit dependencies without creating
247    /// runtimes, opening stores, or constructing pack instances.
248    ///
249    /// Launchers can use this before publishing ownership. Registration uses
250    /// the same validation, including when extra factories are supplied.
251    pub fn validate_pack_selection(names: &[String]) -> Result<(), PackLoadError> {
252        let all: Vec<&'static dyn PackFactory> = inventory::iter::<PackRegistration>
253            .into_iter()
254            .map(|r| r.0)
255            .collect();
256        Self::validate_pack_selection_from(&all, names)
257    }
258
259    fn validate_pack_selection_from(
260        factories: &[&'static dyn PackFactory],
261        names: &[String],
262    ) -> Result<(), PackLoadError> {
263        let factory_for = |name: &str| factories.iter().copied().find(|f| f.name() == name);
264        let mut requested = std::collections::HashSet::new();
265        for name in names {
266            factory_for(name).ok_or_else(|| PackLoadError::UnknownPack(name.clone()))?;
267            if !requested.insert(name.as_str()) {
268                return Err(PackLoadError::DuplicatePack(name.clone()));
269            }
270        }
271        let mut missing = Vec::new();
272        for name in names {
273            let factory = factory_for(name).unwrap(); // All names were validated above.
274            for &dep in factory.requires() {
275                if !requested.contains(dep) {
276                    missing.push((name.clone(), dep.to_string()));
277                }
278            }
279        }
280        if missing.len() == 1 {
281            let (pack, dep) = missing.remove(0);
282            return Err(PackLoadError::MissingDependency { pack, dep });
283        }
284        if !missing.is_empty() {
285            return Err(PackLoadError::MissingDependencies { missing });
286        }
287        Ok(())
288    }
289
290    /// Register the named packs into `builder` using the supplied `runtime`.
291    ///
292    /// Validates the explicit pack list against `PackFactory::requires()` —
293    /// if any requested pack declares a dependency that is absent from `names`,
294    /// registration fails (missing dependency is a boot error, not silently
295    /// auto-added). Callers must include all required packs explicitly.
296    ///
297    /// The [`VerbRegistryBuilder::build`] topo-sort enforces correct load order.
298    ///
299    /// Returns `Ok(())` when all names are recognised and all declared
300    /// dependencies are satisfied; returns `Err(PackLoadError)` with a
301    /// distinct variants for unknown or duplicate packs and missing dependencies.
302    pub fn register_packs(
303        names: &[String],
304        runtime: KhiveRuntime,
305        builder: &mut VerbRegistryBuilder,
306    ) -> Result<(), PackLoadError> {
307        // Build a name→factory index once.
308        let all: Vec<&'static dyn PackFactory> = inventory::iter::<PackRegistration>
309            .into_iter()
310            .map(|r| r.0)
311            .collect();
312        let factory_for = |name: &str| -> Option<&'static dyn PackFactory> {
313            all.iter().copied().find(|f| f.name() == name)
314        };
315
316        Self::validate_pack_selection_from(&all, names)?;
317
318        // Register every requested pack; VerbRegistryBuilder::build()
319        // performs the topo-sort, so insertion order here does not matter.
320        for name in names {
321            let factory = factory_for(name.as_str()).unwrap(); // validated above
322            let install = factory.create_install(runtime.clone());
323            check_pack_has_public_verbs(factory, &install, name)?;
324            if CHANNEL_INGEST_CAPABLE_PACKS.contains(&name.as_str()) {
325                install
326                    .runtime
327                    .accept_channel_ingest_capability(ChannelIngestCapability { _sealed: () });
328            }
329            builder
330                .pack_versions
331                .insert(install.runtime.name().to_owned(), factory.version());
332            builder.register_boxed(install.runtime);
333            if let Some(resolver) = install.resolver {
334                builder.register_resolver(name.clone(), resolver);
335            }
336            if let Some(hook) = install.dispatch_hook {
337                builder.with_dispatch_hook(hook);
338            }
339        }
340
341        Ok(())
342    }
343
344    /// Build a `VerbRegistry` from `runtime`'s own configuration: gate,
345    /// default namespace, visible namespaces, actor id, and the configured
346    /// pack set, then install the registry's aggregated edge rules back onto
347    /// `runtime`. This is the wiring shared by every one-shot CLI ingest path
348    /// (`kkernel code-ingest`, `kkernel git-ingest`) that needs a real
349    /// registry to dispatch through outside of a live MCP server.
350    ///
351    /// `audit_store` selects whether the registry gets the runtime's event
352    /// store; see [`IngestAuditStore`] for what each variant does.
353    ///
354    /// This helper carries only the subset every ingest path duplicated
355    /// verbatim. The MCP server's own registry construction additionally
356    /// wires channel-loop admission, `config_id`, entity-type and
357    /// note-mutation-hook registration, schema-plan application, and the WAL
358    /// checkpoint pool handle — all server-only concerns a one-shot CLI pass
359    /// has no use for, so `KhiveMcpServer::with_packs` keeps its own
360    /// construction rather than calling this helper. Both hosts register pack
361    /// embedding providers and finalize configured engine binding before return.
362    pub fn build_ingest_registry(
363        runtime: &KhiveRuntime,
364        audit_store: IngestAuditStore,
365    ) -> Result<VerbRegistry, RuntimeError> {
366        let mut builder = VerbRegistryBuilder::new();
367        builder.with_gate(runtime.config().gate.clone());
368        builder.with_default_namespace(runtime.config().default_namespace.as_str());
369        builder.with_visible_namespaces(runtime.config().visible_namespaces.clone());
370        builder.with_actor_id(runtime.config().actor_id.clone());
371        if audit_store == IngestAuditStore::Attach {
372            if runtime.is_read_only() {
373                builder.with_read_only_audit_store();
374            } else {
375                // Attach requires a usable sink; build propagates open failures.
376                builder.with_runtime_event_store(runtime)?;
377            }
378        }
379        Self::register_packs(
380            &runtime.config().packs.clone(),
381            runtime.clone(),
382            &mut builder,
383        )
384        .map_err(|e| RuntimeError::Internal(format!("pack registration failed: {e:?}")))?;
385        let registry = builder.build()?;
386        runtime.install_edge_rules(registry.all_edge_rules());
387        registry.initialize_embedding_engines(&[runtime])?;
388        Ok(registry)
389    }
390
391    /// Register the named packs into `builder`, routing each pack to its own runtime.
392    ///
393    /// `runtimes` maps pack name → `KhiveRuntime` (one per backend assignment).
394    /// `default_runtime` is used for any pack whose name is not in `runtimes`.
395    /// The validation logic (unknown pack, missing dependency) is identical to
396    /// [`PackRegistry::register_packs`].
397    ///
398    /// This is the multi-backend boot path (ADR-028). Single-backend callers
399    /// should continue using [`PackRegistry::register_packs`].
400    pub fn register_packs_with_runtimes(
401        names: &[String],
402        runtimes: &HashMap<String, KhiveRuntime>,
403        default_runtime: &KhiveRuntime,
404        builder: &mut VerbRegistryBuilder,
405    ) -> Result<(), PackLoadError> {
406        let all: Vec<&'static dyn PackFactory> = inventory::iter::<PackRegistration>
407            .into_iter()
408            .map(|r| r.0)
409            .collect();
410        Self::register_packs_with_runtimes_from(&all, names, runtimes, default_runtime, builder)
411    }
412
413    /// Like [`Self::register_packs_with_runtimes`], but resolves pack names
414    /// against the link-time `inventory` registry **plus** `extra_factories` —
415    /// pack factories the composition root supplies directly rather than
416    /// discovers through `inventory::iter::<PackRegistration>` (ADR-191 D6,
417    /// ADR-192 S4: "a pack compiled outside this repository ... extends the
418    /// web ontology without any change here" — a host binary that depends on
419    /// a pinned khive revision plus an out-of-tree pack crate, or a
420    /// composition root registering a credential-provider/request-hook
421    /// consumer pack, has no `inventory` presence in *this* binary short of
422    /// its own force-link anchor). An inventory-discovered factory always
423    /// wins a name collision with an `extra_factories` entry — the linked set
424    /// is the trusted default; an extra factory only fills a name inventory
425    /// does not already answer.
426    ///
427    /// This is the seam D6 describes as "kkernel exposes its server
428    /// construction as a library entry point that accepts additional pack
429    /// factories" — the `kkernel` library entry point itself lives in
430    /// `kkernel::compose`, built on this function exactly as
431    /// `khive-mcp/src/serve.rs` builds on [`Self::register_packs_with_runtimes`].
432    pub fn register_packs_with_runtimes_with_extra_factories(
433        extra_factories: &[&'static dyn PackFactory],
434        names: &[String],
435        runtimes: &HashMap<String, KhiveRuntime>,
436        default_runtime: &KhiveRuntime,
437        builder: &mut VerbRegistryBuilder,
438    ) -> Result<(), PackLoadError> {
439        let mut all: Vec<&'static dyn PackFactory> = inventory::iter::<PackRegistration>
440            .into_iter()
441            .map(|r| r.0)
442            .collect();
443        all.extend(extra_factories.iter().copied());
444        Self::register_packs_with_runtimes_from(&all, names, runtimes, default_runtime, builder)
445    }
446
447    /// Shared body for [`Self::register_packs_with_runtimes`] and
448    /// [`Self::register_packs_with_runtimes_with_extra_factories`]: both
449    /// build a `factories` index (inventory-only, or inventory-plus-extra)
450    /// and delegate here. `factory_for` resolves by first match, so a
451    /// duplicate name earlier in `factories` wins over a later one — the two
452    /// public callers above rely on that for their stated collision rule.
453    fn register_packs_with_runtimes_from(
454        factories: &[&'static dyn PackFactory],
455        names: &[String],
456        runtimes: &HashMap<String, KhiveRuntime>,
457        default_runtime: &KhiveRuntime,
458        builder: &mut VerbRegistryBuilder,
459    ) -> Result<(), PackLoadError> {
460        let factory_for = |name: &str| -> Option<&'static dyn PackFactory> {
461            factories.iter().copied().find(|f| f.name() == name)
462        };
463
464        Self::validate_pack_selection_from(factories, names)?;
465
466        builder.kg_read_resolver = Some(Arc::new(crate::kg_read::KgReadResolver::new(
467            default_runtime,
468            runtimes,
469        )));
470
471        for name in names {
472            let factory = factory_for(name.as_str()).unwrap();
473            let runtime = runtimes
474                .get(name.as_str())
475                .cloned()
476                .unwrap_or_else(|| default_runtime.clone());
477            let install = factory.create_install(runtime);
478            check_pack_has_public_verbs(factory, &install, name)?;
479            if CHANNEL_INGEST_CAPABLE_PACKS.contains(&name.as_str()) {
480                install
481                    .runtime
482                    .accept_channel_ingest_capability(ChannelIngestCapability { _sealed: () });
483            }
484            builder
485                .pack_versions
486                .insert(install.runtime.name().to_owned(), factory.version());
487            builder.register_boxed(install.runtime);
488            if let Some(resolver) = install.resolver {
489                builder.register_resolver(name.clone(), resolver);
490            }
491            if let Some(hook) = install.dispatch_hook {
492                builder.with_dispatch_hook(hook);
493            }
494        }
495
496        Ok(())
497    }
498}
499
500#[cfg(test)]
501#[path = "loading_tests.rs"]
502mod tests;