feat(nous-real): cache de embeddings + write-through al CAS de arje

Cierra el ciclo del feedback: el modelo real (fastembed-allMiniLML6V2,
~1-50ms por archivo) era invocado ciegamente en cada re-cluster del
watcher. Ahora se cachea por sha256(bytes-vistos) + model_id, con
write-through al CAS de arje.

Pipeline en handle_file:
1. Lee primeros 8 KiB del archivo (igual que antes).
2. file_sha = ente_cas::sha256_of(buf) — hash de los bytes que el
   modelo *realmente* verá. Garantiza que un archivo creciendo mas
   alla de la ventana sin tocar la cabeza siga sirviendo cache hits.
3. Cache lookup -> HIT: respuesta en us, sin invocar fastembed.
4. MISS: ente_cas::store(&buf) (write-through, no-fatal si falla) ->
   backend.embed_one(text) -> cache.put(...).

Backend de cache: sled local en
$XDG_CACHE_HOME/brahman/nouser-nous-real-embed-cache.sled. Tree
versionado embed_cache_v1; el MODEL_ID viaja en la key, asi que
cambiar de modelo invalida el cache implicitamente. Override por env
NOUSER_NOUS_REAL_CACHE.

Encoding compacto: cada Vec<f32> se serializa como bytes little-endian
(4B por f32, sin overhead). Para 384-d son 1.5 KiB por entry. Decode
tolera bytes corruptos (longitud no-multiplo de 4 -> None, no panic).

Por que sled y no ente-cas directo: el CAS de arje es flat
sha256-keyed; la cache necesita un mapeo (file_sha, model_id) ->
embedding, no expresable como entry CAS. El write-through a CAS queda
como registro consultable + futura GC.

Mock NO se modifica — su embedding pseudo-32d es metadata-hashing puro,
sin costo. Cachearlo seria overhead.

Tests: 5 unitarios verdes (roundtrip, miss, model collision, content
collision, corrupted value). Stub mode (sin feature) sigue compilando
sin tocar cache.

CHANGELOG.md

@@ -6,6 +6,55 @@ ratio/diff ver `git show <sha>`.
 
 ## 2026-05-09
 
+### feat(nous-real): cache de embeddings + write-through al CAS de arje
+Cierra el ciclo de la crítica del usuario: "Si un archivo no ha
+cambiado su hash en el CAS, Nouser ni siquiera debería pedirle al
+LLM que re-genere el embedding". El modelo real
+(`fastembed-allMiniLML6V2-384d`, ~1-50ms por archivo) era invocado
+ciegamente en cada re-cluster del watcher. Ahora se cachea por
+`sha256(bytes-vistos) + model_id`.
+
+Pipeline en `handle_file`:
+1. Lee primeros 8 KiB (igual que antes).
+2. `file_sha = ente_cas::sha256_of(buf)` — hash de los bytes que el
+   modelo *realmente* verá (no del archivo completo). Garantiza
+   que un archivo creciendo más allá de la ventana sin tocar la
+   cabeza siga sirviendo cache hits.
+3. Cache lookup: HIT → respuesta en ~µs.
+4. MISS → `ente_cas::store(&buf)` (write-through al CAS de arje,
+   no-fatal si falla) → `backend.embed_one(text)` → `cache.put(...)`.
+
+Backend de cache: sled local en
+`$XDG_CACHE_HOME/brahman/nouser-nous-real-embed-cache.sled`. Tree
+versionado `embed_cache_v1`; el `MODEL_ID` viaja en la key, así que
+cambiar de modelo invalida el cache implícitamente. Override por env
+`NOUSER_NOUS_REAL_CACHE`.
+
+Encoding compacto: cada `Vec<f32>` se serializa como bytes
+little-endian (4B por f32, sin overhead). Para el modelo default
+(384-d) son 1.5 KiB por entry. Decode tolera bytes corruptos
+(longitud no-múltiplo de 4 → `None`, no panic).
+
+Por qué sled y no `ente-cas` directo: el CAS de arje es flat
+sha256-keyed; la cache necesita un mapeo `(file_sha, model_id) →
+embedding`, no expresable como entry CAS. El write-through a CAS
+queda como registro consultable + futura GC.
+
+API:
+- `EmbedCache::open()` → abre sled, idempotente.
+- `EmbedCache::open_at(dir)` para tests.
+- `EmbedCache::get(sha, model)` → `Option<Vec<f32>>`.
+- `EmbedCache::put(sha, model, &[f32])` → no-fatal en error.
+- `EmbedCache::len()` → contador para logs (best-effort).
+
+Mock NO se modifica — su embedding pseudo-32d es metadata-hashing
+puro, sin costo. Cachearlo sería overhead.
+
+Tests: 5 unitarios (`roundtrip_returns_same_vector`, `miss_returns_none`,
+`different_models_do_not_collide`, `different_content_different_keys`,
+`corrupted_value_returns_none`). Verdes con `--features embeddings`;
+stub mode (sin feature) sigue compilando sin tocar cache.
+
 ### chore(nakui): alinear `nakui-core` con `[workspace.package]` y deps compartidas
 Cleanup de drift de convenciones: `nakui-core` era el único crate del
 monorepo que mantenía `version = "0.1.0"` / `edition = "2021"` /

