feat(module): five new capability families and OpenStore for per-subtree stores

api/src/capabilities.rs

@@ -51,7 +51,7 @@ use crate::error::MemoryError;
 
 /// One capability family a memory driver may advertise.
 ///
-/// The variants are exactly the thirteen families of the memory contract. Each
+/// The variants are exactly the sixteen families of the memory contract. Each
 /// maps to a trait family in the contract, a group of RPC methods, and a group
 /// of agent tools; a driver that does not advertise a family simply has that
 /// surface absent.
@@ -85,6 +85,17 @@ pub enum Capability {
     Maintenance,
     /// Export and import of the whole store as a stream. **Mandatory.**
     Portability,
+    /// Contacts, handle resolution, and closeness scoring.
+    People,
+    /// Direct read access to the stored chunk tier.
+    Chunks,
+    /// Deterministic retrieval primitives: graph walk, time-window cover,
+    /// entity-index search.
+    Retrieval,
+    /// Learned facets about the user.
+    Profile,
+    /// The turn-by-turn conversation record and its segment lifecycle.
+    Episodic,
 }
 
 impl Capability {
@@ -93,7 +104,7 @@ impl Capability {
     /// Declaration order is also bit order in [`Capabilities`] and iteration
     /// order in its serialized form, so this slice is the single ordering
     /// authority for the whole module.
-    pub const ALL: [Capability; 13] = [
+    pub const ALL: [Capability; 18] = [
         Capability::Core,
         Capability::Recall,
         Capability::Ingest,
@@ -107,6 +118,14 @@ impl Capability {
         Capability::Sources,
         Capability::Maintenance,
         Capability::Portability,
+        // Appended, never inserted: declaration order is bit order in
+        // `Capabilities`, so moving an existing variant would silently change
+        // what an already-persisted or already-transmitted bitset means.
+        Capability::People,
+        Capability::Chunks,
+        Capability::Retrieval,
+        Capability::Profile,
+        Capability::Episodic,
     ];
 
     /// The families a driver must advertise to be bindable at all.
@@ -145,6 +164,11 @@ impl Capability {
             Self::Sources => "sources",
             Self::Maintenance => "maintenance",
             Self::Portability => "portability",
+            Self::People => "people",
+            Self::Chunks => "chunks",
+            Self::Retrieval => "retrieval",
+            Self::Profile => "profile",
+            Self::Episodic => "episodic",
         }
     }
 
@@ -187,6 +211,11 @@ impl Capability {
             Self::Sources => 10,
             Self::Maintenance => 11,
             Self::Portability => 12,
+            Self::People => 13,
+            Self::Chunks => 14,
+            Self::Retrieval => 15,
+            Self::Profile => 16,
+            Self::Episodic => 17,
         }
     }
 

api/src/capabilities_tests.rs

@@ -2,7 +2,7 @@
 //!
 //! Three properties are load-bearing and each has its own test:
 //!
-//! 1. the enum has exactly the thirteen contract families and no more;
+//! 1. the enum has exactly the sixteen contract families and no more;
 //! 2. the serialized form is stable snake_case **strings**, never discriminant
 //!    integers — a driver deployed against an older build must keep advertising
 //!    the same set after a variant is inserted mid-enum;
@@ -13,9 +13,9 @@ use super::*;
 use serde_json::json;
 
 #[test]
-fn capability_has_exactly_the_thirteen_contract_families() {
-    assert_eq!(Capability::ALL.len(), 13);
-    assert_eq!(Capability::all().len(), 13);
+fn capability_has_exactly_the_eighteen_contract_families() {
+    assert_eq!(Capability::ALL.len(), 18);
+    assert_eq!(Capability::all().len(), 18);
 
     let names: Vec<&str> = Capability::ALL.iter().map(|c| c.as_str()).collect();
     assert_eq!(
@@ -34,6 +34,11 @@ fn capability_has_exactly_the_thirteen_contract_families() {
             "sources",
             "maintenance",
             "portability",
+            "people",
+            "chunks",
+            "retrieval",
+            "profile",
+            "episodic",
         ]
     );
 }
@@ -141,7 +146,7 @@ fn capabilities_empty_contains_nothing() {
 }
 
 #[test]
-fn capabilities_bit_width_has_room_well_beyond_the_current_thirteen_families() {
+fn capabilities_bit_width_has_room_well_beyond_the_current_sixteen_families() {
     // A `u16` bitset (the original representation) has exactly 16 bit
     // positions, leaving room for only 3 more families before a family's
     // `1 << index` bit-shift overflows. Pin the wider `u64` representation so

api/src/host/embeddings.rs

@@ -20,11 +20,114 @@ use async_trait::async_trait;
 /// provider. Drift between the two silently splits one embedding space into
 /// two, and every vector written on the wrong side of the split becomes
 /// unsearchable without a re-embed.
+/// # Delimiters in a component
+///
+/// A component containing `;`, `=` or `%` is percent-encoded, because without
+/// that the format is ambiguous: `("a;model=b", "c")` and `("a", "b;model=c")`
+/// are different embedding spaces that would otherwise produce one identical
+/// key, and vectors from both would then be compared as though they came from
+/// the same model.
+///
+/// Encoding only those three characters is what keeps this from being a
+/// migration. Every provider and model identifier actually in use is
+/// alphanumeric plus `-`, `_`, `.`, `/` or `:`, and each of those passes
+/// through untouched — so every signature already on disk still formats to the
+/// same bytes. Only a name that could have collided changes, and such a name
+/// has never been written.
 #[must_use]
 pub fn format_embedding_signature(name: &str, model_id: &str, dims: usize) -> String {
+    let name = escape_component(name);
+    let model_id = escape_component(model_id);
     format!("provider={name};model={model_id};dims={dims}")
 }
 
+/// Percent-encode the three characters that carry structure in a signature.
+///
+/// `%` goes first and must: encoding it afterwards would re-encode the `%` this
+/// function just introduced, and `a;b` would arrive as `a%3Bb` from one path
+/// and `a%253Bb` from another.
+fn escape_component(value: &str) -> String {
+    if !value.contains(['%', ';', '=']) {
+        // The overwhelmingly common path, and the one that guarantees existing
+        // keys are untouched: no allocation beyond the copy, no rewriting.
+        return value.to_string();
+    }
+    value
+        .replace('%', "%25")
+        .replace(';', "%3B")
+        .replace('=', "%3D")
+}
+
+#[cfg(test)]
+mod embedding_signature_tests {
+    use super::format_embedding_signature;
+
+    /// The signature format is a **persisted key**, pinned to literal values.
+    ///
+    /// Written against golden strings rather than against another copy of the
+    /// function on purpose: the host used to hold a byte-identical duplicate of
+    /// this file and the two silently diverged once already. A guard that
+    /// compares two implementations stops protecting anything the moment one of
+    /// them goes away — which is exactly what happened when the duplicate was
+    /// removed. Literals outlive that.
+    ///
+    /// Every vector on disk is keyed by one of these strings, so a change here
+    /// is a migration, never an edit.
+    #[test]
+    fn signature_format_is_pinned_to_its_persisted_form() {
+        assert_eq!(
+            format_embedding_signature("ollama", "nomic-embed-text", 768),
+            "provider=ollama;model=nomic-embed-text;dims=768"
+        );
+        assert_eq!(
+            format_embedding_signature("none", "none", 0),
+            "provider=none;model=none;dims=0"
+        );
+    }
+
+    /// Two distinct embedding spaces must never share one signature.
+    ///
+    /// Without escaping these two collide exactly: both format to
+    /// `provider=a;model=b;model=c;dims=3`. A collision here is not a cosmetic
+    /// problem — the signature is what decides which vectors are comparable, so
+    /// two models' vectors would be scored against each other as though they
+    /// came from one space.
+    #[test]
+    fn delimiter_characters_cannot_make_distinct_spaces_collide() {
+        let first = format_embedding_signature("a;model=b", "c", 3);
+        let second = format_embedding_signature("a", "b;model=c", 3);
+        assert_ne!(first, second);
+    }
+
+    /// Escaping `%` last would make the encoding itself ambiguous.
+    #[test]
+    fn an_already_percent_encoded_name_does_not_collide_with_a_literal_one() {
+        assert_ne!(
+            format_embedding_signature("a%3Bb", "m", 3),
+            format_embedding_signature("a;b", "m", 3)
+        );
+    }
+
+    /// The escaping is not a migration: every identifier shaped like the ones
+    /// actually in use formats to the same bytes it always did.
+    #[test]
+    fn identifiers_in_real_use_are_untouched_by_the_escaping() {
+        for (provider, model) in [
+            ("ollama", "nomic-embed-text"),
+            ("openai", "text-embedding-3-small"),
+            ("huggingface", "sentence-transformers/all-MiniLM-L6-v2"),
+            ("local", "bge_base.en-v1.5"),
+            ("backend", "tinyhumans:default"),
+        ] {
+            assert_eq!(
+                format_embedding_signature(provider, model, 768),
+                format!("provider={provider};model={model};dims=768"),
+                "{provider}/{model} must not be rewritten — it is a persisted key"
+            );
+        }
+    }
+}
+
 /// Converts text into numerical vectors.
 #[async_trait]
 pub trait EmbeddingProvider: Send + Sync {

api/src/lib.rs

@@ -41,10 +41,10 @@
 //! - [`recall`]: the borrowed [`recall::RecallOpts`] and owned, serde-derived
 //!   [`recall::OwnedRecallOpts`] recall filters (both re-exported from
 //!   [`types`]).
-//! - [`capabilities`]: the thirteen [`capabilities::Capability`] families and
+//! - [`capabilities`]: the sixteen [`capabilities::Capability`] families and
 //!   the [`capabilities::Capabilities`] set negotiated at bind time.
 //! - [`provider`]: the driver contract — [`provider::MemoryProvider`] plus the
-//!   thirteen capability family traits and the value types they need.
+//!   sixteen capability family traits and the value types they need.
 //! - [`null`]: [`null::NullMemoryProvider`], the reference driver a
 //!   compiled-out or unconfigured memory subsystem binds to.
 //! - [`health`]: [`health::MemoryHealth`], the liveness state a driver reports.