superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/storage/erasure_fence.py

@@ -1,45 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-from __future__ import annotations
-
-import threading
-import time
-
-_TTL_SECONDS = 300.0
-
-_lock = threading.RLock()
-_marks: dict[tuple[str, str], float] = {}
-
-
-def mark_erasing(profile_id: str, fact_id: str) -> None:
-    now = time.time()
-    with _lock:
-        _marks[(profile_id, fact_id)] = now
-        _prune(now)
-
-
-def clear_erasing(profile_id: str, fact_id: str) -> None:
-    with _lock:
-        _marks.pop((profile_id, fact_id), None)
-
-
-def is_erasing(profile_id: str, fact_id: str) -> bool:
-    now = time.time()
-    with _lock:
-        ts = _marks.get((profile_id, fact_id))
-        if ts is None:
-            return False
-        if now - ts > _TTL_SECONDS:
-            _marks.pop((profile_id, fact_id), None)
-            return False
-        return True
-
-
-def _prune(now: float) -> None:
-    expired = [key for key, ts in _marks.items() if now - ts > _TTL_SECONDS]
-    for key in expired:
-        _marks.pop(key, None)
-
-
-__all__ = ["mark_erasing", "clear_erasing", "is_erasing"]

package/src/superlocalmemory/storage/execution_learning.py

