superlocalmemory 4.0.2 → 4.0.4

package/src/superlocalmemory/mcp/tools_brain.py

@@ -9,6 +9,8 @@ or changes a memory answer.
 
 from __future__ import annotations
 
+import asyncio
+import sqlite3
 from pathlib import Path
 from typing import Any, Callable
 
@@ -17,6 +19,7 @@ from mcp.types import ToolAnnotations
 from superlocalmemory.core.admission import admits
 from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.infra.data_root import state_path
+from superlocalmemory.integrations.bounded_loops_mcp import BridgeUnavailable, observe_installed
 from superlocalmemory.storage.agent_experience import (
     AgentExperienceConflictError,
     AgentExperienceStore,
@@ -25,6 +28,12 @@ from superlocalmemory.storage.agent_experience import (
     ProfileAdmissionError,
     get_profile_receipt_summary,
 )
+from superlocalmemory.storage.external_evidence import (
+    ExternalEvidenceConflictError,
+    ExternalEvidenceStore,
+    ExternalEvidenceValidationError,
+    get_profile_external_evidence_summary,
+)
 
 
 def _store_for(engine: Any) -> AgentExperienceStore:
@@ -35,6 +44,14 @@ def _store_for(engine: Any) -> AgentExperienceStore:
     )
 
 
+def _external_store_for(engine: Any) -> ExternalEvidenceStore:
+    active_profile = engine.profile_id
+    return ExternalEvidenceStore(
+        Path(state_path("learning.db")),
+        is_profile_active=lambda profile_id: profile_id == active_profile,
+    )
+
+
 def _require_active_profile(engine: Any, payload: dict[str, Any]) -> str | None:
     supplied = payload.get("profile_id")
     if supplied != engine.profile_id:
@@ -42,6 +59,27 @@ def _require_active_profile(engine: Any, payload: dict[str, Any]) -> str | None:
     return None
 
 
+class _ExternalEvidenceWriteError(Exception):
+    """Preserve committed receipt count when a later snapshot item fails."""
+
+    def __init__(self, created: int, cause: Exception) -> None:
+        super().__init__(str(cause))
+        self.created = created
+        self.cause = cause
+
+
+def _record_external_evidence(store: ExternalEvidenceStore, observed: list[dict[str, Any]]) -> int:
+    """Write bounded evidence off the async MCP loop; return durable inserts."""
+    created = 0
+    for payload in observed:
+        try:
+            if store.record(payload):
+                created += 1
+        except Exception as exc:
+            raise _ExternalEvidenceWriteError(created, exc) from exc
+    return created
+
+
 def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
     """Register transport-neutral receipt reads and writes.
 
@@ -52,7 +90,7 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_brain_evidence_status() -> dict[str, Any]:
-        """Get profile-scoped Agent Experience and Cognitive Turn totals."""
+        """Get profile-scoped, observation-only Brain evidence totals."""
         engine = get_engine()
         return {
             "success": True,
@@ -60,6 +98,9 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
             "agent_experience": get_profile_receipt_summary(
                 state_path("learning.db"), engine.profile_id
             ),
+            "external_graph_evidence": get_profile_external_evidence_summary(
+                state_path("learning.db"), engine.profile_id
+            ),
             "control_plane": "observation_only",
         }
 
@@ -110,9 +151,7 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
 
     @server.tool()
     @admits(OperationKind.REMEMBER)
-    async def finalize_cognitive_turn(
-        receipt_id: str, outcome: dict[str, Any]
-    ) -> dict[str, Any]:
+    async def finalize_cognitive_turn(receipt_id: str, outcome: dict[str, Any]) -> dict[str, Any]:
         """Finalize an active-profile cognitive turn with outcome evidence."""
         engine = get_engine()
         try:
@@ -130,3 +169,49 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
         except (TypeError, ValueError) as exc:
             return {"success": False, "durable": False, "error": str(exc)}
         return {"success": True, "durable": True, "finalized": finalized}
+
+    @server.tool()
+    @admits(OperationKind.REMEMBER)
+    async def observe_bounded_loop_evidence(workspace: str) -> dict[str, Any]:
+        """Import one explicit, read-only snapshot from installed Bounded Loops.
+
+        Bounded Loops remains optional.  This tool negotiates its public MCP
+        contract at runtime, records only compatible terminal evidence, and
+        never changes recall, ranking, routing, or learned behaviour.
+        """
+        engine = get_engine()
+        created = 0
+        try:
+            observed = await observe_installed(workspace=workspace, profile_id=engine.profile_id)
+            store = _external_store_for(engine)
+            created = await asyncio.to_thread(_record_external_evidence, store, observed)
+        except _ExternalEvidenceWriteError as exc:
+            return {
+                "success": False,
+                "durable": exc.created > 0,
+                "created": exc.created,
+                "retryable": isinstance(exc.cause, LearningWriteBusyError),
+                "error": str(exc.cause),
+            }
+        except (
+            BridgeUnavailable,
+            ExternalEvidenceConflictError,
+            ExternalEvidenceValidationError,
+            ProfileAdmissionError,
+            sqlite3.Error,
+        ) as exc:
+            return {
+                "success": False,
+                "durable": created > 0,
+                "created": created,
+                "error": str(exc),
+            }
+        except LearningWriteBusyError as exc:
+            return {"success": False, "durable": False, "retryable": True, "error": str(exc)}
+        return {
+            "success": True,
+            "durable": True,
+            "observed": len(observed),
+            "created": created,
+            "control_plane": "observation_only",
+        }

package/src/superlocalmemory/server/routes/brain.py

@@ -327,7 +327,12 @@ def _compute_agent_experience(profile_id: str) -> dict:
     Receipt rows record observation and verification evidence only; this read
     model never alters retrieval, ranking, or model routing.
     """
