superlocalmemory 4.0.8 → 4.0.9

package/src/superlocalmemory/core/store_pipeline.py

@@ -311,8 +311,13 @@ def enrich_fact(
 # Vector dual-write helper (P1-2 / embeddings-vector-01)
 # ---------------------------------------------------------------------------
 
-def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=None):
-    """Dual-write a fact's embedding to the ANN index + sqlite-vec store.
+def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=None) -> bool:
+    """Dual-write a fact's embedding to the sqlite-vec projection and the ANN index.
+
+    Write order mirrors _attach_vector: the sqlite-vec projection is attempted
+    first because that is what a meaning-based search reads.  The ANN index is
+    updated only when the projection accepts the vector.  Returns True when the
+    fact is now findable by meaning (the projection accepted the vector).
 
     Embeds on-demand when the fact has no embedding (e.g. consolidated
     summary facts created without one), so UPDATE/SUPERSEDE and consolidated
@@ -325,18 +330,44 @@ def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=Non
         except Exception as _emb_exc:  # pragma: no cover - defensive
             _reraise_materialization_deferral(_emb_exc)
             logger.debug("on-demand embed failed for %s: %s", fact.fact_id, _emb_exc)
-            return
+            return False
     if not getattr(fact, "embedding", None):
-        return
-    if ann_index:
-        ann_index.add(fact.fact_id, fact.embedding)
-    # V3.2: VectorStore upsert (sqlite-vec) -- dual-write (Rule 12)
+        return False
+
+    projected = False
+    # Projection first: what a meaning-based search reads.
     if vector_store and getattr(vector_store, "available", False):
-        vector_store.upsert(
-            fact_id=fact.fact_id,
-            profile_id=profile_id,
-            embedding=fact.embedding,
-        )
+        try:
+            projected = bool(vector_store.upsert(
+                fact_id=fact.fact_id,
+                profile_id=profile_id,
+                embedding=fact.embedding,
+            ))
+            if not projected:
+                logger.warning(
+                    "vector projection refused for %s — stored but not "
+                    "findable by meaning", fact.fact_id[:12],
+                )
+        except Exception as _vs_exc:
+            logger.warning(
+                "vector projection failed for %s (%s: %s) — stored but not "
+                "findable by meaning",
+                fact.fact_id[:12], type(_vs_exc).__name__, _vs_exc,
+            )
+
+    # ANN index only when the projection accepted the vector so both
+    # representations stay consistent.  Writing ANN without a vector-store
+    # entry creates a ghost that disappears on restart (ANN is rebuilt from
+    # the vector store at startup).
+    if projected and ann_index:
+        try:
+            ann_index.add(fact.fact_id, fact.embedding)
+        except Exception:
+            logger.warning(
+                "in-memory index rejected %s", fact.fact_id[:12], exc_info=True,
+            )
+
+    return projected
 
 
 class _TombstoneReadError(Exception):
