superlocalmemory 4.0.3 → 4.0.4

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.
 ]
 

package/src/superlocalmemory/storage/migrations/M041_external_evidence_receipts.py

@@ -0,0 +1,189 @@
+"""M041 — typed, observation-only external evidence in ``learning.db``."""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M041_external_evidence_receipts"
+DB_TARGET = "learning"
+
+DDL = """
+BEGIN IMMEDIATE;
+CREATE TABLE IF NOT EXISTS external_evidence_receipts (
+    profile_id TEXT NOT NULL,
+    contract_id TEXT NOT NULL,
+    workspace_id TEXT NOT NULL,
+    run_ref TEXT NOT NULL,
+    run_id TEXT NOT NULL,
+    outcome TEXT NOT NULL,
+    run_state TEXT NOT NULL,
+    demonstration INTEGER NOT NULL CHECK (demonstration IN (0, 1)),
+    eligible_for_learning INTEGER NOT NULL CHECK (eligible_for_learning IN (0, 1)),
+    terminal_at TEXT NOT NULL,
+    graph_digest TEXT NOT NULL,
+    plan_digest TEXT NOT NULL,
+    policy_digest TEXT NOT NULL,
+    receipt_sequence INTEGER NOT NULL,
+    receipt_head_digest TEXT NOT NULL,
+    receipt_trust TEXT NOT NULL,
+    nodes_json TEXT NOT NULL,
+    artifact_digests_json TEXT NOT NULL,
+    payload_sha256 TEXT NOT NULL,
+    observed_at TEXT NOT NULL,
+    PRIMARY KEY (profile_id, contract_id, workspace_id, run_ref)
+);
+CREATE INDEX IF NOT EXISTS idx_external_evidence_profile_terminal
+    ON external_evidence_receipts (profile_id, terminal_at DESC);
+CREATE INDEX IF NOT EXISTS idx_external_evidence_profile_workspace
+    ON external_evidence_receipts (profile_id, workspace_id, terminal_at DESC);
+COMMIT;
+"""
+
+_TABLE = "external_evidence_receipts"
+_COLUMNS = (
+    "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",
+)
+_TYPES = (
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "INTEGER",
+    "INTEGER",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "INTEGER",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+    "TEXT",
+)
+_PRIMARY_KEY = ("profile_id", "contract_id", "workspace_id", "run_ref")
+_INDEXES = {
+    "idx_external_evidence_profile_terminal": (
+        "external_evidence_receipts", (("profile_id", False), ("terminal_at", True)),
+    ),
+    "idx_external_evidence_profile_workspace": (
+        "external_evidence_receipts",
+        (("profile_id", False), ("workspace_id", False), ("terminal_at", True)),
+    ),
+}
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Install the additive receipt table atomically and idempotently."""
+    if _table_exists(conn) and not _table_is_valid(conn):
+        raise sqlite3.OperationalError(
+            "M041 external evidence table is malformed; refusing rebuild"
+        )
+    conn.executescript(DDL)
+    if not verify(conn):
+        repair(conn)
+    if not verify(conn):
+        raise sqlite3.OperationalError("M041 external evidence schema did not reach its end-state")
+
+
+def repair(conn: sqlite3.Connection) -> None:
+    """Restore only M041's derived indexes without touching stored evidence."""
+    if _table_exists(conn) and not _table_is_valid(conn):
+        raise sqlite3.OperationalError(
+            "M041 external evidence table is malformed; refusing rebuild"
+        )
+    if not _table_exists(conn):
+        apply(conn)
+        return
+    drops = "\n".join(f"DROP INDEX IF EXISTS {name};" for name in _INDEXES)
+    creates = "\n".join(
+        f"CREATE INDEX {name} ON {table} ({_index_sql_columns(columns)});"
+        for name, (table, columns) in _INDEXES.items()
+    )
+    conn.executescript(f"BEGIN IMMEDIATE;\n{drops}\n{creates}\nCOMMIT;")
+    if not verify(conn):
+        raise sqlite3.OperationalError("M041 index repair did not restore required end-state")
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    if not _table_is_valid(conn):
+        return False
+    for name, (table, columns) in _INDEXES.items():
+        row = conn.execute(
+            "SELECT tbl_name FROM sqlite_master WHERE type='index' AND name=?", (name,)
+        ).fetchone()
+        if row is None or row[0] != table:
+            return False
+        actual = tuple(
+            (item[2], bool(item[3]))
+            for item in conn.execute(f"PRAGMA index_xinfo({name})")
+            if item[5] and item[2] is not None
+        )
+        if actual != columns:
+            return False
+    return True
+
+
+def _table_exists(conn: sqlite3.Connection) -> bool:
+    return (
+        conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (_TABLE,)
+        ).fetchone()
+        is not None
+    )
+
+
+def _table_is_valid(conn: sqlite3.Connection) -> bool:
+    if not _table_exists(conn):
+        return False
+    info = conn.execute(f"PRAGMA table_info({_TABLE})").fetchall()
+    columns = tuple(row[1] for row in info)
+    types = tuple(str(row[2]).upper() for row in info)
+    primary_key = tuple(row[1] for row in sorted(info, key=lambda row: row[5]) if row[5])
+    not_null = {row[1] for row in info if row[3] or row[5]}
+    return (
+        columns == _COLUMNS
+        and types == _TYPES
+        and primary_key == _PRIMARY_KEY
+        and not_null == set(_COLUMNS)
+        and conn.execute(f"PRAGMA foreign_key_list({_TABLE})").fetchone() is None
+        and _required_checks_present(conn)
+    )
+
+
+def _required_checks_present(conn: sqlite3.Connection) -> bool:
+    row = conn.execute(
+        "SELECT sql FROM sqlite_master WHERE type='table' AND name=?", (_TABLE,)
+    ).fetchone()
+    sql = "" if row is None or row[0] is None else "".join(str(row[0]).lower().split())
+    return (
+        "check(demonstrationin(0,1))" in sql
+        and "check(eligible_for_learningin(0,1))" in sql
+    )
+
+
+def _index_sql_columns(columns: tuple[tuple[str, bool], ...]) -> str:
+    return ", ".join(column + (" DESC" if desc else "") for column, desc in columns)