Cargo.lock

@@ -6418,9 +6418,12 @@ version = "0.1.0"
 dependencies = [
  "brahman-card",
  "brahman-sidecar",
+ "ente-cas",
  "fastembed",
  "nouser-nous",
  "serde_json",
+ "sled",
+ "tempfile",
  "tokio",
  "tracing",
  "tracing-subscriber",

crates/modules/nouser/nous-real/Cargo.toml

@@ -20,8 +20,10 @@ embeddings = ["dep:fastembed"]
 [dependencies]
 brahman-card = { path = "../../../core/brahman-card" }
 brahman-sidecar = { path = "../../../shared/brahman-sidecar" }
+ente-cas = { path = "../../../core/ente-cas" }
 nouser-nous = { path = "../nous" }
 serde_json = { workspace = true }
+sled = { workspace = true }
 tokio = { workspace = true }
 tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
@@ -30,6 +32,9 @@ ulid = { workspace = true }
 # Opcional: gateado por feature `embeddings`.
 fastembed = { version = "4", optional = true }
 
+[dev-dependencies]
+tempfile = { workspace = true }
+
 [[bin]]
 name = "nouser-nous-real"
 path = "src/main.rs"

crates/modules/nouser/nous-real/src/cache.rs

@@ -0,0 +1,199 @@
+//! Cache de embeddings keyed por sha256 del contenido + model_id.
+//!
+//! Razón de existir: el modelo real (`fastembed-allMiniLML6V2`) es
+//! caro (1-50 ms por archivo según tamaño y CPU). Cada vez que el
+//! daemon de nouser re-publica una Mónada o el watcher dispara un
+//! re-cluster por cambio de FS, todos los archivos pasan otra vez
+//! por embed. Para árboles de 1000 archivos, eso son segundos
+//! desperdiciados re-embedidando contenido que no cambió.
+//!
+//! ## Diseño
+//!
+//! - **Cache key**: `sha256(bytes que el modelo realmente vio)` +
+//!   `MODEL_ID` (string). Usar el sha de los bytes-vistos garantiza
+//!   que la cache no devuelva un embedding de contenido viejo
+//!   simplemente porque el path no cambió.
+//! - **Cache value**: el `Vec<f32>` serializado como bytes
+//!   little-endian (4 bytes por f32). Compacto, sin overhead de
+//!   bincode/postcard para datos numéricos puros.
+//! - **Backend**: sled, tree único `embed_cache_v1`. Path:
+//!   `$XDG_CACHE_HOME/brahman/nouser-nous-real-embed-cache.sled`.
+//!
+//! ## Versionado
+//!
+//! El nombre del tree (`embed_cache_v1`) es el "schema version" del
+//! formato value. Si bumpeamos a (p. ej.) almacenar también el
+//! tiempo de cómputo o el ONNX session id, creamos `embed_cache_v2`
+//! y el viejo queda como dato muerto que sled puede limpiar.
+//!
+//! El `MODEL_ID` viaja dentro del key, así que cambiar de modelo
+//! invalida implícitamente las entradas viejas (no se accede más
+//! a esos keys; sled las mantiene hasta GC manual).
+
+use std::path::PathBuf;
+
+/// Wrapper sobre sled::Db con la API justa que necesita `handle_file`.
+#[derive(Clone)]
+pub struct EmbedCache {
+    tree: sled::Tree,
+}
+
+impl EmbedCache {
+    /// Abre (o crea) la cache en su path canónico. El sled::Db queda
+    /// referenciado por el Tree; mientras `EmbedCache` viva, el DB
+    /// vive.
+    pub fn open() -> Result<Self, sled::Error> {
+        let path = default_path();
+        if let Some(parent) = path.parent() {
+            // best-effort: si no podemos crear el dir, sled falla con
+            // mensaje específico abajo.
+            let _ = std::fs::create_dir_all(parent);
+        }
+        let db = sled::open(&path)?;
+        let tree = db.open_tree("embed_cache_v1")?;
+        Ok(Self { tree })
+    }
+
+    /// Variante para tests: cache efímera bajo `dir`.
+    #[cfg(test)]
+    pub fn open_at(dir: &std::path::Path) -> Result<Self, sled::Error> {
+        let db = sled::open(dir)?;
+        let tree = db.open_tree("embed_cache_v1")?;
+        Ok(Self { tree })
+    }
+
+    /// Lookup. `None` si miss; `Some(vec)` si hit.
+    pub fn get(&self, file_sha: &[u8; 32], model_id: &str) -> Option<Vec<f32>> {
+        let key = build_key(file_sha, model_id);
+        let bytes = self.tree.get(&key).ok()??;
+        decode_embedding(&bytes)
+    }
+
+    /// Almacena. Errores se loggean pero no propagan — cache miss es
+    /// recuperable, no querés tirar el embed válido por fallo de I/O
+    /// de cache.
+    pub fn put(&self, file_sha: &[u8; 32], model_id: &str, embedding: &[f32]) {
+        let key = build_key(file_sha, model_id);
+        let bytes = encode_embedding(embedding);
+        if let Err(e) = self.tree.insert(key, bytes) {
+            tracing::warn!(error = %e, "embed-cache put falló (no-fatal)");
+        }
+    }
+
+    /// Cantidad actual de entradas (best-effort para logs).
+    pub fn len(&self) -> usize {
+        self.tree.len()
+    }
+}
+
+/// Path default. Honra `XDG_CACHE_HOME`, cae a `$HOME/.cache`, y de
+/// último recurso a `/tmp` (sin persistencia, pero al menos no
+/// crashea en entornos minimalistas como CI sin HOME).
+fn default_path() -> PathBuf {
+    if let Ok(p) = std::env::var("NOUSER_NOUS_REAL_CACHE") {
+        return PathBuf::from(p);
+    }
+    let base = std::env::var("XDG_CACHE_HOME")
+        .ok()
+        .map(PathBuf::from)
+        .or_else(|| {
+            std::env::var("HOME")
+                .ok()
+                .map(|h| PathBuf::from(h).join(".cache"))
+        })
+        .unwrap_or_else(std::env::temp_dir);
+    base.join("brahman").join("nouser-nous-real-embed-cache.sled")
+}
+
+fn build_key(file_sha: &[u8; 32], model_id: &str) -> Vec<u8> {
+    let mut k = Vec::with_capacity(32 + 1 + model_id.len());
+    k.extend_from_slice(file_sha);
+    // separator byte para que prefijos de model_id no choquen con
+    // bytes del sha (improbable pero barato).
+    k.push(0xff);
+    k.extend_from_slice(model_id.as_bytes());
+    k
+}
+
+fn encode_embedding(v: &[f32]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(v.len() * 4);
+    for f in v {
+        out.extend_from_slice(&f.to_le_bytes());
+    }
+    out
+}
+
+fn decode_embedding(bytes: &[u8]) -> Option<Vec<f32>> {
+    if bytes.len() % 4 != 0 {
+        return None;
+    }
+    let mut out = Vec::with_capacity(bytes.len() / 4);
+    for chunk in bytes.chunks_exact(4) {
+        out.push(f32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]));
+    }
+    Some(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sha(s: &[u8]) -> [u8; 32] {
+        ente_cas::sha256_of(s)
+    }
+
+    #[test]
+    fn roundtrip_returns_same_vector() {
+        let dir = tempfile::tempdir().unwrap();
+        let cache = EmbedCache::open_at(dir.path()).unwrap();
+        let key = sha(b"hello world");
+        let v = vec![0.1f32, -0.5, 1.0, 3.14159];
+        cache.put(&key, "real-fastembed-allMiniLML6V2-384d", &v);
+        let got = cache
+            .get(&key, "real-fastembed-allMiniLML6V2-384d")
+            .expect("hit esperado");
+        assert_eq!(got, v);
+    }
+
+    #[test]
+    fn miss_returns_none() {
+        let dir = tempfile::tempdir().unwrap();
+        let cache = EmbedCache::open_at(dir.path()).unwrap();
+        let key = sha(b"never stored");
+        assert!(cache.get(&key, "real-fastembed-allMiniLML6V2-384d").is_none());
+    }
+
+    #[test]
+    fn different_models_do_not_collide() {
+        let dir = tempfile::tempdir().unwrap();
+        let cache = EmbedCache::open_at(dir.path()).unwrap();
+        let key = sha(b"same content");
+        cache.put(&key, "model-a", &[1.0, 2.0]);
+        cache.put(&key, "model-b", &[7.0, 8.0]);
+        assert_eq!(cache.get(&key, "model-a").unwrap(), vec![1.0, 2.0]);
+        assert_eq!(cache.get(&key, "model-b").unwrap(), vec![7.0, 8.0]);
+    }
+
+    #[test]
+    fn different_content_different_keys() {
+        let dir = tempfile::tempdir().unwrap();
+        let cache = EmbedCache::open_at(dir.path()).unwrap();
+        let k1 = sha(b"abc");
+        let k2 = sha(b"abd");
+        cache.put(&k1, "m", &[1.0]);
+        assert!(cache.get(&k2, "m").is_none());
+    }
+
+    #[test]
+    fn corrupted_value_returns_none() {
+        // Si sled devuelve bytes con length no múltiplo de 4, decode
+        // debe fallar limpio (None) en vez de panicar.
+        let dir = tempfile::tempdir().unwrap();
+        let cache = EmbedCache::open_at(dir.path()).unwrap();
+        let key = sha(b"x");
+        // Insertamos manualmente bytes inválidos.
+        let raw_key = build_key(&key, "m");
+        cache.tree.insert(raw_key, &[1u8, 2, 3][..]).unwrap();
+        assert!(cache.get(&key, "m").is_none());
+    }
+}

