@senpi/runtime 3.0.0-dev.runtime-phase-2.20260623210537 → 3.0.0-dev.runtime-phase-2.20260625112547

package/dist/scanners/external/scaffold/senpi_mcp.py

@@ -0,0 +1,250 @@
+"""`ctx.senpi_mcp` — the MCP client capability (runtime v2.0.0, Block B5).
+
+The author's `scan(inputs, ctx)` is SYNC. `ctx.senpi_mcp.call_tool(name, args)`
+is therefore a SYNC surface: the author never sees `await`. Internally it bridges
+the OFFICIAL MCP Python SDK (`mcp`), which is async-only:
+
+    from mcp import ClientSession
+    from mcp.client.streamable_http import streamablehttp_client
+
+    async with streamablehttp_client(url, headers=...) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            result = await session.call_tool(name, arguments=args)
+
+DECISION (locked, execution-plan B5): use the SDK the STANDARD way — a SINGLE
+PERSISTENT `ClientSession` created ONCE (and `initialize()`d once), reused across
+every call. NO extra guards: no custom timeout, no reconnect/retry wrapper, no
+pooling toggle, no fresh-connection-per-call. The async context managers must
+STAY OPEN for the client's lifetime, so we drive them on a dedicated event loop
+running in a background thread; `call_tool` submits work onto that loop and blocks
+for the result (the sync↔async bridge).
+
+Response normalization MATCHES producer.mjs `createSenpiToolClient`:
+    1. isError truthy            -> RAISE with the error text (never a silent None).
+    2. structuredContent present -> return it.
+    3. else first text content   -> json.loads it (fallback to the raw text).
+    4. else                      -> return content as-is.
+
+The `mcp` package is LAZY-IMPORTED on first connect (NOT at module top), so
+`import scaffold.senpi_mcp` works even where `mcp` is not installed. Missing creds
+are LOUD AT FIRST USE: `call_tool` raises, construction never does.
+
+TEARDOWN (intentional, one-process-per-scanner model): there is NO explicit
+close()/shutdown for the persistent session. The background loop runs on a DAEMON
+thread, so it dies with the process. The scaffold runs exactly ONE client per
+process for that process's whole life — the supervisor restarts by spawning a
+FRESH child process (not by re-running run_scaffold in-place), so a single client
+is never replaced in-process and there is no loop/session leak across restart.
+On graceful stop (SIGTERM/SIGINT) run_scaffold exits its loop and the process
+returns; on a hard kill the OS reclaims the thread. We deliberately do NOT drive
+an AsyncExitStack.aclose() from a shutdown hook: it buys nothing over the dropped
+TCP connection (streamable-http is request/response, no protocol goodbye) and a
+cross-thread aclose() on a wedged transport could itself hang a path that today
+cannot hang.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from typing import Any, Iterable, Optional
+
+
+# --------------------------------------------------------------------------
+# Producer MCP write boundary — read-only by default.
+# --------------------------------------------------------------------------
+#
+# A supervised producer's scan(inputs, ctx) runs in-process with the strategy's
+# full-capability SENPI_API_KEY. Without a boundary it could call ANY MCP tool —
+# including money/state mutations — bypassing every runtime guard (risk-guard,
+# DSL, slots, dedup). MUTATION_TOOLS enumerates those money/state-mutating tools;
+# call_tool BLOCKS them by default unless the EXACT tool name is on the client's
+# write_allowlist (least privilege — one permitted tool does not unlock others).
+#
+# Read tools (discovery_*, leaderboard_*, market_*, strategy_get*, strategy_list,
+# execution_get*, account_get*, user_get*, arena_*, audit_*, get_*,
+# list_senpi_guides, read_senpi_guide, ratchet_stop_get/list/events) are NOT in
+# this set and therefore always pass.
+MUTATION_TOOLS: frozenset[str] = frozenset(
+    {
+        "create_position",
+        "close_position",
+        "edit_position",
+        "cancel_order",
+        "send_usdc",
+        "transfer_spot_to_perps",
+        "strategy_create",
+        "strategy_create_custom_strategy",
+        "strategy_close",
+        "strategy_close_positions",
+        "strategy_update",
+        "strategy_pause",
+        "strategy_top_up",
+        "strategy_withdraw_funds",
+        "strategy_bridge_funds_from_hyperliquid_to_evm",
+        "ratchet_stop_add",
+        "ratchet_stop_edit",
+        "ratchet_stop_delete",
+        "user_claim_referral_rewards",
+    }
+)
+
+# THE allowlist a scaffold maintainer edits to permit a mutation tool for
+# producers. EMPTY BY DEFAULT — every MUTATION_TOOLS entry is blocked. The ONLY
+# way to permit a mutation is to add its exact tool name to this frozenset
+# (e.g. {"create_position"}). This is scaffold-maintainer-owned source: it is
+# not operator/env-configurable and is not reachable by authored producer code.
+PRODUCER_WRITE_ALLOWLIST: frozenset[str] = frozenset()
+
+
+class SenpiMcpClient:
+    """Sync MCP client over the official async SDK with one persistent session.
+
+    Construction is cheap and never touches the network or imports `mcp`. The
+    first `call_tool` lazily imports the SDK, spins up a private event loop on a
+    background thread, opens the transport + ClientSession ONCE, and initializes
+    it ONCE. Every subsequent call reuses that same session.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        mcp_url: Optional[str] = None,
+        write_allowlist: Iterable[str] = (),
+    ) -> None:
+        self._api_key = api_key
+        self._mcp_url = mcp_url
+        # Mutation tools the operator has explicitly permitted. EMPTY by default
+        # → every MUTATION_TOOLS entry is blocked (read-only producer boundary).
+        self._write_allowlist: frozenset[str] = frozenset(write_allowlist)
+
+        # Persistent bridge state — created lazily on first call_tool.
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._thread: Optional[threading.Thread] = None
+        self._session: Any = None
+        self._stack: Any = None
+        self._connected = False
+        self._connect_lock = threading.Lock()
+
+    # -- public sync surface ----------------------------------------------
+
+    def call_tool(self, name: str, args: Optional[dict] = None) -> Any:
+        """Invoke an MCP tool synchronously; return the unwrapped result.
+
+        Raises (loud, never a silent None) when the tool is a money/state
+        mutation not on the write allowlist, when creds are missing, or when the
+        tool reports `isError`.
+        """
+        # Read-only producer boundary, enforced PRE-CONNECT (no transport opened
+        # for a blocked write). A mutation tool passes only if its exact name is
+        # on the write allowlist (least privilege — one tool ≠ all).
+        if name in MUTATION_TOOLS and name not in self._write_allowlist:
+            raise PermissionError(
+                f'senpi_mcp: tool "{name}" is a money/state-mutating MCP tool and '
+                "is blocked — producers are READ-ONLY by default. The ONLY way to "
+                f'permit it is to add "{name}" to the PRODUCER_WRITE_ALLOWLIST '
+                "frozenset in src/scanners/external/scaffold/senpi_mcp.py "
+                "(scaffold-maintainer-owned source; not operator/env-configurable; "
+                "not reachable by authored producer code)."
+            )
+
+        self._ensure_connected()
+        result = self._run(self._session.call_tool(name, arguments=args))
+        return self._unwrap(name, result)
+
+    # -- persistent session lifecycle -------------------------------------
+
+    def _ensure_connected(self) -> None:
+        if self._connected:
+            return
+        with self._connect_lock:
+            if self._connected:
+                return
+
+            # Loud at first use: creds are required to reach the MCP server.
+            if not self._api_key:
+                raise RuntimeError(
+                    "senpi_mcp: SENPI_API_KEY is not set; cannot call MCP tools "
+                    "(creds are resolved at launch from SENPI_API_KEY/SENPI_MCP_URL)."
+                )
+            if not self._mcp_url:
+                raise RuntimeError(
+                    "senpi_mcp: SENPI_MCP_URL is not set; cannot call MCP tools "
+                    "(creds are resolved at launch from SENPI_API_KEY/SENPI_MCP_URL)."
+                )
+
+            # Dedicated event loop on a background thread. The async context
+            # managers (transport + session) must stay OPEN for the client's
+            # lifetime, so we cannot use asyncio.run() per call — that would
+            # tear the session down between calls.
+            self._loop = asyncio.new_event_loop()
+            self._thread = threading.Thread(
+                target=self._loop.run_forever,
+                name="senpi-mcp-loop",
+                daemon=True,
+            )
+            self._thread.start()
+
+            self._run(self._connect())
+            self._connected = True
+
+    async def _connect(self) -> None:
+        """Open the transport + ClientSession ONCE and initialize ONCE.
+
+        Lazy-import the SDK here so `import scaffold.senpi_mcp` succeeds in envs
+        without `mcp` installed (tests inject a fake `mcp` into sys.modules).
+        """
+        from mcp import ClientSession
+        from mcp.client.streamable_http import streamablehttp_client
+
+        # Keep the async context managers alive by holding their __aenter__
+        # values on self and only __aexit__-ing them at close. We use
+        # AsyncExitStack so both nest correctly and unwind in order.
+        from contextlib import AsyncExitStack
+
+        self._stack = AsyncExitStack()
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        read, write, _ = await self._stack.enter_async_context(
+            streamablehttp_client(self._mcp_url, headers=headers)
+        )
+        session = await self._stack.enter_async_context(ClientSession(read, write))
+        await session.initialize()
+        self._session = session
+
+    def _run(self, coro: Any) -> Any:
+        """Drive a coroutine to completion on the persistent loop, blocking."""
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        return future.result()
+
+    # -- response normalization (matches producer.mjs createSenpiToolClient) --
+
+    @staticmethod
+    def _unwrap(name: str, result: Any) -> Any:
+        if getattr(result, "isError", False):
+            content = getattr(result, "content", None)
+            if (
+                isinstance(content, list)
+                and len(content) > 0
+                and getattr(content[0], "type", None) == "text"
+            ):
+                error_text = content[0].text
+            else:
+                error_text = json.dumps(content, default=str)
+            raise RuntimeError(f'MCP tool "{name}" returned error: {error_text}')
+
+        structured = getattr(result, "structuredContent", None)
+        if structured is not None:
+            return structured
+
+        content = getattr(result, "content", None)
+        if isinstance(content, list) and len(content) > 0:
+            first = content[0]
+            if getattr(first, "type", None) == "text":
+                try:
+                    return json.loads(first.text)
+                except (ValueError, TypeError):
+                    return first.text
+
+        return content