package/src/superlocalmemory/storage/migrations/__init__.py

@@ -31,6 +31,7 @@ from . import (
     M038_learning_feedback_channel,
     M039_scene_fact_members,
     M040_agent_experience_receipts,
+    M041_external_evidence_receipts,
 )
 
 # ---------------------------------------------------------------------------
@@ -87,6 +88,7 @@ __all__ = (
     "M038_learning_feedback_channel",
     "M039_scene_fact_members",
     "M040_agent_experience_receipts",
+    "M041_external_evidence_receipts",
     # Legacy re-exports (backward compat):
     "CURRENT_SCHEMA_VERSION",
     "get_schema_version",

package/src/superlocalmemory/ui/js/od-brain.js

@@ -230,6 +230,7 @@
     var feedback = (living && living.feedback) || {};
     var graph = (living && living.graph) || {};
     var experience = (living && living.agent_experience) || {};
+    var externalEvidence = experience.external_graph_evidence || {};
 
     // KPI strip
     var strip = EL('div', { className: 'kpi-strip', style: 'margin-bottom:16px' });
@@ -318,6 +319,8 @@
       ['Claimed evidence authority', String(experience.claimed_evidence_experiences || 0)],
       ['Cognitive turns', String(experience.turns_total || 0) +
         ' · ' + String((experience.turns_by_state || {}).finalized || 0) + ' finalized'],
+      ['Bounded Loop observations', String(externalEvidence.total || 0) +
+        (externalEvidence.is_real ? ' terminal receipts' : ' unavailable')],
       ['Graph evidence', String(graph.fact_nodes || 0) + ' nodes · ' +
         String(graph.association_edges || 0) + ' edges'],
     ].forEach(function (row) {
@@ -362,6 +365,12 @@
       fmtNum((experience.turns_by_state || {}).open || 0) + ' open · ' +
         fmtNum((experience.turns_by_state || {}).finalized || 0) + ' finalized',
       Number(experience.turns_total || 0) > 0, undefined, true));
+    evGrid.appendChild(kpiCard('account_tree', 'Bounded Loop observations',
+      fmtNum(externalEvidence.total || 0),
+      externalEvidence.is_real
+        ? fmtNum(externalEvidence.demonstrations || 0) + ' demonstrations · no automatic learning'
+        : 'connect Bounded Loops to observe terminal runs',
+      Number(externalEvidence.total || 0) > 0, undefined, true));
     evb.appendChild(evGrid);
     evc.appendChild(evb);
     sec.appendChild(evc);