@senpi/runtime 3.0.9-dev.20260710204324 → 3.0.9-dev.feat-strategy-compos.20260716233548

package/dist/composer/verbs/runtime_validate.py

@@ -0,0 +1,422 @@
+"""runtime_validate — the Zod-oracle stage: judge the emitted runtime.yaml (slice 9 steps 4+5).
+
+Two layers, mirroring where the truth lives:
+
+  1. **Composer POLICY (pure Python, always runs)** — PROTECTION BY DEFAULT. A unit with no
+     ``exit:`` section and no explicit ``unmanaged`` opt-out is RED (CMP120). This is the
+     composer's own rule (the runtime schema legally allows exit-less configs), so it never
+     needs node/dist and runs even when the Zod oracle can't.
+
+  2. **The REAL Zod + DSL oracle (spawned node, needs dist/)** — the emitted runtime.yaml is
+     validated by the exact schema + DSL parser the runtime boots with, via the rim entry
+     ``src/cli/validate-runtime-config.mjs``. Its structured ``{path, message, code}`` issues
+     are mapped to the CMP1xx teaching-error class by the table below. When node or dist is
+     absent (CI runs pytest without ``npm run build``), the oracle is SKIPPED with an actionable
+     reason — NOT RED — so the policy layer still gates and the caller/tests can skip cleanly.
+
+The Python↔node spawn mirrors ``src/cli/composer-commands.ts`` (COMPOSER_NODE bin, dist
+resolution, ``detectEnvError`` actionable one-liner); see design §5.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from composer.validator.errors import Location, TeachingError
+
+# repo root = the dir CONTAINING the `composer/` package (…/composer/verbs/ -> parents[2]).
+_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _dist_dir() -> Path:
+    override = os.environ.get("COMPOSER_RUNTIME_DIST")
+    if override:
+        return Path(override)
+    dev = _ROOT / "dist"
+    if (dev / "runtime" / "runtime-schema.js").is_file():
+        return dev
+    # Shipped package: the composer lives INSIDE the runtime dist (dist/composer/), so
+    # _ROOT *is* the dist dir. runtime/runtime-schema.js under _ROOT is unambiguous — a
+    # dev-checkout root keeps it only under dist/ — so both layouts resolve with no env.
+    if (_ROOT / "runtime" / "runtime-schema.js").is_file():
+        return _ROOT
+    return dev
+
+
+def _rim_entry() -> Optional[Path]:
+    # Candidates track _dist_dir() so COMPOSER_RUNTIME_DIST resolves the rim AND the schema
+    # from the same place end-to-end. On a dist-only claw box the composer ships to
+    # dist/composer/, so _ROOT is the dist dir itself and the rim is _dist_dir()/cli/… —
+    # NOT _ROOT/dist/cli/…; without this the Zod oracle silently skips even with the env set.
+    for cand in (
+        _ROOT / "src" / "cli" / "validate-runtime-config.mjs",   # dev checkout (source)
+        _dist_dir() / "cli" / "validate-runtime-config.mjs",     # built/shipped (honors env)
+    ):
+        if cand.is_file():
+            return cand
+    return None
+
+
+def _node_bin() -> str:
+    return os.environ.get("COMPOSER_NODE", "node")
+
+
+def oracle_available() -> bool:
+    """True when the real Zod+DSL oracle can run (dist built, rim entry present, node on PATH)."""
+    return (
+        (_dist_dir() / "runtime" / "runtime-schema.js").is_file()
+        and _rim_entry() is not None
+        and shutil.which(_node_bin()) is not None
+    )
+
+
+@dataclass
+class RuntimeValidateResult:
+    ok: bool
+    errors: list[TeachingError]
+    skipped: bool = False          # the Zod oracle couldn't run (node/dist absent) — not RED
+    skip_reason: Optional[str] = None
+    oracle_ran: bool = False       # the node oracle actually executed
+    info_messages: list[str] = None  # non-error acknowledgements (e.g. expected ops bindings)
+
+    def __post_init__(self) -> None:
+        if self.info_messages is None:
+            self.info_messages = []
+
+
+# --------------------------------------------------------------------------- CMP1xx mapper
+
+def _map_oracle_issue(path: str, message: str, code: str) -> TeachingError:
+    """Table-driven map of one raw Zod/DSL issue -> a CMP1xx teaching error (design §8).
+
+    Keyed so a NEW Zod message can never produce an unlabelled error: unrecognised issues
+    fall to CMP199 (still located + hinted), never to a bare pass-through."""
+    p = path or ""
+    loc = Location(path=p)
+
+    # F1: misplaced top-level dsl_preset (schema superRefine at runtime-schema.ts:378-395).
+    if code == "custom" and p == "dsl_preset":
+        return TeachingError(
+            "CMP111", "`dsl_preset` is at the top level; the runtime reads only `exit.dsl_preset`.",
+            "Nest the preset under `exit:` — `exit:\\n  dsl_preset:\\n    ...`. The composer "
+            "emits this shape automatically; do not hand-place `dsl_preset`.",
+            loc,
+        )
+
+    # risk block is .strict() — unknown / renamed-legacy key.
+    if code in ("unrecognized_keys",) or (p.startswith("risk") and "renamed" in message):
+        return TeachingError(
+            "CMP101", f"the `risk` block has an unknown/renamed key: {message}",
+            "Use only the v2 keys; `data_retention_hours` -> `data_retention_seconds`, "
+            "`cooldown_minutes` -> `cooldown_seconds`. Let the composer emit the risk block.",
+            loc,
+        )
+
+    # A3 install-time-parity classes. These machine codes are ALSO uppercase, so they MUST be
+    # matched before the generic `code.isupper()` DSL-preset fallback below or they'd map to CMP110.
+
+    # F2: DSL exit active but position-tracking wiring missing/broken (Runtime.start() gate).
+    if code == "DSL_POSITION_TRACKING":
+        return TeachingError(
+            "CMP112", f"the DSL exit is active but position-tracking wiring is missing/broken: {message}",
+            "A DSL-managed unit needs a `position_tracker` scanner AND a `POSITION_TRACKER` action "
+            "whose `scanners:` lists that tracker. The composer emits both automatically; regenerate "
+            "with `composer deploy` rather than removing, renaming, or unwiring them.",
+            loc,
+        )
+
+    # F3: duplicate scanner or action name (loadRuntimeConfig post-Zod assert).
+    if code in ("DUP_SCANNER_NAME", "DUP_ACTION_NAME"):
+        return TeachingError(
+            "CMP113", f"a scanner or action name is duplicated: {message}",
+            "Scanner names and action names must each be unique within one runtime. Rename the "
+            "duplicate; the composer emits unique names, so a collision is a hand-edit.",
+            loc,
+        )
+
+    # F4: unresolvable action decision_prompt placeholder (loadRuntimeConfig post-Zod assert).
+    if code == "UNRESOLVED_PROMPT_PLACEHOLDER":
+        return TeachingError(
+            "CMP114", f"an action `decision_prompt` references an unresolvable placeholder: {message}",
+            "Every {{placeholder}} must be provided by a declared context entry (signal_<scanner>, "
+            "context_<scanner>, strategy_<value>, asset_trend_<value>) or a param. The composer emits "
+            "rule-mode actions with no prompt, so a stray placeholder is a hand-edit.",
+            loc,
+        )
+
+    # DSL preset parse errors (uppercase DSL codes) — breaches, tier order, preset config.
+    if code.isupper() and code not in ("", None):
+        return TeachingError(
+            "CMP110", f"the exit DSL preset is invalid: {message} ({code}).",
+            "Use a named preset (protected_standard | protected_tight | protected_wide); its "
+            "phase1/phase2 always parse. If you edited the tiers, keep trigger_pct ascending "
+            "and consecutive_breaches_required an integer >= 1.",
+            loc,
+        )
+
+    # Missing required top-level field.
+    if p in ("name", "strategy", "strategy.wallet") and code in ("invalid_type", "too_small", "invalid_string"):
+        return TeachingError(
+            "CMP100", f"missing/invalid required runtime field `{p}`: {message}",
+            "`name` (non-empty) and `strategy.wallet` (a `${...}` env placeholder) are "
+            "mandatory. The composer binds both from the strategy id.",
+            loc,
+        )
+
+    # guard_rails range issue.
+    if p.startswith("risk.guard_rails") and code in ("too_small", "too_big"):
+        return TeachingError(
+            "CMP102", f"a `risk.guard_rails` value is out of range: {message}",
+            "Respect the field bounds (e.g. drawdown_halt_pct 0–100, cooldown_seconds >= 60). "
+            "The composer's presets stay in-bounds; a risk knob override must too.",
+            loc,
+        )
+
+    # Anything else the schema rejected — still labelled + located.
+    return TeachingError(
+        "CMP199", f"runtime.yaml failed schema validation at `{p or '(root)'}`: {message} [{code}].",
+        "Regenerate the runtime.yaml with `composer deploy` (it emits a Zod-valid unit); if "
+        "you hand-edited it, revert the offending field to the composer's shape.",
+        loc,
+    )
+
+
+# --------------------------------------------------------------------------- placeholder policy
+
+# Mirrors src/runtime/env-resolve.ts VAR_PATTERN exactly: ${VAR} and ${VAR:-default}.
+_ENV_VAR_PATTERN = re.compile(r"\$\{([^}:]+)(?::-([^}]*))?\}")
+
+
+def _iter_strings(obj):
+    """Yield every string VALUE in a parsed-YAML object (mirrors resolveEnvInObject's walk —
+    values only, never keys or comments; env resolution never touches those)."""
+    if isinstance(obj, str):
+        yield obj
+    elif isinstance(obj, dict):
+        for v in obj.values():
+            yield from _iter_strings(v)
+    elif isinstance(obj, (list, tuple)):
+        for v in obj:
+            yield from _iter_strings(v)
+
+
+def _placeholder_policy(yaml_text: str) -> tuple[list[TeachingError], list[str]]:
+    """CMP115 policy: unbound ``${VAR}`` scan (pure Python, runs even when the oracle is skipped).
+
+    The real loader resolves env BEFORE Zod (load-runtime-config.ts:237 -> resolveEnvInObject),
+    turning any UNSET ``${VAR}`` into ``""`` (env-resolve.ts:16-20) — an install-time failure the
+    Zod rim can't see because it validates the raw, unresolved YAML. So this string-level scan
+    lives on the Python side (where the loader's pre-Zod substitution conceptually happens).
+
+    Policy: the sanctioned ops binding class ``${..._WALLET}`` (the composer emits exactly one,
+    ``strategy.wallet``; deploy binds it) is ACKNOWLEDGED, not flagged. ``${VAR:-default}`` is
+    safe (never resolves empty). Every other bare ``${VAR}`` is CMP115.
+
+    Returns ``(errors, acknowledged_bindings)``.
+    """
+    try:
+        import yaml
+
+        doc = yaml.safe_load(yaml_text)
+    except Exception:  # noqa: BLE001 — a YAML/parse defect is surfaced by the oracle, not here
+        return [], []
+
+    errors: list[TeachingError] = []
+    acknowledged: list[str] = []
+    seen_err: set[str] = set()
+    seen_ack: set[str] = set()
+    for s in _iter_strings(doc):
+        for m in _ENV_VAR_PATTERN.finditer(s):
+            name, default = m.group(1), m.group(2)
+            token = m.group(0)
+            if default is not None:
+                continue  # ${VAR:-default} always resolves to something non-empty
+            if name.endswith("_WALLET"):
+                if token not in seen_ack:
+                    seen_ack.add(token)
+                    acknowledged.append(token)
+                continue
+            if token in seen_err:
+                continue
+            seen_err.add(token)
+            errors.append(
+                TeachingError(
+                    "CMP115",
+                    f"unbound env placeholder `{token}` would resolve to empty (\"\") at install.",
+                    "Only the `${<STRATEGY>_WALLET}` placeholder is bound by ops at deploy; every "
+                    "other `${VAR}` is substituted with \"\" at load time and breaks the config. "
+                    "Remove it, hard-code the value, or give it a default (`${VAR:-default}`). The "
+                    "composer emits only the wallet placeholder.",
+                    Location(path=""),  # a value-level defect; no single Zod dot-path locates it
+                )
+            )
+    return errors, acknowledged
+
+
+def bare_env_placeholders(yaml_text: str) -> list[str]:
+    """Every bare ``${VAR}`` (no ``:-default``) string token in the YAML VALUES, deduped in
+    first-seen order.
+
+    STRICTER than :func:`_placeholder_policy`: this counts ``${..._WALLET}`` too. It is the
+    post-bind gate for ``composer install`` — after the deploy-time wallet placeholder is bound
+    to a real address, ANY remaining bare ``${VAR}`` (wallet or not) would resolve to ``""`` at
+    load and is an error. ``${VAR:-default}`` stays exempt (never resolves empty)."""
+    try:
+        import yaml
+
+        doc = yaml.safe_load(yaml_text)
+    except Exception:  # noqa: BLE001 — a YAML defect is the oracle's job to surface, not this scan
+        return []
+    seen: set[str] = set()
+    out: list[str] = []
+    for s in _iter_strings(doc):
+        for m in _ENV_VAR_PATTERN.finditer(s):
+            if m.group(2) is not None:
+                continue  # ${VAR:-default} always resolves non-empty
+            token = m.group(0)
+            if token not in seen:
+                seen.add(token)
+                out.append(token)
+    return out
+
+
+def _run_node_oracle(runtime_yaml_path: Path) -> RuntimeValidateResult:
+    """Judge a runtime.yaml for INSTALLABILITY: the CMP115 unbound-placeholder policy (pure
+    Python, always) + the real Zod+DSL+install-parity oracle (spawned node; SKIPPED not RED when
+    node/dist absent). The placeholder policy is folded in here so BOTH entry points (``check``
+    via temp file and deploy via the staged file) enforce it identically, even on a skip."""
+    ph_errors, acknowledged = ([], [])
+    try:
+        text = runtime_yaml_path.read_text(encoding="utf-8")
+        ph_errors, acknowledged = _placeholder_policy(text)
+    except OSError:
+        pass  # unreadable file is reported by the oracle's own read path below
+
+    res = _run_zod_oracle(runtime_yaml_path)
+    if ph_errors:
+        res.errors = ph_errors + res.errors
+        res.ok = not res.errors
+    if acknowledged:
+        res.info_messages.append(
+            "expected ops bindings (not errors; deploy binds these): " + ", ".join(acknowledged)
+        )
+    return res
+
+
+def _run_zod_oracle(runtime_yaml_path: Path) -> RuntimeValidateResult:
+    """Spawn the node Zod+install-parity oracle over a runtime.yaml file. Returns SKIPPED (not
+    RED) when the node/dist environment is absent (mirrors composer-commands.ts detectEnvError)."""
+    dist = _dist_dir()
+    schema_js = dist / "runtime" / "runtime-schema.js"
+    rim = _rim_entry()
+    if not schema_js.is_file():
+        return RuntimeValidateResult(
+            ok=True, errors=[], skipped=True,
+            skip_reason=(
+                f"Zod oracle skipped: runtime dist not built ({schema_js} absent). "
+                f"Run `npm run build`, or set COMPOSER_RUNTIME_DIST. Protection policy still enforced."
+            ),
+        )
+    if rim is None:
+        return RuntimeValidateResult(
+            ok=True, errors=[], skipped=True,
+            skip_reason="Zod oracle skipped: rim entry validate-runtime-config.mjs not found under src/cli or dist/cli.",
+        )
+    node = _node_bin()
+    if shutil.which(node) is None:
+        return RuntimeValidateResult(
+            ok=True, errors=[], skipped=True,
+            skip_reason=f"Zod oracle skipped: '{node}' not on PATH (set COMPOSER_NODE). Protection policy still enforced.",
+        )
+    try:
+        proc = subprocess.run(
+            [node, str(rim), str(runtime_yaml_path), str(dist)],
+            capture_output=True, text=True, timeout=60,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return RuntimeValidateResult(
+            ok=True, errors=[], skipped=True,
+            skip_reason=f"Zod oracle skipped: node spawn failed ({exc}).",
+        )
+    try:
+        verdict = json.loads(proc.stdout.strip().splitlines()[-1]) if proc.stdout.strip() else {}
+    except (json.JSONDecodeError, IndexError):
+        return RuntimeValidateResult(
+            ok=True, errors=[], skipped=True,
+            skip_reason=f"Zod oracle skipped: unparseable output (stderr: {proc.stderr.strip()[:200]}).",
+        )
+    if verdict.get("env_absent"):
+        return RuntimeValidateResult(
+            ok=True, errors=[], skipped=True,
+            skip_reason=f"Zod oracle skipped: {verdict.get('message', 'runtime dist not importable')}.",
+        )
+    if verdict.get("ok"):
+        return RuntimeValidateResult(ok=True, errors=[], oracle_ran=True)
+    errors = [
+        _map_oracle_issue(e.get("path", ""), e.get("message", ""), e.get("code", ""))
+        for e in verdict.get("errors", [])
+    ]
+    return RuntimeValidateResult(ok=not errors, errors=errors, oracle_ran=True)
+
+
+def validate_runtime_yaml_file(path) -> RuntimeValidateResult:
+    """Run ONLY the Zod oracle over an existing runtime.yaml file (deploy uses this to prove
+    the staged unit validates). The policy layer lives in ``check_runtime_unit``."""
+    return _run_node_oracle(Path(path))
+
+
+def _protection_policy_error(answers) -> Optional[TeachingError]:
+    """CMP120: PROTECTION BY DEFAULT. A unit with no exit and no explicit opt-out is RED.
+
+    The composer always resolves a preset, so an emitted unit is protected unless the author
+    deliberately set ``unmanaged``. This gate exists so that opt-out is a conscious, logged
+    choice — never an accident of an absent field."""
+    if getattr(answers, "unmanaged", False):
+        return None
+    if not getattr(answers, "exit_preset", None):
+        return TeachingError(
+            "CMP120",
+            "this strategy would run UNMANAGED — no exit protection — but you did not opt out.",
+            "Set an exit_preset (protected_standard | protected_tight | protected_wide) to "
+            "protect open positions, OR pass `unmanaged=true` to deliberately opt out (a loud "
+            "warning is emitted). Protection is the default; opting out must be explicit.",
+            Location(path="exit"),
+        )
+    return None
+
+
+def check_runtime_unit(answers) -> tuple[RuntimeValidateResult, list[TeachingError]]:
+    """The full ``check`` runtime_validate stage: PROTECTION policy (CMP120, always) + the
+    real Zod+DSL oracle over the emitted runtime.yaml. Returns ``(oracle_result, policy_errors)``.
+
+    Emits the runtime.yaml to a temp file (the artifact the oracle judges is exactly what
+    deploy stages). When ``unmanaged`` is set, a warning is surfaced by the caller, not an error.
+    """
+    import tempfile
+
+    from composer.authoring.runtime_emit import render_runtime_yaml
+
+    policy_errors: list[TeachingError] = []
+    err = _protection_policy_error(answers)
+    if err is not None:
+        policy_errors.append(err)
+
+    text = render_runtime_yaml(answers)
+    with tempfile.NamedTemporaryFile("w", suffix=".runtime.yaml", delete=False, encoding="utf-8") as fh:
+        fh.write(text)
+        tmp = fh.name
+    try:
+        oracle = _run_node_oracle(Path(tmp))
+    finally:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+    return oracle, policy_errors

package/dist/composer/verbs/smoke.py

@@ -0,0 +1,134 @@
+"""smoke — the fixture-smoke stage of ``composer check`` (promoted from the pytest fixtures).
+
+``composer check`` must prove the emitted ``scan.py`` doesn't merely compile but IMPORTS and
+RUNS: a graph can typecheck yet still blow up on the first tick (a bad primitive call, a
+port wired to the wrong shape). The slice-3 golden tests already exercised this through
+``python-tests/composer/fixtures/composed.py`` (a real scaffold ``ScanContext`` +
+``StateManager`` + a fake MCP), but that machinery lived under the test tree. This module
+promotes the MINIMAL slice of it into ``composer/`` proper so ``check`` runs the same smoke
+OUTSIDE pytest:
+
+    * import the emitted module (exec the compiled source as a live module),
+    * build a real frozen ``ScanContext`` over a temp ``StateManager`` and a benign stub MCP
+      (``StubMcp`` — every corpus read returns ``None`` / empty, which every source
+      normalizer tolerates by dropping the asset; the tick therefore runs clean and returns
+      ``[]``),
+    * call ``scan(inputs, ctx)`` ONCE and assert it returns a list.
+
+The point is liveness, not correctness (correctness is the golden tests): a green smoke
+means "this artifact loads and one tick executes end-to-end without raising". ``scaffold``
+is made importable the same way the pytest run does it (pyproject ``pythonpath`` =
+``src/scanners/external``) by putting that dir on ``sys.path`` — via
+:mod:`composer.scaffold_path`, which resolves it in BOTH the dev checkout (``src/scanners/
+external``) and the claw dist install (``dist/scanners/external``, no ``src/`` segment) with no
+manual ``PYTHONPATH``, honoring a ``COMPOSER_SCAFFOLD_DIR`` override. So the verb works when
+invoked as a plain CLI with no pytest/conftest in the picture, on either layout.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import sys
+import tempfile
+import uuid
+from pathlib import Path
+
+from composer.scaffold_path import ScaffoldNotFound, ensure_scaffold_on_syspath
+from composer.vendoring import emitted_scan_on_syspath
+
+# Best-effort: put `scaffold` on sys.path at import time when it resolves. The AUTHORITATIVE
+# resolution (and the teaching failure when it is genuinely absent) happens in run_smoke, so a
+# missing scaffold surfaces as a RED smoke stage — never a bare `No module named 'scaffold'`
+# that misleads the reader toward the unrelated PyPI `scaffold` package.
+with contextlib.suppress(ScaffoldNotFound):
+    ensure_scaffold_on_syspath()
+
+
+class StubMcp:
+    """A benign ``ctx.senpi_mcp``: every corpus read returns ``None``.
+
+    Source normalizers (``composer.primitives.sources``) all treat a falsy/None response as
+    "drop this asset", and the adapter swallows read errors — so a tick over this stub runs
+    to completion and emits nothing. That is exactly the liveness signal smoke wants: the
+    emitted code's control flow executes over empty-but-valid data without raising.
+    """
+
+    def __init__(self) -> None:
+        self.calls: list = []
+
+    def call_tool(self, name: str, args: dict):
+        self.calls.append((name, args))
+        return None
+
+
+class SmokeError(Exception):
+    """The emitted module failed to import or its first ``scan()`` tick raised/misbehaved."""
+
+
+def _import_scan(source: str, module_name: str):
+    """Exec the compiled ``scan.py`` source as a live module; return its ``scan`` callable.
+
+    The emitted module imports ``strategy_primitives`` (the vendored snapshot), so smoke stages
+    that package beside the temp ``scan.py`` and puts the dir on ``sys.path`` — the on-box
+    scanner-dir layout — via :func:`composer.vendoring.emitted_scan_on_syspath`. This is what
+    makes smoke exercise the SAME self-contained artifact `deploy` stages.
+    """
+    with tempfile.TemporaryDirectory(prefix="composer-smoke-") as tmp:
+        with emitted_scan_on_syspath(source, tmp, module_filename=f"{module_name}.py") as path:
+            spec = importlib.util.spec_from_file_location(module_name, path)
+            module = importlib.util.module_from_spec(spec)
+            # Register so a traceback inside scan() can resolve the module frame.
+            sys.modules[module_name] = module
+            try:
+                spec.loader.exec_module(module)
+            except Exception as exc:  # noqa: BLE001 — surfaced as a teaching-shaped smoke failure
+                raise SmokeError(f"emitted module failed to import: {exc!r}") from exc
+            finally:
+                sys.modules.pop(module_name, None)
+            scan = getattr(module, "scan", None)
+            if not callable(scan):
+                raise SmokeError("emitted module has no callable `scan(inputs, ctx)`.")
+            return scan
+
+
+def run_smoke(scan_source: str, *, scanner_name: str = "composer-smoke") -> dict:
+    """Import the emitted source and run one ``scan()`` tick over a stub ctx.
+
+    Returns a small detail dict (``{signals, mcp_calls}``) on success; raises
+    :class:`SmokeError` if import fails, the tick raises, or the return is not a list.
+    """
+    # Resolve `scaffold` across dev-checkout and claw-dist layouts BEFORE importing it, so a
+    # missing harness is a teaching-shaped RED smoke stage (naming the build step / env var and
+    # warning off `pip install scaffold`) rather than an opaque `No module named 'scaffold'`.
+    try:
+        ensure_scaffold_on_syspath()
+    except ScaffoldNotFound as exc:
+        raise SmokeError(str(exc)) from exc
+    from scaffold.ctx import ScanContext
+    from scaffold.state_manager import StateManager
+
+    module_name = f"composer_smoke_{uuid.uuid4().hex}"
+    scan = _import_scan(scan_source, module_name)
+
+    with tempfile.TemporaryDirectory(prefix="composer-smoke-state-") as tmp:
+        state = StateManager(str(Path(tmp) / "state.json"), state_history_max_count=50)
+        mcp = StubMcp()
+        ctx = ScanContext(
+            state=state,
+            wallet="0xSMOKE",
+            scanner_name=scanner_name,
+            interval_seconds=3600,
+            senpi_mcp=mcp,
+        )
+        try:
+            result = scan({}, ctx)
+        except Exception as exc:  # noqa: BLE001
+            raise SmokeError(f"first scan() tick raised {exc!r}.") from exc
+
+    if not isinstance(result, list):
+        raise SmokeError(
+            f"scan() returned {type(result).__name__}, expected list[dict] (the "
+            f"external_scanner contract)."
+        )
+    return {"signals": len(result), "mcp_calls": len(mcp.calls)}