superlocalmemory 3.7.8 → 3.8.1

package/src/superlocalmemory/loops/__init__.py

@@ -0,0 +1,56 @@
+"""SuperLocalMemory bounded loops.
+
+Agent loops that stop when an independent gate passes — not when the agent
+says it is done — with the run's history persisted in SLM's durable memory.
+
+Public API::
+
+    from superlocalmemory.loops import (
+        Bounds, Rung, Status, Verdict, LapResult, Outcome,
+        run_bounded_loop, InMemoryLedger, SLMMemoryLedger, open_engine_store,
+    )
+"""
+
+from __future__ import annotations
+
+from superlocalmemory.loops.engine import run_bounded_loop
+from superlocalmemory.loops.ledger import (
+    InMemoryLedger,
+    LedgerEntry,
+    LedgerStore,
+    SLMMemoryLedger,
+    engine_backed_ledger,
+    open_engine_store,
+)
+from superlocalmemory.loops.models import (
+    Bounds,
+    LapResult,
+    Outcome,
+    Rung,
+    Status,
+    Verdict,
+)
+from superlocalmemory.loops.rules import (
+    no_progress,
+    rung_requires_approval,
+    stop_condition_met,
+)
+
+__all__ = [
+    "Bounds",
+    "Rung",
+    "Status",
+    "Verdict",
+    "LapResult",
+    "Outcome",
+    "run_bounded_loop",
+    "LedgerEntry",
+    "LedgerStore",
+    "InMemoryLedger",
+    "SLMMemoryLedger",
+    "engine_backed_ledger",
+    "open_engine_store",
+    "no_progress",
+    "rung_requires_approval",
+    "stop_condition_met",
+]

package/src/superlocalmemory/loops/budget.py

