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

package/dist/composer/verbs/install.py

@@ -0,0 +1,586 @@
+"""install — bind a staged unit onto a box and hand it to the frozen consumer (slice A2).
+
+``composer deploy`` STAGES a complete, standalone, pristine unit (placeholder wallet intact).
+``composer install <target> --wallet 0x…`` is the step that actually puts one instance of that
+unit onto THIS box and starts it, without changing anything the runtime/gateway already does
+(the ``openclaw senpi runtime create`` path is FROZEN — this verb only feeds it).
+
+Five steps, each derivable from disk afterwards (resumable-by-artifact; no hidden state):
+
+  (a) PREFLIGHT — resolve the staged tree, verify every staged artifact's bytes against
+      ``manifest.json`` (tamper/hand-edit detection, CMP201), and confirm the recorded oracle
+      verdict is GREEN (VALID; a SKIPPED verdict from an oracle-less box is allowed, INVALID is
+      CMP202). "GREEN means installable" — this is the install-time reuse of the deploy oracle.
+
+  (b) COPY to the CANONICAL, CONTENT-ADDRESSED, IMMUTABLE dir
+      ``<state>/strategies/<strategy>/<hash8>/`` — write to a temp sibling, verify every copied
+      file against the manifest hash (CMP203), then atomic-rename into place. The dir is NEVER
+      edited after it lands, so the frozen inline-YAML in the registry can never drift from the
+      scan.py re-read off disk on a scaffold respawn. ``hash8`` = the content identity of the
+      PRISTINE staged unit (see :func:`compute_hash8`), so identical content always maps to the
+      same dir and a re-install is an idempotent no-op.
+
+  (c) WALLET BIND — substitute the real ``--wallet`` for the ``${..._WALLET}`` placeholder in the
+      COPIED ``main/runtime.yaml`` ONLY (the staged source stays pristine, placeholder intact),
+      record the binding in ``install.json`` beside the copied tree, and re-run the placeholder
+      policy on the bound YAML: after binding, ANY remaining bare ``${VAR}`` is an error (CMP115).
+
+  (d) INVOKE the frozen consumer through an INJECTABLE SEAM (``create_fn``): in production it
+      shells out to ``openclaw senpi runtime create -p <hashdir>/main/runtime.yaml`` (PATH mode —
+      never ``--content``, which would drop the scanner dir the external scanner needs); tests
+      fake it.
+
+  (e) VERIFY + REPORT — map the known installRuntime failure classes (duplicate id,
+      one-runtime-per-wallet, wallet not ACTIVE, YAML invalid, entrypoint missing) to
+      teaching-shaped errors telling the user exactly what to do next (CMP210-219).
+
+Scope (phase 1): the agent supplies ``--wallet``; wallet creation/funding is OUT. The
+update/reinstall flow (delete + create) is OUT beyond the teaching error that names the delete
+command. No wall-clock is baked in: the binding timestamp is an injected value (``bound_at``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+from composer.validator.errors import Location, TeachingError
+from composer.validator.loader import load_graph
+
+from . import _box
+from ._box import McpFn
+from .runtime_validate import bare_env_placeholders
+
+INSTALLED = "INSTALLED"
+ALREADY_INSTALLED = "ALREADY_INSTALLED"
+REFUSED = "REFUSED"
+FAILED = "FAILED"
+
+INSTALL_JSON = "install.json"
+REGISTRY_FILENAME = "installed_runtimes.json"
+
+# The ops-bound placeholder the composer emits (exactly one, at strategy.wallet). Mirrors
+# composer/authoring/runtime_emit.py::_env_wallet — ${<SLUG>_WALLET}.
+_WALLET_TOKEN = re.compile(r"\$\{[A-Za-z0-9_]+_WALLET\}")
+# A 0x… EVM address (light format gate; ownership is the gateway's job, best-effort).
+_WALLET_ADDR = re.compile(r"^0x[0-9a-fA-F]{40}$")
+
+
+# --------------------------------------------------------------------------- injectable seam
+
+@dataclass
+class CreateResult:
+    """What the frozen ``openclaw senpi runtime create`` consumer returned. The seam yields
+    this so the mapper reads exit code + text without knowing HOW it was produced."""
+
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+    @property
+    def text(self) -> str:
+        return f"{self.stdout}\n{self.stderr}"
+
+
+CreateFn = Callable[[str, str], CreateResult]
+
+
+def _default_create(runtime_yaml_path: str, runtime_id: str) -> CreateResult:
+    """Production seam: shell out to the FROZEN consumer in PATH mode (never --content — the
+    external scanner needs the recipe dir the -p path carries; index.ts:1088, senpi-commands.ts:94).
+    Captures stdout/stderr so the verdict is parsed truthfully rather than inherited to the tty."""
+    openclaw = os.environ.get("OPENCLAW_BIN", "openclaw")
+    proc = subprocess.run(  # noqa: S603 — fixed argv, no shell
+        [openclaw, "senpi", "runtime", "create", "-p", runtime_yaml_path, "--runtime-id", runtime_id],
+        capture_output=True,
+        text=True,
+    )
+    return CreateResult(proc.returncode, proc.stdout or "", proc.stderr or "")
+
+
+# --------------------------------------------------------------------------- content identity
+
+def compute_hash8(manifest: dict) -> str:
+    """The content identity of a PRISTINE staged unit: the first 8 hex chars of a sha256 over the
+    manifest ``artifacts`` map (sorted ``relpath\\0filesha\\n`` — the same stable aggregation
+    deploy uses for ``manifest.primitives.sha256``, but over EVERY artifact).
+
+    Deterministic and wallet-independent: the staged runtime.yaml carries the ``${..._WALLET}``
+    PLACEHOLDER, not a wallet, so authoring the same unit always yields the same hash8 → the same
+    immutable on-box dir → an idempotent re-install. Binding a wallet mutates only the COPY, never
+    this identity."""
+    import hashlib
+
+    artifacts = manifest.get("artifacts") or {}
+    h = hashlib.sha256()
+    for rel in sorted(artifacts):
+        h.update(rel.encode("utf-8"))
+        h.update(b"\0")
+        h.update(str(artifacts[rel]).encode("utf-8"))
+        h.update(b"\n")
+    return h.hexdigest()[:8]
+
+
+def _sha256_file(path: Path) -> str:
+    import hashlib
+
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def derive_runtime_id(strategy: str, hash8: str) -> str:
+    """``<strategy>-<hash8>`` sanitized to the registry's id charset (mirrors
+    strategy-registry.ts::sanitizeId: [A-Za-z0-9_-], collapse repeats, ≤64).
+
+    Content-keyed on purpose: the SAME staged content always derives the SAME id, so a duplicate
+    is meaningful ("this exact strategy version is already installed") and the whole verb is
+    resumable-by-artifact. installRuntime re-sanitizes, so this is already its final form."""
+    raw = f"{strategy}-{hash8}"
+    out = re.sub(r"[^A-Za-z0-9_-]", "_", raw)
+    out = re.sub(r"_+", "_", out).lstrip("_")
+    return (out or "runtime")[:64]
+
+
+# --------------------------------------------------------------------------- result
+
+@dataclass
+class InstallResult:
+    target: str
+    verdict: str
+    wallet: str
+    hash8: Optional[str] = None
+    runtime_id: Optional[str] = None
+    canonical_dir: Optional[str] = None
+    errors: list[TeachingError] = field(default_factory=list)
+    message: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.verdict in (INSTALLED, ALREADY_INSTALLED)
+
+    def to_json(self) -> dict:
+        return {
+            "verb": "install",
+            "target": self.target,
+            "verdict": self.verdict,
+            "wallet": self.wallet,
+            "hash8": self.hash8,
+            "runtime_id": self.runtime_id,
+            "canonical_dir": self.canonical_dir,
+            "error_count": len(self.errors),
+            "errors": [e.to_dict() for e in self.errors],
+            "message": self.message,
+        }
+
+    def render(self) -> str:
+        head = f"{self.verdict}: {self.target}"
+        lines = [head]
+        if self.hash8:
+            lines.append(f"  hash8      : {self.hash8}")
+        if self.runtime_id:
+            lines.append(f"  runtime id : {self.runtime_id}")
+        if self.canonical_dir:
+            lines.append(f"  on-box dir : {self.canonical_dir}")
+        if self.wallet:
+            lines.append(f"  wallet     : {self.wallet}")
+        if self.message:
+            lines.append(f"  {self.message}")
+        for e in self.errors:
+            lines.append(e.render())
+        return "\n".join(lines) + "\n"
+
+
+def _refused(target: str, wallet: str, error: TeachingError, **kw) -> InstallResult:
+    return InstallResult(target=target, verdict=REFUSED, wallet=wallet, errors=[error],
+                         message=error.message, **kw)
+
+
+# --------------------------------------------------------------------------- target resolution
+
+def _resolve_staged(target: str, out_dir: Optional[str]) -> Optional[Path]:
+    """Resolve ``target`` into the staged tree dir (the dir containing ``manifest.json``).
+
+    Accepts either the staged package dir directly, OR a graph source file plus ``--out`` — then
+    the staged tree is ``<out>/<strategy>`` (matching deploy's layout). Returns None if no staged
+    manifest is found (CMP200)."""
+    p = Path(target)
+    if p.is_dir() and (p / "manifest.json").is_file():
+        return p
+    if p.is_file() and out_dir is not None:
+        try:
+            doc, _ = load_graph(p.read_text(encoding="utf-8"))
+            strategy = str((doc.get("metadata") or {}).get("strategy")
+                           or p.stem.replace(".graph", ""))
+        except Exception:  # noqa: BLE001
+            strategy = p.stem.replace(".graph", "")
+        candidate = Path(out_dir) / strategy
+        if (candidate / "manifest.json").is_file():
+            return candidate
+    return None
+
+
+def _auto_bind_wallet(target: str, out_dir: Optional[str], base_state_dir: str,
+                      mcp_fn: McpFn) -> tuple[str, Optional[TeachingError]]:
+    """Resolve a wallet WITHOUT an explicit ``--wallet``: read the strategy's ``wallet.json``
+    (written by ``composer fund``) and bind it ONLY if MCP confirms the strategy is ACTIVE.
+
+    Returns ``(wallet, None)`` on a confirmed ACTIVE wallet, or ``("", TeachingError)`` otherwise
+    (CMP206 for missing / pending / stale / unverifiable; CMP223 when MCP creds are absent)."""
+    # Imported lazily to avoid an import cycle (fund/close import install at module load).
+    from ._box import LIVE_STATUSES, McpCredsMissing, McpError
+    from .close import _find_list, _strat_id, _strat_status, _strat_wallet
+    from .fund import _match_strategy, _read_wallet_json, wallet_json_path
+
+    def _cmp206(msg: str, fix: str) -> tuple[str, TeachingError]:
+        return "", TeachingError("CMP206", msg, fix, Location())
+
+    staged = _resolve_staged(target, out_dir)
+    if staged is None:
+        return _cmp206(
+            "`--wallet` was omitted and the target is not a staged unit (no manifest.json found).",
+            "Pass `--wallet 0x…`, or point at a `composer deploy` staging dir (plus `-o` if the "
+            "target is a graph file) so the strategy's wallet.json can be located.",
+        )
+    try:
+        manifest = json.loads((staged / "manifest.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        manifest = {}
+    strategy = str(manifest.get("strategy") or staged.name)
+    wj = wallet_json_path(base_state_dir, strategy)
+    rec = _read_wallet_json(wj)
+    if rec is None:
+        return _cmp206(
+            f"`--wallet` was omitted and no funded wallet.json exists for {strategy!r}.",
+            f"Run `composer fund <target> --budget N` first (it creates + funds the wallet and "
+            f"writes {wj}), then re-run `composer install` to auto-bind it — or pass `--wallet 0x…` "
+            f"explicitly.",
+        )
+    rec_wallet = str(rec.get("wallet") or "")
+    rec_sid = rec.get("strategyId")
+    try:
+        strategies = _find_list(mcp_fn("strategy_list", status=LIVE_STATUSES), "strategies")
+    except McpCredsMissing as e:
+        return "", TeachingError(
+            "CMP223", f"MCP credentials missing: {e}",
+            "Set SENPI_AUTH_TOKEN or SENPI_API_KEY (and optionally SENPI_MCP_URL) — auto-binding "
+            "a wallet.json requires MCP to confirm the strategy is ACTIVE. Or pass `--wallet 0x…`.",
+            Location(),
+        )
+    except McpError:
+        return _cmp206(
+            f"`--wallet` was omitted; could not reach MCP to confirm {strategy!r} is ACTIVE.",
+            "Re-run once MCP is reachable, or pass `--wallet 0x…` explicitly.",
+        )
+    s = _match_strategy(strategies, rec_sid, rec_wallet)
+    status = str(_strat_status(s) or "").upper() if s else ""
+    addr = str(_strat_wallet(s) or "") if s else ""
+    if status == "ACTIVE" and (addr or rec_wallet):
+        return (addr or rec_wallet), None
+    if s is not None and status:
+        return _cmp206(
+            f"the wallet.json for {strategy!r} exists but its strategy is not ACTIVE (status "
+            f"{status}).",
+            "Run `composer fund <target> --budget N` to poll it to ACTIVE (idempotent), then "
+            "re-run `composer install`. Explicit `--wallet 0x…` bypasses this check.",
+        )
+    return _cmp206(
+        f"the wallet.json for {strategy!r} is stale — its strategy is not in your active set.",
+        f"It was likely closed. Delete the stale marker `{wj}` and run `composer fund <target> "
+        f"--budget N` for a fresh wallet, then re-run `composer install`.",
+    )
+
+
+# --------------------------------------------------------------------------- installRuntime mapper
+
+def _map_create_failure(res: CreateResult) -> TeachingError:
+    """Map a FROZEN-consumer failure to a teaching error by matching the stable substrings the
+    installRuntime RPC emits (src/index.ts:1074-1347). Order matters — the most specific class
+    first — so a generic fallback (CMP219) only catches genuinely unrecognised failures."""
+    t = res.text
+    if "already exists" in t and "runtime with id" in t:
+        return TeachingError(
+            "CMP210", "a runtime with this id already exists on the box.",
+            "This exact strategy version is already installed. Tear it down first with "
+            "`composer close <strategy>` (the sanctioned path — it stops the runtime, flattens "
+            "positions, and returns funds), then re-install. The update/reinstall flow is out of "
+            "phase-1 scope.",
+            Location(),
+        )
+    if "is already running" in t:
+        return TeachingError(
+            "CMP211", "a runtime for this wallet is already running (one running runtime per wallet).",
+            "The box allows ONE running runtime per wallet. Tear the existing one down with "
+            "`composer close <strategy>` (stops the runtime, flattens positions, returns funds), "
+            "then re-install. Its id is in the message above and in `openclaw senpi runtime list`.",
+            Location(),
+        )
+    if "was not found in your Senpi account" in t or "requires ACTIVE status" in t or "has status" in t:
+        return TeachingError(
+            "CMP212", "the strategy wallet is not ACTIVE (or not found in your Senpi account).",
+            "A runtime can only bind an ACTIVE strategy wallet. Call the MCP tool `strategy_list` "
+            "and use a wallet whose status is ACTIVE for `--wallet`; if it is still initializing, "
+            "wait for it to reach ACTIVE and retry.",
+            Location(),
+        )
+    if "entrypoint not found" in t:
+        return TeachingError(
+            "CMP214", "the external-scanner entrypoint (scan.py) was not found on disk.",
+            "The canonical hash dir is missing its scan module. This should not happen after a "
+            "verified copy — re-run `composer install` (the copy is re-verified against the "
+            "manifest), and if it persists re-`composer deploy` the graph.",
+            Location(),
+        )
+    if "invalid or incomplete YAML" in t or "Could not start the runtime" in t:
+        return TeachingError(
+            "CMP213", "the runtime YAML was invalid/incomplete at load.",
+            "The gateway rejected the runtime.yaml at load. Re-run `composer check <graph>` (its "
+            "runtime oracle mirrors the loader) and re-`composer deploy`; do not hand-edit the "
+            "staged or copied YAML.",
+            Location(),
+        )
+    detail = (res.stderr or res.stdout or "").strip()[:300]
+    return TeachingError(
+        "CMP219", f"`openclaw senpi runtime create` failed (exit {res.returncode}).",
+        "The frozen install consumer failed for an unrecognised reason. Check its output"
+        + (f": {detail}" if detail else "") + ". Verify the box is provisioned "
+        "(`openclaw senpi runtime list` works) and retry.",
+        Location(),
+    )
+
+
+# --------------------------------------------------------------------------- the verb
+
+def run_install(
+    target: str,
+    wallet: Optional[str],
+    base_state_dir: str,
+    *,
+    out_dir: Optional[str] = None,
+    runtime_id: Optional[str] = None,
+    bound_at: Optional[str] = None,
+    create_fn: CreateFn = _default_create,
+    mcp_fn: McpFn = _box.default_mcp_call,
+) -> InstallResult:
+    """Install one instance of a staged unit onto this box (see module docstring)."""
+    wallet = (wallet or "").strip()
+    auto_bound = False
+
+    # (a0) WALLET RESOLUTION. Explicit `--wallet` ALWAYS wins. When it is omitted, try to
+    # auto-bind the strategy's funded wallet from `<state>/strategies/<strategy>/wallet.json`
+    # (written by `composer fund`) — but ONLY if MCP confirms that strategy is ACTIVE.
+    if not wallet:
+        resolved, err = _auto_bind_wallet(target, out_dir, base_state_dir, mcp_fn)
+        if err is not None:
+            return _refused(target, "", err)
+        wallet, auto_bound = resolved, True
+
+    # (a0) --wallet gate — a light 0x… format check; ownership/ACTIVE is the gateway's job.
+    if not _WALLET_ADDR.match(wallet):
+        return _refused(target, wallet, TeachingError(
+            "CMP205", "`--wallet` is missing or not a 0x… address.",
+            "Pass the strategy's ACTIVE wallet: `composer install <staged-dir> --wallet 0x…` "
+            "(40 hex chars), or run `composer fund <target> --budget N` first and omit `--wallet` "
+            "to auto-bind the funded wallet. Get an address from MCP `strategy_list` "
+            "(strategyWalletAddress).",
+            Location(),
+        ))
+
+    # (a) PREFLIGHT — staged tree exists.
+    staged = _resolve_staged(target, out_dir)
+    if staged is None:
+        return _refused(target, wallet, TeachingError(
+            "CMP200", "the install target is not a staged unit (no manifest.json found).",
+            "Point `composer install` at a `composer deploy` staging dir (the one containing "
+            "manifest.json + main/), or pass the graph file plus `-o <staging-dir>`. Run "
+            "`composer deploy <graph> -o <dir>` first.",
+            Location(),
+        ))
+
+    try:
+        manifest = json.loads((staged / "manifest.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return _refused(target, wallet, TeachingError(
+            "CMP200", "the staged manifest.json could not be read/parsed.",
+            "Re-run `composer deploy <graph> -o <dir>` to regenerate a valid staged unit.",
+            Location(),
+        ))
+
+    # (a) PREFLIGHT — every staged artifact's bytes match its manifest hash (tamper/hand-edit).
+    artifacts: dict = manifest.get("artifacts") or {}
+    mismatched = _verify_tree(staged, artifacts)
+    if mismatched:
+        return _refused(target, wallet, TeachingError(
+            "CMP201", f"staged artifact(s) do not match manifest.json: {', '.join(mismatched)}.",
+            "The staging dir was corrupted or hand-edited after deploy. Never edit a staged unit "
+            "in place — re-run `composer deploy <graph> -o <dir>` to restage from the graph.",
+            Location(),
+        ))
+
+    # (a) PREFLIGHT — the recorded oracle verdict must be GREEN. VALID = green; SKIPPED = allowed
+    # (oracle-less box, mirrors deploy/check's own skip-is-not-red policy); INVALID is blocked.
+    zod_verdict = str((manifest.get("runtime") or {}).get("zod_verdict") or "")
+    if zod_verdict == "INVALID":
+        return _refused(target, wallet, TeachingError(
+            "CMP202", "the staged unit's recorded oracle verdict is INVALID — it will not install.",
+            "The runtime.yaml failed the Zod/DSL oracle at deploy. Fix the graph, re-run "
+            "`composer check <graph>` until GREEN, then `composer deploy` before installing.",
+            Location(),
+        ))
+
+    strategy = str(manifest.get("strategy") or staged.name)
+    hash8 = compute_hash8(manifest)
+    rid = runtime_id or derive_runtime_id(strategy, hash8)
+    canonical = Path(base_state_dir) / "strategies" / strategy / hash8
+    installed_marker = _registry_has(Path(base_state_dir), rid)
+
+    # (b) COPY into the canonical, content-addressed, immutable dir (idempotent).
+    if canonical.exists():
+        # Same content dir already present — check it is bound to THIS wallet (CMP204 otherwise).
+        prior = _read_install_json(canonical)
+        if prior is not None and prior.get("wallet") and prior["wallet"] != wallet:
+            return _refused(target, wallet, TeachingError(
+                "CMP204", f"this content is already installed on the box bound to wallet "
+                          f"{prior['wallet']}.",
+                "A content-addressed hash dir is immutable and holds ONE wallet binding. To run the "
+                "same strategy on a different wallet, re-author it as a distinct strategy (the "
+                "multi-wallet/update flow is out of phase-1 scope).",
+                Location(),
+            ), hash8=hash8, runtime_id=rid, canonical_dir=str(canonical))
+        # Idempotent no-op: content already landed for this wallet.
+        if installed_marker:
+            return InstallResult(
+                target=target, verdict=ALREADY_INSTALLED, wallet=wallet, hash8=hash8,
+                runtime_id=rid, canonical_dir=str(canonical),
+                message=f"runtime {rid!r} already installed for this content + wallet (no-op).",
+            )
+        # Dir landed + bound but never registered (interrupted run) — resume at (d), skip re-copy.
+    else:
+        err = _copy_verified(staged, canonical, artifacts)
+        if err is not None:
+            return _refused(target, wallet, err, hash8=hash8, runtime_id=rid)
+
+    # (c) WALLET BIND — into the COPIED runtime.yaml only; the staged source stays pristine.
+    copied_runtime = canonical / "main" / "runtime.yaml"
+    bound_text, n_bound = _WALLET_TOKEN.subn(wallet, copied_runtime.read_text(encoding="utf-8"))
+    copied_runtime.write_text(bound_text, encoding="utf-8")
+
+    # Re-run the placeholder policy on the BOUND yaml: any remaining bare ${VAR} is now an error.
+    leftover = bare_env_placeholders(bound_text)
+    if leftover:
+        return _refused(target, wallet, TeachingError(
+            "CMP115", f"unbound env placeholder(s) remain after wallet binding: {', '.join(leftover)}.",
+            "Only the `${<STRATEGY>_WALLET}` placeholder is bound at install; every other `${VAR}` "
+            "resolves to \"\" at load and breaks the config. Remove it or give it a default "
+            "(`${VAR:-default}`) in the graph, then re-`composer deploy`.",
+            Location(path=""),
+        ), hash8=hash8, runtime_id=rid, canonical_dir=str(canonical))
+
+    _write_install_json(canonical, wallet=wallet, hash8=hash8, strategy=strategy,
+                        runtime_id=rid, bound_count=n_bound, bound_at=bound_at)
+
+    # (d) INVOKE the frozen consumer through the seam (PATH mode).
+    create = create_fn(str(copied_runtime), rid)
+
+    # (e) VERIFY + REPORT.
+    if create.ok:
+        auto = " (wallet auto-bound from wallet.json)" if auto_bound else ""
+        return InstallResult(
+            target=target, verdict=INSTALLED, wallet=wallet, hash8=hash8, runtime_id=rid,
+            canonical_dir=str(canonical),
+            message=f"installed runtime {rid!r} on wallet {wallet}{auto} from {canonical}.",
+        )
+    err = _map_create_failure(create)
+    return InstallResult(
+        target=target, verdict=FAILED, wallet=wallet, hash8=hash8, runtime_id=rid,
+        canonical_dir=str(canonical), errors=[err], message=err.message,
+    )
+
+
+# --------------------------------------------------------------------------- fs helpers
+
+def _verify_tree(root: Path, artifacts: dict) -> list[str]:
+    """Return the sorted relpaths whose on-disk bytes do NOT match the manifest hash (missing
+    files count as mismatched)."""
+    bad: list[str] = []
+    for rel, sha in artifacts.items():
+        f = root / rel
+        if not f.is_file() or _sha256_file(f) != sha:
+            bad.append(rel)
+    return sorted(bad)
+
+
+def _copy_verified(staged: Path, canonical: Path, artifacts: dict) -> Optional[TeachingError]:
+    """Copy the staged tree to a temp sibling, verify EVERY manifest artifact against its hash,
+    then atomic-rename into ``canonical``. Returns a CMP203 teaching error on a hash mismatch
+    (the temp dir is cleaned up and nothing lands). Never edits in place."""
+    canonical.parent.mkdir(parents=True, exist_ok=True)
+    tmp = canonical.parent / f".{canonical.name}.tmp-{uuid.uuid4().hex[:8]}"
+    if tmp.exists():
+        shutil.rmtree(tmp)
+    shutil.copytree(staged, tmp)
+    mismatched = _verify_tree(tmp, artifacts)
+    if mismatched:
+        shutil.rmtree(tmp, ignore_errors=True)
+        return TeachingError(
+            "CMP203", f"copied file(s) do not match manifest.json: {', '.join(mismatched)}.",
+            "The copy into the canonical hash dir was corrupted (tamper or IO fault). Nothing was "
+            "installed. Retry `composer install`; if it persists, re-`composer deploy` the graph.",
+            Location(),
+        )
+    os.rename(tmp, canonical)
+    return None
+
+
+def _read_install_json(canonical: Path) -> Optional[dict]:
+    p = canonical / INSTALL_JSON
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _write_install_json(canonical: Path, *, wallet: str, hash8: str, strategy: str,
+                        runtime_id: str, bound_count: int, bound_at: Optional[str]) -> None:
+    """Record the wallet binding beside the copied tree (the resumable-by-artifact marker for
+    step c). ``bound_at`` is an INJECTED value (no wall-clock) — None when the caller omits it."""
+    payload = {
+        "strategy": strategy,
+        "wallet": wallet,
+        "hash8": hash8,
+        "runtime_id": runtime_id,
+        "runtime_yaml": "main/runtime.yaml",
+        "wallet_bindings_applied": bound_count,
+        "bound_at": bound_at,
+    }
+    (canonical / INSTALL_JSON).write_text(
+        json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+
+
+def _registry_has(base_state_dir: Path, runtime_id: str) -> bool:
+    """True if the box registry already lists ``runtime_id`` (install-complete marker written by
+    the frozen installRuntime, strategy-registry.ts). Read-only — the composer never writes it."""
+    reg = base_state_dir / REGISTRY_FILENAME
+    try:
+        data = json.loads(reg.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return any(
+        isinstance(e, dict) and e.get("id") == runtime_id
+        for e in (data.get("runtimes") or [])
+    )
+
+
+def install_target(target, wallet, base_state_dir, **kw) -> InstallResult:
+    """Path-taking convenience wrapper mirroring ``deploy_file`` / ``check_file``."""
+    return run_install(str(target), wallet, str(base_state_dir), **kw)