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;