superlocalmemory 4.0.3 → 4.0.5

package/src/superlocalmemory/storage/database.py

@@ -569,6 +569,62 @@ class DatabaseManager:
             created_at=d["created_at"],
         )
 
+    def insert_fact_immutable(self, fact: AtomicFact) -> str:
+        """Insert one known-new fact without content deduplication or replacement.
+
+        Reviewed correction successors require a caller-chosen immutable
+        identity.  Unlike normal remember ingestion, equal content must not
+        reinforce an existing row, and an occupied ID must abort the enclosing
+        transaction rather than overwrite history.
+        """
+        scope = getattr(fact, "scope", None) or "personal"
+        shared = _jd(getattr(fact, "shared_with", None))
+        self.execute(
+            """INSERT INTO atomic_facts
+           (fact_id, memory_id, profile_id, content, fact_type,
+            entities_json, canonical_entities_json,
+            observation_date, referenced_date, interval_start, interval_end,
+            confidence, importance, evidence_count, access_count,
+            source_turn_ids_json, session_id,
+            embedding, fisher_mean, fisher_variance,
+            lifecycle, langevin_position,
+            emotional_valence, emotional_arousal, signal_type, created_at,
+            scope, shared_with)
+           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+            (
+                fact.fact_id,
+                fact.memory_id,
+                fact.profile_id,
+                fact.content,
+                fact.fact_type.value,
+                json.dumps(fact.entities),
+                json.dumps(fact.canonical_entities),
+                fact.observation_date,
+                fact.referenced_date,
+                fact.interval_start,
+                fact.interval_end,
+                fact.confidence,
+                fact.importance,
+                fact.evidence_count,
+                fact.access_count,
+                json.dumps(fact.source_turn_ids),
+                fact.session_id,
+                _jd(fact.embedding),
+                _jd(fact.fisher_mean),
+                _jd(fact.fisher_variance),
+                fact.lifecycle.value,
+                _jd(fact.langevin_position),
+                fact.emotional_valence,
+                fact.emotional_arousal,
+                fact.signal_type.value,
+                fact.created_at,
+                scope,
+                shared,
+            ),
+        )
+        self.store_temporal_validity(fact.fact_id, fact.profile_id)
+        return fact.fact_id
+
     def set_pinned(self, fact_id: str, pinned: bool) -> None:
         """Set or clear the pinned flag on a fact (v3.4.65 core-memory)."""
         self.execute(
@@ -604,7 +660,23 @@ class DatabaseManager:
             "ORDER BY importance DESC",
             (*params,),
         )
-        return [self._row_to_fact(r) for r in rows]
+        facts = [self._row_to_fact(r) for r in rows]
+        if not facts:
+            return facts
+        try:
+            blocked = self.get_nonapplied_correction_successor_ids(
+                [fact.fact_id for fact in facts],
+                profile_id,
+                include_global=include_global,
+                include_shared=include_shared,
+            )
+        except Exception as exc:
+            logger.warning("Pinned correction admission lookup failed: %s", exc)
+            return []
+        if not isinstance(blocked, set):
+            logger.warning("Pinned correction admission returned malformed data")
+            return []
+        return [fact for fact in facts if fact.fact_id not in blocked]
 
     def _has_archive_status(self) -> bool:
         """Whether atomic_facts carries the M011 ``archive_status`` column.
@@ -1647,12 +1719,14 @@ class DatabaseManager:
     def invalidate_fact_temporal(
         self, fact_id: str, invalidated_by: str,
         invalidation_reason: str,
+        *,
+        event_valid_until: str | None = None,
     ) -> None:
         """Mark a fact as invalidated, preserving bi-temporal independence.
 
-        - valid_until (event-time): when the fact ceased to be true in the
-          real world.  Sourced from the fact's referenced_date so the
-          real-world boundary is preserved, not overwritten with wall-clock time.
+        - valid_until (event-time): changed only when a reviewer supplies an
+          independently validated real-world boundary.  Review time, source
+          timestamps, and a detector's conclusion are not a valid substitute.
         - system_expired_at (transaction-time): when the system learned the
           fact was invalid — always set to now.
 
@@ -1666,29 +1740,12 @@ class DatabaseManager:
         from datetime import datetime as _dt
         now = _dt.now(UTC).isoformat()
 
-        # Resolve the event-time boundary from the fact's referenced_date.
-        # Falls back to the current valid_until (which may already be set),
-        # and ultimately to now if neither is available.
-        fact_rows = self.execute(
-            "SELECT referenced_date FROM atomic_facts WHERE fact_id = ?",
-            (fact_id,),
-        )
-        referenced_date = dict(fact_rows[0]).get("referenced_date") if fact_rows else None
-
-        tv_rows = self.execute(
-            "SELECT valid_until FROM fact_temporal_validity WHERE fact_id = ?",
-            (fact_id,),
-        )
-        existing_valid_until = dict(tv_rows[0]).get("valid_until") if tv_rows else None
-
-        valid_until = referenced_date or existing_valid_until or now
-
         self.execute(
             "UPDATE fact_temporal_validity "
-            "SET valid_until = ?, system_expired_at = ?, "
+            "SET valid_until = COALESCE(?, valid_until), system_expired_at = ?, "
             "    invalidated_by = ?, invalidation_reason = ? "
-            "WHERE fact_id = ?",
-            (valid_until, now, invalidated_by, invalidation_reason, fact_id),
+            "WHERE fact_id = ? AND system_expired_at IS NULL",
+            (event_valid_until, now, invalidated_by, invalidation_reason, fact_id),
         )
 
     def get_valid_facts(self, profile_id: str) -> list[str]:
@@ -1804,6 +1861,119 @@ class DatabaseManager:
                 invalid.add(dict(r)["fact_id"])
         return invalid
 
+    def get_nonapplied_correction_successor_ids(
+        self,
+        fact_ids: list[str],
+        profile_id: str,
+        *,
+        include_global: bool = False,
+        include_shared: bool = False,
+    ) -> set[str]:
+        """Return candidate successors that are not current review truth.
+
+        M042 is optional for older databases.  Its absence is safe because
+        canonical proposal never commits a successor unless the same
+        transaction also writes M042.  Once present, a read failure must reach
+        the retrieval fail-closed boundary rather than be converted to empty.
+        """
+        if not fact_ids:
+            return set()
+        present = self.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='correction_cases'"
+        )
+        if not present:
+            return set()
+        scope_where, scope_params = _scope_where(
+            profile_id,
+            include_global=include_global,
+            include_shared=include_shared,
+            prefix="f",
+        )
+        inadmissible: set[str] = set()
+        for start in range(0, len(fact_ids), 900):
+            batch = fact_ids[start:start + 900]
+            placeholders = ",".join("?" for _ in batch)
+            rows = self.execute(
+                "SELECT c.successor_fact_id FROM correction_cases c "
+                "JOIN atomic_facts f ON f.fact_id=c.successor_fact_id "
+                f"WHERE c.successor_fact_id IN ({placeholders}) AND {scope_where} "
+                "AND c.profile_id=f.profile_id "
+                "AND c.status IN ('proposed', 'rejected', 'rolled_back')",
+                (*batch, *scope_params),
+            )
+            inadmissible.update(str(row["successor_fact_id"]) for row in rows)
+        return inadmissible
+
+    def get_correction_inadmissible_fact_ids(
+        self,
+        fact_ids: list[str],
+        profile_id: str,
+        as_of: str | None = None,
+        *,
+        include_global: bool = False,
+        include_shared: bool = False,
+    ) -> set[str]:
+        """Return current-lifecycle exclusions with one bounded SQLite read.
+
+        Recall needs both sides of reviewed correction truth: an expired
+        predecessor and a successor whose case is not applied.  The older
+        public helpers preserve their focused contracts, but invoking them
+        consecutively opened two SQLite connections on every candidate stage.
+        This read-model helper uses one connection and one UNION query while
+        retaining the same profile/scope and historical ``as_of`` semantics.
+        It is intentionally read-only and does not cache lifecycle state.
+        """
+        if not fact_ids:
+            return set()
+        scope_where, scope_params = _scope_where(
+            profile_id,
+            include_global=include_global,
+            include_shared=include_shared,
+            prefix="f",
+        )
+        inadmissible: set[str] = set()
+        with self.raw_connection() as conn:
+            correction_table = conn.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='correction_cases'"
+            ).fetchone()
+            for start in range(0, len(fact_ids), 900):
+                batch = fact_ids[start:start + 900]
+                placeholders = ",".join("?" for _ in batch)
+                temporal_conditions = (
+                    "AND tv.system_expired_at IS NOT NULL "
+                    + ("AND tv.system_expired_at <= ?" if as_of is not None else "")
+                )
+                temporal_sql = (
+                    "SELECT tv.fact_id AS fact_id "
+                    "FROM fact_temporal_validity tv "
+                    "JOIN atomic_facts f ON f.fact_id=tv.fact_id "
+                    f"WHERE tv.fact_id IN ({placeholders}) AND {scope_where} "
+                    "AND tv.profile_id=f.profile_id "
+                    f"{temporal_conditions}"
+                )
+                temporal_params: tuple[Any, ...] = (
+                    *batch,
+                    *scope_params,
+                    *((as_of,) if as_of is not None else ()),
+                )
+                if correction_table is None:
+                    rows = conn.execute(temporal_sql, temporal_params).fetchall()
+                else:
+                    correction_sql = (
+                        "SELECT c.successor_fact_id AS fact_id "
+                        "FROM correction_cases c "
+                        "JOIN atomic_facts f ON f.fact_id=c.successor_fact_id "
+                        f"WHERE c.successor_fact_id IN ({placeholders}) AND {scope_where} "
+                        "AND c.profile_id=f.profile_id "
+                        "AND c.status IN ('proposed', 'rejected', 'rolled_back')"
+                    )
+                    rows = conn.execute(
+                        f"{temporal_sql} UNION {correction_sql}",
+                        (*temporal_params, *batch, *scope_params),
+                    ).fetchall()
+                inadmissible.update(str(row["fact_id"]) for row in rows)
+        return inadmissible
+
     def get_strict_temporal_inadmissible_fact_ids(
         self,
         fact_ids: list[str],

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,12 @@ 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.migrations import (
+    M042_correction_case_ledger as _M042,
+)
 from superlocalmemory.storage._schema_version import (
     SUPPORTED_SCHEMA_VERSION,
     SchemaVersionError,
@@ -234,6 +240,12 @@ 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,)),
+    # Review-gated correction metadata is self-contained in memory.db. It
+    # contains identifiers only and does not alter temporal fact state.
+    Migration(name=_M042.NAME, db_target="memory", ddl=_M042.DDL,
+              dependencies=(_M032.NAME,)),
     # M006 + M011 are deliberately NOT here — see DEFERRED_MIGRATIONS below.
 ]