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

package/dist/composer/validator/schema_checks.py

@@ -0,0 +1,147 @@
+"""schema_checks — stage (c): JSON Schema validation, translated to teaching errors.
+
+The registry-generated ``composer/generated/graph.schema.json`` already carries the FULL
+per-node parameter validation (types, bounds, choices, required, unknown-key rejection)
+via its ``allOf`` if/then branches. This module does NOT re-implement any of that — it
+runs the schema with ``jsonschema`` and translates each finding into a located, fix-hinted
+:class:`TeachingError`, so schema violations read the same way as the graph-semantic
+checks layered on top of them.
+
+Two deliberate translations:
+  * The ``enum`` failure on a node's ``node:`` field (an unknown node type) is SKIPPED
+    here — the graph checker emits a far better CMP030 that names the nearest valid
+    alternatives. Reporting both would be noise.
+  * ``additionalProperties`` inside a ``with:`` block is turned into a per-parameter
+    "unknown parameter" error that names the offending key and points at `composer
+    describe <node>`.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from jsonschema import Draft202012Validator
+
+from .errors import Location, TeachingError
+
+_SCHEMA_PATH = (
+    Path(__file__).resolve().parent.parent / "generated" / "graph.schema.json"
+)
+
+
+def load_schema() -> dict:
+    return json.loads(_SCHEMA_PATH.read_text(encoding="utf-8"))
+
+
+def _node_id_at(doc: dict, path) -> tuple[str | None, int | None, dict]:
+    """Given a jsonschema error path, resolve (node_id, none, node_index) context."""
+    path = list(path)
+    if len(path) >= 2 and path[0] == "nodes" and isinstance(path[1], int):
+        idx = path[1]
+        try:
+            entry = doc["nodes"][idx]
+        except (KeyError, IndexError, TypeError):
+            return None, None, {}
+        if isinstance(entry, dict):
+            return entry.get("id"), idx, entry
+    return None, None, {}
+
+
+def schema_errors(doc: dict, line_index: dict) -> list[TeachingError]:
+    schema = load_schema()
+    validator = Draft202012Validator(schema)
+    out: list[TeachingError] = []
+
+    for err in validator.iter_errors(doc):
+        path = list(err.absolute_path)
+        node_id, _idx, _entry = _node_id_at(doc, path)
+        line = line_index.get("nodes", {}).get(node_id)
+        loc = Location(node=node_id, line=line)
+
+        # Unknown node type: let the graph checker produce the good message.
+        if err.validator == "enum" and path and path[-1] == "node":
+            continue
+
+        if err.validator == "additionalProperties" and path and path[-1] == "with":
+            allowed = set((err.schema or {}).get("properties", {}))
+            extra = sorted(k for k in (err.instance or {}) if k not in allowed)
+            names = ", ".join(f"`{k}`" for k in extra) or "a parameter"
+            node_name = _entry.get("node") if isinstance(_entry, dict) else None
+            hint_node = node_name or (node_id or "<node>")
+            out.append(
+                TeachingError(
+                    code="CMP010",
+                    message=f"unknown parameter(s) {names} in `with:`.",
+                    fix_hint=f"Remove {names}; run `composer describe {hint_node}` to see valid params.",
+                    location=loc,
+                )
+            )
+            continue
+
+        if err.validator in ("minimum", "maximum"):
+            param = path[-1] if path else None
+            loc = Location(node=node_id, port=None, line=line)
+            bound = err.validator
+            limit = err.validator_value
+            out.append(
+                TeachingError(
+                    code="CMP011",
+                    message=f"parameter `{param}` = {err.instance!r} violates {bound} {limit}.",
+                    fix_hint=f"Set `{param}` to a value with {bound} {limit}.",
+                    location=loc,
+                )
+            )
+            continue
+
+        if err.validator == "type":
+            param = path[-1] if path and path[-1] != "with" else None
+            want = err.validator_value
+            desc = f"parameter `{param}`" if param else "value"
+            out.append(
+                TeachingError(
+                    code="CMP012",
+                    message=f"{desc} = {err.instance!r} must be of type {want}.",
+                    fix_hint=(
+                        f"Change `{param}` to a {want} value."
+                        if param
+                        else f"Provide a {want} here."
+                    ),
+                    location=loc,
+                )
+            )
+            continue
+
+        if err.validator == "required":
+            # e.message like "'x' is a required property"
+            missing = err.message.split("'")[1] if "'" in err.message else "a field"
+            if node_id or (path and path[0] == "nodes"):
+                out.append(
+                    TeachingError(
+                        code="CMP013",
+                        message=f"required parameter `{missing}` is missing.",
+                        fix_hint=f"Add `{missing}` under this node's `with:` block.",
+                        location=loc,
+                    )
+                )
+            else:
+                out.append(
+                    TeachingError(
+                        code="CMP013",
+                        message=f"required top-level field `{missing}` is missing.",
+                        fix_hint=f"Add a top-level `{missing}:` key to the document.",
+                        location=Location(),
+                    )
+                )
+            continue
+
+        # Fallback: any other schema keyword.
+        out.append(
+            TeachingError(
+                code="CMP014",
+                message=err.message,
+                fix_hint="Adjust the document to satisfy the graph schema.",
+                location=loc,
+            )
+        )
+    return out

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/vendoring.py

@@ -0,0 +1,103 @@
+"""Vendor ``composer.primitives`` into an emitted strategy package as ``strategy_primitives``.
+
+The composer compiles a graph into ``scan.py`` + ``runtime.yaml``. On a user's box the
+runtime scaffold puts the SCANNER DIRECTORY on ``sys.path`` and imports ``scan.py`` by module
+name (``src/scanners/external/scaffold/entrypoint_loader.py``) — NOTHING from the composer
+checkout exists there. So the emitted ``scan.py`` must never ``import composer.primitives``;
+it imports ``strategy_primitives``, a verbatim, point-in-time SNAPSHOT of
+``composer/primitives/`` staged as a SIBLING package of ``scan.py`` (same scanner dir → the
+scaffold's ``sys.path`` entry resolves it exactly like ``scan`` itself).
+
+This module is the SINGLE place that copy happens, so:
+
+  * ``composer deploy`` stages a self-contained tree
+    (``main/scanners/{scan.py, strategy_primitives/}``);
+  * the in-checkout harnesses that EXEC emitted ``scan.py`` (``composer.verbs.smoke``,
+    ``composer.eval.replay``, the golden-test fixtures) stage the SAME snapshot beside the
+    temp ``scan.py`` and put its dir on ``sys.path`` — the on-box layout — so they exercise
+    the real vendored package rather than the in-checkout ``composer.primitives``;
+  * the deploy manifest hashes every vendored file DETERMINISTICALLY (sorted relpaths).
+
+Snapshot semantics are the point: the copy freezes the primitives at deploy/compile time.
+Evolving ``composer/primitives/`` later never mutates an already-staged strategy.
+
+All primitives-internal imports are RELATIVE (``from .`` / ``from ._candles``) and no
+primitive references ``composer`` in code, so a verbatim copy under a new package name
+imports cleanly — there are no absolute ``composer.`` imports to rewrite. The
+self-containment test (``python-tests/composer/test_vendored_primitives.py``) guards this by
+importing a STAGED ``scan.py`` in a subprocess where the ``composer`` checkout is NOT
+importable.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import sys
+from pathlib import Path
+from typing import Iterator
+
+# The package name the emitted scan.py imports (the vendored sibling of scan.py).
+VENDORED_PACKAGE = "strategy_primitives"
+
+_PRIMITIVES_DIR = Path(__file__).resolve().parent / "primitives"
+
+
+def _snapshot_files() -> list[Path]:
+    """Every ``.py`` under ``composer/primitives/``, deterministically sorted, ``__pycache__``
+    excluded. Stable ordering is what makes the deploy manifest reproducible."""
+    return sorted(
+        p
+        for p in _PRIMITIVES_DIR.rglob("*.py")
+        if "__pycache__" not in p.relative_to(_PRIMITIVES_DIR).parts
+    )
+
+
+def vendor_primitives(dest_dir: str | Path) -> dict[str, str]:
+    """Copy ``composer/primitives/`` VERBATIM into ``<dest_dir>/strategy_primitives/``.
+
+    Returns an ordered ``{posix_relpath: sha256}`` map over every file written — relpaths are
+    ``strategy_primitives/<file>`` — for the deploy manifest. Iteration is over
+    :func:`_snapshot_files` (sorted), so the returned dict is deterministic. Idempotent:
+    re-running overwrites the snapshot with identical bytes.
+    """
+    dest = Path(dest_dir)
+    pkg_dir = dest / VENDORED_PACKAGE
+    hashes: dict[str, str] = {}
+    for src in _snapshot_files():
+        rel = src.relative_to(_PRIMITIVES_DIR)
+        target = pkg_dir / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        data = src.read_bytes()
+        target.write_bytes(data)
+        hashes[f"{VENDORED_PACKAGE}/{rel.as_posix()}"] = hashlib.sha256(data).hexdigest()
+    return hashes
+
+
+@contextlib.contextmanager
+def emitted_scan_on_syspath(
+    source: str, dest_dir: str | Path, *, module_filename: str = "scan.py"
+) -> Iterator[Path]:
+    """Stage emitted ``scan.py`` + a vendored ``strategy_primitives`` snapshot into ``dest_dir``
+    and put ``dest_dir`` on ``sys.path`` for the duration — reproducing the on-box scanner-dir
+    layout so ``import strategy_primitives`` resolves exactly as it will in production.
+
+    Yields the written ``scan.py`` path. Used by the in-checkout harnesses that EXEC emitted
+    output; the ``sys.path`` entry is inserted idempotently and removed on exit (the snapshot
+    is byte-identical every time, and the primitives package stays cached in ``sys.modules``
+    after the first import, so later execs resolve it from cache).
+    """
+    dest = Path(dest_dir)
+    dest.mkdir(parents=True, exist_ok=True)
+    vendor_primitives(dest)
+    scan_path = dest / module_filename
+    scan_path.write_text(source, encoding="utf-8")
+    added = str(dest) not in sys.path
+    if added:
+        sys.path.insert(0, str(dest))
+    try:
+        yield scan_path
+    finally:
+        if added:
+            with contextlib.suppress(ValueError):
+                sys.path.remove(str(dest))

package/dist/composer/verbs/__init__.py

@@ -0,0 +1,49 @@
+"""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.
+    install  — copy a staged unit to a canonical hash dir, bind the wallet, hand to the
+               frozen `openclaw senpi runtime create` consumer (slice A2).
+    close    — safe teardown: stop the runtime → confirm gone → trigger MCP strategy_close (B1).
+    status   — DERIVED lifecycle position + next verb (no journals; the spec file is state),
+               extended down the install chain (landed → registered → running) when a box is named.
+    docs     — catalog index + per-node describe (registry-generated).
+"""
+
+from .check import CheckResult, check_file, run_check
+from .close import CloseResult, run_close
+from .deploy import DeployResult, deploy_file, run_deploy
+from .docs import catalog_text, describe_text
+from .fund import FundResult, fund_target, run_fund
+from .install import CreateResult, InstallResult, install_target, run_install
+from .smoke import SmokeError, run_smoke
+from .status import StatusResult, run_status
+
+__all__ = [
+    "CheckResult",
+    "run_check",
+    "check_file",
+    "DeployResult",
+    "run_deploy",
+    "deploy_file",
+    "InstallResult",
+    "CreateResult",
+    "run_install",
+    "install_target",
+    "FundResult",
+    "run_fund",
+    "fund_target",
+    "CloseResult",
+    "run_close",
+    "StatusResult",
+    "run_status",
+    "catalog_text",
+    "describe_text",
+    "SmokeError",
+    "run_smoke",
+]