@senpi/runtime 2.0.2-dev.openclaw-upgrade-mai.20260622175851 → 3.0.0-dev.runtime-phase-2.20260623210537

package/dist/scanners/external/momentum/producer.mjs

@@ -0,0 +1,251 @@
+/**
+ * External momentum producer.
+ *
+ * A standalone momentum scanner that:
+ *   1. Pulls instruments + latest candles from the live Senpi MCP server.
+ *   2. Computes last-vs-prev close % move against configurable thresholds.
+ *   3. Pushes MOMENTUM_BREAKOUT signals into a running runtime via the
+ *      `openclaw senpi external-scanner ingest` CLI command.
+ *
+ * Prereqs:
+ *   - `npm run build` so dist/ is current (used only for the MCP provider bridge).
+ *   - A runtime installed from ./momentum.yaml is running for STRATEGY_ADDRESS.
+ *   - `openclaw` CLI on PATH and authenticated against that runtime.
+ *   - SENPI_API_KEY and SENPI_MCP_URL env vars set.
+ *
+ * Run:  node src/scanners/external/momentum/producer.mjs
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { createSenpiScannerProviders } from "../../../../dist/scanners/index.js";
+import { pushScannerSignals } from "../shared/ingest.mjs";
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+const SENPI_API_KEY = process.env.SENPI_API_KEY;
+const SENPI_MCP_URL = process.env.SENPI_MCP_URL;
+const STRATEGY_ADDRESS = process.env.STRATEGY_ADDRESS;
+const SCANNER_NAME =
+  process.env.EXTERNAL_SCANNER_NAME ?? "external_momentum";
+const OPENCLAW_BIN = process.env.OPENCLAW_BIN ?? "openclaw";
+const SCANNER_ID = "external-momentum-producer";
+
+const config = {
+  timeframe: process.env.TIMEFRAME ?? "1h",
+  minMovePct: numEnv("MIN_MOVE_PCT", 1.5),
+  minDayVolume: numEnv("MIN_DAY_VOLUME", 1_000_000),
+  minLeverage: numEnv("MIN_LEVERAGE", 5),
+  maxCandidates: numEnv("MAX_CANDIDATES", 20),
+  minSignalScore: numEnv("MIN_SIGNAL_SCORE", 0.2),
+};
+
+if (!SENPI_API_KEY || !SENPI_MCP_URL || !STRATEGY_ADDRESS) {
+  console.error(
+    "Missing required env vars. Set SENPI_API_KEY, SENPI_MCP_URL, and STRATEGY_ADDRESS.\n" +
+      "  export SENPI_API_KEY='...'\n" +
+      "  export SENPI_MCP_URL='https://mcp.prod.senpi.ai/mcp'\n" +
+      "  export STRATEGY_ADDRESS='0x...'",
+  );
+  process.exit(1);
+}
+
+function numEnv(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Env ${name} must be a finite number, got "${raw}"`);
+  }
+  return parsed;
+}
+
+// ─── MCP → SenpiToolClient bridge ───────────────────────────────────────────
+
+function createSenpiToolClient(mcpClient) {
+  return {
+    async callTool(name, args) {
+      const result = await mcpClient.callTool({ name, arguments: args });
+
+      if (result.isError) {
+        const errorText =
+          Array.isArray(result.content) &&
+          result.content.length > 0 &&
+          result.content[0].type === "text"
+            ? result.content[0].text
+            : JSON.stringify(result.content);
+        throw new Error(`MCP tool "${name}" returned error: ${errorText}`);
+      }
+
+      if (result.structuredContent !== undefined) {
+        return result.structuredContent;
+      }
+
+      if (Array.isArray(result.content) && result.content.length > 0) {
+        const first = result.content[0];
+        if (first.type === "text") {
+          try {
+            return JSON.parse(first.text);
+          } catch {
+            return first.text;
+          }
+        }
+      }
+
+      return result.content;
+    },
+  };
+}
+
+// ─── Momentum logic ─────────────────────────────────────────────────────────
+// Self-contained port of src/scanners/implementations/momentum.ts. Kept free
+// of any runtime-internal imports.
+
+function clamp01(value) {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+function selectCandidates(instruments, cfg) {
+  const eligible = instruments.filter((inst) => {
+    if (inst.isDelisted) return false;
+    if ((inst.maxLeverage ?? 0) < cfg.minLeverage) return false;
+    const vol = inst.context?.dayNtlVlm ?? 0;
+    return vol >= cfg.minDayVolume;
+  });
+  eligible.sort(
+    (a, b) => (b.context?.dayNtlVlm ?? 0) - (a.context?.dayNtlVlm ?? 0),
+  );
+  return eligible.slice(0, cfg.maxCandidates);
+}
+
+function computeMovePct(series) {
+  if (!series || series.length < 2) return null;
+  const prev = series[series.length - 2]?.close;
+  const last = series[series.length - 1]?.close;
+  if (!Number.isFinite(prev) || !Number.isFinite(last) || prev <= 0) {
+    return null;
+  }
+  return { prev, last, movePct: ((last - prev) / prev) * 100 };
+}
+
+function buildSignal({ instrument, move, timeframe, now }) {
+  const movePct = move.movePct;
+  const absMove = Math.abs(movePct);
+  const direction = movePct > 0 ? "LONG" : "SHORT";
+  // Score scales from 0 at minMovePct to 1 at 5% move, clamped.
+  const score = clamp01((absMove - config.minMovePct) / (5 - config.minMovePct));
+
+  return {
+    scannerId: SCANNER_ID,
+    signalType: "MOMENTUM_BREAKOUT",
+    asset: instrument.name,
+    direction,
+    score,
+    timestamp: now,
+    factors: {
+      breakout: true,
+      large_move: absMove >= 3,
+    },
+    meta: {
+      timeframe,
+      movePct,
+      prev: move.prev,
+      last: move.last,
+      dayNtlVlm: instrument.context?.dayNtlVlm ?? 0,
+      maxLeverage: instrument.maxLeverage,
+    },
+  };
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log(`External momentum producer`);
+  console.log(`  MCP:      ${SENPI_MCP_URL}`);
+  console.log(`  address:  ${STRATEGY_ADDRESS}`);
+  console.log(`  scanner:  ${SCANNER_NAME}`);
+  console.log(`  config:   ${JSON.stringify(config)}`);
+
+  const transport = new StreamableHTTPClientTransport(new URL(SENPI_MCP_URL), {
+    requestInit: { headers: { Authorization: `Bearer ${SENPI_API_KEY}` } },
+  });
+  const mcpClient = new Client({
+    name: "external-momentum",
+    version: "0.0.1",
+  });
+  await mcpClient.connect(transport);
+
+  const providers = createSenpiScannerProviders({
+    client: createSenpiToolClient(mcpClient),
+    logLevel: "warn",
+    cacheTtlMs: { instruments: 0, smData: 0, candles: 0 },
+    candleIntervals: [config.timeframe],
+    maxCandleAssets: config.maxCandidates,
+    retries: 2,
+  });
+
+  try {
+    const instruments = await providers.getInstruments(STRATEGY_ADDRESS);
+    const candidates = selectCandidates(instruments, config);
+    console.log(
+      `\nInstruments: ${instruments.length}, candidates: ${candidates.length}`,
+    );
+
+    if (candidates.length === 0) {
+      console.log("No candidates after filtering — skipping ingest.");
+      return;
+    }
+
+    const candles = await providers.getCandles(STRATEGY_ADDRESS, candidates, {
+      scannerId: SCANNER_ID,
+      preferredAssets: candidates.map((c) => c.name),
+    });
+
+    const now = Date.now();
+    const signals = [];
+    for (const inst of candidates) {
+      const series = candles[inst.name]?.candles?.[config.timeframe];
+      const move = computeMovePct(series);
+      if (!move) continue;
+      if (Math.abs(move.movePct) < config.minMovePct) continue;
+      const signal = buildSignal({
+        instrument: inst,
+        move,
+        timeframe: config.timeframe,
+        now,
+      });
+      if (signal.score < config.minSignalScore) continue;
+      signals.push(signal);
+    }
+
+    console.log(`\nSignals: ${signals.length}`);
+    for (const s of signals) {
+      console.log(
+        `  ${s.asset} ${s.direction} move=${s.meta.movePct.toFixed(2)}% score=${s.score.toFixed(2)}`,
+      );
+    }
+
+    if (signals.length === 0) {
+      console.log("\nNothing to ingest — skipping gateway call.");
+      return;
+    }
+
+    const response = await pushScannerSignals({
+      address: STRATEGY_ADDRESS,
+      scanner: SCANNER_NAME,
+      signals,
+      openclawBin: OPENCLAW_BIN,
+    });
+    console.log("\nIngest response:", JSON.stringify(response));
+  } finally {
+    await transport.close();
+  }
+}
+
+main().catch((error) => {
+  console.error("\nProducer failed:", error.message ?? error);
+  process.exit(1);
+});

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

@@ -1,25 +1,17 @@
-"""Process entry for the scaffold core (v2).
+"""Process entry for the scaffold core.
 
 Usage: python3 -m scaffold <launch-config.json>
 
-The launch config JSON is the FROZEN launcher<->scaffold contract (design §4a).
-This side READS every §4a key the B1 launcher writes and threads them into
-run_scaffold. Hard cut: old key names are gone (`interval` -> `interval_seconds`,
-`params` -> `inputs`).
-
-Required keys (missing => fail loud, non-zero exit):
-    path                            — directory added to sys.path (scanner working dir).
-    entrypoint                      — module name to import from `path`.
-    interval_seconds                — tick cadence in seconds (was `interval`).
-    default_signal_validity_seconds — fallback signal TTL (seconds); no magic default.
-    wallet                          — strategy wallet (-> ctx.wallet).
-    scanner_name                    — this scanner's recipe name (-> ctx.scanner_name).
-
-Optional keys:
-    timeout_seconds                 — per-tick wall-clock budget (default: interval_seconds).
-    state_path                      — JSON state file path (None => no persistence).
-    inputs                          — tunables dict for scan() (was `params`); default {}.
-    state_history_max_count         — state series bound; default 0 = history disabled.
+The launch config JSON must contain:
+    path        — directory added to sys.path (the scanner's working directory).
+    entrypoint  — module name to import from `path`.
+    interval    — seconds between tick starts.
+
+Optional fields:
+    timeout_seconds — per-tick wall-clock budget (default: interval).
+    params          — tunables dict passed to scan() as the first argument.
+    state_path      — path to the JSON state file.
+    max_ticks       — cap on tick count (for tests).
 
 Delivery sink is wired when EXTERNAL_SCANNER_ID and SIGNAL_INGESTION_URL are set in
 the environment. If either is absent the scaffold runs with the default no-op sink
@@ -31,18 +23,15 @@ import os
 import sys
 
 
-def _main(argv=None) -> int:
-    if argv is None:
-        argv = sys.argv
-
-    if len(argv) < 2:
+def _main() -> int:
+    if len(sys.argv) < 2:
         print(
             "Usage: python3 -m scaffold <launch-config.json>",
             file=sys.stderr,
         )
         return 1
 
-    config_path = argv[1]
+    config_path = sys.argv[1]
     try:
         with open(config_path, "r", encoding="utf-8") as fh:
             config = json.load(fh)
@@ -50,43 +39,22 @@ def _main(argv=None) -> int:
         print(f"[scaffold] launch config error: {exc}", file=sys.stderr)
         return 1
 
-    # ---- Required §4a keys: missing => fail loud (no magic default) ----
     try:
         path = config["path"]
         entrypoint = config["entrypoint"]
-        interval = float(config["interval_seconds"])
-        default_signal_validity_seconds = int(config["default_signal_validity_seconds"])
-        wallet = config["wallet"]
-        scanner_name = config["scanner_name"]
+        interval = float(config["interval"])
     except (KeyError, TypeError, ValueError) as exc:
-        print(
-            f"[scaffold] launch config missing/invalid required field: {exc}",
-            file=sys.stderr,
-        )
+        print(f"[scaffold] launch config missing required field: {exc}", file=sys.stderr)
         return 1
 
-    # ---- Optional §4a keys ----
     timeout_seconds = config.get("timeout_seconds")
-    # Hard cut: only `inputs` is read. The legacy `params` key is NOT honored.
-    inputs = config.get("inputs") or {}
+    params = config.get("params") or {}
     state_path = config.get("state_path")
-    state_history_max_count = config.get("state_history_max_count") or 0
-    # Per-signal data{} schema (§4a). None / absent => no scaffold-side validation
-    # (intake still validates authoritatively). A dict turns on early, loud
-    # scaffold-side validation that POSTs a violation to /errors.
-    signal_data_schema = config.get("signal_data_schema")
-    if signal_data_schema is not None and not isinstance(signal_data_schema, dict):
-        signal_data_schema = None
     max_ticks = config.get("max_ticks")
 
-    import scaffold as scaffold_pkg
-    from scaffold import ScanEntrypointError, ScanSignatureError
+    from scaffold import ScanEntrypointError, ScanSignatureError, run_scaffold
     from scaffold.loop_primitives import log_event
 
-    # Resolve run_scaffold via the package symbol so a test stub patched onto the
-    # package (or this module) is picked up.
-    run_scaffold = globals().get("run_scaffold") or scaffold_pkg.run_scaffold
-
     # Build the delivery sink when scanner_id and intake URL are available.
     sink = None
     scanner_id = os.environ.get("EXTERNAL_SCANNER_ID", "").strip()
@@ -99,24 +67,19 @@ def _main(argv=None) -> int:
             post_timeout = float(os.environ.get("SIGNAL_POST_TIMEOUT_SECONDS", "5"))
 
             # Derive journal path from the state file directory when available.
-            journal_path = None
+            journal_path: str | None = None
             if state_path:
-                journal_path = os.path.join(
-                    os.path.dirname(os.path.abspath(state_path)),
+                import os as _os
+                journal_path = _os.path.join(
+                    _os.path.dirname(_os.path.abspath(state_path)),
                     "delivery-journal.jsonl",
                 )
 
-            # §4a threads the per-data-key schema (`signal_data_schema`) to the
-            # scaffold so the envelope validates each signal's `data` scaffold-side
-            # and POSTs a violation to /errors (early, loud feedback). None ⇒ no
-            # scaffold-side validation. The intake still performs authoritative
-            # server-side schema validation regardless (this is additive).
             sink = build_delivery_sink(
                 scanner_id=scanner_id,
                 intake_url=intake_url,
+                interval=interval,
                 journal_path=journal_path,
-                signal_data_schema=signal_data_schema,
-                default_signal_validity_seconds=default_signal_validity_seconds,
                 timeout=post_timeout,
             )
             log_event("delivery_sink_enabled", scanner_id=scanner_id, intake_url=intake_url)
@@ -135,12 +98,8 @@ def _main(argv=None) -> int:
             entrypoint,
             interval=interval,
             timeout_seconds=timeout_seconds,
-            inputs=inputs,
+            params=params,
             state_path=state_path,
-            scanner_name=scanner_name,
-            wallet=wallet,
-            default_signal_validity_seconds=default_signal_validity_seconds,
-            state_history_max_count=state_history_max_count,
             sink=sink,
             max_ticks=max_ticks,
         )

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

@@ -4,9 +4,8 @@ build_delivery_sink(
     *,
     scanner_id: str,
     intake_url: str,
+    interval: float,          # seconds; valid_until default = produced_at + 2*interval
     journal_path: str | None,
-    signal_data_schema: dict | None,        # per-data-key {type, required?}; None = no validation
-    default_signal_validity_seconds: int,   # fallback signal TTL (seconds)
     timeout: float = 5.0,
     clock: Callable[[], float] = time.time,
 ) -> sink
@@ -33,7 +32,6 @@ from __future__ import annotations
 
 import sys
 import time
-import uuid
 from typing import Any, Callable
 
 from .http_post import ERRORS_PATH, SIGNALS_PATH, TransportError, post_json
@@ -49,14 +47,14 @@ def build_delivery_sink(
     *,
     scanner_id: str,
     intake_url: str,
+    interval: float,
     journal_path: str | None,
-    signal_data_schema: dict | None,
-    default_signal_validity_seconds: int,
     timeout: float = 5.0,
     clock: Callable[[], float] = time.time,
 ):
     """Factory: build and return the delivery sink callable."""
 
+    interval_ms = int(interval * 1000)
     journal = Journal(journal_path)
     replayed = [False]  # mutable cell; replay runs once on first invocation
 
@@ -89,35 +87,16 @@ def build_delivery_sink(
             log_event("delivery_dropped_expired", entry_id=entry.id, asset=entry.asset)
         return to_send
 
-    def _on_reject(reason: dict) -> None:
-        """Loud rejection: log AND POST to /errors (design §4 — never a silent drop)."""
-        log_event("delivery_candidate_invalid", **reason)
-        _post_error({"type": "candidate_rejected", **reason})
-
     def _wrap_candidates(candidates, produced_at_ms: int) -> list[tuple]:
-        """Wrap candidates into (signal, entry_id) pairs, skipping invalid ones.
-
-        Schema-rejected candidates are NOT silently dropped: candidate_to_signal
-        calls _on_reject, which logs AND POSTs to /errors.
-        """
+        """Wrap candidates into (signal, entry_id) pairs, skipping invalid ones."""
         result = []
         for c in candidates:
-            # Mint the stable signal_id (the journal eid) up front and thread it
-            # through the envelope so the POSTed signal carries it. record_produced
-            # re-uses this same id as the entry id, so wire signal_id == journal eid.
-            eid = uuid.uuid4().hex
-            sig = candidate_to_signal(
-                c,
-                produced_at_ms,
-                signal_id=eid,
-                signal_data_schema=signal_data_schema,
-                default_signal_validity_seconds=default_signal_validity_seconds,
-                on_reject=_on_reject,
-            )
+            sig = candidate_to_signal(c, produced_at_ms, interval_ms)
             if sig is None:
+                log_event("delivery_candidate_invalid", candidate=repr(c))
                 continue
-            entry_id = journal.record_produced(sig, now_ms=produced_at_ms)
-            result.append((sig, entry_id))
+            eid = journal.record_produced(sig, now_ms=produced_at_ms)
+            result.append((sig, eid))
         return result
 
     def _post_signals(signals: list[dict]) -> tuple[int, Any]:
@@ -146,33 +125,20 @@ def build_delivery_sink(
         if not isinstance(per_signal, list):
             per_signal = []
 
-        # Match per-signal outcomes BY signal_id, NEVER by array position. The wire
-        # signal_id IS the journal entry id, so a pending eid set is the lookup key.
-        # Index-matching would cross-attribute outcomes (asset A's "accepted"
-        # recorded against asset B) under out-of-order or partial responses —
-        # capital-sensitive. Robust to: out-of-order, partial (fewer statuses than
-        # signals), and unknown/missing signal_id (ignored safely, never applied by
-        # position). An unmatched entry stays pending and is retried.
-        pending = set(pending_eids)
-        for sig_status in per_signal:
-            if not isinstance(sig_status, dict):
-                continue
-            eid = sig_status.get("signal_id")
-            # Missing or unknown signal_id: cannot be matched -> ignore safely.
-            if not isinstance(eid, str) or eid not in pending:
-                log_event("delivery_status_unmatched", signal_id=eid)
-                continue
-            st = sig_status.get("status")
-            if st == "accepted":
-                journal.record_outcome(eid, "delivered", correlationId=sig_status.get("correlationId", ""))
-            elif st == "rejected":
-                journal.record_outcome(eid, "rejected", reason=sig_status.get("reason", ""))
-            elif st in ("expired", "superseded"):
-                journal.record_outcome(eid, st)
-            else:
-                # Unknown status — treat as undelivered (no outcome written)
-                log_event("delivery_unknown_status", entry_id=eid, status=st)
-        # Entries with no matching status returned stay pending (retry next tick).
+        for i, eid in enumerate(pending_eids):
+            if i < len(per_signal):
+                sig_status = per_signal[i]
+                st = sig_status.get("status") if isinstance(sig_status, dict) else None
+                if st == "accepted":
+                    journal.record_outcome(eid, "delivered", correlationId=sig_status.get("correlationId", ""))
+                elif st == "rejected":
+                    journal.record_outcome(eid, "rejected", reason=sig_status.get("reason", ""))
+                elif st in ("expired", "superseded"):
+                    journal.record_outcome(eid, st)
+                else:
+                    # Unknown status — treat as undelivered (no outcome written)
+                    log_event("delivery_unknown_status", entry_id=eid, status=st)
+            # If no per-signal status returned for this entry, leave it pending (retry)
 
         return True
 

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 scan(inputs, ctx)."""
+    """scan's call shape is incompatible with scaffold(params, state[, client])."""
 
 
 def add_path_to_sys_path(path: str) -> None:
@@ -32,22 +32,16 @@ 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 module_name in sys.modules:
-            del sys.modules[module_name]
-        return importlib.import_module(module_name)
+        if entrypoint in sys.modules:
+            del sys.modules[entrypoint]
+        return importlib.import_module(entrypoint)
     except Exception as exc:
         raise ScanEntrypointError(
             f"Failed to import entrypoint '{entrypoint}' from '{path}': {exc}"
@@ -73,25 +67,19 @@ def locate_scan(module) -> Callable:
 
 
 def verify_scan_signature(scan: Callable) -> None:
-    """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.
+    """Verify scan's call shape is compatible with scan(params, state[, client]).
 
     Accepted shapes:
-        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(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(*args, **kwargs)                 — fully variadic, accepts anything
 
     Rejected shapes:
         scan()                                — 0 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.
+        scan(params)                          — 1 required
+        scan(a, b, c, d)                      — >=4 fixed required
 
     Raises ScanSignatureError naming the found arity on mismatch.
     """
@@ -106,39 +94,57 @@ 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
+    )
 
-    # Required (non-defaulted) fixed positional params.
-    required_fixed = [
+    # 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 = [
         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
     ]
-    n_required = len(required_fixed)
+    required_fixed = [
+        p for p in fixed_positional
+        if p.default is inspect.Parameter.empty
+    ]
 
-    # 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
+    n_required = len(required_fixed)
+    n_fixed = len(fixed_positional)
 
     if n_required < 2:
         raise ScanSignatureError(
-            f"scan has {n_required} required positional param(s); the v2 contract "
-            f"requires exactly 2 (inputs, ctx). Found arity: {n_required}."
+            f"scan has {n_required} required positional param(s); "
+            f"expected at least 2 (params, state). Found arity: {n_required}."
         )
 
-    if n_required > 2:
+    if n_required >= 4:
         raise ScanSignatureError(
-            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}."
+            f"scan has {n_required} required positional params; "
+            f"expected at most 3 (params, state, client). Found arity: {n_required}."
         )