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

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

@@ -20,7 +20,7 @@ class ScanEntrypointError(Exception):
 
 
 class ScanSignatureError(Exception):
-    """scan's call shape is incompatible with scaffold(params, state[, client])."""
+    """scan's call shape is incompatible with scan(inputs, ctx)."""
 
 
 def add_path_to_sys_path(path: str) -> None:
@@ -32,16 +32,22 @@ def add_path_to_sys_path(path: str) -> None:
 def import_entrypoint(path: str, entrypoint: str):
     """Put `path` on sys.path, then import `entrypoint` by module name.
 
+    The recipe expresses `entrypoint` as a FILENAME (e.g. `scan.py`, the shape the
+    B1 launcher writes verbatim into the launch config and the §4a entrypoint FS
+    check validates). importlib needs a MODULE name, so a trailing `.py` is
+    stripped here — the only place the filename<->module-name bridge lives.
+
     Raises ScanEntrypointError on any import/syntax/missing-sibling failure,
     chaining the underlying exception.
     """
     add_path_to_sys_path(path)
+    module_name = entrypoint[:-3] if entrypoint.endswith(".py") else entrypoint
     try:
         # Force re-import when the module has been previously imported so that
         # tests can write fresh modules to tmp_path without cache collisions.
-        if entrypoint in sys.modules:
-            del sys.modules[entrypoint]
-        return importlib.import_module(entrypoint)
+        if module_name in sys.modules:
+            del sys.modules[module_name]
+        return importlib.import_module(module_name)
     except Exception as exc:
         raise ScanEntrypointError(
             f"Failed to import entrypoint '{entrypoint}' from '{path}': {exc}"
@@ -67,19 +73,25 @@ def locate_scan(module) -> Callable:
 
 
 def verify_scan_signature(scan: Callable) -> None:
-    """Verify scan's call shape is compatible with scan(params, state[, client]).
+    """Verify scan's call shape is compatible with the v2 contract scan(inputs, ctx).
+
+    v2 calls scan with EXACTLY two positionals (inputs, ctx). A signature must be
+    callable that way.
 
     Accepted shapes:
-        scan(params, state)                   — 2 required
-        scan(params, state, client)           — 3 required
-        scan(params, state, client=None)      — 2 required, 1 optional
-        scan(params, state, *args)            — variadic absorbs client
+        scan(inputs, ctx)                     — 2 required (the canonical shape)
+        scan(inputs, ctx, extra=None)         — 2 required + defaulted extra
+        scan(inputs, ctx, *args)              — variadic absorbs nothing extra here
         scan(*args, **kwargs)                 — fully variadic, accepts anything
 
     Rejected shapes:
         scan()                                — 0 required
-        scan(params)                          — 1 required
-        scan(a, b, c, d)                      — >=4 fixed required
+        scan(inputs)                          — 1 required
+        scan(params, state, client)           — 3 required (the OLD v1 client shape)
+        scan(a, b, c, d)                      — >=4 required
+
+    The contract is now EXACTLY two positionals: a 3rd REQUIRED positional cannot
+    be satisfied by scan(inputs, ctx) and is rejected.
 
     Raises ScanSignatureError naming the found arity on mismatch.
     """
@@ -94,57 +106,39 @@ def verify_scan_signature(scan: Callable) -> None:
     has_var_positional = any(
         p.kind == inspect.Parameter.VAR_POSITIONAL for p in params
     )
-    has_var_keyword = any(
-        p.kind == inspect.Parameter.VAR_KEYWORD for p in params
-    )
-
-    # A *args/**kwargs-only signature accepts any positional call.
-    if has_var_positional or has_var_keyword:
-        # Check that it actually accepts at least 2 positional args (i.e., no
-        # required positional params ahead of *args that block the call).
-        required_before_var = [
-            p for p in params
-            if p.kind in (
-                inspect.Parameter.POSITIONAL_ONLY,
-                inspect.Parameter.POSITIONAL_OR_KEYWORD,
-            )
-            and p.default is inspect.Parameter.empty
-        ]
-        # If there are >=4 required positionals even WITH *args, reject.
-        if len(required_before_var) >= 4:
-            raise ScanSignatureError(
-                f"scan requires {len(required_before_var)} fixed positional params; "
-                f"expected 2 or 3 (found arity: {len(required_before_var)})."
-            )
-        # Otherwise, variadic accepts our call.
-        return
 
-    # Count fixed positional params (POSITIONAL_ONLY or POSITIONAL_OR_KEYWORD).
-    fixed_positional = [
+    # Required (non-defaulted) fixed positional params.
+    required_fixed = [
         p for p in params
         if p.kind in (
             inspect.Parameter.POSITIONAL_ONLY,
             inspect.Parameter.POSITIONAL_OR_KEYWORD,
         )
+        and p.default is inspect.Parameter.empty
     ]
-    required_fixed = [
-        p for p in fixed_positional
-        if p.default is inspect.Parameter.empty
-    ]
-
     n_required = len(required_fixed)
-    n_fixed = len(fixed_positional)
+
+    # A *args (or *args/**kwargs) signature accepts the 2-positional call as long
+    # as it has no MORE than 2 required fixed positionals ahead of *args.
+    if has_var_positional:
+        if n_required > 2:
+            raise ScanSignatureError(
+                f"scan requires {n_required} fixed positional params; the v2 "
+                f"contract calls scan(inputs, ctx) — exactly 2. Found arity: {n_required}."
+            )
+        return
 
     if n_required < 2:
         raise ScanSignatureError(
-            f"scan has {n_required} required positional param(s); "
-            f"expected at least 2 (params, state). Found arity: {n_required}."
+            f"scan has {n_required} required positional param(s); the v2 contract "
+            f"requires exactly 2 (inputs, ctx). Found arity: {n_required}."
         )
 
-    if n_required >= 4:
+    if n_required > 2:
         raise ScanSignatureError(
-            f"scan has {n_required} required positional params; "
-            f"expected at most 3 (params, state, client). Found arity: {n_required}."
+            f"scan has {n_required} required positional params; the v2 contract "
+            f"calls scan(inputs, ctx) — exactly 2. A 3rd required positional "
+            f"(the old v1 client shape) is no longer accepted. Found arity: {n_required}."
         )
 
 

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

@@ -90,8 +90,19 @@ class Journal:
     # ------------------------------------------------------------------
 
     def record_produced(self, signal: dict, *, now_ms: int) -> str:
-        """Write a 'produced' line and enqueue the signal. Returns entry id."""
-        entry_id = uuid.uuid4().hex
+        """Write a 'produced' line and enqueue the signal. Returns entry id.
+
+        The entry id IS the wire `signal_id`: the journal stamps `signal_id` onto
+        the persisted/queued signal so the POSTed signal carries the dedup key, and
+        a replay re-uses the SAME id (no fresh id minted on restart). If the signal
+        already carries a `signal_id` (the delivery sink threaded the eid in via the
+        envelope), that id is re-used as the entry id; otherwise one is minted.
+        """
+        existing = signal.get("signal_id")
+        entry_id = existing if isinstance(existing, str) and existing else uuid.uuid4().hex
+        # Stamp the id onto the wire signal so the persisted produced line and the
+        # POSTed body both carry signal_id == entry id.
+        signal["signal_id"] = entry_id
         asset = signal.get("asset", "")
         valid_until = signal.get("valid_until", 0)
 

package/dist/scanners/external/scaffold/requirements.txt

@@ -0,0 +1,11 @@
+# Runtime dependencies for the scaffold harness (src/scanners/external/scaffold/).
+#
+# The scaffold is shipped to the scanner box and run via `python3 -m scaffold`.
+# `mcp` (the official Model Context Protocol Python SDK) backs ctx.senpi_mcp:
+# `streamablehttp_client` + a single persistent `ClientSession` (see senpi_mcp.py).
+# It is LAZY-IMPORTED at first use, so the package still imports where `mcp` is
+# absent (e.g. unit tests inject a fake SDK) — install this on the box that runs
+# scanners that call ctx.senpi_mcp.
+#
+# `mcp[cli]` is NOT needed — only the client transport + ClientSession surface.
+mcp>=1.9.0

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

@@ -1,11 +1,14 @@
-"""Scaffold core loop.
+"""Scaffold core loop (v2).
 
 run_scaffold(...) loads the author's entrypoint, finds and validates scan(),
-then drives the interval loop: time-box per tick, graceful stop on SIGTERM/SIGINT,
-parent-death detection via ppid, state in/out, candidates to sink.
-
-`path` is a scaffold concern only — it is put on sys.path before import and
-never passed to scan(). scan() is called as scan(params, state, client=None).
+builds the ScanContext, then drives the interval loop: time-box per tick, graceful
+stop on SIGTERM/SIGINT, parent-death detection via ppid, transactional state via
+ctx.state, candidates to sink.
+
+`path` is a scaffold concern only — it is put on sys.path before import and never
+passed to scan(). scan() is called as scan(inputs, ctx) — 2-arg, sync, returning a
+plain list[dict]. State mutates ONLY via ctx.state (commit on a clean tick, rollback
+on error/timeout/malformed/failed-persist — transactional discard wins on failure).
 """
 
 import inspect
@@ -14,6 +17,7 @@ import time
 import threading
 from typing import Any, Callable, Optional
 
+from .ctx import ScanContext
 from .entrypoint_loader import (
     ScanEntrypointError,
     ScanSignatureError,
@@ -29,40 +33,44 @@ from .loop_primitives import (
     _interruptible_sleep,
     log_event,
 )
-from .scaffold_state import read_state, write_state
+from .state_manager import StateManager
 
 
-def _call_scan(scan: Callable, params: dict, state: Any, client: Any) -> tuple:
-    """Call scan with the right arity.
+def _build_senpi_mcp() -> Any:
+    """Construct the MCP client when creds are present; else return None.
 
-    Tries scan(params, state, client) first; if that raises TypeError because
-    scan only accepts 2 positional args, falls back to scan(params, state).
-    This lets 2-arg and 3-arg (and variadic) scan functions all work uniformly.
+    Creds come from the launch env (SENPI_API_KEY / SENPI_MCP_URL), injected by
+    the launcher regardless of how the operator supplied them. With neither set,
+    return None so the no-creds path does not crash — the client is loud at FIRST
+    USE (see scaffold.senpi_mcp). Reference the class through the module attribute
+    so a test stub patched onto scaffold.senpi_mcp is honored.
     """
-    sig = None
-    try:
-        sig = inspect.signature(scan)
-    except (ValueError, TypeError):
-        pass
-
-    if sig is not None:
-        params_list = list(sig.parameters.values())
-        has_var_positional = any(
-            p.kind == inspect.Parameter.VAR_POSITIONAL for p in params_list
-        )
-        fixed_positional = [
-            p for p in params_list
-            if p.kind in (
-                inspect.Parameter.POSITIONAL_ONLY,
-                inspect.Parameter.POSITIONAL_OR_KEYWORD,
-            )
-        ]
-        # If only 2 fixed positional params (no *args), call 2-arg form.
-        if not has_var_positional and len(fixed_positional) == 2:
-            return scan(params, state)
+    api_key = os.environ.get("SENPI_API_KEY") or None
+    mcp_url = os.environ.get("SENPI_MCP_URL") or None
+    if not api_key and not mcp_url:
+        return None
+
+    from . import senpi_mcp as senpi_mcp_mod
+
+    # Read-only-by-default producer MCP boundary: the set of MUTATION tools
+    # producers are permitted to call is owned SOLELY by the scaffold-source
+    # PRODUCER_WRITE_ALLOWLIST constant (EMPTY by default → all mutations
+    # blocked). It is edited by the scaffold maintainer in senpi_mcp.py — it is
+    # NOT operator/env-configurable and NOT reachable by authored producer code.
+    return senpi_mcp_mod.SenpiMcpClient(
+        api_key=api_key,
+        mcp_url=mcp_url,
+        write_allowlist=senpi_mcp_mod.PRODUCER_WRITE_ALLOWLIST,
+    )
 
-    # Default: 3-arg call (variadic or 3-param).
-    return scan(params, state, client)
+
+def _call_scan(scan: Callable, inputs: dict, ctx: Any):
+    """Call scan(inputs, ctx) — the v2 2-arg contract.
+
+    There is no `client` and no 3-arg path. scan returns a plain list[dict];
+    validation of that return happens in the tick loop.
+    """
+    return scan(inputs, ctx)
 
 
 def run_scaffold(
@@ -71,13 +79,17 @@ def run_scaffold(
     *,
     interval: float,
     timeout_seconds: Optional[float] = None,
-    params: Optional[dict] = None,
+    inputs: Optional[dict] = None,
     state_path: Optional[str] = None,
+    scanner_name: str,
+    wallet: str,
+    default_signal_validity_seconds: int,
+    state_history_max_count: int = 0,
     sink: Optional[Callable] = None,
     max_ticks: Optional[int] = None,
     install_signal_handlers: bool = True,
 ) -> int:
-    """Load the author's entrypoint and run its scan() on an interval loop.
+    """Load the author's entrypoint and run its scan() on an interval loop (v2).
 
     Args:
         path:        Directory added to sys.path before import. Never passed to scan().
@@ -86,9 +98,15 @@ def run_scaffold(
         timeout_seconds:
                      Per-tick wall-clock budget. Defaults to `interval`. Must be > 0.
                      Enforced via SIGALRM on platforms that support it.
-        params:      Tunables dict passed as scan()'s first argument. Default {}.
-        state_path:  Path to the JSON state file. Reads on start, written after
-                     each clean tick. None means no persistence.
+        inputs:      Tunables dict passed as scan()'s first argument. Default {}.
+        state_path:  Path to the JSON state file. None means no persistence.
+        scanner_name: This scanner's recipe name (read-only ctx metadata).
+        wallet:      Strategy wallet (read-only ctx metadata).
+        default_signal_validity_seconds:
+                     Fallback signal TTL (seconds); threaded to the envelope path.
+        state_history_max_count:
+                     Bound on the persisted state series. 0/unset = history disabled
+                     (ctx.state.append raises).
         sink:        Callable(candidates) invoked after each clean tick. Default no-op.
         max_ticks:   Stop after this many ticks (for tests). None = unbounded.
         install_signal_handlers:
@@ -112,14 +130,41 @@ def run_scaffold(
     if timeout_seconds <= 0:
         raise ValueError(f"timeout_seconds must be > 0; got {timeout_seconds!r}")
 
-    if params is None:
-        params = {}
+    if inputs is None:
+        inputs = {}
 
     # Import and locate scan — any failure raises before tick 1.
     module = import_entrypoint(path, entrypoint)
     scan = locate_scan(module)
     verify_scan_signature(scan)
 
+    # ---------- ctx + state setup ----------
+
+    # The StateManager (B2) is the persisted series. It reads any prior state from
+    # disk on construction. state_history_max_count 0/unset => history disabled
+    # (append raises). It is passed into ctx AS-IS (never wrapped).
+    state = StateManager(state_path, state_history_max_count) if state_path is not None \
+        else StateManager(None, state_history_max_count)
+
+    # ctx.interval_seconds is the integer-seconds cadence (design §2.1). The loop's
+    # `interval` may be a sub-second float in tests; expose the int seconds when it
+    # is whole, else the float as-is.
+    interval_seconds = int(interval) if float(interval).is_integer() else interval
+
+    # B5: fill ctx.senpi_mcp when MCP creds are present (resolved at launch from
+    # SENPI_API_KEY / SENPI_MCP_URL). With no creds the slot stays None and launch
+    # must NOT crash — the client is loud at FIRST USE, not at construction. Import
+    # is deferred so a stub patched onto scaffold.senpi_mcp in tests is honored.
+    senpi_mcp = _build_senpi_mcp()
+
+    ctx = ScanContext(
+        state=state,
+        wallet=wallet,
+        scanner_name=scanner_name,
+        interval_seconds=interval_seconds,
+        senpi_mcp=senpi_mcp,
+    )
+
     # ---------- Lifecycle setup ----------
 
     stop_event = threading.Event()
@@ -128,24 +173,17 @@ def run_scaffold(
 
     start_ppid = os.getppid()
 
-    # Read initial state — corrupt/missing -> None (logged inside read_state).
-    state = read_state(state_path) if state_path is not None else None
-
     log_event(
         "scaffold_started",
         path=path,
         entrypoint=entrypoint,
         interval=interval,
         timeout_seconds=timeout_seconds,
+        scanner_name=scanner_name,
         max_ticks=max_ticks,
     )
 
-    client = None  # placeholder; will be the real data handle in a later unit
     tick_count = 0
-    # True once a state write has failed and we have escalated to /errors;
-    # cleared when a write next succeeds. Throttles the escalation to one
-    # post per failure run (a persistent failure would otherwise post every tick).
-    state_persist_degraded = False
 
     try:
         while not stop_event.is_set():
@@ -159,40 +197,28 @@ def run_scaffold(
             tick_started_at = time.time()
             tick_status = "ok"
             tick_error = None
-            candidates = []
-            new_state = state  # default: keep current state on error
+            candidates: list = []
 
             armed = False
             try:
                 armed = _arm_tick_alarm(timeout_seconds)
                 try:
-                    result = _call_scan(scan, params, state, client)
+                    result = _call_scan(scan, inputs, ctx)
 
-                    # Validate the return value: must be a 2-tuple.
-                    if (
-                        not isinstance(result, tuple)
-                        or len(result) != 2
-                    ):
+                    # v2 return contract: a PLAIN list[dict]. Anything else is
+                    # malformed (a tuple — the old v1 shape — included).
+                    if not isinstance(result, list):
                         tick_status = "malformed"
                         log_event(
                             "scaffold_tick_malformed",
                             tick=tick_count,
-                            reason=f"scan() returned {type(result).__name__!r}, expected (candidates, new_state) tuple",
+                            reason=(
+                                f"scan() returned {type(result).__name__!r}; expected a "
+                                f"plain list[dict] (the v1 (candidates, state) tuple is gone)"
+                            ),
                         )
                     else:
-                        raw_candidates, returned_state = result
-                        # Validate that candidates is iterable.
-                        try:
-                            candidates = list(raw_candidates)
-                        except TypeError:
-                            tick_status = "malformed"
-                            log_event(
-                                "scaffold_tick_malformed",
-                                tick=tick_count,
-                                reason=f"candidates is not iterable (got {type(raw_candidates).__name__!r})",
-                            )
-                        else:
-                            new_state = returned_state
+                        candidates = result
 
                 except _TickTimeout as exc:
                     tick_status = "timeout"
@@ -223,48 +249,40 @@ def run_scaffold(
 
                 duration_ms = int((time.time() - tick_started_at) * 1000)
 
-                # --- Clean tick: persist (best-effort), advance state, deliver ---
+                # --- Clean tick: commit ctx.state, deliver candidates ---
                 if tick_status == "ok":
-                    # Disk persistence is best-effort: advance the in-memory state
-                    # regardless of the write result, so the next tick never
-                    # recomputes from stale state (which could re-deliver the same
-                    # signal). But a persist failure is almost always persistent
-                    # (unserialisable state, read-only dir, full disk), and the
-                    # un-persisted ticks are LOST on the next restart — silently
-                    # degrading any scanner that decides on accumulated history.
-                    # So escalate it like a tick error: post to /errors once on the
-                    # first failure (throttled while it keeps failing) and clear
-                    # when a write next succeeds.
-                    if state_path is not None:
-                        if write_state(state_path, new_state):
-                            if state_persist_degraded:
-                                state_persist_degraded = False
-                                log_event("scaffold_state_persist_recovered", tick=tick_count)
-                        else:
-                            log_event("scaffold_state_persist_failed", tick=tick_count)
-                            if not state_persist_degraded:
-                                state_persist_degraded = True
-                                if sink is not None and hasattr(sink, "post_error"):
-                                    try:
-                                        sink.post_error({
-                                            "type": "state_persist_failed",
-                                            "tick": tick_count,
-                                            "message": (
-                                                "scanner state could not be persisted; "
-                                                "accumulated history will be lost on restart"
-                                            ),
-                                        })
-                                    except Exception as perr:  # noqa: BLE001
-                                        log_event(
-                                            "scaffold_post_error_failed",
-                                            tick=tick_count,
-                                            error_type=type(perr).__name__,
-                                            error=str(perr),
-                                        )
-                    state = new_state
-
-                    # Hand candidates to the delivery sink.
-                    if sink is not None:
+                    # Transactional commit. A failed persist RAISES (StateManager
+                    # enforces it) and does NOT advance the committed snapshot — so
+                    # the next tick recomputes from the un-advanced state. On a
+                    # commit failure we roll back and treat the tick as failed
+                    # (discard wins on failed-persist; no advance-on-persist-failure).
+                    committed = True
+                    try:
+                        ctx.state.commit()
+                    except Exception as commit_exc:  # noqa: BLE001
+                        committed = False
+                        ctx.state.rollback()
+                        log_event(
+                            "scaffold_state_persist_failed",
+                            tick=tick_count,
+                            error_type=type(commit_exc).__name__,
+                            error=str(commit_exc),
+                        )
+                        if sink is not None and hasattr(sink, "post_error"):
+                            _post_error_safe(
+                                sink,
+                                {
+                                    "type": "state_persist_failed",
+                                    "tick": tick_count,
+                                    "message": (
+                                        "scanner state could not be persisted; "
+                                        "tick discarded, state not advanced"
+                                    ),
+                                },
+                                tick_count,
+                            )
+
+                    if committed and sink is not None:
                         try:
                             sink(candidates)
                         except Exception as sink_exc:  # noqa: BLE001
@@ -275,18 +293,14 @@ def run_scaffold(
                                 error=str(sink_exc),
                             )
                 else:
-                    # Non-ok tick (error / timeout / malformed): report it to the
-                    # runtime's errors endpoint via the sink, when supported.
+                    # Non-ok tick (error / timeout / malformed): roll back the
+                    # working buffer (discard the tick's mutations — state not
+                    # advanced) and report to /errors via the sink, when supported.
+                    ctx.state.rollback()
                     if sink is not None and hasattr(sink, "post_error"):
-                        try:
-                            sink.post_error(tick_error or {"type": tick_status})
-                        except Exception as perr:  # noqa: BLE001
-                            log_event(
-                                "scaffold_post_error_failed",
-                                tick=tick_count,
-                                error_type=type(perr).__name__,
-                                error=str(perr),
-                            )
+                        _post_error_safe(
+                            sink, tick_error or {"type": tick_status}, tick_count
+                        )
 
                 log_event(
                     "scaffold_tick_finished",
@@ -297,11 +311,15 @@ def run_scaffold(
                 )
 
             except _TickTimeout as late_exc:
-                # A SIGALRM queued by the OS was delivered after the inner
-                # try/except exited (e.g. during write_state, sink, or log_event).
-                # Absorb it: the tick already did its work; disarm just in case,
-                # log the late arrival, and let the loop continue.
+                # A SIGALRM queued by the OS, delivered after the inner try/except
+                # exited (e.g. during commit, sink, or log_event). Absorb it: the
+                # tick already did its work; disarm, roll back any uncommitted
+                # mutations, log the late arrival, and let the loop continue.
                 _disarm_tick_alarm()
+                try:
+                    ctx.state.rollback()
+                except Exception:  # noqa: BLE001
+                    pass
                 log_event(
                     "scaffold_tick_timeout_late",
                     tick=tick_count,
@@ -328,3 +346,16 @@ def run_scaffold(
         log_event("scaffold_stopping", tick_count=tick_count)
 
     return tick_count
+
+
+def _post_error_safe(sink: Any, error: dict, tick_count: int) -> None:
+    """Call sink.post_error(error), swallowing/logging any failure."""
+    try:
+        sink.post_error(error)
+    except Exception as perr:  # noqa: BLE001
+        log_event(
+            "scaffold_post_error_failed",
+            tick=tick_count,
+            error_type=type(perr).__name__,
+            error=str(perr),
+        )