package/dist/scanners/external/scaffold/signal_envelope.py

@@ -1,75 +1,218 @@
-"""Pure candidate -> wire-signal mapping.
+"""Pure candidate -> wire-signal mapping (v2: lenient + loud).
+
+    candidate_to_signal(
+        candidate,
+        produced_at_ms,
+        *,
+        signal_id=None,                     # stable production id (journal eid); minted if absent
+        signal_data_schema,                 # dict {key: {type, required?}} | None
+        default_signal_validity_seconds,    # int REQUIRED fallback TTL (seconds)
+        on_reject=None,                     # callback(reason_dict) on reject -> /errors
+    ) -> dict | None
+
+Returns the wire dict on success:
+    {signal_id, asset, direction, produced_at, valid_until, data}
+plus signal_type only when the author set a non-empty string, and the canonical
+sizing fields `marginUsd` (USD margin, not a percent) and/or `leverage` at the
+TOP LEVEL (not inside `data`) when the candidate sets them — the runtime reads
+signal.marginUsd / signal.leverage directly. A present-but-non-positive-number
+marginUsd/leverage is a LOUD reject.
+
+Returns None (never raises for a bad CANDIDATE) when the candidate is invalid,
+and — when on_reject is supplied — calls on_reject(reason) so the rejection is
+LOUD (logged AND posted to /errors), never a silent drop.
+
+v2 contract (design §4):
+- direction is NORMALIZED case: "long"/"LONG"/"Long" -> "LONG"; "short"/.. -> "SHORT".
+  Surrounding whitespace is stripped. "buy"/"sell"/""/non-string -> REJECT.
+- asset + direction are MANDATORY (non-empty string asset).
+- `data` is VALIDATED against signal_data_schema (when a dict is supplied):
+  missing-required / wrong-type / extra (unknown) keys all REJECT. A None schema
+  means "no validation" (passthrough — used when no schema is threaded in).
+- valid_until = produced_at_ms + (valid_for_seconds else
+  default_signal_validity_seconds) * 1000. The v1 produced_at + 2*interval default
+  is GONE; there is no interval_ms arg. A non-positive / non-int valid_for_seconds
+  is REJECTED. A MISSING default_signal_validity_seconds (None) when it is NEEDED
+  fails LOUD (raises) — no magic fallback.
+- author absolute `valid_until` is DROPPED (never honored, never leaks).
+- The keys on the wire are {signal_id, asset, direction, produced_at,
+  valid_until, data} (+ optional signal_type, marginUsd, leverage). `marginUsd`/
+  `leverage` are the canonical top-level sizing fields (validated positive numbers
+  when present; `marginUsd` is a USD value, not a percent). `signal_id` is the
+  scaffold-minted
+  stable production id (the journal eid), threaded in by the delivery sink — it is
+  the intake dedup key. An author-supplied `signal_id` in the candidate dict is
+  IGNORED: the scaffold owns the dedup key, an author cannot spoof it. Apart from
+  signal_id/signal_type, author bookkeeping never leaks.
+"""
 
-candidate_to_signal(candidate, produced_at_ms, interval_ms) -> dict | None
+from __future__ import annotations
 
-Returns the six-key wire dict on success:
-    {asset, direction, produced_at, valid_until, data}
-plus signal_type only when the author set a non-empty string.
+import uuid
+from typing import Any, Optional
 
-Returns None (never raises) when the candidate is invalid:
-- non-mapping candidate
-- missing / blank / non-string asset
-- missing / non-LONG/SHORT direction (no case coercion)
 
-Wire rules (TS intake: additionalProperties:false):
-- direction must be exactly "LONG" or "SHORT"
-- produced_at / valid_until are int epoch ms
-- valid_until = author override verbatim when present, else produced_at + 2*interval_ms
-- data is the author's open record passed through as-is (missing -> {})
-- NO extra keys on the wire
-"""
+# JSON type name -> Python type(s) for schema validation. `bool` is excluded from
+# "number" because a bool is an int subclass in Python but is not a numeric value.
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _is_string(value: Any) -> bool:
+    return isinstance(value, str)
+
+
+def _is_boolean(value: Any) -> bool:
+    return isinstance(value, bool)
+
+
+def _is_object(value: Any) -> bool:
+    return isinstance(value, dict)
+
+
+def _is_array(value: Any) -> bool:
+    return isinstance(value, list)
 
