Let configuration select the memory engine, gated by the registry

Issue #18 §A5. The driver registry could answer "is this driver id real, and is
it allowed to answer for memory", and nothing asked it: `DriverRegistry::admit`
had no caller outside its own tests, `MemoryHostConfig::memory_provider()` had
no reader, and the memory client factory constructed TinyCortex unconditionally.
Configuration could not choose an engine.

`DriverRegistry::select` closes that: it reads the engine from the host's
configuration and puts it through `admit`, so both surfaces are now live.

Two corrections to the issue, both load-bearing.

§A5 names `memory_provider()` as the selector. That method is a `provider:model`
routing string for the memory *workload* — which language model does
summarisation and entity extraction — not the store the memory lives in.
Reading it would have let a model change repoint a company's storage. Selection
reads a new `memory_driver()` instead, defaulted to `None` so it breaks no
existing implementation, and a test pins that the two fields stay independent.

§A5 also asks that `create_memory_*` return a bound `Arc<dyn MemoryProvider>`.
It cannot, and the reason is structural rather than unfinished: since §C3
`adapters/tinycortex` depends on `tinymemory-core`, so a core factory returning
a constructed adapter provider is a dependency cycle. Selection therefore
resolves the decision and the host constructs — which is what `src/registry`'s
module docs have said all along: "It resolves the class, not the instance."

A configuration naming no engine gets the reserved embedded default, so adding
selection does not turn "I configured nothing" into a host that fails to start.
Going through `select` does not loosen admission either: an external engine
named in config is still refused without endpoint, credential and trust.

Refs #18 (§A5)

Author: YellowSnnowmann

Cargo.toml

@@ -72,6 +72,9 @@ serde = { version = "1", features = ["derive"] }
 [dev-dependencies]
 # The mandatory-family tests are async.
 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+# `TestHostConfig`, for the driver-selection tests. A dev-dependency: the
+# facade must not carry a test double into a consumer's graph.
+tinymemory-api = { path = "api", features = ["test-support"] }
 # The reference driver and the behavioural suite, for the workspace-level
 # integration tests. A dev-dependency only: the facade must not carry a test
 # harness into a consumer's dependency graph.

api/src/host/config.rs