@@ -0,0 +1,58 @@
+"""Cumulative budget accounting for a bounded-loop run.
+
+The meter tracks laps, tokens, and wall-clock time and reports when any bound
+in effect has been exceeded. It is intentionally tiny and side-effect-free
+apart from its own internal counters, and the clock is injected so tests are
+deterministic.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from superlocalmemory.loops.models import Bounds
+
+
+class BudgetMeter:
+    """Accumulate spend across laps and answer "have we gone over?".
+
+    ``now`` is a zero-argument callable returning monotonic-ish seconds
+    (``time.monotonic`` in production, a fake in tests). The start time is
+    captured at construction so wall-clock enforcement needs no globals.
+    """
+
+    def __init__(self, now: Callable[[], float]) -> None:
+        self._now = now
+        self._start = now()
+        self._tokens = 0
+
+    def spend(self, tokens: int) -> None:
+        """Record token spend for a completed lap (negative values ignored)."""
+        if tokens > 0:
+            self._tokens += tokens
+
+    def exceeded(self, lap: int, bounds: Bounds) -> tuple[bool, str]:
+        """Return ``(tripped, reason)`` for the bounds checked before a lap runs.
+
+        Checked in priority order: iteration cap, token budget, wall-clock.
+        ``lap`` is the 1-based number of the lap about to run, so exceeding
+        ``max_iterations`` is reported when the (max+1)-th lap is attempted.
+        """
+        if lap > bounds.max_iterations:
+            return True, "max-iterations"
+        # >= so a budget of N never permits an (N+1)-th lap's worth of spend:
+        # once cumulative tokens reach the ceiling, the next lap is refused.
+        if bounds.max_tokens is not None and self._tokens >= bounds.max_tokens:
+            return True, "token-budget"
+        if bounds.max_wallclock_s is not None:
+            elapsed = self._now() - self._start
+            if elapsed > bounds.max_wallclock_s:
+                return True, "wallclock"
+        return False, ""
+
+    def snapshot(self) -> dict:
+        """Point-in-time spend, suitable for a ledger entry."""
+        return {
+            "tokens": self._tokens,
+            "wallclock_s": round(self._now() - self._start, 3),
+        }

package/src/superlocalmemory/loops/engine.py

@@ -0,0 +1,164 @@
+"""The bounded-loop orchestrator.
+
+``run_bounded_loop`` executes a loop for a single goal under a fixed set of
+:class:`Bounds`. Its one non-negotiable invariant: **the independent gate
+decides when the loop is finished — never the agent.** A runner's
+``agent_claimed_done`` flag is written to the ledger for audit and is never
+read when deciding to terminate.
+
+Each lap, in strict order:
+
+1. Poll the kill switch (highest priority — checked before any work).
+2. Check the budget bounds (iteration cap, tokens, wall-clock).
+3. Run the agent's proposer for one lap.
+4. Accumulate token spend.
+5. Ask the *independent* gate for a verdict.
+6. Decide: a passing gate (plus any required approval) ends the run; an
+   exhausted no-progress window halts it; otherwise continue.
+
+Runner and gate are plain callables taking the 1-based lap number, so this
+engine carries no subprocess, sandbox, or framework machinery — SLM loops
+converge on a checkable memory/verification condition, and heavier isolation
+belongs to the standalone bounded-loops engine, not here.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Callable, Optional
+
+from superlocalmemory.loops.budget import BudgetMeter
+from superlocalmemory.loops.ledger import InMemoryLedger, LedgerEntry, LedgerStore
+from superlocalmemory.loops.models import (
+    Bounds,
+    LapResult,
+    Outcome,
+    Rung,
+    Status,
+    Verdict,
+)
+from superlocalmemory.loops.rules import (
+    no_progress,
+    rung_requires_approval,
+    stop_condition_met,
+)
+
+RunnerFn = Callable[[int], LapResult]
+GateFn = Callable[[int], Verdict]
+ApproverFn = Callable[[Verdict], bool]
+KillSwitchFn = Callable[[], bool]
+ClockFn = Callable[[], str]
+
+_KILL_ENV = "SLM_LOOP_KILL"
+
+
+def _utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _env_killed() -> bool:
+    return bool(os.environ.get(_KILL_ENV))
+
+
+def run_bounded_loop(
+    name: str,
+    *,
+    bounds: Bounds,
+    runner: RunnerFn,
+    gate: GateFn,
+    rung: Rung = Rung.L1,
+    ledger: Optional[LedgerStore] = None,
+    approver: Optional[ApproverFn] = None,
+    killswitch: Optional[KillSwitchFn] = None,
+    clock: Optional[ClockFn] = None,
+    monotonic: Optional[Callable[[], float]] = None,
+    run_id: Optional[str] = None,
+) -> Outcome:
+    """Run one bounded loop and return its :class:`Outcome`.
+
+    Only ``name``, ``bounds``, ``runner`` and ``gate`` are required. Every
+    other dependency is injected for determinism in tests; sensible defaults
+    (UTC clock, monotonic timer, env-var kill switch, in-memory ledger) apply
+    otherwise.
+    """
+    run_id = run_id or f"{name}-{uuid.uuid4().hex[:8]}"
+    ledger = ledger if ledger is not None else InMemoryLedger()
+    clock = clock or _utc_now_iso
+    monotonic = monotonic or time.monotonic
+    killswitch = killswitch or _env_killed
+    budget = BudgetMeter(monotonic)
+
+    lap_changes: list[bool] = []
+    lap = 0
+
+    def emit(decision: str, verdict: Verdict, result: LapResult | None = None) -> None:
+        ledger.record(
+            LedgerEntry(
+                run_id=run_id,
+                name=name,
+                lap=lap,
+                ts=clock(),
+                decision=decision,
+                passed=verdict.passed,
+                detail=verdict.detail,
+                # The agent's own claim is recorded for audit only — never used
+                # to terminate (see the loop invariant). Log is capped so a
+                # verbose runner can't bloat the ledger row.
+                agent_claimed_done=bool(result.agent_claimed_done) if result else False,
+                runner_log=(result.log or "")[:2000] if result else "",
+                budget=budget.snapshot(),
+            )
+        )
+
+    while True:
+        lap += 1
+
+        # 1. Kill switch — before any work (so laps reports completed laps).
+        if killswitch():
+            emit("killed", Verdict(False, "kill switch tripped"))
+            return Outcome(Status.KILLED, "killed", lap - 1, run_id)
+
+        # 2. Budget bounds — before running the agent.
+        tripped, why = budget.exceeded(lap, bounds)
+        if tripped:
+            emit("halt", Verdict(False, why))
+            return Outcome(Status.HALT, why, lap - 1, run_id)
+
+        # 3. Run the proposer for one lap.
+        try:
+            result = runner(lap)
+        except Exception as exc:  # runner failure is a terminal ERROR
+            detail = f"runner error: {type(exc).__name__}: {exc}"
+            emit("error", Verdict(False, detail))
+            return Outcome(Status.ERROR, detail, lap, run_id)
+
+        # 4. Accumulate spend.
+        budget.spend(result.tokens)
+        lap_changes.append(result.changed)
+
+        # 5. Independent gate — agent's own claim is never consulted here.
+        try:
+            verdict = gate(lap)
+        except Exception as exc:
+            detail = f"gate error: {type(exc).__name__}: {exc}"
+            emit("error", Verdict(False, detail), result)
+            return Outcome(Status.ERROR, detail, lap, run_id)
+
+        # 6. Decide.
+        if stop_condition_met(verdict):
+            if rung_requires_approval(rung, bounds):
+                granted = bool(approver(verdict)) if approver is not None else False
+                if not granted:
+                    emit("pause", verdict, result)
+                    return Outcome(Status.PAUSE, "awaiting-approval", lap, run_id)
+            emit("done", verdict, result)
+            return Outcome(Status.DONE, "gate-passed", lap, run_id)
+
+        if no_progress(lap_changes, bounds.no_progress_window):
+            emit("halt", Verdict(False, "no-progress"), result)
+            return Outcome(Status.HALT, "no-progress", lap, run_id)
+
+        emit("continue", verdict, result)