-    return get_profile_receipt_summary(_learning_db_path(), profile_id)
+    from superlocalmemory.storage.external_evidence import get_profile_external_evidence_summary
+    path = _learning_db_path()
+    return {
+        **get_profile_receipt_summary(path, profile_id),
+        "external_graph_evidence": get_profile_external_evidence_summary(path, profile_id),
+    }
 
 
 def _resolve_phase(signals: int, model_active: bool,

package/src/superlocalmemory/storage/_migration_internals.py

@@ -147,6 +147,9 @@ from superlocalmemory.storage.migrations import (
 from superlocalmemory.storage.migrations import (
     M040_agent_experience_receipts as _M040,
 )
+from superlocalmemory.storage.migrations import (
+    M041_external_evidence_receipts as _M041,
+)
 
 # Emit under the runner's logger name so operational log filters that key on
 # "superlocalmemory.storage.migration_runner" keep matching after this split.
@@ -195,6 +198,7 @@ _MODULES = {
     _M038.NAME: _M038,
     _M039.NAME: _M039,
     _M040.NAME: _M040,
+    _M041.NAME: _M041,
 }
 
 # Exact historical DDL fingerprints whose resulting schema is intentionally

package/src/superlocalmemory/storage/_schema_version.py

@@ -21,9 +21,9 @@ import sqlite3
 from pathlib import Path
 
 #: Highest schema_version this runner can write.  Matches the trailing serial
-#: of the latest migration (M040).  Increment when adding new migrations or
+#: of the latest migration (M041).  Increment when adding new migrations or
 #: table-level breaking changes.
-SUPPORTED_SCHEMA_VERSION: int = 40
+SUPPORTED_SCHEMA_VERSION: int = 41
 
 
 class SchemaVersionError(RuntimeError):

package/src/superlocalmemory/storage/agent_experience.py

@@ -245,17 +245,29 @@ class AgentExperienceStore:
             turn_count = conn.execute(
                 "DELETE FROM cognitive_turn_receipts WHERE profile_id=?", (profile_id,)
             ).rowcount
+            external_count = 0
+            has_external = conn.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' "
+                "AND name='external_evidence_receipts'"
+            ).fetchone() is not None
+            if has_external:
+                external_count = conn.execute(
+                    "DELETE FROM external_evidence_receipts WHERE profile_id=?", (profile_id,)
+                ).rowcount
+            receipt_tables = ["agent_experiences", "cognitive_turn_receipts"]
+            if has_external:
+                receipt_tables.append("external_evidence_receipts")
             residue = sum(
                 int(
                     conn.execute(
                         f"SELECT COUNT(*) FROM {table} WHERE profile_id=?", (profile_id,)
                     ).fetchone()[0]
                 )
-                for table in ("agent_experiences", "cognitive_turn_receipts")
+                for table in receipt_tables
             )
             if residue:
                 raise RuntimeError("learning receipt erasure left profile residue")
-            return experience_count + turn_count
+            return experience_count + turn_count + external_count
 
         return self._write(erase)
 
@@ -422,7 +434,7 @@ def purge_profile_receipts(
             for row in conn.execute(
                 "SELECT name FROM sqlite_master WHERE type='table' "
                 "AND name IN ('agent_experiences', 'cognitive_turn_receipts', "
-                "'agent_receipt_profile_closures')"
+                "'agent_receipt_profile_closures', 'external_evidence_receipts')"
             )
         }
     if not tables:
@@ -431,6 +443,16 @@ def purge_profile_receipts(
         "agent_experiences", "cognitive_turn_receipts", "agent_receipt_profile_closures"
     }
     if tables != expected:
+        if tables == expected | {"external_evidence_receipts"}:
+            from superlocalmemory.storage.migrations import M041_external_evidence_receipts as m041
+
+            with sqlite3.connect(path) as conn:
+                # Erasure needs a valid table, not its optional performance indexes.
+                # A damaged index must never strand profile-scoped evidence.
+                if m041._table_is_valid(conn):
+                    return AgentExperienceStore(
+                        path, is_profile_active=lambda _: True
+                    ).erase_profile(profile_id, close_profile=close_profile)
         raise sqlite3.OperationalError("incomplete Agent Experience receipt schema")
     return AgentExperienceStore(
         path, is_profile_active=lambda _: True
@@ -459,7 +481,7 @@ def get_profile_receipt_summary(
     if not path.exists():
         return unavailable
     try:
-        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=0.5)
+        conn = sqlite3.connect(f"{path.resolve().as_uri()}?mode=ro", uri=True, timeout=0.5)
         try:
             experience = conn.execute(
                 "SELECT COUNT(*) FROM agent_experiences WHERE profile_id=?", (profile_id,)

package/src/superlocalmemory/storage/external_evidence.py

@@ -0,0 +1,359 @@
+"""Typed storage for versioned, observation-only MCP evidence."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sqlite3
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from superlocalmemory.storage.agent_experience import (
+    _PROCESS_LOCKS,
+    _PROCESS_LOCKS_GUARD,
+    _PROFILE_GATES,
+    LearningWriteBusyError,
+    ProfileAdmissionError,
+    _ProfileAdmissionGate,
+)
+
+_CONTRACT = "bounded-loops.dev/slm-bridge/v1"
+_SHA256 = re.compile(r"\Asha256:[a-f0-9]{64}\Z")
+_IDENTIFIER = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z")
+_RUN_STATES = frozenset({"SUCCEEDED", "FAILED", "HALTED", "CANCELLED", "EXPIRED"})
+_OUTCOMES = frozenset({"SUCCEEDED", "FAILED", "CANCELLED"})
+_MAX_NODES = 256
+_MAX_ARTIFACTS_PER_NODE = 64
+_MAX_ARTIFACTS_TOTAL = 2_048
+_MAX_NODES_JSON_BYTES = 64 * 1024
+_MAX_TIMESTAMP_BYTES = 128
+_MAX_RECEIPT_SEQUENCE = (1 << 63) - 1
+_INSERT = (
+    "INSERT INTO external_evidence_receipts (profile_id, contract_id, workspace_id, "
+    "run_ref, run_id, outcome, run_state, demonstration, "
+    "eligible_for_learning, terminal_at, graph_digest, plan_digest, "
+    "policy_digest, receipt_sequence, receipt_head_digest, receipt_trust, "
+    "nodes_json, artifact_digests_json, payload_sha256, observed_at) "
+    "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
+    "ON CONFLICT(profile_id, contract_id, workspace_id, run_ref) DO NOTHING"
+)
+
+
+class ExternalEvidenceConflictError(ValueError):
+    """A stable external run address produced a different terminal receipt head."""
+
+
+class ExternalEvidenceValidationError(ValueError):
+    """An external evidence document does not satisfy the public v1 contract."""
+
+
+class ExternalEvidenceStore:
+    """Persist evidence without entering SLM's memory/recall lock domain."""
+
+    def __init__(self, path: str | Path, *, is_profile_active: Callable[[str], bool]) -> None:
+        self._path = Path(path)
+        self._is_profile_active = is_profile_active
+        resolved = str(self._path.resolve())
+        with _PROCESS_LOCKS_GUARD:
+            self._lock = _PROCESS_LOCKS.setdefault(resolved, threading.Lock())
+            self._gate = _PROFILE_GATES.setdefault(resolved, _ProfileAdmissionGate())
+
+    def record(self, payload: dict[str, Any]) -> bool:
+        _validate(payload)
+        profile_id = payload["profile_id"]
+        self._gate.admit(profile_id, self._is_profile_active)
+        digest = _payload_digest(payload)
+        deadline = time.monotonic() + 0.90
+        if not self._lock.acquire(timeout=0.90):
+            self._gate.release(profile_id)
+            raise LearningWriteBusyError("external evidence write deadline exceeded")
+        try:
+            while True:
+                conn: sqlite3.Connection | None = None
+                try:
+                    conn = sqlite3.connect(str(self._path), timeout=0, isolation_level=None)
+                    conn.row_factory = sqlite3.Row
+                    conn.execute("PRAGMA journal_mode=WAL")
+                    conn.execute("PRAGMA busy_timeout=0")
+                    conn.execute("PRAGMA synchronous=NORMAL")
+                    conn.execute("BEGIN IMMEDIATE")
+                    _assert_profile_open(conn, profile_id)
+                    row = _row(payload, digest)
+                    cursor = conn.execute(_INSERT, row)
+                    if cursor.rowcount:
+                        conn.execute("COMMIT")
+                        return True
+                    existing = _get_conn(
+                        conn,
+                        profile_id,
+                        payload["contract"],
+                        payload["workspace_id"],
+                        payload["run_ref"],
+                    )
+                    conn.execute("ROLLBACK")
+                    if _payload_digest(existing) == digest:
+                        return False
+                    raise ExternalEvidenceConflictError(
+                        "external run address has a different receipt head"
+                    )
+                except sqlite3.OperationalError as exc:
+                    if conn is not None and conn.in_transaction:
+                        conn.execute("ROLLBACK")
+                    busy = "locked" in str(exc).lower() or "busy" in str(exc).lower()
+                    if not busy or time.monotonic() >= deadline:
+                        if busy:
+                            raise LearningWriteBusyError(
+                                "external evidence write deadline exceeded"
+                            ) from exc
+                        raise
+                    time.sleep(0.02)
+                finally:
+                    if conn is not None:
+                        conn.close()
+        finally:
+            self._lock.release()
+            self._gate.release(profile_id)
+
+    def get(self, profile_id: str, workspace_id: str, run_ref: str) -> dict[str, Any] | None:
+        conn = sqlite3.connect(f"{self._path.resolve().as_uri()}?mode=ro", uri=True, timeout=0.5)
+        conn.row_factory = sqlite3.Row
+        try:
+            return _get_conn(conn, profile_id, _CONTRACT, workspace_id, run_ref)
+        finally:
+            conn.close()
+
+
+def get_profile_external_evidence_summary(path: str | Path, profile_id: str) -> dict[str, Any]:
+    """Return indexed Living Brain totals without opening SLM's memory database."""
+    empty = {
+        "is_real": False,
+        "availability": "unavailable",
+        "total": 0,
+        "by_run_state": {},
+        "demonstrations": 0,
+    }
+    target = Path(path)
+    if not target.exists():
+        return empty
+    conn: sqlite3.Connection | None = None
+    try:
+        conn = sqlite3.connect(f"{target.resolve().as_uri()}?mode=ro", uri=True, timeout=0.5)
+        total = conn.execute(
+            "SELECT COUNT(*) FROM external_evidence_receipts WHERE profile_id=?", (profile_id,)
+        ).fetchone()[0]
+        demo = conn.execute(
+            "SELECT COUNT(*) FROM external_evidence_receipts "
+            "WHERE profile_id=? AND demonstration=1",
+            (profile_id,),
+        ).fetchone()[0]
+        rows = conn.execute(
+            "SELECT run_state, COUNT(*) FROM external_evidence_receipts "
+            "WHERE profile_id=? GROUP BY run_state",
+            (profile_id,),
+        ).fetchall()
+    except sqlite3.Error:
+        return empty
+    finally:
+        if conn is not None:
+            conn.close()
+    return {
+        "is_real": True,
+        "availability": "available",
+        "total": int(total),
+        "by_run_state": {str(k): int(v) for k, v in rows},
+        "demonstrations": int(demo),
+        "control_plane": "observation_only",
+    }
+
+
+def _validate(payload: dict[str, Any]) -> None:
+    required = {
+        "contract",
+        "profile_id",
+        "workspace_id",
+        "run_ref",
+        "run_id",
+        "outcome",
+        "run_state",
+        "demonstration",
+        "eligible_for_learning",
+        "terminal_at",
+        "graph_digest",
+        "plan_digest",
+        "policy_digest",
+        "receipt",
+        "nodes",
+    }
+    if set(payload) != required:
+        raise ExternalEvidenceValidationError("external evidence fields do not match v1")
+    if payload["contract"] != _CONTRACT:
+        raise ExternalEvidenceValidationError("unsupported external evidence contract")
+    for name in ("profile_id", "run_ref", "run_id"):
+        if not isinstance(payload[name], str) or not _IDENTIFIER.match(payload[name]):
+            raise ExternalEvidenceValidationError(f"{name} must be a safe identifier")
+    for name in ("workspace_id", "graph_digest", "plan_digest", "policy_digest"):
+        if not isinstance(payload[name], str) or not _SHA256.match(payload[name]):
+            raise ExternalEvidenceValidationError(f"{name} must be a sha256 digest")
+    if payload["outcome"] not in _OUTCOMES or payload["run_state"] not in _RUN_STATES:
+        raise ExternalEvidenceValidationError("outcome or run_state is unsupported")
+    if payload["run_state"] == "SUCCEEDED" and payload["outcome"] != "SUCCEEDED":
+        raise ExternalEvidenceValidationError("SUCCEEDED run_state must keep its outcome")
+    if (
+        not isinstance(payload["terminal_at"], str)
+        or len(payload["terminal_at"].encode("utf-8")) > _MAX_TIMESTAMP_BYTES
+    ):
+        raise ExternalEvidenceValidationError("terminal_at must be an RFC3339 timestamp")
+    try:
+        datetime.fromisoformat(payload["terminal_at"].replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ExternalEvidenceValidationError("terminal_at must be an RFC3339 timestamp") from exc
+    if (
+        not isinstance(payload["demonstration"], bool)
+        or payload["eligible_for_learning"] is not False
+    ):
+        raise ExternalEvidenceValidationError("v1 evidence is observation-only")
+    receipt = payload["receipt"]
+    if not isinstance(receipt, dict) or set(receipt) != {
+        "sequence",
+        "head_digest",
+        "trust",
+    }:
+        raise ExternalEvidenceValidationError("receipt shape is invalid")
+    if (
+        not isinstance(receipt["sequence"], int)
+        or receipt["sequence"] < 1
+        or receipt["sequence"] > _MAX_RECEIPT_SEQUENCE
+        or receipt["trust"] != "local_hash_chain_only"
+    ):
+        raise ExternalEvidenceValidationError("receipt metadata is invalid")
+    if not isinstance(receipt["head_digest"], str) or not _SHA256.match(receipt["head_digest"]):
+        raise ExternalEvidenceValidationError("receipt head digest is invalid")
+    if not isinstance(payload["nodes"], list):
+        raise ExternalEvidenceValidationError("nodes must be a list")
+    if len(payload["nodes"]) > _MAX_NODES:
+        raise ExternalEvidenceValidationError("node count exceeds v1 safety limit")
+    artifact_count = 0
+    for node in payload["nodes"]:
+        if not isinstance(node, dict) or set(node) != {
+            "node_id",
+            "state",
+            "gate_passed",
+            "attempts",
+            "artifact_digests",
+        }:
+            raise ExternalEvidenceValidationError("node shape is invalid")
+        valid_node = _IDENTIFIER.match(str(node["node_id"])) and _IDENTIFIER.match(
+            str(node["state"])
+        )
+        if not valid_node:
+            raise ExternalEvidenceValidationError("node identifiers are invalid")
+        if (
+            node["gate_passed"] not in (True, False, None)
+            or not isinstance(node["attempts"], int)
+            or node["attempts"] < 1
+        ):
+            raise ExternalEvidenceValidationError("node gate metadata is invalid")
+        if not isinstance(node["artifact_digests"], list) or any(
+            not isinstance(item, str) or not _SHA256.match(item)
+            for item in node["artifact_digests"]
+        ):
+            raise ExternalEvidenceValidationError("node artifact digests are invalid")
+        if len(node["artifact_digests"]) > _MAX_ARTIFACTS_PER_NODE:
+            raise ExternalEvidenceValidationError("node artifact count exceeds v1 safety limit")
+        artifact_count += len(node["artifact_digests"])
+        if artifact_count > _MAX_ARTIFACTS_TOTAL:
+            raise ExternalEvidenceValidationError("artifact count exceeds v1 safety limit")
+    if len(_json(payload["nodes"]).encode("utf-8")) > _MAX_NODES_JSON_BYTES:
+        raise ExternalEvidenceValidationError("node evidence exceeds v1 size limit")
+
+
+def _row(payload: dict[str, Any], digest: str) -> tuple[Any, ...]:
+    artifacts = sorted({item for node in payload["nodes"] for item in node["artifact_digests"]})
+    receipt = payload["receipt"]
+    return (
+        payload["profile_id"],
+        payload["contract"],
+        payload["workspace_id"],
+        payload["run_ref"],
+        payload["run_id"],
+        payload["outcome"],
+        payload["run_state"],
+        int(payload["demonstration"]),
+        0,
+        payload["terminal_at"],
+        payload["graph_digest"],
+        payload["plan_digest"],
+        payload["policy_digest"],
+        receipt["sequence"],
+        receipt["head_digest"],
+        receipt["trust"],
+        _json(payload["nodes"]),
+        _json(artifacts),
+        digest,
+        datetime.now(timezone.utc).isoformat(),
+    )
+
+
+def _assert_profile_open(conn: sqlite3.Connection, profile_id: str) -> None:
+    """Use M040's durable tombstone inside this writer transaction."""
+    table = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' "
+        "AND name='agent_receipt_profile_closures'"
+    ).fetchone()
+    if (
+        table is not None
+        and conn.execute(
+            "SELECT 1 FROM agent_receipt_profile_closures WHERE profile_id=?", (profile_id,)
+        ).fetchone()
+        is not None
+    ):
+        raise ProfileAdmissionError("profile is inactive or closing for erasure")
+
+
+def _get_conn(
+    conn: sqlite3.Connection,
+    profile_id: str,
+    contract_id: str,
+    workspace_id: str,
+    run_ref: str,
+) -> dict[str, Any] | None:
+    row = conn.execute(
+        "SELECT * FROM external_evidence_receipts WHERE profile_id=? AND contract_id=? "
+        "AND workspace_id=? AND run_ref=?",
+        (profile_id, contract_id, workspace_id, run_ref),
+    ).fetchone()
+    if row is None:
+        return None
+    return {
+        "contract": row["contract_id"],
+        "profile_id": row["profile_id"],
+        "workspace_id": row["workspace_id"],
+        "run_ref": row["run_ref"],
+        "run_id": row["run_id"],
+        "outcome": row["outcome"],
+        "run_state": row["run_state"],
+        "demonstration": bool(row["demonstration"]),
+        "eligible_for_learning": bool(row["eligible_for_learning"]),
+        "terminal_at": row["terminal_at"],
+        "graph_digest": row["graph_digest"],
+        "plan_digest": row["plan_digest"],
+        "policy_digest": row["policy_digest"],
+        "receipt": {
+            "sequence": row["receipt_sequence"],
+            "head_digest": row["receipt_head_digest"],
+            "trust": row["receipt_trust"],
+        },
+        "nodes": json.loads(row["nodes_json"]),
+    }
+
+
+def _payload_digest(payload: dict[str, Any]) -> str:
+    return hashlib.sha256(_json(payload).encode("utf-8")).hexdigest()
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True)

package/src/superlocalmemory/storage/migration_runner.py

@@ -154,6 +154,9 @@ from superlocalmemory.storage.migrations import (
 from superlocalmemory.storage.migrations import (
     M040_agent_experience_receipts as _M040,
 )
+from superlocalmemory.storage.migrations import (
+    M041_external_evidence_receipts as _M041,
+)
 from superlocalmemory.storage._schema_version import (
     SUPPORTED_SCHEMA_VERSION,
     SchemaVersionError,
@@ -234,6 +237,8 @@ MIGRATIONS: list[Migration] = [
     # lifecycle performs explicit cross-store erasure rather than an FK.
     Migration(name=_M040.NAME, db_target="learning", ddl=_M040.DDL,
               dependencies=(_M003.NAME,)),
+    Migration(name=_M041.NAME, db_target="learning", ddl=_M041.DDL,
+              dependencies=(_M040.NAME,)),
     # M006 + M011 are deliberately NOT here — see DEFERRED_MIGRATIONS below.
 ]