@@ -741,6 +772,15 @@ def run_store(
             materialization_progress["relational_started"] = True
 
         is_queryable_promotion = fact.fact_id in queryable_ids
+        # When a promoted fact is being materialised the embedding column is
+        # written in a separate step AFTER the projection attempt so that the
+        # two representations stay in the correct order: projection first,
+        # canonical column second (mirroring _attach_vector's invariant).
+        # Writing the column before the projection and then failing the
+        # projection leaves the fact with embedding IS NOT NULL but no entry
+        # in fact_embeddings — invisible to meaning-search and invisible to
+        # every repair pass that selects WHERE embedding IS NULL.
+        _deferred_canonical_embedding = None  # set below if promotion path taken
         if is_queryable_promotion:
             db.update_fact(fact.fact_id, {
                 "content": fact.content,
@@ -757,15 +797,22 @@ def run_store(
                 "access_count": fact.access_count,
                 "source_turn_ids_json": fact.source_turn_ids,
                 "session_id": fact.session_id,
-                "embedding": fact.embedding,
-                "fisher_mean": fact.fisher_mean,
-                "fisher_variance": fact.fisher_variance,
+                # embedding / fisher fields omitted here — written after
+                # the projection attempt below so canonical is never ahead
+                # of the projection.
                 "lifecycle": fact.lifecycle,
                 "langevin_position": fact.langevin_position,
                 "emotional_valence": fact.emotional_valence,
                 "emotional_arousal": fact.emotional_arousal,
                 "signal_type": fact.signal_type,
             })
+            if fact.embedding:
+                _deferred_canonical_embedding = (
+                    fact.fact_id,
+                    fact.embedding,
+                    fact.fisher_mean,
+                    fact.fisher_variance,
+                )
         if consolidator:
             try:
                 action = consolidator.consolidate(
@@ -793,6 +840,9 @@ def run_store(
                     target_id = action.existing_fact_id
                     if is_queryable_promotion and target_id:
                         db.delete_fact(fact.fact_id)
+                        # The original promoted fact was deleted; its deferred
+                        # canonical embedding write must not happen.
+                        _deferred_canonical_embedding = None
                     existing_fact = db.get_fact(target_id) if target_id else None
                     if existing_fact is None:
                         continue
@@ -838,9 +888,31 @@ def run_store(
             if materialization_progress is not None:
                 materialization_progress["fact_ids"] = tuple(stored_ids)
 
-        # Dual-write embedding to ANN index + vector store (embed on-demand if
-        # a consolidated ADD fact arrived without one). See _upsert_fact_vectors.
+        # Projection first (vector store then ANN index, on-demand embed for
+        # consolidated facts that arrived without one).
         _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder)
+
+        # Canonical embedding write: deferred to here from the queryable-
+        # promotion block above so the projection is always attempted first.
+        # The column is written regardless of whether the projection accepted
+        # the vector (the vector is real data; withholding it would force
+        # every repair pass to re-compute a model call that the same
+        # installation condition would refuse again anyway).
+        if _deferred_canonical_embedding is not None:
+            _dc_fid, _dc_emb, _dc_fmean, _dc_fvar = _deferred_canonical_embedding
+            try:
+                db.update_fact(_dc_fid, {
+                    "embedding": _dc_emb,
+                    "fisher_mean": _dc_fmean,
+                    "fisher_variance": _dc_fvar,
+                })
+            except Exception as _dc_exc:
+                logger.warning(
+                    "canonical embedding write failed for %s: %s",
+                    _dc_fid[:12], _dc_exc,
+                )
+            _deferred_canonical_embedding = None
+
         # Phase 2: Generate contextual description (after consolidator, before graph_builder)
         if context_generator:
             try:
@@ -1139,15 +1211,11 @@ def run_store_fact_direct(
         )
         fact.canonical_entities = list(canonical.values())
     db.store_fact(fact)
-    if fact.embedding and ann_index:
-        ann_index.add(fact.fact_id, fact.embedding)
-    # V3.2: VectorStore upsert (dual-write)
-    if fact.embedding and vector_store and vector_store.available:
-        vector_store.upsert(
-            fact_id=fact.fact_id,
-            profile_id=profile_id,
-            embedding=fact.embedding,
-        )
+    # Projection first (vector store), ANN only on success — matching
+    # _attach_vector's invariant.  The return value (projected) is not used
+    # here because run_store_fact_direct is a fire-and-forget path with no
+    # receipt to update; the caller is responsible for any enrichment status.
+    _upsert_fact_vectors(fact, profile_id, ann_index, vector_store)
     if graph_builder:
         graph_builder.build_edges(fact, profile_id)
     # The graph projection must run after GraphBuilder: syncing immediately

package/src/superlocalmemory/core/topic_signature.py

@@ -4,8 +4,6 @@
 
 """Topic signature — deterministic, Unicode-safe, ReDoS-resistant 16-char hex.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.2.
 
 Hot-path contract:
   - stdlib-only imports (no third-party packages).

package/src/superlocalmemory/core/transactions/concrete_owners.py

@@ -15,6 +15,7 @@ from superlocalmemory.core.transactions.owners import (
     OwnerResult,
 )
 from superlocalmemory.core.transactions.service import MemoryTransactionService
+from superlocalmemory.storage.embedding_codec import decode_embedding
 
 REQUIRED_ADMISSION_OWNERS: tuple[str, ...] = ("bm25", "temporal", "vector")
 
@@ -438,10 +439,16 @@ class VectorOwner(_FactScopedOwner):
         for row in rows:
             record = dict(row)
             fid = record.get("fact_id")
-            embedding = record.get("embedding")
-            if fid is None or not embedding:
+            raw_embedding = record.get("embedding")
+            if fid is None or not raw_embedding:
                 continue
-            result[fid] = _fingerprint("vector", str(embedding))
+            # Decode so TEXT and BLOB rows produce the same fingerprint for the
+            # same embedding values.  A ValueError here (corrupt buffer) must
+            # propagate — a bad fingerprint is worse than no fingerprint.
+            decoded = decode_embedding(raw_embedding, fact_id=fid)
+            if decoded is None:
+                continue
+            result[fid] = _fingerprint("vector", str(decoded))
         return result
 
     def _table_present(
@@ -496,11 +503,11 @@ class VectorOwner(_FactScopedOwner):
         raw = dict(rows[0]).get("embedding")
         if not raw:
             return False
-        try:
-            embedding = json.loads(raw)
-        except (TypeError, json.JSONDecodeError):
-            return False
-        if not isinstance(embedding, list) or not embedding:
+        # decode_embedding accepts both TEXT (JSON) and BLOB (float32 binary);
+        # ValueError for corrupt data propagates — a heal that silently
+        # returns False on corruption is indistinguishable from "not present".
+        embedding = decode_embedding(raw, fact_id=fact_id)
+        if not embedding:
             return False
         ok = self._vector_store.upsert(
             fact_id=fact_id, profile_id=context.profile_id, embedding=embedding,

package/src/superlocalmemory/dynamics/eap_scheduler.py

@@ -29,12 +29,14 @@ from __future__ import annotations
 
 import json
 import logging
+import sqlite3
 from typing import TYPE_CHECKING
 
 import numpy as np
 from numpy.typing import NDArray
 
 from superlocalmemory.core.config import QuantizationConfig
+from superlocalmemory.storage.embedding_codec import decode_embedding
 
 if TYPE_CHECKING:
     from superlocalmemory.math.ebbinghaus import EbbinghausCurve
@@ -262,7 +264,13 @@ class EAPScheduler:
         Tries embedding_metadata -> fact_embeddings (vec0 table).
         Falls back to atomic_facts.embedding JSON column.
         """
-        # Try atomic_facts.embedding (JSON column)
+        # Try atomic_facts.embedding (TEXT JSON or BLOB float32).
+        # Two-stage error handling:
+        #   - DB query failures (any exception from execute) → log + return None.
+        #   - Format errors from decode_embedding (ValueError) → propagate.
+        #     A corrupt embedding must NOT be silently collapsed to None because
+        #     the caller cannot distinguish "embedding absent" from "data lost".
+        raw = None
         try:
             rows = self._db.execute(
                 "SELECT embedding FROM atomic_facts WHERE fact_id = ?",
@@ -270,14 +278,17 @@ class EAPScheduler:
             )
             if rows:
                 raw = dict(rows[0]).get("embedding")
-                if raw and raw != "null":
-                    data = json.loads(raw) if isinstance(raw, str) else raw
-                    if data:
-                        return np.array(data, dtype=np.float64)
-        except Exception as exc:
+        except Exception as exc:  # noqa: BLE001 — isolates DB failure from decode failure
             logger.debug(
                 "Could not load embedding from atomic_facts for %s: %s",
                 fact_id, exc,
             )
+            return None
+
+        if raw and raw != "null":
+            # ValueError from decode_embedding propagates intentionally.
+            vec = decode_embedding(raw, fact_id=fact_id)
+            if vec:
+                return np.array(vec, dtype=np.float64)
 
         return None

package/src/superlocalmemory/encoding/graph_builder.py

@@ -9,7 +9,7 @@ last 50 memories; this version searches ALL facts per canonical entity.
 
 Edge types: ENTITY (shared entity, weight 1.0), TEMPORAL (exp-decay,
 1-week window), SEMANTIC (ANN cosine > 0.7), CAUSAL (causal markers,
-weight 0.8). CONTRADICTION exposed for external Sheaf module (Wave 4).
+weight 0.8). CONTRADICTION exposed for external Sheaf module (added in v3.5).
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
 License: AGPL-3.0-or-later
@@ -101,7 +101,7 @@ class GraphBuilder:
         self, fact_id_a: str, fact_id_b: str, profile_id: str,
         severity: float = 1.0,
     ) -> GraphEdge:
-        """Add a contradiction edge. Called by Sheaf module (Wave 4)."""
+        """Add a contradiction edge. Called by the Sheaf module (introduced in v3.5)."""
         edge = GraphEdge(
             profile_id=profile_id,
             source_id=fact_id_a,

package/src/superlocalmemory/encoding/scene_builder.py

@@ -15,6 +15,8 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import json
+
+from superlocalmemory.storage.embedding_codec import decode_embedding
 import logging
 from datetime import UTC, datetime
 
@@ -357,8 +359,12 @@ class SceneBuilder:
             embedding = None
             if raw_embedding:
                 try:
-                    embedding = json.loads(raw_embedding)
-                except (TypeError, ValueError, json.JSONDecodeError):
+                    embedding = decode_embedding(
+                        raw_embedding, fact_id=str(data.get("scene_id", "<scene>")),
+                    )
+                except ValueError:
+                    # A malformed stored value, not an absent one. Scenes are an
+                    # optimisation, so one bad row must not sink the batch.
                     embedding = None
             result[str(data["scene_id"])] = embedding
         return result

package/src/superlocalmemory/hooks/adapter_base.py

@@ -4,8 +4,6 @@
 
 """Cross-platform adapter base — shared Protocol and atomic write primitive.
 
-LLD reference: ``.backup/active-brain/lld/LLD-05-cross-platform-adapters.md``
-Sections: 2 (component catalog), 4.4 (atomic write), 9.3 (sync log contract).
 
 Every adapter (Cursor, Antigravity, Copilot) implements the ``Adapter``
 Protocol. The shared ``_atomic_write`` primitive enforces the hard-rule

package/src/superlocalmemory/hooks/context_payload.py

@@ -4,8 +4,6 @@
 
 """Shared content builder — single source for every adapter body.
 
-LLD reference: ``.backup/active-brain/lld/LLD-05-cross-platform-adapters.md``
-Section 3 (Content Builder). One builder → five formatters. Every string is
 passed through ``redact_secrets`` before entering the dataclass, so no
 adapter ever writes an unredacted secret.
 

package/src/superlocalmemory/hooks/portable_kit.py

@@ -2,16 +2,16 @@
 # Licensed under AGPL-3.0-or-later - see LICENSE file
 # Part of SuperLocalMemory V3 | https://qualixar.com
 
-"""WP-08 portable kit — ``slm connect <ide>`` MCP-wiring.
+"""Portable kit — ``slm connect <ide>`` MCP-wiring.
 
 Writes SLM's MCP block into the target IDE config via MERGE-NOT-CLOBBER:
 - Only touches the ``superlocalmemory`` server key.
 - All other servers + top-level keys are preserved byte-for-byte.
 - Atomic write (.tmp + os.replace); aborts on parse error (file untouched).
-- claude-code is OUT: short-circuits to a WP-06 plugin pointer, no config written.
+- claude-code is OUT: short-circuits to a plugin pointer, no config written.
 - AGENTS.md is appended with <!-- SLM-START/END --> markers (never overwrite).
 
-IDE_MATRIX verified against ide/configs/* templates (read-only, WP-04 owns).
+IDE_MATRIX verified against ide/configs/* templates (read-only; configs are the authoritative source).
 """
 
 from __future__ import annotations
@@ -39,7 +39,7 @@ SLM_MARKER_END = "<!-- SLM-END -->"
 VALID_TRANSPORTS: frozenset[str] = frozenset({"stdio", "http", "http-mcp-remote"})
 
 CLAUDE_CODE_PLUGIN_POINTER = (
-    "slm connect claude-code: Claude Code is configured via the SLM plugin (WP-06).\n"
+    "slm connect claude-code: Claude Code is configured via the SLM plugin (see plugin/ directory).\n"
     "Run: slm plugin install  OR  see plugin-src/ for manual installation.\n"
     "No MCP config file is written by this command."
 )
@@ -206,17 +206,17 @@ IDE_MATRIX: dict[str, IDEDescriptor] = {
         },
         caveats="contextProviders is a LIST; append+dedupe by serverName",
     ),
-    # --- OUT: claude-code defers to WP-06 ---
+    # --- OUT: claude-code defers to the plugin installer ---
     "claude-code": IDEDescriptor(
         ide_id="claude-code",
-        display="Claude Code (WP-06 plugin)",
+        display="Claude Code (plugin)",
         mcp_path_global="",
         mcp_path_project=None,
         server_key="",
         fmt="",
         agents_md_path=None,
         server_block={},
-        caveats="OUT — WP-06 plugin pointer only; no MCP config written",
+        caveats="OUT — plugin pointer only; no MCP config written",
     ),
     # --- EXPERIMENTAL (gated, not wired by default) ---
     # chatgpt-desktop, perplexity, cody: gated behind --experimental
@@ -702,7 +702,7 @@ if __name__ == "__main__":  # pragma: no cover
         metavar="IDE",
         help=(
             "IDE ids to connect.  Pass 'all' to connect every supported IDE "
-            "(excluding claude-code which uses the WP-06 plugin)."
+            "(excluding claude-code which uses the plugin installer)."
         ),
     )
     _parser.add_argument("--home", help="Override home directory (test hook).")

package/src/superlocalmemory/hooks/post_tool_async_hook.py

@@ -4,8 +4,6 @@
 
 """PostToolUse async:true hook — fire-and-forget prewarm via stdlib urllib.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.4.
 
 HARD RULES (enforced by tests):
   - stdlib only — ``urllib.request``, NOT ``httpx`` / ``requests``.

package/src/superlocalmemory/hooks/prewarm_auth.py

@@ -4,8 +4,6 @@
 
 """Authentication primitives for the /internal/prewarm daemon route.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.5.
 
 Four gates, applied in order, BEFORE any engine work:
   1. Loopback-only — client address must be 127.0.0.1 / ::1.

package/src/superlocalmemory/hooks/user_prompt_hook.py

@@ -4,8 +4,6 @@
 
 """UserPromptSubmit hook — Python fallback (compiled binary preferred).
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.3.
 
 HARD RULES (enforced by tests):
   - stdlib-only imports at module load (SLM modules delayed-imported).

package/src/superlocalmemory/infra/backup.py

@@ -16,6 +16,7 @@ import hashlib
 import json
 import logging
 import shutil
+import tempfile
 import sqlite3
 import time
 import uuid
@@ -735,15 +736,50 @@ class BackupManager:
         target = self.db_path.parent / target_name
 
         try:
-            self.create_backup(label="pre-restore")
+            # Stage the source OUTSIDE backup_dir before anything else runs.
+            #
+            # create_backup() below calls _enforce_retention(), which globs this
+            # same directory and unlinks the oldest files — including, when the
+            # backup being restored is the oldest, the source itself. A plain
+            # sqlite3.connect() on that now-missing path RECREATES it as an
+            # empty database, which is then copied over the live store while the
+            # call returns True, leaving a zero-byte file under the original
+            # name so a second attempt also appears to succeed.
+            #
+            # Reproduced before this fix: 11 snapshots, max_backups=10, a
+            # 500-fact store restored to 0 tables, restore_backup() -> True.
+            with tempfile.TemporaryDirectory(prefix="slm-restore-") as staging:
+                staged = Path(staging) / filename
+
+                # mode=ro fails loudly on a missing file instead of creating one.
+                src_ro = sqlite3.connect(f"file:{backup_path}?mode=ro", uri=True)
+                try:
+                    if not [r[0] for r in src_ro.execute(
+                            "SELECT name FROM sqlite_master WHERE type='table'")]:
+                        logger.error(
+                            "Restore rejected: %s contains no tables — refusing to "
+                            "overwrite %s with an empty database",
+                            filename, target_name,
+                        )
+                        return False
+                    staged_dst = sqlite3.connect(str(staged))
+                    try:
+                        src_ro.backup(staged_dst)
+                    finally:
+                        staged_dst.close()
+                finally:
+                    src_ro.close()
 
-            src = sqlite3.connect(str(backup_path))
-            dst = sqlite3.connect(str(target))
-            try:
-                src.backup(dst)
-            finally:
-                dst.close()
-                src.close()
+                self.create_backup(label="pre-restore")
+
+                # Restore from the staged copy, which retention cannot reach.
+                src = sqlite3.connect(f"file:{staged}?mode=ro", uri=True)
+                dst = sqlite3.connect(str(target))
+                try:
+                    src.backup(dst)
+                finally:
+                    dst.close()
+                    src.close()
 
             logger.info("Restored: %s -> %s", filename, target.name)
 

package/src/superlocalmemory/integrations/bounded_loops_mcp.py

@@ -96,6 +96,29 @@ async def observe_terminal_runs(
     return observed
 
 
+def _assert_trusted_executable(executable: Path) -> None:
+    """Raise BridgeUnavailable if executable does not pass the bridge trust checks."""
+    try:
+        st = executable.stat()
+    except OSError as exc:
+        raise BridgeUnavailable("bounded-loops bridge path is unavailable") from exc
+    mode = st.st_mode
+    if not stat.S_ISREG(mode) or (
+        os.name != "nt" and mode & (stat.S_IWGRP | stat.S_IWOTH)
+    ):
+        raise BridgeUnavailable("bounded-loops executable is not a trusted regular file")
+    # Windows trust-check limitation: only S_ISREG applies on Windows.
+    # The mode-bit check above (group/other writable) and the uid/owner check
+    # below are both skipped because:
+    #   - Python's os.stat() on Windows returns emulated Unix-style mode bits
+    #     that do not reflect real ACL permissions; the check would be meaningless.
+    #   - os.geteuid() does not exist on Windows (AttributeError); st_uid is
+    #     always 0 there, so the ownership check cannot identify non-root owners.
+    # Proper Windows ownership verification requires Win32 ACL APIs (advapi32),
+    # which would introduce a heavy optional dependency.  Scoped for a future release.
+    if os.name != "nt" and st.st_uid not in {0, os.geteuid()}:
+        raise BridgeUnavailable("bounded-loops executable owner is not trusted")
+
 async def observe_from_stdio(*, command: str, cwd: str, profile_id: str) -> list[dict[str, Any]]:
     """Run one bounded, explicit MCP 2 observation; never call from recall or remember."""
     executable, workspace = Path(command), Path(cwd)
@@ -112,15 +135,9 @@ async def observe_from_stdio(*, command: str, cwd: str, profile_id: str) -> list
     try:
         executable = executable.resolve(strict=True)
         workspace = workspace.resolve(strict=True)
-        mode = executable.stat().st_mode
     except OSError as exc:
         raise BridgeUnavailable("bounded-loops bridge path is unavailable") from exc
-    if not stat.S_ISREG(mode) or (
-        os.name != "nt" and mode & (stat.S_IWGRP | stat.S_IWOTH)
-    ):
-        raise BridgeUnavailable("bounded-loops executable is not a trusted regular file")
-    if executable.stat().st_uid not in {0, os.geteuid()}:
-        raise BridgeUnavailable("bounded-loops executable owner is not trusted")
+    _assert_trusted_executable(executable)
 
     from mcp import ClientSession, StdioServerParameters
     from mcp.client.stdio import stdio_client

package/src/superlocalmemory/learning/arm_catalog.py

@@ -4,8 +4,6 @@
 
 """Static 40-arm catalog for the contextual Thompson bandit.
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Section 5.1 — arm = (semantic, bm25, entity_graph, temporal,
 cross_encoder_bias) weight bundle drawn from a 7-point canonical grid.
 
 Pure-data module — zero imports from the rest of the codebase. Audit-friendly

package/src/superlocalmemory/learning/bandit.py

@@ -4,8 +4,6 @@
 
 """Contextual Thompson-sampling bandit over discrete channel-weight arms.
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Sections 3 (algorithm), 5.3 (file spec), 8 (hard rules).
 
 Schema: ``bandit_arms`` + ``bandit_plays`` live in ``learning.db``, created by
 LLD-07 M005. This module NEVER defines DDL — it only READs / WRITEs.

package/src/superlocalmemory/learning/bandit_cache.py

@@ -4,8 +4,6 @@
 
 """Per-(profile, stratum) posterior LRU cache for the contextual bandit.
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Section 5.2.
 
 Key design:
   - Loader runs OUTSIDE the lock so DB reads never serialise across strata.

package/src/superlocalmemory/learning/dedup_hnsw.py

@@ -28,6 +28,7 @@ from pathlib import Path
 from typing import Any, Iterable, Sequence
 
 from superlocalmemory.core.ram_lock import ram_reservation
+from superlocalmemory.storage.embedding_codec import decode_embedding
 
 logger = logging.getLogger(__name__)
 
@@ -71,19 +72,18 @@ __all__ = (
 )
 
 
-def _parse_embedding(raw: str | None) -> list[float] | None:
+def _parse_embedding(raw: bytes | str | None) -> list[float] | None:
+    """Parse an embedding from either TEXT (JSON) or BLOB (binary float32).
+
+    Returns None only when the embedding is genuinely absent (None or empty).
+    Raises ValueError for malformed data so callers can distinguish absence
+    from corruption.
+    """
     if not raw:
         return None
-    try:
-        vec = json.loads(raw)
-    except (TypeError, ValueError):
-        return None
-    if not isinstance(vec, list) or not vec:
-        return None
-    try:
-        return [float(x) for x in vec]
-    except (TypeError, ValueError):
-        return None
+    # decode_embedding raises ValueError for corrupt data; callers that want
+    # to skip a bad fact should catch ValueError explicitly, not silently.
+    return decode_embedding(raw)
 
 
 # L-P-01: vectorise ``_cosine`` via NumPy when available. NumPy cold

package/src/superlocalmemory/learning/ensemble.py

@@ -4,8 +4,6 @@
 
 """Bandit / LightGBM ensemble blender.
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Section 5.4.
 
 D8 blend policy (``choose_ensemble``):
   - 0..199 signals OR model is None → ``EnsembleWeights(1.0, 0.0)`` (bandit-only).

package/src/superlocalmemory/learning/labeler.py

@@ -4,8 +4,6 @@
 
 """Integer-label mapping for LightGBM ``lambdarank`` training.
 
-LLD reference: ``.backup/active-brain/lld/LLD-02-signal-pipeline-and-lightgbm.md``
-Section 4.7 — single source of truth for outcome-reward / position → int label.
 
 Rules:
     - Labels are integers in ``[0, 4]`` (5 relevance tiers).

package/src/superlocalmemory/learning/legacy_migration.py

@@ -4,8 +4,6 @@
 
 """Legacy ``learning_feedback`` row migration — data movement only.
 
-LLD reference: ``.backup/active-brain/lld/LLD-07-schema-migrations-and-security-primitives.md``
-Section 5 (Legacy learning_feedback Migration).
 
 Hard rule H15 (LLD-06 §10): this module MUST NOT contain any schema
 DDL. All schema definitions live in