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

package/dist/composer/verbs/deploy.py

@@ -0,0 +1,279 @@
+"""deploy — idempotent, HARD-gated on check; stage the COMPLETE standalone unit (slice 9).
+
+``composer deploy <graph.yaml> --out <dir>`` is the compile-on-deploy step. It:
+
+    1. Runs ``composer check`` and REFUSES on RED (verdict ``REFUSED``). There is no
+       ``--force`` — a graph that isn't GREEN never deploys, by construction (the whole
+       trust-by-construction premise: you cannot ship an unverified strategy). Because
+       ``check`` now includes the ``runtime_validate`` stage, a unit that is not Zod-valid or
+       not PROTECTED (CMP120) never deploys either.
+    2. Stages a COMPLETE, standalone strategy PACKAGE TREE (design §6) into ``<out>/<strategy>/``:
+         strategy.yaml            catalog + funding manifest, single instance (§7).
+         main/runtime.yaml        the complete emitted runtime (strategy/scanners/actions/exit/risk).
+         main/scanners/scan.py    the compiled module (the scaffold `entrypoint`).
+         main/scanners/strategy_primitives/  a vendored SNAPSHOT of composer/primitives/ (a
+                                  sibling package of scan.py) — what makes the unit self-contained:
+                                  scan.py imports `strategy_primitives`, never `composer.*`, so it
+                                  runs on a box that has none of the composer checkout.
+         main/<strategy>.graph.yaml  the spec-is-state graph source (D7), under the instance.
+         manifest.json            content hashes (graph + scan + runtime.yaml + every vendored
+                                  primitives file), schema version, node count, and the zod-oracle
+                                  verdict for the staged runtime.
+         deploy.json              the verdict describing exactly what happened.
+    3. Is IDEMPOTENT: re-deploying with identical graph/scan/runtime bytes is a no-op with
+       verdict ``UNCHANGED`` — the spec file is the identity, matching status's staleness derivation.
+
+The staged unit is COMPLETE: it carries its own ``exit`` (DSL protection), its ``OPEN_POSITION``
+entry action, and a funded-wallet manifest — no host runtime.yaml to borrow (the slice-8 wrap
+hack is retired). Deploy STAGES only; ``composer install`` (``composer/verbs/install.py``) is the
+box-side step that copies one instance of this staged unit to a content-addressed immutable dir,
+binds a ``--wallet`` for the ``${..._WALLET}`` placeholder, and hands it to the frozen
+``openclaw senpi runtime create`` consumer. Ops (``senpi-strategy-ops``) drives the multi-instance
+handoff: it reads ``strategy.yaml.instances[]``, mints one wallet per instance, funds by
+``funding_share``, and installs each. The composer never creates wallets or moves money
+(design §7 scope boundary).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from composer.authoring.runtime_emit import answers_from_metadata, render_runtime_yaml
+from composer.authoring.strategy_manifest import render_strategy_yaml
+from composer.registry import SCHEMA_VERSION
+from composer.validator.loader import load_graph
+from composer.vendoring import VENDORED_PACKAGE, vendor_primitives
+
+from .check import CheckResult, run_check
+from .runtime_validate import validate_runtime_yaml_file
+
+DEPLOYED = "DEPLOYED"
+UNCHANGED = "UNCHANGED"
+REFUSED = "REFUSED"
+
+# How ops installs the staged unit (documented handoff, not invoked here).
+_OPS_MECHANISM = "senpi-strategy-ops deploy.py create/runtime — one wallet per instance, then `openclaw senpi runtime create`"
+
+
+def _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _aggregate_sha(hashes: dict) -> str:
+    """One stable identity over a set of ``{relpath: filesha}`` entries (sorted relpaths), so
+    the vendored primitives snapshot gets a single content hash in the manifest."""
+    h = hashlib.sha256()
+    for rel in sorted(hashes):
+        h.update(rel.encode("utf-8"))
+        h.update(b"\0")
+        h.update(hashes[rel].encode("utf-8"))
+        h.update(b"\n")
+    return h.hexdigest()
+
+
+@dataclass
+class DeployResult:
+    source: str
+    verdict: str
+    check: CheckResult
+    staged_dir: Optional[str] = None
+    manifest: Optional[dict] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.verdict in (DEPLOYED, UNCHANGED)
+
+    def to_json(self) -> dict:
+        out: dict = {
+            "verb": "deploy",
+            "graph": self.source,
+            "verdict": self.verdict,
+            "check": {
+                "verdict": self.check.verdict,
+                "error_count": self.check.to_json()["error_count"],
+            },
+        }
+        if self.verdict == REFUSED:
+            out["check"]["errors"] = self.check.to_json()["errors"]
+            out["message"] = "check RED — deploy refused (no --force; a graph must be GREEN)."
+            return out
+        man = self.manifest or {}
+        out["staged"] = {
+            "dir": self.staged_dir,
+            "artifacts": sorted(man.get("artifacts", {}).keys()),
+            "graph_sha256": man.get("graph_sha256"),
+            "scan_sha256": man.get("scan_sha256"),
+            "runtime_sha256": man.get("runtime_sha256"),
+            "strategy_sha256": man.get("strategy_sha256"),
+            "schema_version": man.get("schema_version"),
+            "runtime_zod_verdict": man.get("runtime", {}).get("zod_verdict"),
+        }
+        # The staged unit is COMPLETE and standalone — its own exit + entry action + funding
+        # manifest. Ops installs it; there is no host runtime.yaml to borrow (the wrap hack is gone).
+        out["install"] = {
+            "wired": False,
+            "handoff": _OPS_MECHANISM,
+            "complete_unit": True,
+            "note": (
+                "a COMPLETE standalone strategy runtime is staged: main/runtime.yaml carries the "
+                "OPEN_POSITION entry action AND the DSL exit (protection-by-default), plus a "
+                "position_tracker. Hand the staged dir to senpi-strategy-ops: it reads "
+                "strategy.yaml.instances[], mints one funded wallet per instance (funding_share), "
+                "and renders each runtime.yaml onto its wallet. The composer never funds or installs."
+            ),
+        }
+        # Every OK verdict names the ABSOLUTE staged dir; UNCHANGED says so in the plainest terms
+        # (nothing was rewritten — so an author who sees no fresh mtimes isn't left wondering).
+        out["message"] = (
+            f"{self.verdict.lower()}: complete unit staged to {self.staged_dir}"
+            if self.verdict == DEPLOYED
+            else f"unchanged: already staged at {self.staged_dir}, nothing rewritten "
+            f"(idempotent no-op — the graph/scan/runtime bytes match the prior staging)."
+        )
+        return out
+
+    def render(self) -> str:
+        if self.verdict == REFUSED:
+            return (
+                f"REFUSED: {self.source} — check is {self.check.verdict} "
+                f"({self.check.to_json()['error_count']} error(s)); deploy is hard-gated on a "
+                f"GREEN check (there is no --force). Run `composer check {self.source}`.\n"
+            )
+        j = self.to_json()
+        s = j["staged"]
+        # The absolute staged dir leads EVERY ok verdict; UNCHANGED spells out that nothing was
+        # rewritten (the idempotent no-op) so an empty-looking mtime never reads as a silent failure.
+        headline = (
+            f"UNCHANGED: {self.source} — already staged at {self.staged_dir}, nothing rewritten "
+            f"(idempotent no-op)."
+            if self.verdict == UNCHANGED
+            else f"DEPLOYED: {self.source} — complete unit staged."
+        )
+        lines = [
+            headline,
+            f"  staged dir : {self.staged_dir}",
+            f"  artifacts  : {', '.join(s['artifacts'])}",
+            f"  graph sha  : {(s['graph_sha256'] or '')[:12]}…",
+            f"  scan sha   : {(s['scan_sha256'] or '')[:12]}…",
+            f"  runtime sha: {(s['runtime_sha256'] or '')[:12]}…  (zod: {s['runtime_zod_verdict']})",
+            f"  install    : complete standalone unit — hand off to ops ({_OPS_MECHANISM}).",
+        ]
+        return "\n".join(lines) + "\n"
+
+
+def run_deploy(source_text: str, source_name: str, out_dir) -> DeployResult:
+    """Check, then stage the complete standalone unit as a package tree (idempotent). See docstring."""
+    check = run_check(source_text, source_name)
+    if not check.ok:
+        return DeployResult(source_name, REFUSED, check)
+
+    doc, _line_index = load_graph(source_text)
+    metadata = doc.get("metadata") or {}
+    strategy = str(metadata.get("strategy") or Path(source_name).stem.replace(".graph", ""))
+    archetype = str(metadata.get("archetype") or "unknown")
+
+    # The runtime.yaml + strategy.yaml derive from the SAME metadata.answers the scan.py did
+    # (design §6): recompiling regenerates all three byte-identically.
+    answers = answers_from_metadata(metadata)
+    scan_source = check.scan_source or ""
+    runtime_source = check.runtime_source or render_runtime_yaml(answers)
+    strategy_source = render_strategy_yaml(answers)
+
+    graph_sha = _sha256(source_text)
+    scan_sha = _sha256(scan_source)
+    runtime_sha = _sha256(runtime_source)
+    strategy_sha = _sha256(strategy_source)
+
+    # Absolutize the staging root against the CURRENT working dir BEFORE composing the tree, so
+    # every reported ``staged_dir`` is an ABSOLUTE path the caller can `cd` into — a relative
+    # ``-o`` (e.g. the default ``dist``) resolved against an unexpected cwd was the "deploy exited
+    # 0 but there are no files where I looked" failure. ``abspath`` absolutizes against the current
+    # working dir WITHOUT resolving symlinks (so a caller-supplied absolute path is returned
+    # byte-identical, only a relative one is joined onto cwd); the child runs in the caller's real
+    # cwd (the rim never sets one), so this is the caller's own working dir.
+    stage_dir = Path(os.path.abspath(out_dir)) / strategy
+    instance_dir = stage_dir / "main"
+    scanners_dir = instance_dir / "scanners"
+    manifest_path = stage_dir / "manifest.json"
+    graph_filename = f"{strategy}.graph.yaml"
+
+    # Idempotency: the spec file IS the identity (D7). A prior staging whose manifest records
+    # the same graph + scan + runtime bytes is an UNCHANGED no-op — don't rewrite anything.
+    if manifest_path.is_file():
+        try:
+            prior = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            prior = {}
+        if (
+            prior.get("graph_sha256") == graph_sha
+            and prior.get("scan_sha256") == scan_sha
+            and prior.get("runtime_sha256") == runtime_sha
+        ):
+            return DeployResult(source_name, UNCHANGED, check,
+                                staged_dir=str(stage_dir), manifest=prior)
+
+    manifest = {
+        "strategy": strategy,
+        "archetype": archetype,
+        "schema_version": SCHEMA_VERSION,
+        "node_count": len(doc.get("nodes") or []),
+        "graph_sha256": graph_sha,
+        "scan_sha256": scan_sha,
+        "runtime_sha256": runtime_sha,
+        "strategy_sha256": strategy_sha,
+        "artifacts": {
+            "strategy.yaml": strategy_sha,
+            "main/runtime.yaml": runtime_sha,
+            "main/scanners/scan.py": scan_sha,
+            f"main/{graph_filename}": graph_sha,
+        },
+        "runtime": {"path": "main/runtime.yaml", "sha256": runtime_sha},
+        "generated_by": "composer deploy",
+    }
+
+    # Write the complete package tree.
+    scanners_dir.mkdir(parents=True, exist_ok=True)
+    (scanners_dir / "scan.py").write_text(scan_source, encoding="utf-8")
+    # Vendor a SNAPSHOT of the primitives beside scan.py so the staged unit is fully
+    # self-contained: the scaffold puts the scanner dir on sys.path, so scan.py's
+    # `import strategy_primitives` resolves with NOTHING from the composer checkout present.
+    # The copy freezes the primitives at deploy time (future primitives changes never mutate
+    # an already-staged strategy — and the idempotency triple below, keyed on graph/scan/
+    # runtime bytes, keeps a redeploy of the SAME graph UNCHANGED, so the frozen snapshot stays).
+    # Every vendored file folds into the manifest deterministically (sorted relpaths).
+    vendored = vendor_primitives(scanners_dir)
+    manifest["artifacts"].update(
+        {f"main/scanners/{rel}": sha for rel, sha in vendored.items()}
+    )
+    manifest["primitives"] = {
+        "package": f"main/scanners/{VENDORED_PACKAGE}",
+        "file_count": len(vendored),
+        "sha256": _aggregate_sha(vendored),
+    }
+    (instance_dir / "runtime.yaml").write_text(runtime_source, encoding="utf-8")
+    (instance_dir / graph_filename).write_text(source_text, encoding="utf-8")
+    (stage_dir / "strategy.yaml").write_text(strategy_source, encoding="utf-8")
+
+    # Prove the STAGED runtime.yaml validates against the real oracle; record the verdict.
+    ov = validate_runtime_yaml_file(instance_dir / "runtime.yaml")
+    manifest["runtime"]["zod_verdict"] = (
+        "SKIPPED" if ov.skipped else ("VALID" if ov.ok else "INVALID")
+    )
+
+    manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    result = DeployResult(source_name, DEPLOYED, check, staged_dir=str(stage_dir), manifest=manifest)
+    (stage_dir / "deploy.json").write_text(
+        json.dumps(result.to_json(), indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    return result
+
+
+def deploy_file(path, out_dir) -> DeployResult:
+    p = Path(path)
+    return run_deploy(p.read_text(encoding="utf-8"), p.name, out_dir)

package/dist/composer/verbs/docs.py

@@ -0,0 +1,30 @@
+"""docs — the catalog / describe verbs (the registry-generated progressive-disclosure surface).
+
+``composer catalog`` prints the ~1-2k-token index (node names + one-liners + param
+summaries); ``composer describe <node>`` prints one node's full ports/params/example.
+
+Both read straight from the committed ``composer/generated/`` artifacts when present (they
+are byte-identical to a fresh render — a golden test enforces that), and fall back to
+rendering from the registry in-memory otherwise, so the verbs work in any checkout.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from composer.registry import generate
+
+_GENERATED = Path(__file__).resolve().parents[1] / "generated"
+
+
+def catalog_text() -> str:
+    """The catalog index (prefer the committed artifact; render from the registry if absent)."""
+    path = _GENERATED / "catalog.md"
+    if path.is_file():
+        return path.read_text(encoding="utf-8")
+    return generate.render_catalog()
+
+
+def describe_text(node: str) -> str:
+    """One node's reference block. Raises KeyError (with a nearest-name hint) if unknown."""
+    return generate.render_describe_node(node)