@@ -1,285 +0,0 @@
-"""Bridge-v2 immutable receipt storage and strictly bounded execution learning.
-
-This module deliberately has no dependency on recall, semantic facts, or user
-preferences.  Bounded Loops receipts can only update the rebuildable execution
-event projection after the consumer validates every eligibility condition.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import re
-import sqlite3
-from copy import deepcopy
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any, Callable
-
-from superlocalmemory.storage.agent_experience import (
-    _ProfileAdmissionGate,
-    _PROCESS_LOCKS_GUARD,
-    _PROFILE_GATES,
-    ProfileAdmissionError,
-)
-
-_CONTRACT = "bounded-loops.dev/slm-bridge/v2"
-_SHA256_PREFIX = "sha256:"
-_ALLOWED_STATES = frozenset({"SUCCEEDED", "FAILED"})
-_MAX_PAYLOAD_BYTES = 32 * 1024
-_MAX_NODES = 256
-_MAX_ARTIFACTS_PER_NODE = 64
-_SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
-_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
-
-
-class ExecutionLearningValidationError(ValueError):
-    """A v2 receipt is not eligible for execution-learning ingestion."""
-
-
-# This is deliberately an in-process capability, not a serializable field in
-# the producer payload.  An MCP producer can send JSON; it cannot mint this
-# boundary witness.  It prevents an accidental future caller from turning a
-# schema-valid JSON document directly into learned execution behaviour.
-_BRIDGE_SEAL = object()
-
-
-@dataclass(frozen=True)
-class VerifiedExecutionEvidence:
-    """A v2 payload bound to one negotiated, locally observed producer session.
-
-    ``payload`` intentionally remains available for the immutable receipt
-    record.  The private seal is checked by :class:`ExecutionLearningStore`
-    and never crosses MCP or disk boundaries.
-    """
-
-    payload: dict[str, Any]
-    producer_identity: str
-    capability_digest: str
-    terminal_listing_digest: str
-    payload_sha256: str
-    _seal: object
-
-
-def _seal_verified_execution_evidence(
-    payload: dict[str, Any],
-    *,
-    producer_identity: str,
-    capability_digest: str,
-    terminal_listing_digest: str,
-) -> VerifiedExecutionEvidence:
-    """Create the sole accepted execution-learning input at the MCP boundary."""
-    _validate(payload)
-    for label, value in {
-        "producer identity": producer_identity,
-        "capability digest": capability_digest,
-        "terminal listing digest": terminal_listing_digest,
-    }.items():
-        if not isinstance(value, str) or not value:
-            raise ExecutionLearningValidationError(f"v2 receipt has no verified {label}")
-    sealed_payload = deepcopy(payload)
-    return VerifiedExecutionEvidence(
-        payload=sealed_payload,
-        producer_identity=producer_identity,
-        capability_digest=capability_digest,
-        terminal_listing_digest=terminal_listing_digest,
-        payload_sha256=_digest(sealed_payload),
-        _seal=_BRIDGE_SEAL,
-    )
-
-
-class ExecutionLearningStore:
-    """Atomically persist v2 receipts before their derived event projection."""
-
-    def __init__(self, path: str | Path, *, is_profile_active: Callable[[str], bool]) -> None:
-        self._path = Path(path).resolve()
-        self._is_profile_active = is_profile_active
-        with _PROCESS_LOCKS_GUARD:
-            self._gate = _PROFILE_GATES.setdefault(str(self._path), _ProfileAdmissionGate())
-
-    def ingest(self, evidence: VerifiedExecutionEvidence) -> bool:
-        if (
-            not isinstance(evidence, VerifiedExecutionEvidence)
-            or evidence._seal is not _BRIDGE_SEAL
-        ):
-            raise ExecutionLearningValidationError(
-                "v2 execution learning requires verified bridge provenance"
-            )
-        payload = evidence.payload
-        if evidence.payload_sha256 != _digest(payload):
-            raise ExecutionLearningValidationError(
-                "v2 execution-learning provenance was modified after verification"
-            )
-        _validate(payload)
-        profile_id = payload["profile_id"]
-        self._gate.admit(profile_id, self._is_profile_active)
-        digest = _digest(payload)
-        receipt = payload["receipt"]
-        route_key = _route_key(payload["route"])
-        signal = 1 if payload["run_state"] == "SUCCEEDED" else -1
-        now = datetime.now(timezone.utc).isoformat()
-        conn: sqlite3.Connection | None = None
-        try:
-            conn = sqlite3.connect(str(self._path), timeout=1.0, isolation_level=None)
-            conn.execute("BEGIN IMMEDIATE")
-            # The same process-wide admission gate drains in-flight writes
-            # before erasure. This durable closure check also prevents a late
-            # transaction from resurrecting a profile after a completed close.
-            closed = conn.execute(
-                "SELECT 1 FROM agent_receipt_profile_closures WHERE profile_id=?", (profile_id,)
-            ).fetchone()
-            if closed is not None:
-                raise ProfileAdmissionError("profile is inactive or closing for erasure")
-            existing = conn.execute(
-                "SELECT payload_sha256 FROM execution_learning_receipts "
-                "WHERE profile_id=? AND workspace_id=? AND run_ref=?",
-                (profile_id, payload["workspace_id"], payload["run_ref"]),
-            ).fetchone()
-            if existing is not None:
-                if existing[0] != digest:
-                    raise ExecutionLearningValidationError(
-                        "external run address has a different receipt head"
-                    )
-                conn.execute("ROLLBACK")
-                return False
-            conn.execute(
-                "INSERT INTO execution_learning_receipts "
-                "(profile_id, workspace_id, run_ref, run_id, receipt_head_digest, "
-                "payload_json, payload_sha256, producer_identity, capability_digest, "
-                "terminal_listing_digest, observed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-                (profile_id, payload["workspace_id"], payload["run_ref"], payload["run_id"],
-                 receipt["head_digest"], _json(payload), digest, evidence.producer_identity,
-                 evidence.capability_digest, evidence.terminal_listing_digest, now),
-            )
-            conn.execute(
-                "INSERT INTO execution_learning_events "
-                "(profile_id, workspace_id, run_ref, receipt_head_digest, route_key, signal, created_at) "
-                "VALUES (?, ?, ?, ?, ?, ?, ?)",
-                (profile_id, payload["workspace_id"], payload["run_ref"],
-                 receipt["head_digest"], route_key, signal, now),
-            )
-            conn.execute("COMMIT")
-            return True
-        except Exception:
-            if conn is not None and conn.in_transaction:
-                conn.execute("ROLLBACK")
-            raise
-        finally:
-            if conn is not None:
-                conn.close()
-            self._gate.release(profile_id)
-
-    def status(self, profile_id: str) -> dict[str, int]:
-        conn = sqlite3.connect(str(self._path), timeout=0.5)
-        try:
-            receipts = conn.execute(
-                "SELECT COUNT(*) FROM execution_learning_receipts WHERE profile_id=?", (profile_id,)
-            ).fetchone()[0]
-            totals = conn.execute(
-                "SELECT COUNT(*), COALESCE(SUM(signal = 1), 0), COALESCE(SUM(signal = -1), 0) "
-                "FROM execution_learning_events WHERE profile_id=?", (profile_id,),
-            ).fetchone()
-            return {"receipts_total": int(receipts), "learning_events_total": int(totals[0]),
-                    "positive_events": int(totals[1]), "negative_events": int(totals[2])}
-        finally:
-            conn.close()
-
-
-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",
-                "learning_authority", "route", "usage"}
-    if set(payload) != required or payload.get("contract") != _CONTRACT:
-        raise ExecutionLearningValidationError("v2 receipt does not match the bounded contract")
-    if len(_json(payload).encode("utf-8")) > _MAX_PAYLOAD_BYTES:
-        raise ExecutionLearningValidationError("v2 receipt exceeds the bounded payload size")
-    for field in ("profile_id", "workspace_id", "run_ref", "run_id"):
-        if not isinstance(payload[field], str) or not _SAFE_ID.fullmatch(payload[field]):
-            raise ExecutionLearningValidationError(f"v2 receipt has an invalid {field}")
-    for field in ("workspace_id", "graph_digest", "plan_digest", "policy_digest"):
-        if not isinstance(payload[field], str) or not _DIGEST.fullmatch(payload[field]):
-            raise ExecutionLearningValidationError(f"v2 receipt has an invalid {field}")
-    if not isinstance(payload["terminal_at"], str) or len(payload["terminal_at"]) > 64:
-        raise ExecutionLearningValidationError("v2 receipt has an invalid terminal timestamp")
-    if payload["demonstration"] is not False or payload["eligible_for_learning"] is not True:
-        raise ExecutionLearningValidationError("receipt is not eligible for execution learning")
-    if payload["run_state"] not in _ALLOWED_STATES or payload["outcome"] != payload["run_state"]:
-        raise ExecutionLearningValidationError("only terminal succeeded or executed-gate failure is learnable")
-    receipt, authority = payload["receipt"], payload["learning_authority"]
-    if not isinstance(receipt, dict) or not isinstance(authority, dict):
-        raise ExecutionLearningValidationError("receipt authority is malformed")
-    if set(receipt) != {"sequence", "head_digest", "trust"}:
-        raise ExecutionLearningValidationError("receipt chain metadata is malformed")
-    if (
-        isinstance(receipt["sequence"], bool)
-        or not isinstance(receipt["sequence"], int)
-        or receipt["sequence"] < 1
-        or receipt["trust"] != "local_hash_chain_only"
-        or not isinstance(receipt.get("head_digest"), str)
-        or not _DIGEST.fullmatch(receipt["head_digest"])
-    ):
-        raise ExecutionLearningValidationError("receipt chain head is invalid")
-    if authority != {"scope": "execution_reliability_only", "reason_code": "verified_terminal_receipt",
-                     "verification_state": "reconciled", "gate_authority": "deterministic_gate",
-                     "trust_class": "local_hash_chain_only"}:
-        raise ExecutionLearningValidationError("receipt lacks bounded deterministic learning authority")
-    _validate_nodes(payload["nodes"])
-    _validate_route(payload["route"])
-    _validate_usage(payload["usage"])
-
-
-def _validate_nodes(nodes: Any) -> None:
-    if not isinstance(nodes, list) or not nodes or len(nodes) > _MAX_NODES:
-        raise ExecutionLearningValidationError("receipt nodes are malformed")
-    for node in nodes:
-        if not isinstance(node, dict) or set(node) != {
-            "node_id", "state", "gate_passed", "attempts", "artifact_digests"
-        }:
-            raise ExecutionLearningValidationError("receipt node schema is malformed")
-        if (
-            not isinstance(node["node_id"], str)
-            or not _SAFE_ID.fullmatch(node["node_id"])
-            or not isinstance(node["state"], str)
-            or not _SAFE_ID.fullmatch(node["state"])
-            or node["gate_passed"] not in (True, False, None)
-            or isinstance(node["attempts"], bool)
-            or not isinstance(node["attempts"], int)
-            or not 0 <= node["attempts"] <= 10_000
-            or not isinstance(node["artifact_digests"], list)
-            or len(node["artifact_digests"]) > _MAX_ARTIFACTS_PER_NODE
-            or not all(isinstance(item, str) and _DIGEST.fullmatch(item)
-                       for item in node["artifact_digests"])
-        ):
-            raise ExecutionLearningValidationError("receipt node values are malformed")
-
-
-def _validate_route(route: Any) -> None:
-    if not isinstance(route, dict) or set(route) - {"runner", "provider", "model", "effort"}:
-        raise ExecutionLearningValidationError("route or usage is malformed")
-    if not all(isinstance(value, str) and _SAFE_ID.fullmatch(value) for value in route.values()):
-        raise ExecutionLearningValidationError("route or usage is malformed")
-
-
-def _validate_usage(usage: Any) -> None:
-    if (
-        not isinstance(usage, dict)
-        or set(usage) != {"attempts"}
-        or isinstance(usage["attempts"], bool)
-        or not isinstance(usage["attempts"], int)
-        or not 0 <= usage["attempts"] <= 1_000_000
-    ):
-        raise ExecutionLearningValidationError("route or usage is malformed")
-
-
-def _route_key(route: dict[str, Any]) -> str:
-    return "|".join(str(route.get(key, "")) for key in ("runner", "provider", "model", "effort"))
-
-
-def _json(value: Any) -> str:
-    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
-
-
-def _digest(value: dict[str, Any]) -> str:
-    return hashlib.sha256(_json(value).encode("utf-8")).hexdigest()

package/src/superlocalmemory/storage/external_evidence.py

@@ -1,359 +0,0 @@
-"""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)