package/src/superlocalmemory/loops/ledger.py

@@ -0,0 +1,263 @@
+"""Durable, queryable ledger for bounded-loop runs.
+
+Every lap produces one append-only :class:`LedgerEntry`. A ledger persists
+those entries so a run can be inspected, resumed, and audited after the fact.
+
+Two implementations ship:
+
+* :class:`InMemoryLedger` — a dict-backed store used by tests and as a safe
+  fallback when no SLM data root is available.
+* :class:`SLMMemoryLedger` — the real backend. It writes each lap through a
+  SuperLocalMemory engine so the ledger *is* memory: queryable via ``slm
+  recall``, visible in the dashboard, and resumable across sessions. This is
+  what makes SLM's take on bounded loops distinct — the loop's history lives
+  in the same durable store as everything else the agent remembers.
+
+The engine-backed store mirrors the exact profile-scoped SQL contract the
+shipped framework adapters already rely on, so it stays valid as the engine
+evolves.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+LEDGER_TAG = "slm-loop"
+_LEDGER_IMPORTANCE = 2  # below ordinary user memories so laps never crowd recall
+_SESSION_PREFIX = "loop:"
+
+
+@dataclass(frozen=True)
+class LedgerEntry:
+    """One immutable row recording what happened on a single lap."""
+
+    run_id: str
+    name: str
+    lap: int
+    ts: str
+    decision: str  # continue | done | halt | pause | killed | error
+    passed: bool
+    detail: str
+    # The runner's own claim (audit-only; never terminates the loop) + its log.
+    agent_claimed_done: bool = False
+    runner_log: str = ""
+    budget: dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, text: str) -> "LedgerEntry | None":
+        try:
+            data = json.loads(text)
+        except (TypeError, json.JSONDecodeError):
+            return None
+        if not isinstance(data, dict) or "run_id" not in data or "lap" not in data:
+            return None
+        return cls(
+            run_id=str(data.get("run_id", "")),
+            name=str(data.get("name", "")),
+            lap=int(data.get("lap", 0)),
+            ts=str(data.get("ts", "")),
+            decision=str(data.get("decision", "")),
+            passed=bool(data.get("passed", False)),
+            detail=str(data.get("detail", "")),
+            agent_claimed_done=bool(data.get("agent_claimed_done", False)),
+            runner_log=str(data.get("runner_log", "")),
+            budget=data.get("budget") if isinstance(data.get("budget"), dict) else {},
+        )
+
+
+@runtime_checkable
+class LedgerStore(Protocol):
+    """Append-only audit trail keyed by run."""
+
+    def record(self, entry: LedgerEntry) -> None: ...
+    def laps(self, run_id: str) -> list[LedgerEntry]: ...
+    def runs(self, name: str) -> list[str]: ...
+
+
+class InMemoryLedger:
+    """Process-local ledger. Never raises; ideal for tests and offline demos."""
+
+    def __init__(self) -> None:
+        self._by_run: dict[str, list[LedgerEntry]] = {}
+
+    def record(self, entry: LedgerEntry) -> None:
+        self._by_run.setdefault(entry.run_id, []).append(entry)
+
+    def laps(self, run_id: str) -> list[LedgerEntry]:
+        return list(self._by_run.get(run_id, ()))
+
+    def runs(self, name: str) -> list[str]:
+        seen: list[str] = []
+        for run_id, entries in self._by_run.items():
+            if entries and entries[0].name == name and run_id not in seen:
+                seen.append(run_id)
+        return seen
+
+
+class SLMMemoryLedger:
+    """Ledger backed by a SuperLocalMemory engine store.
+
+    ``store`` is any object exposing ``add(content, *, session_id, metadata)``,
+    ``list_session(session_id)`` and ``list_prefix(prefix)`` — the small
+    contract :func:`open_engine_store` provides. Injecting it keeps this class
+    free of engine-construction concerns and trivially testable with a fake.
+    """
+
+    def __init__(self, store: Any) -> None:
+        self._store = store
+
+    @staticmethod
+    def _session_id(run_id: str) -> str:
+        return f"{_SESSION_PREFIX}{run_id}"
+
+    def record(self, entry: LedgerEntry) -> None:
+        self._store.add(
+            entry.to_json(),
+            session_id=self._session_id(entry.run_id),
+            metadata={
+                "integration": "slm-loop",
+                "loop_name": entry.name,
+                "loop_run_id": entry.run_id,
+                "loop_lap": entry.lap,
+                "loop_decision": entry.decision,
+                "tags": [LEDGER_TAG, f"loop:{entry.name}"],
+                "importance": _LEDGER_IMPORTANCE,
+                "project_name": "slm-loop",
+            },
+        )
+
+    def laps(self, run_id: str) -> list[LedgerEntry]:
+        rows = self._store.list_session(self._session_id(run_id))
+        entries = [LedgerEntry.from_json(r.get("content", "")) for r in rows]
+        return [e for e in entries if e is not None]
+
+    def runs(self, name: str) -> list[str]:
+        """Run ids for ``name``, newest run first.
+
+        ``list_prefix`` returns rows created_at DESC, so the first time a run's
+        id is seen it is its most-recent lap; ``slm loop history`` therefore
+        lists the most recent runs first.
+        """
+        rows = self._store.list_prefix(_SESSION_PREFIX)
+        ordered: list[str] = []
+        for row in rows:
+            entry = LedgerEntry.from_json(row.get("content", ""))
+            if entry is not None and entry.name == name and entry.run_id not in ordered:
+                ordered.append(entry.run_id)
+        return ordered
+
+
+class _EngineLedgerStore:
+    """Minimal profile-scoped store over a SuperLocalMemory engine.
+
+    Uses the engine's non-blocking write-through path when available and
+    direct, escaped, profile-scoped reads.  The ``store`` fallback preserves
+    compatibility with lightweight adapter/test engines that predate
+    ``store_fast``.
+    """
+
+    def __init__(self, engine: Any, *, owns_engine: bool = True) -> None:
+        self._engine = engine
+        # When False, this store does NOT own the engine's lifecycle (the
+        # caller — e.g. the MCP daemon — keeps it), so close() must not tear
+        # down a shared engine. open_engine_store() passes True (it built the
+        # engine); engine_backed_ledger() passes False (daemon-owned engine).
+        self._owns_engine = owns_engine
+
+    def add(self, content: str, *, session_id: str, metadata: dict) -> None:
+        # A loop ledger needs the durable parent row and immediate lexical
+        # recall, not synchronous embeddings/entity/graph enrichment. Loading
+        # the heavyweight embedding worker for every bounded-loop lap can stall
+        # the loop for the full worker timeout and consume ~1 GB for metadata.
+        # The write-through path persists the same session-scoped content in
+        # milliseconds; ordinary background enrichment can still promote it.
+        fast_metadata = {**metadata, "session_id": session_id}
+        store_fast = getattr(self._engine, "store_fast", None)
+        if callable(store_fast):
+            store_fast(
+                content,
+                metadata=fast_metadata,
+                index_external=False,
+            )
+            return
+
+        self._engine.store(
+            content,
+            session_id=session_id,
+            metadata=metadata,
+        )
+
+    def list_session(self, session_id: str) -> list[dict]:
+        # Cap the read: a bounded-loop run is capped at max_iterations laps, so
+        # a legitimate run is small; the LIMIT stops a pathologically long
+        # session_id from forcing an unbounded materialization on every
+        # `slm loop show` / history lookup.
+        rows = self._engine.db.execute(
+            "SELECT content, created_at FROM memories "
+            "WHERE profile_id=? AND session_id=? "
+            "ORDER BY created_at ASC, rowid ASC LIMIT 5000",
+            (self._engine.profile_id, session_id),
+        )
+        return [dict(row) for row in rows]
+
+    def list_prefix(self, prefix: str) -> list[dict]:
+        escaped = prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        # Cap the scan so a long-lived, high-volume ledger can't force an
+        # unbounded read on `slm loop history`.
+        rows = self._engine.db.execute(
+            "SELECT content, created_at FROM memories "
+            "WHERE profile_id=? AND session_id LIKE ? ESCAPE '\\' "
+            "ORDER BY created_at DESC, rowid DESC LIMIT 5000",
+            (self._engine.profile_id, escaped + "%"),
+        )
+        return [dict(row) for row in rows]
+
+    def close(self) -> None:
+        if self._owns_engine:
+            self._engine.close()
+
+
+def engine_backed_ledger(engine: Any) -> SLMMemoryLedger:
+    """Build an SLM-backed ledger over an ALREADY-OPEN engine.
+
+    Unlike :func:`open_engine_store`, this neither creates nor owns the engine —
+    the caller (e.g. the MCP daemon, which keeps one long-lived engine per
+    profile) retains full ownership and lifecycle. The returned ledger never
+    closes the engine, so it is safe to build one per tool call. The engine's
+    per-call, WAL-mode connection model makes the ledger's reads/writes safe
+    from a worker thread.
+    """
+    return SLMMemoryLedger(_EngineLedgerStore(engine, owns_engine=False))
+
+
+def open_engine_store(db_path: str | Path) -> _EngineLedgerStore:
+    """Build an engine-backed ledger store rooted at ``db_path``.
+
+    Raises ``ImportError`` with an install hint if the SLM runtime is missing.
+    """
+    from dataclasses import replace
+
+    try:
+        from superlocalmemory.core.config import SLMConfig
+        from superlocalmemory.core.engine import MemoryEngine
+        from superlocalmemory.storage.models import Mode
+    except ImportError as exc:  # pragma: no cover - defensive
+        raise ImportError(
+            "SuperLocalMemory runtime is required for the SLM-backed loop "
+            "ledger. Install it with: python -m pip install superlocalmemory."
+        ) from exc
+
+    path = Path(db_path).expanduser().resolve()
+    config = SLMConfig.for_mode(Mode.A, base_dir=path.parent)
+    config.db_path = path
+    config.forgetting = replace(config.forgetting, enabled=False)
+    config.retrieval.use_cross_encoder = False
+    engine = MemoryEngine(config)
+    engine.initialize()
+    return _EngineLedgerStore(engine)

package/src/superlocalmemory/loops/models.py

@@ -0,0 +1,152 @@
+"""Immutable value types for SuperLocalMemory bounded loops.
+
+A *bounded loop* is an agent loop that terminates when an independent gate
+passes — never when the agent claims it is finished. This module holds the
+pure data types the loop engine reasons over.
+
+Design rules (kept deliberately strict):
+  * Standard-library imports only. No I/O, no framework, no side effects.
+  * Every dataclass is ``frozen=True`` — any attribute mutation raises
+    ``TypeError`` at runtime, so a lap result cannot be rewritten after the
+    gate has judged it.
+  * Timestamps are ISO-8601 strings supplied by the engine's clock, never
+    produced here with ``datetime.now()``.
+
+This is SuperLocalMemory's own realization of the bounded-loop concept; the
+loop-control discipline it encodes (gate-verified termination, enforced
+bounds, an advisory-only agent claim) is a general practice, reimplemented
+here against SLM's durable memory rather than a flat file.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class Rung(str, Enum):
+    """Autonomy rung governing how much a human stays in the loop.
+
+    ``L1`` report      — a human reads every verdict; the loop still exits on
+                         a passing gate but nothing is auto-approved.
+    ``L2`` assisted     — the agent acts but pauses for human approval before a
+                         passing gate is accepted as DONE.
+    ``L3`` unattended   — the agent acts autonomously; approval is derived from
+                         the bounds alone.
+
+    Subclassing ``(str, Enum)`` makes ``Rung.L2 == "L2"`` true and
+    ``Rung("L2")`` reconstruct the member, so a rung round-trips through JSON
+    or a CLI argument without a hand-written lookup table.
+    """
+
+    L1 = "L1"
+    L2 = "L2"
+    L3 = "L3"
+
+
+class Status(str, Enum):
+    """Terminal status of a bounded-loop run.
+
+    ``DONE``   — the gate passed and approval was granted or not required.
+    ``HALT``   — a safety bound tripped (iteration cap, no progress, budget).
+    ``PAUSE``  — the gate passed but required approval was not granted.
+    ``KILLED`` — an external kill switch tripped between laps.
+    ``ERROR``  — the runner or gate raised before a verdict was produced.
+    """
+
+    DONE = "DONE"
+    HALT = "HALT"
+    PAUSE = "PAUSE"
+    KILLED = "KILLED"
+    ERROR = "ERROR"
+
+
+@dataclass(frozen=True)
+class Bounds:
+    """The safety envelope a loop runs inside.
+
+    ``max_iterations``     hard cap on laps; required and must be >= 1.
+    ``no_progress_window`` consecutive no-change laps that trigger a HALT.
+    ``max_tokens``         cumulative token budget across laps, or ``None``.
+    ``max_wallclock_s``    wall-clock ceiling in seconds, or ``None``.
+    ``require_approval``    ``True``/``False`` forces the approval posture;
+                           ``None`` derives it from the rung (L1 -> no
+                           approval, L2/L3 -> approval required).
+    """
+
+    max_iterations: int
+    no_progress_window: int = 3
+    max_tokens: Optional[int] = None
+    max_wallclock_s: Optional[float] = None
+    require_approval: Optional[bool] = None
+
+    def __post_init__(self) -> None:
+        if self.max_iterations < 1:
+            raise ValueError("max_iterations must be >= 1")
+        if self.no_progress_window < 0:
+            raise ValueError("no_progress_window must be >= 0")
+        if self.max_tokens is not None and self.max_tokens < 0:
+            raise ValueError("max_tokens must be >= 0 when set")
+        if self.max_wallclock_s is not None and self.max_wallclock_s < 0:
+            raise ValueError("max_wallclock_s must be >= 0 when set")
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """The independent gate's judgement of a single lap.
+
+    ``passed``   True only when the gate mechanically confirmed the goal.
+    ``detail``   human-readable one-line summary (required, non-empty).
+    ``evidence`` structured gate output (counts, tails, diffs). Defaults to a
+                 fresh dict per instance via ``default_factory`` so verdicts do
+                 not share one mutable dict.
+
+    ``passed=True`` is necessary but not sufficient for the loop to exit; the
+    engine still consults the approval rung.
+    """
+
+    passed: bool
+    detail: str
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class LapResult:
+    """What the runner reports after proposing one lap of work.
+
+    ``changed``            True if the runner altered the workspace/state.
+    ``agent_claimed_done`` the agent's own "I am finished" signal. Recorded for
+                           audit and **never** used to terminate the loop — the
+                           gate is the sole authority.
+    ``tokens``             tokens spent this lap (0 when unknown).
+    ``log``                short runner log for the lap.
+    """
+
+    changed: bool
+    agent_claimed_done: bool = False
+    tokens: int = 0
+    log: str = ""
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """The final result of a bounded-loop run.
+
+    ``status``   terminal status.
+    ``reason``   short machine-friendly explanation ("gate-passed",
+                 "no-progress", "max-iterations", "awaiting-approval",
+                 "killed", or a gate/runner error string).
+    ``laps``     number of laps executed at termination.
+    ``run_id``   identifier used to locate this run's ledger in SLM memory.
+    """
+
+    status: Status
+    reason: str
+    laps: int
+    run_id: str
+
+    @property
+    def ok(self) -> bool:
+        """True only for a DONE outcome — the single success state."""
+        return self.status is Status.DONE