-from __future__ import annotations
 
-from typing import Any
+_TYPE_CHECKS = {
+    "number": _is_number,
+    "string": _is_string,
+    "boolean": _is_boolean,
+    "object": _is_object,
+    "array": _is_array,
+}
+
+
+def _validate_data_against_schema(data: dict, schema: dict) -> Optional[str]:
+    """Validate `data` against `schema`. Returns a reason string on violation,
+    or None when valid. additionalProperties:false — unknown keys reject."""
+    allowed = set(schema.keys())
+
+    # Extra (unknown) keys reject.
+    for key in data:
+        if key not in allowed:
+            return f"data has unknown key {key!r} (not in signal_data_schema)"
+
+    # Missing-required and wrong-type.
+    for key, spec in schema.items():
+        spec = spec if isinstance(spec, dict) else {}
+        required = spec.get("required", True)  # required unless explicitly False
+        if key not in data:
+            if required:
+                return f"data missing required key {key!r}"
+            continue
+        declared_type = spec.get("type")
+        check = _TYPE_CHECKS.get(declared_type)
+        if check is not None and not check(data[key]):
+            return (
+                f"data key {key!r} has wrong type "
+                f"(expected {declared_type}, got {type(data[key]).__name__})"
+            )
+    return None
 
 
 def candidate_to_signal(
     candidate: Any,
     produced_at_ms: int,
-    interval_ms: int,
+    *,
+    signal_id: Optional[str] = None,
+    signal_data_schema: Optional[dict],
+    default_signal_validity_seconds: Optional[int],
+    on_reject=None,
 ) -> dict | None:
