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

package/dist/composer/validator/validate.py

@@ -0,0 +1,86 @@
+"""validate — the pipeline that runs the stages and collects every error together.
+
+Stage order (each stage's findings are added to the same :class:`ValidationResult`;
+stages do not stop at the first error — the whole point is to report every defect at
+once so the agent repairs in one pass):
+
+    (a) load + anchor/alias/merge rejection        -> loader
+    (b) `pipeline:` desugaring into nodes+edges     -> desugar   (before schema)
+    (c) JSON Schema validation (registry-generated) -> schema_checks
+    (d) graph-semantic checks                       -> graph_checks
+    (e) pure_fn checks (purity + inline tests)      -> composer.pure_fn.checks
+
+A hard load failure (a) is terminal — there is no document to check further. Everything
+after that accumulates.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from composer.pure_fn import checks as pure_fn_checks
+
+from . import desugar as _desugar
+from . import graph_checks, schema_checks
+from .errors import Location, TeachingError, ValidationResult
+from .loader import AnchorError, YamlLoadError, load_graph
+
+
+def validate_text(text: str, source: str = "<text>") -> ValidationResult:
+    result = ValidationResult(source=source)
+
+    # (a) load + anchor rejection
+    try:
+        data, line_index = load_graph(text)
+    except AnchorError as exc:
+        result.add(
+            TeachingError(
+                code="CMP002",
+                message=f"YAML {exc.what} is not allowed in a strategy graph.",
+                fix_hint="Remove the anchor/alias/merge key and write the value out in full (D6 bans them).",
+                location=Location(line=exc.line),
+            )
+        )
+        return result
+    except YamlLoadError as exc:
+        result.add(
+            TeachingError(
+                code="CMP001",
+                message=f"YAML syntax error: {exc.message}",
+                fix_hint="Fix the YAML syntax at the reported line (check indentation and quoting).",
+                location=Location(line=exc.line),
+            )
+        )
+        return result
+
+    if not isinstance(data, dict):
+        result.add(
+            TeachingError(
+                code="CMP003",
+                message="the document root is empty or not a mapping.",
+                fix_hint="A graph is a mapping with at least a `nodes:` list (or a `pipeline:` shorthand).",
+            )
+        )
+        return result
+
+    # (b) desugar pipeline -> nodes+edges (before schema)
+    if _desugar.has_pipeline(data):
+        data, desugar_errors = _desugar.desugar(data)
+        result.extend(desugar_errors)
+
+    # (c) JSON Schema validation
+    result.extend(schema_checks.schema_errors(data, line_index))
+
+    # (d) graph-semantic checks
+    result.extend(graph_checks.check(data, line_index))
+
+    # (e) pure_fn purity + inline fixture tests (D2 kind 2)
+    result.extend(pure_fn_checks.check(data, line_index))
+
+    return result
+
+
+def validate_file(path: str | Path) -> ValidationResult:
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    return validate_text(text, source=str(p))

package/dist/composer/verbs/__init__.py

@@ -0,0 +1,33 @@
+"""verbs — the slice-7 composer verbs (check / deploy / status / catalog / describe).
+
+Each verb is a thin, pure-ish Python surface producing a structured result with both a
+human ``render()`` and a ``to_json()`` (the shape the TS rim passes through). The lifecycle
+they implement — ``new → check → deploy``, with ``status`` deriving position and naming the
+next verb — is D7; the TS wrapper is verdict-passthrough only (D8).
+
+    check    — ONE verdict aggregating validate + pure_fn tests + compile + fixture smoke.
+    deploy   — idempotent, HARD-gated on check; stages the deployable artifact set.
+    status   — DERIVED lifecycle position + next verb (no journals; the spec file is state).
+    docs     — catalog index + per-node describe (registry-generated).
+"""
+
+from .check import CheckResult, check_file, run_check
+from .deploy import DeployResult, deploy_file, run_deploy
+from .docs import catalog_text, describe_text
+from .smoke import SmokeError, run_smoke
+from .status import StatusResult, run_status
+
+__all__ = [
+    "CheckResult",
+    "run_check",
+    "check_file",
+    "DeployResult",
+    "run_deploy",
+    "deploy_file",
+    "StatusResult",
+    "run_status",
+    "catalog_text",
+    "describe_text",
+    "SmokeError",
+    "run_smoke",
+]

package/dist/composer/verbs/check.py

@@ -0,0 +1,193 @@
+"""check — ONE verdict aggregating the whole build gate (D7).
+
+``composer check <graph.yaml>`` collapses everything that must be true before a graph is
+deployable into a single GREEN/RED verdict, run as ordered stages that short-circuit:
+
+    validate         schema + graph-semantic + pure_fn PURITY checks (the teaching validator).
+    pure_fn_tests    the pure_fn inline fixture tests (CMP05x), reported as their own stage.
+    compile          deterministic materialization to scan.py on the external_scanner contract.
+    smoke            import the emitted module + run one scan() tick over a stub ctx (liveness).
+    runtime_validate PROTECTION policy (CMP120) + the REAL Zod+DSL oracle over the emitted
+                     runtime.yaml (CMP1xx). Protection-by-default is enforced HERE: an unmanaged
+                     unit with no explicit opt-out is RED. The Zod oracle needs a built dist/; when
+                     absent (CI without `npm run build`) it is noted SKIPPED, not RED — the policy
+                     layer still gates. Opt-out (`unmanaged=true`) is GREEN with a loud warning.
+
+The validator runs purity AND the inline fixture tests in one pass, so rather than re-run
+them we PARTITION that single run's errors: CMP05x (inline-test) findings become the
+``pure_fn_tests`` stage; everything else is the ``validate`` stage. A stage is SKIPPED once
+an earlier stage is RED (compiling an invalid graph, or smoking a graph that won't compile,
+would only produce noise). The verdict is GREEN iff every stage is GREEN.
+
+The result is both human-rendered and ``--json`` (verdict + per-stage status + located
+errors). ``deploy`` consumes this object directly as its hard gate; the compiled source is
+carried on the result so ``deploy`` need not recompile.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from composer.compiler import CompileError, compile_text
+from composer.validator import validate_text
+from composer.validator.errors import TeachingError
+from composer.validator.loader import load_graph
+
+from .runtime_validate import check_runtime_unit
+from .smoke import SmokeError, run_smoke
+
+# Inline pure_fn fixture-test error codes (partitioned into their own stage).
+_PURE_FN_TEST_CODES = {"CMP050", "CMP051", "CMP052"}
+
+GREEN = "GREEN"
+RED = "RED"
+SKIPPED = "SKIPPED"
+
+
+@dataclass
+class Stage:
+    name: str
+    status: str = SKIPPED
+    errors: list[TeachingError] = field(default_factory=list)
+    # free-text findings for stages that don't produce TeachingErrors (compile / smoke)
+    messages: list[str] = field(default_factory=list)
+    detail: Optional[dict] = None
+
+    def to_json(self) -> dict:
+        out: dict = {
+            "stage": self.name,
+            "status": self.status,
+            "errors": [e.to_dict() for e in self.errors],
+        }
+        if self.messages:
+            out["messages"] = list(self.messages)
+        if self.detail is not None:
+            out["detail"] = self.detail
+        return out
+
+
+@dataclass
+class CheckResult:
+    source: str
+    stages: list[Stage]
+    scan_source: Optional[str] = None  # the emitted scan.py when compile succeeded
+    runtime_source: Optional[str] = None  # the emitted runtime.yaml when runtime_validate ran
+
+    @property
+    def verdict(self) -> str:
+        return GREEN if all(s.status == GREEN for s in self.stages) else RED
+
+    @property
+    def ok(self) -> bool:
+        return self.verdict == GREEN
+
+    def to_json(self) -> dict:
+        errors = [e.to_dict() for s in self.stages for e in s.errors]
+        return {
+            "verb": "check",
+            "graph": self.source,
+            "verdict": self.verdict,
+            "stages": [s.to_json() for s in self.stages],
+            "error_count": len(errors),
+            "errors": errors,
+        }
+
+    def render(self) -> str:
+        lines = [f"{self.verdict}: {self.source}"]
+        for s in self.stages:
+            mark = {"GREEN": "ok  ", "RED": "FAIL", "SKIPPED": "skip"}[s.status]
+            lines.append(f"  [{mark}] {s.name}")
+            for e in sorted(s.errors, key=lambda e: e.sort_key):
+                lines.append("        " + e.render().replace("\n", "\n        "))
+            for m in s.messages:
+                lines.append(f"        {m}")
+        lines.append("")
+        lines.append(
+            "check GREEN — ready to deploy." if self.ok
+            else "check RED — fix the failing stage(s); deploy is refused until GREEN."
+        )
+        return "\n".join(lines) + "\n"
+
+
+def run_check(source_text: str, source_name: str) -> CheckResult:
+    """Run the whole gate over graph YAML text; return the aggregated verdict."""
+    validate_stage = Stage("validate")
+    pure_fn_stage = Stage("pure_fn_tests")
+    compile_stage = Stage("compile")
+    smoke_stage = Stage("smoke")
+    runtime_stage = Stage("runtime_validate")
+    stages = [validate_stage, pure_fn_stage, compile_stage, smoke_stage, runtime_stage]
+
+    # --- validate (+ partition the pure_fn inline-test findings into their own stage) ---
+    vresult = validate_text(source_text, source=source_name)
+    for err in vresult.errors:
+        (pure_fn_stage if err.code in _PURE_FN_TEST_CODES else validate_stage).errors.append(err)
+    validate_stage.status = RED if validate_stage.errors else GREEN
+    pure_fn_stage.status = RED if pure_fn_stage.errors else GREEN
+
+    if not vresult.ok:
+        # compile/smoke stay SKIPPED — nothing valid to materialize.
+        return CheckResult(source_name, stages)
+
+    # --- compile ---
+    scan_source: Optional[str] = None
+    try:
+        scan_source = compile_text(source_text, source_name=source_name)
+        compile_stage.status = GREEN
+    except CompileError as exc:
+        compile_stage.status = RED
+        compile_stage.messages.append(str(exc).splitlines()[0])
+        return CheckResult(source_name, stages, scan_source=None)
+
+    # --- smoke (import + one tick over a stub ctx) ---
+    try:
+        detail = run_smoke(scan_source, scanner_name=source_name)
+        smoke_stage.status = GREEN
+        smoke_stage.detail = detail
+    except SmokeError as exc:
+        smoke_stage.status = RED
+        smoke_stage.messages.append(str(exc))
+        return CheckResult(source_name, stages, scan_source=scan_source)
+
+    # --- runtime_validate (protection policy + the real Zod+DSL oracle over runtime.yaml) ---
+    runtime_source = _run_runtime_validate(source_text, runtime_stage)
+
+    return CheckResult(source_name, stages, scan_source=scan_source, runtime_source=runtime_source)
+
+
+def _run_runtime_validate(source_text: str, stage: Stage) -> Optional[str]:
+    """Emit runtime.yaml from the graph's metadata, enforce PROTECTION policy (CMP120), and run
+    the real Zod+DSL oracle. Records status/errors/messages on ``stage``; returns the emitted
+    runtime.yaml text (so deploy can stage it without re-emitting)."""
+    from composer.authoring.runtime_emit import answers_from_metadata, render_runtime_yaml
+
+    try:
+        doc, _ = load_graph(source_text)
+        answers = answers_from_metadata(doc.get("metadata") or {})
+    except Exception as exc:  # noqa: BLE001 — a bad metadata block is a graph defect, reported here
+        stage.status = RED
+        stage.messages.append(f"could not derive runtime answers from metadata: {exc}")
+        return None
+
+    runtime_source = render_runtime_yaml(answers)
+    oracle, policy_errors = check_runtime_unit(answers)
+    stage.errors.extend(policy_errors)
+    stage.errors.extend(oracle.errors)
+
+    if answers.unmanaged:
+        stage.messages.append(
+            "WARNING: unmanaged=true — this unit ships with NO exit protection (no stop-loss, "
+            "no trailing floor, no time-cut). Positions can run to liquidation. Opt-out accepted."
+        )
+    if oracle.skipped and oracle.skip_reason:
+        stage.messages.append(oracle.skip_reason)
+
+    stage.status = RED if stage.errors else GREEN
+    return runtime_source
+
+
+def check_file(path) -> CheckResult:
+    p = Path(path)
+    return run_check(p.read_text(encoding="utf-8"), p.name)

package/dist/composer/verbs/deploy.py

@@ -0,0 +1,223 @@
+"""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/<strategy>.graph.yaml  the spec-is-state graph source (D7), under the instance.
+         manifest.json            content hashes (graph + scan + runtime.yaml), 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). Ops (``senpi-strategy-ops``) begins where the composer ends: it reads
+``strategy.yaml.instances[]``, mints one wallet per instance, funds by ``funding_share``, and
+renders each ``runtime.yaml`` onto its wallet (``openclaw senpi runtime create``). The composer
+never creates wallets, moves money, or installs (design §7 scope boundary).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+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 .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()
+
+
+@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."
+            ),
+        }
+        out["message"] = (
+            f"{self.verdict.lower()}: complete unit staged to {self.staged_dir}"
+            if self.verdict == DEPLOYED
+            else f"unchanged: staged unit at {self.staged_dir} matches (idempotent no-op)."
+        )
+        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"]
+        lines = [
+            f"{self.verdict}: {self.source}",
+            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)
+
+    stage_dir = Path(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")
+    (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)