@@ -125,6 +125,25 @@ pub trait MemoryHostConfig: Send + Sync + std::fmt::Debug {
     /// `provider:model` routing string for the memory workload, if pinned.
     fn memory_provider(&self) -> Option<&str>;
 
+    /// The memory **engine** this host selects, when its configuration names
+    /// one — `tinycortex`, `supermemory`, `mem0`, `cognee`, `null`.
+    ///
+    /// Deliberately distinct from [`Self::memory_provider`], which despite the
+    /// name is a `provider:model` routing string for the memory *workload* —
+    /// which language model does summarisation and entity extraction. That is a
+    /// different axis from which store the memory lives in, and conflating them
+    /// would let a model change repoint a company's storage.
+    ///
+    /// `None` means "the host's default", which the host resolves rather than
+    /// this trait: the driver registry admits a reserved embedded id with no
+    /// configuration entry precisely so an unconfigured host still binds
+    /// something instead of failing to start.
+    ///
+    /// Defaulted so adding it breaks no existing implementation.
+    fn memory_driver(&self) -> Option<&str> {
+        None
+    }
+
     /// The local model id for a workload, when that workload is routed to
     /// Ollama (`"ollama:<model>"`). `None` for cloud or unset workloads.
     ///

api/src/host/test_support.rs

@@ -45,6 +45,8 @@ pub struct TestHostConfig {
     pub embeddings_provider: Option<String>,
     /// See [`MemoryHostConfig::memory_provider`].
     pub memory_provider: Option<String>,
+    /// See [`MemoryHostConfig::memory_driver`]. `None` selects the host default.
+    pub memory_driver: Option<String>,
     /// See [`MemoryHostConfig::api_url`].
     pub api_url: Option<String>,
     /// See [`MemoryHostConfig::default_model`].
@@ -113,6 +115,10 @@ impl MemoryHostConfig for TestHostConfig {
         self.memory_provider.as_deref()
     }
 
+    fn memory_driver(&self) -> Option<&str> {
+        self.memory_driver.as_deref()
+    }
+
     fn workload_local_model(&self, workload: &str) -> Option<String> {
         let raw = match workload {
             "memory" => self.memory_provider.as_deref(),

src/registry/mod.rs

@@ -40,6 +40,8 @@
 use std::collections::BTreeMap;
 use std::fmt;
 
+use tinymemory_api::host::MemoryHostConfig;
+
 mod class;
 
 pub use class::{DriverClass, DriverClassParseError};
@@ -284,6 +286,43 @@ impl DriverRegistry {
         Ok(admission)
     }
 
+    /// Selects and admits the memory driver this host's configuration names.
+    ///
+    /// The half of driver binding that was specified but never wired: the
+    /// registry could answer "is this driver id real and allowed", and nothing
+    /// asked it. This reads the id from the host's own configuration and puts
+    /// it through [`Self::admit`], so configuration decides the engine instead
+    /// of a factory hardcoding one (issue #18 §A5).
+    ///
+    /// It reads [`MemoryHostConfig::memory_driver`], **not**
+    /// `memory_provider` — despite the name, the latter is a `provider:model`
+    /// routing string choosing which language model does summarisation, which
+    /// is a different axis from which store the memory lives in.
+    ///
+    /// A configuration that names no driver gets [`TINYCORTEX_DRIVER_ID`], the
+    /// reserved embedded default. That is what keeps an unconfigured host
+    /// booting: an embedded id is admitted without a `drivers` entry, while an
+    /// external one is refused without endpoint, credential and trust
+    /// configuration.
+    ///
+    /// This resolves the *decision*, not the instance. Constructing the
+    /// provider, caching it per workspace, and wrapping it in a policy guard
+    /// stay with the host — see the module docs for why.
+    ///
+    /// # Errors
+    ///
+    /// Returns the [`FallbackReason`] to record and publish when the configured
+    /// driver is refused, exactly as [`Self::admit`] does.
+    pub fn select(
+        &self,
+        config: &dyn MemoryHostConfig,
+        entry: Option<DriverEntry<'_>>,
+        labels: ConfigLabels<'_>,
+    ) -> Result<Admission, FallbackReason> {
+        let driver = config.memory_driver().unwrap_or(TINYCORTEX_DRIVER_ID);
+        self.admit(driver, entry, labels)
+    }
+
     /// The class an id implies when nothing says otherwise.
     ///
     /// `context` names which part of the config was missing; the refusal echoes

src/registry/test.rs

@@ -259,3 +259,77 @@ fn driver_class_serde_matches_the_config_spelling() {
         assert_eq!(json, format!("\"{}\"", class.as_str()));
     }
 }
+
+// ── Selection from configuration (issue #18 §A5) ─────────────────────────────
+//
+// Before this, the registry could answer "is this driver id real and allowed"
+// and nothing asked it: `admit` had no production caller, and the memory client
+// factory constructed TinyCortex unconditionally. These pin the wiring.
+
+use tinymemory_api::host::test_support::TestHostConfig;
+
+fn config_naming(driver: Option<&str>) -> TestHostConfig {
+    // `TestHostConfig` is `#[non_exhaustive]`, so it is built and then mutated
+    // rather than named field-by-field — which is what its own docs ask for.
+    let mut config = TestHostConfig::default();
+    config.memory_driver = driver.map(str::to_owned);
+    config
+}
+
+#[test]
+fn a_configuration_naming_no_driver_gets_the_embedded_default() {
+    // The property that keeps an unconfigured host booting: a reserved embedded
+    // id is admitted without any `drivers` entry.
+    let admission = DriverRegistry::builtin()
+        .select(&config_naming(None), None, labels())
+        .expect("an unconfigured host still binds");
+    assert_eq!(admission.id, TINYCORTEX_DRIVER_ID);
+    assert_eq!(admission.class, DriverClass::Embedded);
+}
+
+#[test]
+fn a_configuration_naming_an_engine_selects_that_engine() {
+    let admission = DriverRegistry::builtin()
+        .select(&config_naming(Some(NULL_DRIVER_ID)), None, labels())
+        .expect("the null driver is admitted without an entry");
+    assert_eq!(admission.id, NULL_DRIVER_ID);
+    assert_eq!(admission.class, DriverClass::Null);
+}
+
+#[test]
+fn selecting_a_hosted_engine_still_requires_its_entry() {
+    // Selection does not loosen admission: an external driver named in config
+    // but left unconfigured is refused fail-closed, exactly as `admit` refuses
+    // it directly.
+    let reason = DriverRegistry::builtin()
+        .select(&config_naming(Some("supermemory")), None, labels())
+        .expect_err("an external driver with no entry must be refused");
+    assert_eq!(reason.configured_driver, "supermemory");
+}
+
+#[test]
+fn selecting_a_hosted_engine_succeeds_once_it_is_configured_and_trusted() {
+    let entry = DriverEntry {
+        class: None,
+        trust_state: TRUSTED,
+    };
+    let admission = DriverRegistry::builtin()
+        .select(&config_naming(Some("supermemory")), Some(entry), labels())
+        .expect("a configured, trusted external driver is admitted");
+    assert_eq!(admission.class, DriverClass::External);
+}
+
+#[test]
+fn selection_reads_the_engine_field_and_not_the_model_routing_one() {
+    // `memory_provider` is a `provider:model` routing string choosing which
+    // language model does summarisation. Reading it here would let a model
+    // change repoint a company's storage, which is why selection has its own
+    // field.
+    let mut config = TestHostConfig::default();
+    config.memory_provider = Some("ollama:llama3".to_owned());
+    config.memory_driver = None;
+    let admission = DriverRegistry::builtin()
+        .select(&config, None, labels())
+        .expect("model routing must not affect engine selection");
+    assert_eq!(admission.id, TINYCORTEX_DRIVER_ID);
+}

tests/driver_selection.rs

@@ -3,22 +3,29 @@
 //!
 //! Exercises only the public surface of the `tinymemory` facade.
 //!
-//! # Scope note
+//! # Selection
 //!
-//! Issue #18 §E3 describes this file as also asserting that "the bound
-//! provider's `driver_id()` matches" the configured id. That step needs
-//! `MemoryHostConfig::memory_provider()` to actually select an engine, which is
-//! §A5 and does not exist yet — `create_memory_client_with_local_ai` still
-//! constructs TinyCortex unconditionally. The issue's own sequencing says to
-//! write these tests "against the *current* behaviour first", so this file
-//! pins what admission does today. The binding half joins it when §A5 lands,
-//! and this file is where it goes.
+//! Configuration now chooses the engine (§A5). One correction to the issue is
+//! worth recording here, because it would otherwise have wired the wrong thing:
+//! §A5 names `MemoryHostConfig::memory_provider()` as the selector, but that
+//! method is a `provider:model` routing string for the memory *workload* —
+//! which language model summarises — not the engine the memory lives in.
+//! Selection reads `memory_driver()` instead, added for the purpose.
+//!
+//! What still does not exist is the last clause of §A5, that `create_memory_*`
+//! return a bound `Arc<dyn MemoryProvider>`. It cannot, and the reason is
+//! structural rather than unfinished: `adapters/tinycortex` depends on
+//! `tinymemory-core` since §C3, so a core factory returning a constructed
+//! adapter provider would be a dependency cycle. Selection resolves the
+//! *decision*; the host constructs — which is what `src/registry`'s own module
+//! docs have always said.
 
 // A failing assertion in a test *is* a panic; the crate-wide `expect_used` /
 // `unwrap_used` / `panic` lints exist to keep the library from panicking, not
 // the tests. Same allowance, and same reasoning, as `src/registry/test.rs`.
 #![allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
 
+use tinymemory::api::host::test_support::TestHostConfig;
 use tinymemory::registry::{
     ConfigLabels, DriverClass, DriverEntry, DriverRegistry, COGNEE_DRIVER_ID, MEM0_DRIVER_ID,
     SUPERMEMORY_DRIVER_ID, TINYCORTEX_DRIVER_ID, TRUSTED,
@@ -159,3 +166,65 @@ fn a_config_class_typo_is_echoed_back_to_the_operator() {
         reason.reason
     );
 }
+
+// ── The selection half, through the public facade ────────────────────────────
+
+fn config_naming(driver: Option<&str>) -> TestHostConfig {
+    let mut config = TestHostConfig::default();
+    config.memory_driver = driver.map(str::to_owned);
+    config
+}
+
+#[test]
+fn configuration_chooses_the_engine_and_admission_gates_it() {
+    let admission = DriverRegistry::builtin()
+        .select(
+            &config_naming(Some(COGNEE_DRIVER_ID)),
+            Some(trusted_external()),
+            labels(),
+        )
+        .expect("a configured, trusted external engine binds");
+    assert_eq!(admission.id, COGNEE_DRIVER_ID);
+    assert_eq!(admission.class, DriverClass::External);
+}
+
+#[test]
+fn an_unconfigured_host_still_binds_the_embedded_default() {
+    // The property that matters most operationally: adding engine selection
+    // must not turn "I configured nothing" into a host that fails to start.
+    let admission = DriverRegistry::builtin()
+        .select(&config_naming(None), None, labels())
+        .expect("an unconfigured host binds the embedded default");
+    assert_eq!(admission.id, TINYCORTEX_DRIVER_ID);
+    assert_eq!(admission.class, DriverClass::Embedded);
+}
+
+#[test]
+fn selection_does_not_loosen_the_fail_closed_external_gate() {
+    // Going through `select` rather than `admit` must not become a way around
+    // the trust requirement.
+    let untrusted = DriverEntry {
+        class: None,
+        trust_state: "untrusted",
+    };
+    let reason = DriverRegistry::builtin()
+        .select(
+            &config_naming(Some(MEM0_DRIVER_ID)),
+            Some(untrusted),
+            labels(),
+        )
+        .expect_err("an untrusted external engine is refused however it was chosen");
+    assert!(reason.reason.contains(TRUSTED), "{}", reason.reason);
+}
+
+#[test]
+fn the_model_routing_field_cannot_repoint_the_store() {
+    // `memory_provider` chooses a language model; `memory_driver` chooses the
+    // store. Conflating them would let a model change move a company's memory.
+    let mut config = TestHostConfig::default();
+    config.memory_provider = Some("ollama:llama3".to_owned());
+    let admission = DriverRegistry::builtin()
+        .select(&config, None, labels())
+        .expect("model routing leaves engine selection alone");
+    assert_eq!(admission.id, TINYCORTEX_DRIVER_ID);
+}