-    """Wrap a scan() candidate into a wire signal dict.
+    """Wrap a scan() candidate into a wire signal dict (v2).
 
-    Returns the signal dict on success, None when the candidate is invalid.
-    Never raises.
+    Returns the signal dict on success, None when the candidate is invalid (and
+    calls on_reject(reason) so the rejection is loud). Raises only when the
+    OPERATOR config is wrong (missing default_signal_validity_seconds when needed).
     """
+
+    def _reject(reason: str) -> None:
+        if on_reject is not None:
+            on_reject({"reason": reason, "candidate": repr(candidate)})
+
     if not isinstance(candidate, dict):
+        _reject(f"candidate is not a mapping (got {type(candidate).__name__})")
         return None
 
+    # -- asset: mandatory, non-empty string --------------------------------
     asset = candidate.get("asset")
     if not isinstance(asset, str) or not asset.strip():
+        _reject(f"asset missing/blank/non-string (got {asset!r})")
         return None
 
+    # -- direction: mandatory string, case-normalized to LONG / SHORT ------
     direction = candidate.get("direction")
-    if direction not in ("LONG", "SHORT"):
+    if not isinstance(direction, str) or isinstance(direction, bool):
+        _reject(f"direction is not a string (got {direction!r})")
+        return None
+    normalized = direction.strip().upper()
+    if normalized not in ("LONG", "SHORT"):
+        _reject(f"direction must be long/short (got {direction!r})")
         return None
 
-    # valid_until: author override verbatim when a real number, or default.
-    # bool is a subclass of int in Python, but is not a valid epoch ms value.
-    if "valid_until" in candidate:
-        valid_until = candidate["valid_until"]
-        if not isinstance(valid_until, (int, float)) or isinstance(valid_until, bool):
-            from .loop_primitives import log_event
-            log_event("delivery_candidate_invalid",
-                      reason="valid_until_not_numeric",
-                      candidate=repr(candidate))
+    # -- valid_until from valid_for_seconds else the default ---------------
+    # (compute BEFORE schema so a missing operator default still fails loud.)
+    if "valid_for_seconds" in candidate:
+        vfs = candidate["valid_for_seconds"]
+        # int only (bool excluded), strictly positive.
+        if not isinstance(vfs, int) or isinstance(vfs, bool) or vfs <= 0:
+            _reject(f"valid_for_seconds must be a positive int (got {vfs!r})")
             return None
+        validity_seconds = vfs
     else:
-        valid_until = produced_at_ms + 2 * interval_ms
+        if default_signal_validity_seconds is None:
+            # OPERATOR error, not a candidate bug — fail LOUD (no magic fallback).
+            raise ValueError(
+                "default_signal_validity_seconds is required when a candidate has "
+                "no valid_for_seconds; got None (no magic fallback in v2)."
+            )
+        validity_seconds = default_signal_validity_seconds
+
+    valid_until = produced_at_ms + validity_seconds * 1000
 
+    # -- data: validate against schema (when supplied) ---------------------
     data = candidate.get("data", {})
     if not isinstance(data, dict):
         data = {}
+    if signal_data_schema is not None:
+        violation = _validate_data_against_schema(data, signal_data_schema)
+        if violation is not None:
+            _reject(violation)
+            return None
+
+    # -- canonical sizing: marginUsd + leverage ride at the TOP LEVEL of the wire
+    #    signal, NOT inside `data`. `marginUsd` is the USD margin (not a percent);
+    #    the runtime consumes signal.marginUsd / signal.leverage directly (data is
+    #    freeform context only), so per-signal sizing/leverage from the producer is
+    #    honored instead of silently dropped. Present-but-invalid is a LOUD reject —
+    #    sizing must never fall back silently.
+    sizing: dict = {}
+    for field in ("marginUsd", "leverage"):
+        if candidate.get(field) is None:
+            continue
+        value = candidate[field]
+        if not _is_number(value) or value <= 0:
+            _reject(f"{field} must be a positive number when set (got {value!r})")
+            return None
+        sizing[field] = value
 
     sig: dict = {
+        # scaffold-minted stable production id (journal eid); the author cannot
+        # override it via the candidate dict — the kwarg is authoritative. The
+        # delivery sink threads the eid in; when no id is supplied a stable one is
+        # minted so the wire ALWAYS carries a signal_id (required end-to-end).
+        "signal_id": signal_id if (isinstance(signal_id, str) and signal_id) else uuid.uuid4().hex,
         "asset": asset,
-        "direction": direction,
+        "direction": normalized,
         "produced_at": produced_at_ms,
         "valid_until": valid_until,
         "data": data,
     }
 
+    # Lift the validated sizing fields onto the wire signal at the top level.
+    sig.update(sizing)
+
     signal_type = candidate.get("signal_type")
     if signal_type and isinstance(signal_type, str):
         sig["signal_type"] = signal_type

package/dist/scanners/external/scaffold/state_manager.py

@@ -0,0 +1,175 @@
+"""Disk-backed, bounded, transactional state series for the scaffold core.
+
+`StateManager` is the `ctx.state` capability the supervised external scanner
+author sees: a list-like series of dict records, persisted between ticks and
+bounded by `state_history_max_count`.
+
+Shape (per scanner-and-ctx-design.md §2.3):
+
+    StateManager(state_path, state_history_max_count)
+
+  Author surface:
+    append(record)   record MUST be a dict; a reserved `recorded_at` (float
+                     SECONDS, time.time() magnitude — never ms) is injected.
+                     scaffold wins on a `recorded_at` collision. returns None.
+                     RAISES when state_history_max_count is 0/unset — history
+                     disabled is a hard error, never a silent no-op.
+    recent(n)        last n entries, chronological (oldest->newest); n<=0 -> [].
+    last()           most recent entry, or None if empty.
+    __len__ / __getitem__ (index + slice) / __iter__ (oldest -> newest).
+
+  Internals: backed by collections.deque(maxlen=state_history_max_count).
+  Loading an on-disk series longer than the bound keeps the NEWEST entries
+  (deque eviction drops the oldest).
+
+  Transactional (one commit per tick):
+    commit()    persists the working buffer via the atomic write_state.
+                JSON-serializability is enforced LOUD here — a failed persist
+                RAISES and does NOT advance the committed snapshot, leaving the
+                prior on-disk state intact.
+    rollback()  discards mid-tick mutations: the working buffer is restored to
+                the last committed snapshot.
+    read-your-writes within a tick: appended records are visible via
+    len/recent/last/iter/getitem BEFORE commit.
+"""
+
+from __future__ import annotations
+
+import copy
+import time
+from collections import deque
+
+from .scaffold_state import read_state, write_state
+
+# Reserved, scaffold-owned key injected into every record. Float seconds.
+RECORDED_AT_KEY = "recorded_at"
+
+
+class StateManager:
+    """A disk-backed, bounded, transactional series of dict records."""
+
+    def __init__(self, state_path: str, state_history_max_count):
+        self._state_path = state_path
+        # 0 / None / falsy => history disabled. Kept as-is so append can raise.
+        self._max_count = state_history_max_count
+
+        # Load any persisted series. read_state never raises: missing/corrupt
+        # -> None. A non-list payload is treated as "no usable history".
+        # state_path None => no disk persistence (commit advances the in-memory
+        # snapshot but never writes). read_state needs a real path.
+        loaded = read_state(state_path) if state_path is not None else None
+        if not isinstance(loaded, list):
+            loaded = []
+
+        # The committed snapshot is the last durably-persisted series; the
+        # working buffer is what the current tick reads/mutates. Both are
+        # bounded the same way (deque(maxlen=...)); loading a longer-than-bound
+        # series keeps the NEWEST entries (deque evicts from the left).
+        self._committed = self._new_deque(loaded)
+        self._working = self._snapshot(self._committed)
+
+    # -- internals ---------------------------------------------------------
+
+    def _new_deque(self, initial=()):
+        """A deque bounded by max_count. When history is disabled (max_count is
+        0/None) the bound is 0 — nothing can ever be buffered."""
+        maxlen = self._max_count if self._max_count else 0
+        return deque(initial, maxlen=maxlen)
+
+    def _snapshot(self, source):
+        """An independent bounded deque whose records share NO mutable state
+        with `source`. Committed and working buffers must never alias the same
+        dict objects — otherwise a mid-tick mutation of a record (an author
+        scribbling on a dict handed back by last()/recent()/getitem) would
+        survive a rollback and corrupt the very snapshot the rollback restores.
+        Deep-copy at every snapshot boundary (load / commit / rollback)."""
+        return self._new_deque(copy.deepcopy(entry) for entry in source)
+
+    # -- author surface ----------------------------------------------------
+
+    def append(self, record) -> None:
+        """Append a dict record to the working buffer.
+
+        Injects the reserved `recorded_at` (float seconds, scaffold wins on
+        collision). Raises TypeError if record is not a dict. Raises if history
+        is disabled (state_history_max_count 0/unset) — never a silent no-op.
+        """
+        if not self._max_count:
+            raise ValueError(
+                "state is disabled: state_history_max_count is 0 or unset "
+                "(set it > 0 to use ctx.state.append)"
+            )
+        # bool is an int subclass but never a dict; explicit dict check rejects
+        # lists/tuples/sets/strings/numbers/None/objects/bool alike.
+        if not isinstance(record, dict):
+            raise TypeError(
+                f"state record must be a dict, got {type(record).__name__}"
+            )
+
+        # Copy so the author's dict is never mutated, then stamp recorded_at.
+        # scaffold wins on collision: assign AFTER copying author keys.
+        entry = dict(record)
+        entry[RECORDED_AT_KEY] = time.time()
+        self._working.append(entry)
+        return None
+
+    def recent(self, n) -> list:
+        """The last n entries, chronological (oldest->newest).
+
+        n <= 0 returns []; n greater than the buffer returns the whole buffer.
+        Negative n is NOT a from-the-end slice — it is meaningless for "last n"
+        and yields [].
+        """
+        if n <= 0:
+            return []
+        items = list(self._working)
+        return items[-n:]
+
+    def last(self):
+        """The most recent entry, or None if empty."""
+        if not self._working:
+            return None
+        return self._working[-1]
+
+    # -- sequence protocol -------------------------------------------------
+
+    def __len__(self) -> int:
+        return len(self._working)
+
+    def __getitem__(self, key):
+        # deque supports integer indexing (raising IndexError out of range) but
+        # not slicing; materialise a list so slices work with Python semantics
+        # (clamping, steps, negative bounds) and index errors still propagate.
+        if isinstance(key, slice):
+            return list(self._working)[key]
+        return self._working[key]
+
+    def __iter__(self):
+        return iter(self._working)
+
+    # -- transaction -------------------------------------------------------
+
+    def commit(self) -> None:
+        """Persist the working buffer atomically via write_state.
+
+        JSON-serializability is enforced LOUD: write_state returns False on a
+        non-serializable value (or IO failure) without touching the existing
+        file. We raise on that False so a failed persist never silently
+        advances the committed snapshot — the prior on-disk state stays intact.
+        """
+        payload = list(self._working)
+        # No disk path => commit advances the in-memory snapshot only.
+        ok = True if self._state_path is None else write_state(self._state_path, payload)
+        if not ok:
+            raise RuntimeError(
+                f"failed to persist state to {self._state_path} "
+                "(non-serializable value or IO error); state not advanced"
+            )
+        # Durable: advance the committed snapshot to match what is on disk.
+        # Deep-copy so the committed snapshot does not alias working records.
+        self._committed = self._snapshot(self._working)
+
+    def rollback(self) -> None:
+        """Discard mid-tick mutations: restore the working buffer to the last
+        committed snapshot. Never touches disk."""
+        self._working = self._snapshot(self._committed)