crates/modules/nouser/nous-real/src/embeddings.rs

@@ -28,6 +28,8 @@ use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
 use tokio::net::UnixStream;
 use tracing::{info, warn};
 
+use crate::cache::EmbedCache;
+
 const MAX_FILE_BYTES: usize = 8192;
 
 /// Backend concreto: posee el modelo cargado.
@@ -56,7 +58,11 @@ impl Backend {
     }
 }
 
-pub async fn handle_conn(stream: UnixStream, backend: Arc<Backend>) -> std::io::Result<()> {
+pub async fn handle_conn(
+    stream: UnixStream,
+    backend: Arc<Backend>,
+    cache: Option<EmbedCache>,
+) -> std::io::Result<()> {
     let mut reader = BufReader::new(stream);
     let mut line = String::new();
     let n = reader.read_line(&mut line).await?;
@@ -73,7 +79,7 @@ pub async fn handle_conn(stream: UnixStream, backend: Arc<Backend>) -> std::io::
 
     let started = Instant::now();
     let result = match req.kind {
-        RequestKind::EmbedFile => handle_file(req.payload, &backend, started),
+        RequestKind::EmbedFile => handle_file(req.payload, &backend, cache.as_ref(), started),
         RequestKind::EmbedText => handle_text(req.payload, &backend, started),
         RequestKind::Ping => handle_ping(),
     };
@@ -110,23 +116,71 @@ fn handle_text(
 fn handle_file(
     payload: serde_json::Value,
     backend: &Backend,
+    cache: Option<&EmbedCache>,
     started: Instant,
 ) -> Result<String, String> {
     let p: EmbedFilePayload =
         serde_json::from_value(payload).map_err(|e| format!("payload: {e}"))?;
-    info!(path = %p.path, "embed_file (lee contenido)");
 
     let path = PathBuf::from(&p.path);
     let mut file = File::open(&path).map_err(|e| format!("abrir archivo: {e}"))?;
     let mut buf = vec![0u8; MAX_FILE_BYTES];
     let n = file.read(&mut buf).map_err(|e| format!("leer archivo: {e}"))?;
     buf.truncate(n);
-    let text = String::from_utf8_lossy(&buf).to_string();
 
+    let model_id = super::model_id();
+    // Hash de los bytes que el modelo realmente verá. Si el archivo
+    // crece pasada la ventana MAX_FILE_BYTES sin modificar la cabeza,
+    // el hash NO cambia — el embedding cacheado sigue siendo válido
+    // bajo la semántica del proveedor (el modelo nunca vio los bytes
+    // adicionales). Si la cabeza cambia, el hash cambia y caemos a
+    // re-embed naturalmente.
+    let file_sha = ente_cas::sha256_of(&buf);
+
+    if let Some(cache) = cache {
+        if let Some(cached) = cache.get(&file_sha, model_id) {
+            info!(
+                path = %p.path,
+                sha = %ente_cas::hex(&file_sha),
+                bytes = n,
+                "embed_file: cache HIT"
+            );
+            let resp = EmbedResponse {
+                embedding: cached,
+                model: model_id.to_string(),
+                elapsed_ms: started.elapsed().as_millis() as u64,
+            };
+            return serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"));
+        }
+    }
+
+    info!(
+        path = %p.path,
+        sha = %ente_cas::hex(&file_sha),
+        bytes = n,
+        "embed_file: cache MISS — invocando modelo"
+    );
+
+    // Write-through al CAS de arje: hacemos la cabeza del archivo
+    // direccionable por contenido. No es la fuente de verdad para
+    // el cache (sled lo es) pero deja un registro consultable por
+    // herramientas como `ente-cas gc` y permite que otros consumers
+    // resuelvan los bytes por hash.
+    if let Err(e) = ente_cas::store(&buf) {
+        // No-fatal: si CAS no escribe, cacheamos el embedding igual.
+        warn!(error = %e, "ente_cas::store falló (no-fatal)");
+    }
+
+    let text = String::from_utf8_lossy(&buf).to_string();
     let v = backend.embed_one(&text)?;
+
+    if let Some(cache) = cache {
+        cache.put(&file_sha, model_id, &v);
+    }
+
     let resp = EmbedResponse {
         embedding: v,
-        model: super::model_id().to_string(),
+        model: model_id.to_string(),
         elapsed_ms: started.elapsed().as_millis() as u64,
     };
     serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))

crates/modules/nouser/nous-real/src/main.rs

@@ -40,6 +40,8 @@ use nouser_nous::{transport, FLOW_EMBED_REQUEST, FLOW_EMBED_RESULT, FLOW_TYPE_NA
 use tokio::net::UnixListener;
 use tracing::info;
 
+#[cfg(feature = "embeddings")]
+mod cache;
 #[cfg(feature = "embeddings")]
 mod embeddings;
 #[cfg(not(feature = "embeddings"))]
@@ -90,15 +92,30 @@ async fn main() -> std::io::Result<()> {
     #[cfg(feature = "embeddings")]
     let backend = std::sync::Arc::new(backend);
 
-    // 4. Accept loop.
+    // 4. Abrir el cache de embeddings (sled local, sha256-keyed).
+    //    Si falla, seguimos sin cache — degrada a "siempre embed".
+    #[cfg(feature = "embeddings")]
+    let embed_cache = match cache::EmbedCache::open() {
+        Ok(c) => {
+            info!(entries = c.len(), "embed-cache abierto");
+            Some(c)
+        }
+        Err(e) => {
+            tracing::warn!(error = %e, "embed-cache no disponible — todas las requests irán al modelo");
+            None
+        }
+    };
+
+    // 5. Accept loop.
     loop {
         let (stream, _addr) = listener.accept().await?;
 
         #[cfg(feature = "embeddings")]
         {
             let backend = backend.clone();
+            let cache = embed_cache.clone();
             tokio::spawn(async move {
-                if let Err(e) = embeddings::handle_conn(stream, backend).await {
+                if let Err(e) = embeddings::handle_conn(stream, backend, cache).await {
                     tracing::warn!(error = %e, "conn falló");
                 }
             });