cortexm 0.3.0__py3-none-any.whl

cortexm/enterprise/governance.py

@@ -0,0 +1,239 @@
+"""Data governance: GDPR erasure, retention, backup/restore, PITR.
+
+These are the four operations an enterprise buyer's security review
+actually blocks on:
+
+  erase_user()     — Art. 17 right-to-erasure: hard-delete every trace
+                     of a subject (facts, chunks, vectors, lexicon,
+                     aliases, vault entries), crypto-shred the PII vault,
+                     and leave the audit chain intact (legal exemption)
+                     with an erasure ATTESTATION record.
+  apply_retention() — Art. 5(1)(e) storage-limitation: expire facts and
+                     chunks older than the policy window, keeping the
+                     bi-temporal tombstones so history remains honest.
+  snapshot()/restore() — atomic, integrity-checked backup envelope
+                     (SQLite backup API + manifest + Merkle-style digest
+                     of the artifact).
+  state_at()       — point-in-time recovery read: the bi-temporal Trace
+                     replays "what did the system believe at T?" using
+                     transaction times (tx_from/tx_to) — no snapshot
+                     needed, the database IS the WAL.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from datetime import datetime, timezone
+
+from cortexm.security.hashes import HashProvider
+
+
+class Governance:
+    def __init__(self, memory) -> None:
+        self.memory = memory
+        self.store = memory.store
+        self.palace = memory.palace
+        self.audit = getattr(memory, "audit_log", None)
+
+    def _log(self, action: str, resource: str | None = None,
+             outcome: str = "success", meta: dict | None = None) -> None:
+        if self.audit is not None:
+            self.audit.log(action, resource=resource, outcome=outcome,
+                           meta=meta)
+
+    # ------------------------------------------------------------ erasure
+    def erase_user(self, user_id: str, *, hard: bool = True,
+                   crypto_shred: bool = True) -> dict:
+        """GDPR Art. 17 — remove the subject from every layer."""
+        t0 = time.time()
+        conn = self.store.conn
+        counts = {}
+        counts["facts"] = conn.execute(
+            "SELECT COUNT(*) AS c FROM facts WHERE user_id=?",
+            (user_id,)).fetchone()["c"]
+        counts["chunks"] = conn.execute(
+            "SELECT COUNT(*) AS c FROM chunks WHERE user_id=?",
+            (user_id,)).fetchone()["c"]
+        # orphaned edges touching removed facts
+        fact_ids = [r["id"] for r in conn.execute(
+            "SELECT id FROM facts WHERE user_id=?", (user_id,))]
+        if fact_ids:
+            qmarks = ",".join("?" * len(fact_ids))
+            counts["edges"] = conn.execute(
+                f"SELECT COUNT(*) AS c FROM edges WHERE src IN ({qmarks}) "
+                f"OR dst IN ({qmarks})", fact_ids + fact_ids).fetchone()["c"]
+            conn.execute(f"DELETE FROM edges WHERE src IN ({qmarks}) "
+                         f"OR dst IN ({qmarks})", fact_ids + fact_ids)
+        conn.execute("DELETE FROM facts WHERE user_id=?", (user_id,))
+        conn.execute("DELETE FROM chunks WHERE user_id=?", (user_id,))
+        # kv residue: lexicon, names, alias caches
+        kv_removed = 0
+        for k, _v in list(self.store.iter_kv(f"lexicon:{user_id}")):
+            self.store.kv_delete(k); kv_removed += 1
+        for k, _v in list(self.store.iter_kv(f"name:{user_id}")):
+            self.store.kv_delete(k); kv_removed += 1
+        counts["kv"] = kv_removed
+        # PII vault: crypto-shred if enabled and configured
+        vault = getattr(self.memory, "pii_vault", None)
+        if vault is not None and crypto_shred:
+            counts["vault_shredded"] = vault.crypto_shred()
+        # palace vectors for those facts
+        vec_removed = 0
+        if fact_ids:
+            vec_removed = self.palace.remove_ids(fact_ids)
+        counts["vectors"] = vec_removed
+        conn.commit()
+        # erasure attestation in the tamper-evident chain (Art. 30 records)
+        self._log("governance.erase", resource=user_id, outcome="erased",
+                  meta={"counts": counts,
+                        "duration_ms": round((time.time() - t0) * 1e3, 1),
+                        "hard": hard, "crypto_shred": crypto_shred})
+        # residual scan: no row may reference the subject anywhere
+        residual = {
+            "facts": conn.execute(
+                "SELECT COUNT(*) AS c FROM facts WHERE user_id=?",
+                (user_id,)).fetchone()["c"],
+            "chunks": conn.execute(
+                "SELECT COUNT(*) AS c FROM chunks WHERE user_id=?",
+                (user_id,)).fetchone()["c"],
+        }
+        return {"user_id": user_id, "erased": residual["facts"] == 0
+                and residual["chunks"] == 0,
+                "counts": counts, "residual": residual,
+                "duration_ms": round((time.time() - t0) * 1e3, 1)}
+
+    # ------------------------------------------------------------ retention
+    def apply_retention(self, days: int, *, user_id: str | None = None,
+                        dry_run: bool = False) -> dict:
+        """Expire facts whose last transaction time is older than ``days``."""
+        if days <= 0:
+            raise ValueError("days must be positive")
+        cutoff = datetime.now(timezone.utc).timestamp() - days * 86400
+        cutoff_iso = datetime.fromtimestamp(cutoff, tz=timezone.utc).isoformat()
+        conn = self.store.conn
+        q = ("SELECT COUNT(*) AS c FROM facts WHERE tx_from < ? "
+             "AND tx_to IS NULL")
+        args = [cutoff_iso]
+        if user_id:
+            q += " AND user_id=?"
+            args.append(user_id)
+        stale = conn.execute(q, args).fetchone()["c"]
+        if dry_run:
+            return {"stale_facts": stale, "applied": False}
+        q2 = "UPDATE facts SET tx_to=?, is_active=0 WHERE tx_from < ? AND tx_to IS NULL"
+        args2 = [datetime.now(timezone.utc).isoformat(), cutoff_iso]
+        if user_id:
+            q2 += " AND user_id=?"
+            args2.append(user_id)
+        cur = conn.execute(q2, args2)
+        conn.commit()
+        self._log("governance.retention",
+                  meta={"days": days, "expired": cur.rowcount,
+                        "user_id": user_id or "all"})
+        return {"stale_facts": cur.rowcount, "applied": True,
+                "cutoff": cutoff_iso}
+
+    # ------------------------------------------------------------ snapshot
+    def snapshot(self, path: str) -> dict:
+        """Atomic backup: online-backup the SQLite file + write a manifest.
+        The backup API copies page-by-page under a read transaction —
+        safe while writers are active."""
+        os.makedirs(os.path.dirname(os.path.abspath(path)) or ".", exist_ok=True)
+        if path.endswith("/"):
+            raise ValueError("path must be a file, not a directory")
+        target = sqlite_backup(self.store.db_path, path)
+        digest = _file_digest(target)
+        manifest = {
+            "format": "context-m-snapshot/1",
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "source_db": self.store.db_path,
+            "file": os.path.basename(target),
+            "size_bytes": os.path.getsize(target),
+            "sha256": digest,
+            "facts": self.store.conn.execute(
+                "SELECT COUNT(*) AS c FROM facts").fetchone()["c"],
+            "audit_head": (self.audit.verify()["head_hash"]
+                           if self.audit else None),
+        }
+        mpath = target + ".manifest.json"
+        with open(mpath, "w", encoding="utf-8") as fh:
+            json.dump(manifest, fh, indent=2)
+        self._log("governance.snapshot",
+                  resource=path, meta={"sha256": digest,
+                                       "size": manifest["size_bytes"]})
+        return {"path": target, "manifest": manifest, "manifest_path": mpath}
+
+    def restore(self, snapshot_path: str, *, verify: bool = True) -> dict:
+        """Restore from a snapshot manifest pair. Refuses mismatched digests."""
+        mpath = snapshot_path + ".manifest.json"
+        if verify and not os.path.exists(mpath):
+            raise FileNotFoundError("manifest missing — cannot verify integrity")
+        if os.path.exists(mpath):
+            with open(mpath, encoding="utf-8") as fh:
+                manifest = json.load(fh)
+            if verify:
+                digest = _file_digest(snapshot_path)
+                if digest != manifest["sha256"]:
+                    raise ValueError(
+                        f"integrity check failed: {digest} != {manifest['sha256']}")
+        # close current handles, replace file, reopen
+        db_path = self.store.db_path
+        self.memory.close()
+        import shutil
+        shutil.copyfile(snapshot_path, db_path)
+        self.memory._reopen()
+        # _reopen() built a NEW Governance object; this method is running
+        # on the old one — rebind self so the audit attestation below
+        # writes through the fresh store, not the closed one.
+        self.store = self.memory.store
+        self.palace = self.memory.palace
+        self.audit = self.memory.audit_log
+        self._log("governance.restore", resource=snapshot_path)
+        return {"restored": db_path, "verified": verify}
+
+    # ------------------------------------------------------------ PITR
+    def state_at(self, when, *, user_id: str | None = None,
+                 limit: int = 500) -> list[dict]:
+        """Point-in-time read: facts the system believed true at ``when``
+        (transaction-time replay — the database is its own WAL)."""
+        from cortexm.api.memory import parse_ts
+        ts = parse_ts(when) if not isinstance(when, datetime) else when
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=timezone.utc)
+        # normalize to the Z-suffix format facts are stored with, so the
+        # string comparison in SQL matches the stored tx_from exactly
+        iso = ts.strftime("%Y-%m-%dT%H:%M:%SZ")
+        q = ("SELECT * FROM facts WHERE tx_from <= ? AND "
+             "(tx_to IS NULL OR tx_to > ?) AND quarantined=0")
+        args: list = [iso, iso]
+        if user_id:
+            q += " AND user_id=?"
+            args.append(user_id)
+        q += " ORDER BY valid_from DESC LIMIT ?"
+        args.append(limit)
+        rows = [dict(r) for r in self.store.conn.execute(q, args)]
+        self._log("governance.pitr", meta={"when": iso, "rows": len(rows)})
+        return rows
+
+
+# ------------------------------------------------------------------ helpers
+def sqlite_backup(src_db: str, dst_path: str) -> str:
+    import sqlite3
+    src = sqlite3.connect(src_db)
+    dst = sqlite3.connect(dst_path)
+    with dst:
+        src.backup(dst)
+    dst.close()
+    src.close()
+    return dst_path
+
+
+def _file_digest(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()

cortexm/errors.py

@@ -0,0 +1,35 @@
+"""Exception hierarchy for Context-M."""
+
+from __future__ import annotations
+
+
+class ContextMError(Exception):
+    """Base class."""
+
+
+class StoreError(ContextMError):
+    """Trace / SQLite layer failure."""
+
+
+class ExtractionError(ContextMError):
+    """Deterministic extraction pipeline failure."""
+
+
+class SecurityError(ContextMError):
+    """Provenance / hash verification failure."""
+
+
+class VerificationError(SecurityError):
+    """Hash or Merkle proof did not verify."""
+
+
+class BranchError(ContextMError):
+    """Memory-Git operation failure (unknown branch, dirty state...)."""
+
+
+class MigrationError(ContextMError):
+    """Import from a foreign memory system failed."""
+
+
+class CodecError(ContextMError):
+    """Vector codec failure (untrained PQ, corrupt record...)."""

cortexm/features/git.py

@@ -0,0 +1,204 @@
+"""Memory Git — version control for agent memory.
+
+Every add() is a hash-chained commit on a Merkle-style DAG. Branches
+fork memory state (A/B-test an agent personality), merges replay
+theirs-onto-ours with deterministic conflict resolution via the
+lifecycle engine, diffs show exactly which facts changed, and blame
+traces which commit introduced a fact. Enterprises get regulatory
+rollback and forensic audit as first-class operations.
+"""
+
+from __future__ import annotations
+
+import json
+
+from cortexm.errors import BranchError
+from cortexm.trace.fact import Fact, SINGLE_VALUED
+from cortexm.trace.store import TraceStore
+from cortexm.util import new_id, similarity
+
+
+class MemoryGit:
+    def __init__(self, store: TraceStore, palace=None) -> None:
+        self.store = store
+        self.palace = palace
+
+    # ------------------------------------------------------------- basics
+    def branch(self, name: str, from_commit: str | None = None,
+               switch: bool = True) -> str:
+        base = self.store.create_branch(name, from_commit, switch=switch)
+        return base
+
+    def checkout(self, name: str) -> None:
+        self.store.checkout(name)
+
+    def branches(self) -> list[dict]:
+        return self.store.branches()
+
+    def log(self, branch: str | None = None, limit: int = 50) -> list[dict]:
+        return self.store.log(branch, limit)
+
+    # ------------------------------------------------------------- sets
+    def active_at(self, commit_id: str) -> dict[str, Fact]:
+        anc = self.store.ancestry(commit_id)
+        rows = self.store.conn.execute(
+            "SELECT id, birth_commit, retired_commit FROM facts "
+            "WHERE birth_commit IS NOT NULL").fetchall()
+        ids = [r["id"] for r in rows
+               if r["birth_commit"] in anc
+               and (not r["retired_commit"] or r["retired_commit"] not in anc)]
+        return {f.id: f for f in self.store.get_facts(ids)}
+
+    def _triple_key(self, f: Fact) -> tuple:
+        return (f.subject, f.relation, f.value.lower())
+
+    # ------------------------------------------------------------- diff
+    def diff(self, a: str, b: str) -> dict:
+        fa, fb = self.active_at(a), self.active_at(b)
+        ka = {self._triple_key(f): f for f in fa.values()}
+        kb = {self._triple_key(f): f for f in fb.values()}
+        added = [kb[k] for k in kb.keys() - ka.keys()]
+        removed = [ka[k] for k in ka.keys() - kb.keys()]
+        return {
+            "from": a, "to": b,
+            "added": [{"id": f.id, "fact": f.display(),
+                       "valid_from": f.valid_from} for f in added],
+            "removed": [{"id": f.id, "fact": f.display(),
+                         "valid_from": f.valid_from} for f in removed],
+            "n_added": len(added), "n_removed": len(removed),
+        }
+
+    # ------------------------------------------------------------- blame
+    def blame(self, subject: str, relation: str | None = None,
+              user_id: str | None = None) -> list[dict]:
+        clauses = ["subject=?"]
+        params: list = [subject]
+        if relation:
+            clauses.append("relation=?")
+            params.append(relation)
+        if user_id:
+            clauses.append("user_id=?")
+            params.append(user_id)
+        rows = self.store.conn.execute(
+            f"SELECT id, relation, value, valid_from, valid_to, is_active, "
+            f"birth_commit, tx_from FROM facts WHERE {' AND '.join(clauses)} "
+            f"ORDER BY tx_from", params).fetchall()
+        out = []
+        for r in rows:
+            commit = self.store.commit(r["birth_commit"]) if r["birth_commit"] else None
+            out.append({
+                "fact_id": r["id"],
+                "fact": f"({subject}, {r['relation']}, {r['value']})",
+                "valid": f"{r['valid_from']}→{r['valid_to'] or '∞'}",
+                "active": bool(r["is_active"]),
+                "commit": r["birth_commit"],
+                "commit_message": commit["message"] if commit else None,
+                "recorded_at": r["tx_from"],
+            })
+        return out
+
+    # ------------------------------------------------------------- merge
+    def merge(self, name: str, strategy: str = "latest-wins",
+              message: str = "") -> dict:
+        """3-way merge of branch ``name`` into the current branch."""
+        if strategy not in ("latest-wins", "union"):
+            raise BranchError(f"unknown strategy {strategy!r}")
+        cur = self.store.current_branch()
+        ours_head = self.store.head(cur)
+        theirs_head = self.store.head(name)
+        if not theirs_head:
+            raise BranchError(f"branch {name!r} has no commits")
+        if theirs_head == ours_head:
+            return {"status": "already-merged", "commit": ours_head,
+                    "applied": 0, "conflicts": 0}
+
+        ours = self.active_at(ours_head)
+        theirs = self.active_at(theirs_head)
+        base_head = self._common_ancestor(ours_head, theirs_head)
+        base = self.active_at(base_head) if base_head else {}
+
+        kb = {self._triple_key(f): f for f in base.values()}
+        ko = {self._triple_key(f): f for f in ours.values()}
+        kt = {self._triple_key(f): f for f in theirs.values()}
+
+        added_by_theirs = [kt[k] for k in kt.keys() - kb.keys()]
+        retired_by_theirs = [kb[k] for k in kb.keys() - kt.keys()]
+
+        merge_commit = self.store.create_commit(
+            message or f"merge {name} into {cur} ({strategy})",
+            branch=cur, parents=[ours_head, theirs_head])
+        applied, conflicts = 0, 0
+
+        ours_by_sr: dict[tuple, list[Fact]] = {}
+        for f in ours.values():
+            ours_by_sr.setdefault((f.subject, f.relation), []).append(f)
+
+        for f in added_by_theirs:
+            key = self._triple_key(f)
+            if key in ko:
+                continue  # already present on our side
+            conflict = any(g.value.lower() != f.value.lower()
+                           for g in ours_by_sr.get((f.subject, f.relation), [])
+                           if g.is_active)
+            if conflict and f.relation in SINGLE_VALUED and strategy == "latest-wins":
+                for g in ours_by_sr.get((f.subject, f.relation), []):
+                    if not g.is_active:
+                        continue
+                    if (g.tx_from or "") <= (f.tx_from or ""):
+                        self.store.update_fact(
+                            g.id, is_active=0, retired_commit=merge_commit,
+                            tx_to=f.tx_from,
+                            provenance={**g.provenance,
+                                        "merged_away": merge_commit})
+                        conflicts += 1
+                self._copy_fact(f, merge_commit)
+                applied += 1
+            elif conflict:
+                self._copy_fact(f, merge_commit)  # union: keep both
+                conflicts += 1
+                applied += 1
+            else:
+                self._copy_fact(f, merge_commit)
+                applied += 1
+
+        for f in retired_by_theirs:
+            key = self._triple_key(f)
+            if key in ko and ko[key].is_active:
+                self.store.update_fact(
+                    ko[key].id, is_active=0, retired_commit=merge_commit,
+                    provenance={**ko[key].provenance,
+                                "merged_away": f"retired in {name}"})
+                applied += 1
+
+        self.store.conn.commit()
+        return {"status": "merged", "commit": merge_commit,
+                "base": base_head, "applied": applied, "conflicts": conflicts,
+                "strategy": strategy}
+
+    def _copy_fact(self, f: Fact, commit_id: str) -> Fact:
+        nf = Fact(
+            id=new_id(), subject=f.subject, relation=f.relation, value=f.value,
+            valid_from=f.valid_from, valid_to=f.valid_to, tx_from=f.tx_from,
+            confidence=f.confidence, source_hash=f.source_hash,
+            source_id=f.source_id, user_id=f.user_id, agent_id=f.agent_id,
+            run_id=f.run_id, memory_type=f.memory_type,
+            access_count=f.access_count, reinforcement=f.reinforcement,
+            is_active=True, is_derived=f.is_derived,
+            provenance={**f.provenance, "merged_from": f.id})
+        self.store.insert_fact(nf, commit_id)
+        if self.palace is not None:
+            self.palace.add(nf.id, self.palace.encode_fact(nf))
+        return nf
+
+    def _common_ancestor(self, a: str, b: str) -> str | None:
+        anc_a = self.store.ancestry(a)
+        anc_b = self.store.ancestry(b)
+        common = anc_a & anc_b
+        if not common:
+            return None
+        best, best_ts = None, ""
+        for cid in common:
+            c = self.store.commit(cid)
+            if c and c["ts"] > best_ts:
+                best, best_ts = cid, c["ts"]
+        return best

cortexm/features/prefetch.py

@@ -0,0 +1,88 @@
+"""Predictive Memory Prefetching — the Memory Branch Target Buffer.
+
+Learns co-access patterns across retrievals ("agents that asked about X
+next asked about Y") and prefetches predicted facts into the fusion
+boost set before the next query lands — branch prediction for agent
+memory. Wrong predictions cost nothing (a tiny score boost); right
+predictions cut effective retrieval latency toward the SLB hit path.
+"""
+
+from __future__ import annotations
+
+
+class Prefetcher:
+    def __init__(self, max_pairs: int = 200_000, decay: float = 0.98,
+                 min_weight: float = 0.05, window: int = 6) -> None:
+        self.max_pairs = max_pairs
+        self.decay = decay
+        self.min_weight = min_weight
+        self.window = window
+        self._by_fid: dict[str, dict[str, float]] = {}
+        self._recent: list[str] = []
+        self._last_predict: dict[str, float] = {}
+        self._total_pairs = 0
+        self.hits = 0
+        self.predictions = 0
+        self.predicted_total = 0
+
+    # ------------------------------------------------------------------
+    def _bump(self, a: str, b: str) -> None:
+        row = self._by_fid.setdefault(a, {})
+        prev = row.get(b, 0.0)
+        row[b] = prev + 1.0
+        if prev == 0.0:
+            self._total_pairs += 1
+
+    def observe(self, fact_ids: list[str]) -> None:
+        """Called after each retrieval with the delivered fact set."""
+        combined = list(dict.fromkeys(
+            (self._recent[-self.window:] or []) + list(fact_ids)))
+        for i, a in enumerate(combined):
+            for b in combined[i + 1:i + 5]:
+                if a != b:
+                    self._bump(a, b)
+                    self._bump(b, a)
+        self._recent = list(fact_ids)
+        if self._total_pairs > self.max_pairs:
+            self._prune()
+
+    def _prune(self) -> None:
+        for fid in list(self._by_fid):
+            row = self._by_fid[fid]
+            for other in list(row):
+                row[other] *= self.decay
+                if row[other] < self.min_weight:
+                    del row[other]
+                    self._total_pairs -= 1
+            if not row:
+                del self._by_fid[fid]
+
+    # ------------------------------------------------------------------
+    def predict(self) -> dict[str, float]:
+        """Predict next-access facts from recent history (MBTB lookup)."""
+        out: dict[str, float] = {}
+        for fid in self._recent[-self.window:]:
+            row = self._by_fid.get(fid)
+            if not row:
+                continue
+            for other, w in row.items():
+                if w >= 1.0:
+                    out[other] = max(out.get(other, 0.0), min(1.0, w / 8.0))
+        self._last_predict = out
+        self.predictions += 1
+        self.predicted_total += len(out)
+        return out
+
+    def note_hits(self, delivered_ids: list[str]) -> int:
+        hits = sum(1 for fid in delivered_ids if fid in self._last_predict)
+        self.hits += hits
+        return hits
+
+    def stats(self) -> dict:
+        return {
+            "pairs": self._total_pairs,
+            "predictions": self.predictions,
+            "prefetch_hits": self.hits,
+            "prefetch_hit_ratio": round(self.hits / self.predicted_total, 4)
+            if self.predicted_total else 0.0,
+        }

cortexm/features/zk.py

@@ -0,0 +1,105 @@
+"""Zero-Knowledge Memory Proofs (ZK-lite).
+
+Proves a retrieved fact satisfies a query WITHOUT revealing its content
+to the LLM: a Merkle membership proof over the tamper-evident leaf set
+(blake3 source hashes) plus an HMAC attestation binding
+{statement, root, timestamp}. The LLM receives only
+``[ZK-Proof: match on <relation> verified. Content redacted.]``.
+
+Honest scope: this is a commit-and-prove membership attestation — full
+ZK-SNARKs over the similarity predicate are on the roadmap (the binary
+codec's Hamming-distance similarity is a natural circuit candidate;
+HRR circular convolution is a group operation, the algebraic
+requirement standard cosine similarity cannot satisfy).
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+
+from cortexm.errors import VerificationError
+from cortexm.security.hashes import (HashProvider, attest, merkle_proof,
+                                       merkle_verify, verify_attest)
+
+
+class ZKProver:
+    def __init__(self, store, reader, provider: HashProvider | None = None) -> None:
+        self.store = store
+        self.reader = reader
+        self.hasher = provider or store.hasher
+        key = self.store.kv_get("ZK_KEY")
+        if not key:
+            key = secrets.token_hex(32)
+            self.store.kv_set("ZK_KEY", key)
+        self._key = bytes.fromhex(key)
+        self._leaf_cache: tuple[str, list[str]] = ("", [])
+
+    # ------------------------------------------------------------------
+    def _leaves(self) -> list[str]:
+        head = self.store.head() or ""
+        if self._leaf_cache[0] != head or not self._leaf_cache[1]:
+            hashes = self.store.active_fact_hashes()
+            leaves = [f"{fid}:{h}" for fid, h in hashes]
+            # leaf hash -> hex digest for merkle
+            leaves = [self.hasher.hash_text(l) for l in leaves]
+            self._leaf_cache = (head, leaves)
+        return self._leaf_cache[1]
+
+    # ------------------------------------------------------------------
+    def prove(self, query: str, *, user_id: str = "default",
+              threshold: float = 0.2) -> dict:
+        """Retrieve top match and produce a content-free proof."""
+        result = self.reader.search(query, user_id=user_id, k=1)
+        if not result.facts:
+            raise VerificationError("no matching fact to prove")
+        f = result.facts[0]
+        leaves = self._leaves()
+        idx = None
+        want = self.hasher.hash_text(f"{f.id}:{f.source_hash}")
+        for i, leaf in enumerate(leaves):
+            if leaf == want:
+                idx = i
+                break
+        if idx is None:
+            raise VerificationError("fact not in active leaf set")
+        root, path = merkle_proof(self.hasher, leaves, idx)
+        score = result.scores.get(f.id, 0.0)
+        if score < threshold:
+            raise VerificationError(
+                f"similarity {score:.3f} below threshold {threshold}")
+        statement = (f"EXISTS fact f in Trace: sim(query, f) >= {threshold} "
+                     f"AND blake3(source(f)) = {f.source_hash[:16]}... "
+                     f"(content redacted)")
+        ts = time.time()
+        tag = attest(self.hasher, self._key, f"{statement}|{root}|{ts}")
+        return {
+            "statement": statement,
+            "fact_commitment": f.source_hash,       # content-free commitment
+            "leaf_commitment": want,                # merkle leaf hash
+            "relation": f.relation,                  # safe to disclose
+            "sim_score": round(score, 4),
+            "merkle_root": root,
+            "merkle_path": path,
+            "timestamp": ts,
+            "attestation": tag,
+            "llm_view": f"[ZK-Proof: high-confidence match on '{f.relation}' "
+                        f"verified (score {score:.2f}). Content redacted.]",
+        }
+
+    # ------------------------------------------------------------------
+    def verify(self, proof: dict) -> bool:
+        """Verify membership + attestation. Returns True if sound."""
+        if not verify_attest(self.hasher, self._key,
+                             f"{proof['statement']}|{proof['merkle_root']}|"
+                             f"{proof['timestamp']}",
+                             proof["attestation"]):
+            return False
+        leaf = proof.get("leaf_commitment") or proof["fact_commitment"]
+        return merkle_verify(self.hasher, leaf,
+                             proof["merkle_path"], proof["merkle_root"])
+
+    def verify_membership(self, leaf_hex: str, proof: dict) -> bool:
+        """Full membership verification for a known leaf commitment."""
+        return merkle_verify(self.hasher, leaf_hex, proof["merkle_path"],
+                             proof["merkle_root"])