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

package/dist/composer/requirements.txt

@@ -0,0 +1,21 @@
+# Dev/CI Python dependencies for the strategy composer (composer/).
+#
+# Mirrors the scaffold's requirements.txt convention: this repo is otherwise pure
+# TypeScript/vitest and pytest is a CI-only toolchain, so composer's Python deps are
+# declared here (not in pyproject) and installed in the `python-tests` CI job.
+#
+#   pydantic — the node registry is pydantic models; the single source of truth from
+#              which JSON Schema + catalog + validator + compiler all derive (D4, D8).
+#   jinja2   — per-node emission templates the compiler walks to produce scan.py (D8).
+#   pyyaml   — parse the authored YAML graph before validating the JSON canonical form
+#              (D6: YAML authored, JSON Schema canonical; anchors/merge keys banned).
+#   jsonschema — validate the desugared graph against composer/generated/graph.schema.json
+#              (Draft 2020-12); the validator translates its findings into teaching errors
+#              rather than re-implementing the registry's per-node param validation (slice 2).
+#
+# NO orchestration/DAG framework (LangGraph/Dagster/Prefect/Hamilton/networkx): the DAG
+# never executes as a DAG — the compiler linearizes topo order into straight-line Python.
+pydantic>=2.0
+jinja2>=3.0
+pyyaml>=6.0
+jsonschema>=4.18

package/dist/composer/scaffold_path.py

@@ -0,0 +1,118 @@
+"""Locate the ``scaffold`` harness package across the dev checkout AND the claw dist install.
+
+``scaffold`` (``src/scanners/external/scaffold``) is the FROZEN runtime's scanner harness — the
+``ScanContext`` / ``StateManager`` an emitted ``scan.py`` runs under. The composer's in-checkout
+liveness harnesses (``composer.verbs.smoke`` and ``composer.eval.replay``) import it to exec a
+compiled ``scan.py`` and run one real tick. It is NOT distributed on PyPI — and there is an
+UNRELATED package literally named ``scaffold`` on PyPI, so ``pip install scaffold`` NEVER fixes a
+missing import here; it silently installs the wrong thing (the original dev-box failure: the bare
+``No module named 'scaffold'`` led straight to that dead end).
+
+``scaffold`` ships in two layouts, and this module resolves BOTH with no manual ``PYTHONPATH``:
+
+  * **dev checkout** — ``composer/`` sits at the trading_runtime repo root, and scaffold lives at
+    ``<repo>/src/scanners/external`` (with the ``src/`` segment).
+  * **claw dist install** — ``npm run build`` runs ``copy:composer`` (lands the package at
+    ``dist/composer``) and ``copy:external-scanners`` (lands scaffold at ``dist/scanners/external``,
+    with NO ``src/`` segment). The old ``repo_root/src/scanners/external`` computation pointed at
+    ``dist/src/scanners/external`` — which does not exist — so scaffold never went on ``sys.path``.
+
+Both are found RELATIVE to this file (which travels with the ``composer`` package, so it is right
+in either layout). An explicit ``COMPOSER_SCAFFOLD_DIR`` override (the dir that CONTAINS
+``scaffold/``) wins over auto-detection; ``COMPOSER_ROOT`` (the dir that contains ``composer/`` —
+the TS rim's dev-checkout override) is honored as a search base too, so the Python side agrees
+with the rim without a second env var to set.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+# The dir that CONTAINS the `composer/` package (repo root in a dev checkout; `dist/` in a claw
+# install). `composer/scaffold_path.py` -> parents[0]=composer, parents[1]=that containing dir.
+_COMPOSER_PARENT = Path(__file__).resolve().parents[1]
+
+# `scaffold`'s parent dir under a search base, in each layout.
+_DEV_SUBPATH = ("src", "scanners", "external")  # dev checkout: repo/src/scanners/external
+_DIST_SUBPATH = ("scanners", "external")        # claw dist:    dist/scanners/external
+
+# The env var name (documented in the teaching error) — kept in sync with the rim's COMPOSER_ prefix.
+SCAFFOLD_DIR_ENV = "COMPOSER_SCAFFOLD_DIR"
+
+
+class ScaffoldNotFound(RuntimeError):
+    """The ``scaffold`` harness package could not be located in any known layout.
+
+    Carries a teaching-shaped message that names the ACTUAL fix (build step / env var) and warns
+    explicitly against ``pip install scaffold`` (an unrelated PyPI package)."""
+
+
+def _search_bases() -> List[Path]:
+    """The dirs under which to try ``<base>/src/scanners/external`` and ``<base>/scanners/external``.
+
+    ``COMPOSER_ROOT`` (the rim's dev override, the dir that holds ``composer/``) is tried first when
+    set, then the package's own containing dir (self-location — correct in both layouts)."""
+    bases: List[Path] = []
+    root = os.environ.get("COMPOSER_ROOT", "").strip()
+    if root:
+        bases.append(Path(root).expanduser())
+    bases.append(_COMPOSER_PARENT)
+    return bases
+
+
+def _candidate_parents() -> List[Path]:
+    """Every dir that MIGHT contain ``scaffold/``, in resolution order (override → dev → dist)."""
+    candidates: List[Path] = []
+    override = os.environ.get(SCAFFOLD_DIR_ENV, "").strip()
+    if override:
+        candidates.append(Path(override).expanduser())
+    for base in _search_bases():
+        candidates.append(base.joinpath(*_DEV_SUBPATH))
+        candidates.append(base.joinpath(*_DIST_SUBPATH))
+    return candidates
+
+
+def scaffold_parent() -> Optional[Path]:
+    """Return the dir that CONTAINS the ``scaffold`` package, or ``None`` if none is found.
+
+    Resolution order: ``COMPOSER_SCAFFOLD_DIR`` (explicit override) → dev-checkout layout → claw
+    dist layout, under ``COMPOSER_ROOT`` first (if set) then this package's own location."""
+    for cand in _candidate_parents():
+        if (cand / "scaffold").is_dir():
+            return cand
+    return None
+
+
+def _teaching_message() -> str:
+    looked = "\n".join(f"    - {c}" for c in _candidate_parents())
+    return (
+        "the `scaffold` harness package could not be located. composer smoke/replay import it to "
+        "run a compiled scan.py under the real runtime ScanContext/StateManager, so `check` (and "
+        "therefore `deploy`) cannot prove liveness without it.\n"
+        f"  Looked for a `scaffold/` dir under:\n{looked}\n"
+        "  Fix, depending on how the composer is installed:\n"
+        "    - claw dist install: run `npm run build` (its copy:external-scanners step stages "
+        "scaffold into dist/scanners/external) and run the composer from that dist tree.\n"
+        "    - dev checkout: run the composer from the trading_runtime repo root, OR set "
+        f"{SCAFFOLD_DIR_ENV} to the dir that CONTAINS `scaffold/` (i.e. .../src/scanners/external).\n"
+        "  Do NOT `pip install scaffold`: that is an UNRELATED PyPI package and will NOT satisfy "
+        "this import — scaffold ships with the runtime, never from PyPI."
+    )
+
+
+def ensure_scaffold_on_syspath() -> Path:
+    """Resolve the scaffold parent and put it on ``sys.path`` (idempotently); return that dir.
+
+    Raises :class:`ScaffoldNotFound` with the teaching message when no layout resolves — callers
+    surface that as their own teaching-shaped failure (e.g. a RED smoke stage) rather than letting
+    a bare ``No module named 'scaffold'`` escape and mislead the reader toward PyPI."""
+    parent = scaffold_parent()
+    if parent is None:
+        raise ScaffoldNotFound(_teaching_message())
+    s = str(parent)
+    if s not in sys.path:
+        sys.path.insert(0, s)
+    return parent

package/dist/composer/templates/__init__.py

@@ -0,0 +1,13 @@
+"""templates — per-node emission templates and archetype templates-as-code (D7, D8).
+
+Two template families live here. Per-node emission templates (Jinja2, or plain f-string
+templates) sit next to their registry entries and are what the compiler walks in topo
+order to emit straight-line ``scan.py``. Archetype templates are the machine-generated
+first-draft anchors for ``composer new``: they are CODE built from the same pydantic
+registry types (never YAML-with-holes), so a template referencing a nonexistent node or
+port fails CI and cannot drift from the vocabulary. ``composer new`` binds mechanically
+bindable answers (universe, intervals, top-N, TTL, exit preset) directly and leaves
+genuinely bespoke slots (weights, thresholds, edge logic) TODO-marked WITH working
+defaults, so the emitted graph validates and compiles before any edit. (Only the
+archetypes the POC graphs need are added, in slice 6 — not all ten.)
+"""

package/dist/composer/templates/scan.py.j2

@@ -0,0 +1,34 @@
+{{ '"""' }}AUTOGENERATED by `composer compile` from {{ source_name }} — do not edit by hand.
+
+Strategy: {{ strategy }} (archetype: {{ archetype }}).
+Emitted onto the external_scanner contract: scan(inputs, ctx) -> list[dict].
+The graph is materialized straight-line in topological order; each block below is
+named with its graph node id. Regenerate with `composer compile` — edits are lost.
+
+Nodes ({{ node_count }}): {{ node_ids }}.
+{{ '"""' }}
+import time
+{% for imp in extra_imports %}import {{ imp }}
+{% endfor %}
+# strategy_primitives is a self-contained, vendored SNAPSHOT of the composer primitives,
+# staged as a sibling package of this scan.py (the scanner dir is on sys.path). The composer
+# checkout does NOT ship to the runtime box — this package is what makes the strategy standalone.
+from strategy_primitives import emitters, filters, indicators, rankers, scorers, sources, stateful
+from strategy_primitives.adapter import make_adapter
+
+# Base universe — the candles_fetch whitelist, overridable via inputs["whitelist"].
+_BASE_UNIVERSE = {{ base_universe }}
+
+
+def scan(inputs, ctx):
+    _now = time.time()
+    src = make_adapter(ctx)
+    base_universe = [str(_a).upper() for _a in inputs.get("whitelist", _BASE_UNIVERSE)]
+
+{% for line in prologue %}    {{ line }}
+{% endfor %}
+{% for line in body %}    {{ line }}
+{% endfor %}
+{% for line in epilogue %}    {{ line }}
+{% endfor %}
+    return {{ return_var }}

package/dist/composer/validator/__init__.py

@@ -0,0 +1,29 @@
+"""validator — schema and graph typecheck whose teaching errors are the product.
+
+The validator parses authored YAML to JSON (anchors/merge keys banned per D6), validates
+it against the registry-generated JSON Schema, then runs the graph checks: cycle
+detection, topo-sort, port typechecking, parameter-bound checks, and unknown-node refusal
+that names the nearest valid alternatives. The graph never executes as a DAG, so these are
+~50-100 lines of plain checks, not an orchestration framework. Error format is a
+first-class deliverable (the SERR037 lesson): every error carries location (node id /
+port / line), what is wrong, and a concrete fix hint, so a small model can repair it in
+one iteration. (Implemented in slice 2 as a table of one-error-class-per-test cases.)
+
+Public API:
+    validate_text / validate_file — run the full pipeline, return a ValidationResult.
+    ValidationResult              — collected errors; .ok, .render() (text), .to_json().
+    TeachingError / Location      — the located, fix-hinted error model.
+    ERROR_CODES                   — stable code -> error-class table.
+"""
+
+from .errors import ERROR_CODES, Location, TeachingError, ValidationResult
+from .validate import validate_file, validate_text
+
+__all__ = [
+    "validate_text",
+    "validate_file",
+    "ValidationResult",
+    "TeachingError",
+    "Location",
+    "ERROR_CODES",
+]

package/dist/composer/validator/desugar.py

@@ -0,0 +1,133 @@
+"""desugar — expand the ``pipeline:`` shorthand into the canonical nodes+edges DAG (D1).
+
+Stage (b), applied BEFORE schema validation so every later stage (schema, graph checks,
+and eventually the compiler) sees exactly one representation: the DAG. The shorthand
+exists because the common case is a straight line — ``candles -> indicator -> score ->
+rank -> emit`` — and making the agent hand-wire that by port is needless friction. Once a
+strategy needs fan-out/join it drops the shorthand and writes nodes+edges directly (D1:
+"once you need joins you need named references, which is a DAG").
+
+A ``pipeline`` is a list of steps; each step is either a bare node-type string
+(``candles_fetch``) or a mapping in the same shape as a node entry (``{id?, node,
+with?}``). Consecutive steps are wired primary-output -> primary-input, where "primary"
+is the first non-``state`` output / input port the registry declares for that node. Ids
+default to the node type, de-duplicated with a ``_2`` suffix. The result is byte-for-byte
+the DAG the author would have written by hand — proven by the desugar-equivalence test.
+"""
+
+from __future__ import annotations
+
+from composer.registry import NODES_BY_NAME, PortType
+
+from .errors import Location, TeachingError
+
+
+def has_pipeline(doc: object) -> bool:
+    return isinstance(doc, dict) and "pipeline" in doc
+
+
+def _primary_output(node_name: str) -> str | None:
+    node = NODES_BY_NAME.get(node_name)
+    if node is None:
+        return None
+    for port in node.outputs:
+        if port.type != PortType.state:
+            return port.name
+    return None
+
+
+def _primary_input(node_name: str) -> str | None:
+    node = NODES_BY_NAME.get(node_name)
+    if node is None:
+        return None
+    for port in node.inputs:
+        if port.type != PortType.state:
+            return port.name
+    return None
+
+
+def desugar(doc: dict) -> tuple[dict, list[TeachingError]]:
+    """Return ``(canonical_doc, errors)``.
+
+    ``canonical_doc`` has the ``pipeline`` key replaced by generated ``nodes`` and
+    ``edges``. On a malformed pipeline the returned doc still carries whatever nodes could
+    be built, so downstream stages can pile on additional findings (errors collect, they
+    do not short-circuit).
+    """
+    errors: list[TeachingError] = []
+    steps = doc.get("pipeline")
+    if not isinstance(steps, list):
+        errors.append(
+            TeachingError(
+                code="CMP020",
+                message="`pipeline:` must be a list of node steps.",
+                fix_hint="Write `pipeline:` as a YAML list, e.g. `pipeline: [candles_fetch, sma]`.",
+            )
+        )
+        return doc, errors
+
+    if "nodes" in doc or "edges" in doc:
+        errors.append(
+            TeachingError(
+                code="CMP020",
+                message="`pipeline:` cannot be combined with explicit `nodes:`/`edges:`.",
+                fix_hint="Use EITHER the `pipeline:` shorthand OR an explicit `nodes:`+`edges:` graph, not both.",
+            )
+        )
+
+    nodes: list[dict] = []
+    edges: list[dict] = []
+    id_counts: dict[str, int] = {}
+    prev: dict | None = None  # {"id":..., "node":...}
+
+    for i, step in enumerate(steps):
+        if isinstance(step, str):
+            entry: dict = {"node": step}
+        elif isinstance(step, dict):
+            entry = dict(step)
+        else:
+            errors.append(
+                TeachingError(
+                    code="CMP020",
+                    message=f"pipeline step #{i + 1} is neither a node name nor a node mapping.",
+                    fix_hint="Each step must be a node-type string or a `{node: <name>, with: {...}}` mapping.",
+                )
+            )
+            continue
+
+        node_name = entry.get("node")
+        if not isinstance(node_name, str) or not node_name:
+            errors.append(
+                TeachingError(
+                    code="CMP020",
+                    message=f"pipeline step #{i + 1} has no `node:` type.",
+                    fix_hint="Give the step a registry node type, e.g. `- node: sma`.",
+                )
+            )
+            continue
+
+        base_id = entry.get("id") or node_name
+        count = id_counts.get(base_id, 0) + 1
+        id_counts[base_id] = count
+        node_id = base_id if count == 1 else f"{base_id}_{count}"
+
+        node: dict = {"id": node_id, "node": node_name}
+        if "with" in entry:
+            node["with"] = entry["with"]
+        nodes.append(node)
+
+        if prev is not None:
+            out_port = _primary_output(prev["node"])
+            in_port = _primary_input(node_name)
+            if out_port and in_port:
+                edges.append(
+                    {"from": f"{prev['id']}.{out_port}", "to": f"{node_id}.{in_port}"}
+                )
+            # If either node type is unknown the auto-edge is skipped; the unknown-node
+            # graph check (CMP030) will name it — no need to guess a wiring.
+        prev = node
+
+    canonical = {k: v for k, v in doc.items() if k != "pipeline"}
+    canonical["nodes"] = nodes
+    canonical["edges"] = edges
+    return canonical, errors

package/dist/composer/validator/errors.py

@@ -0,0 +1,227 @@
+"""errors — the teaching-error model; the slice-2 product (the SERR037 lesson).
+
+An unhelpful validator error ("schema violation at $.nodes[3].with") makes a small model
+guess; a *teaching* error tells it exactly where, what, and the one concrete thing to do
+next, so it repairs in a single iteration. Every error the validator emits is a
+:class:`TeachingError` carrying:
+
+    code       — a stable identifier (``CMP0xx``); never changes meaning across releases,
+                 so agents/tests can match on it.
+    location   — where: node id, port, and YAML line where each is available.
+    message    — what is wrong, in one sentence.
+    fix_hint   — one CONCRETE next action (a name to use, a command to run, a bound to
+                 respect) — not "fix the schema".
+
+All errors from one run are collected into a :class:`ValidationResult` and reported
+together, ordered by location, so the agent sees every defect at once rather than
+peeling them off one round-trip at a time. The result renders to plain text an LLM reads
+directly, and to a JSON structure for the ``--json`` CLI surface.
+
+The codes are the layered graph-semantic checks the validator adds ON TOP of JSON Schema
+param validation (which the registry-generated schema already carries in full) — the
+validator does not re-check param bounds itself, it translates the schema's findings into
+this same teaching shape and adds the checks a schema cannot express (ports, types,
+cycles, connectivity).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ---------------------------------------------------------------- stable error-code table
+# code -> one-line description of the error class it marks. Kept here so it is impossible
+# to add an ad-hoc code without also naming its class (and so tests can enumerate them).
+ERROR_CODES: dict[str, str] = {
+    "CMP001": "YAML could not be parsed (syntax error).",
+    "CMP002": "YAML anchors, aliases, or merge keys are not allowed (D6).",
+    "CMP003": "Document root is not a mapping / is empty.",
+    "CMP010": "Unknown parameter passed to a node's `with:` block.",
+    "CMP011": "Parameter value is out of its allowed range.",
+    "CMP012": "Parameter value has the wrong type.",
+    "CMP013": "A required parameter or top-level field is missing.",
+    "CMP014": "Document violates the graph schema (other).",
+    "CMP020": "The `pipeline:` shorthand is malformed.",
+    "CMP030": "Unknown node type (names nearest valid alternatives).",
+    "CMP031": "Duplicate node id.",
+    "CMP032": "Edge references a node id that does not exist.",
+    "CMP033": "Edge references a port that the node does not declare.",
+    "CMP034": "Edge connects two ports of incompatible type.",
+    "CMP035": "The graph contains a cycle (reports the cycle path).",
+    "CMP036": "A required input port has no incoming edge.",
+    "CMP037": "Two or more edges write to the same (non-mergeable) input port.",
+    "CMP038": "A node declares neither a registry `node:` type nor `kind: pure_fn`.",
+    "CMP039": "A `raw` port feeds a non-pure_fn node (raw may only feed a pure_fn normalizer).",
+    # ---- pure_fn purity (D2 kind 2): static AST allowlist on the fn body ----
+    "CMP040": "A pure_fn `fn:` block is not exactly one well-formed top-level function def.",
+    "CMP041": "A pure_fn body imports a module outside the allowlist (math, statistics only).",
+    "CMP042": "A pure_fn body uses a disallowed builtin or reflection escape (I/O, eval, dunder).",
+    "CMP043": "A pure_fn body references a forbidden/undeclared name (ctx, MCP, or an external).",
+    "CMP044": "A pure_fn signature does not match its declared input ports + params.",
+    "CMP045": "A pure_fn does not return its declared outputs (arity mismatch).",
+    "CMP046": "A pure_fn writes global/nonlocal state.",
+    # ---- escape hatch (mcp_read source): read-only, snapshot-bounded tool checks ----
+    "CMP060": "An mcp_read `tool` is not in the committed MCP snapshot (unknown tool).",
+    "CMP061": "An mcp_read `tool` is a mutation (write) tool — scanners are read-only producers.",
+    # ---- pure_fn inline fixture tests (run at validate time) ----
+    "CMP050": "A pure_fn inline test produced the wrong output.",
+    "CMP051": "A pure_fn inline test raised an exception when run.",
+    "CMP052": "A pure_fn inline test is malformed (unknown/ unbindable input or output).",
+    # ---- runtime-unit (slice 9): the emitted runtime.yaml, judged by the real Zod+DSL oracle ----
+    "CMP100": "Missing a required top-level runtime field (`name` or `strategy.wallet`).",
+    "CMP101": "The `risk` block has an unknown or renamed-legacy key (`.strict()` object).",
+    "CMP102": "A `risk.guard_rails` value is out of its allowed range.",
+    "CMP110": "The exit DSL preset is invalid (breaches / tier order / preset config).",
+    "CMP111": "`dsl_preset` is misplaced at the top level (must be nested under `exit:`).",
+    # ---- A3 install-time parity: checks that only fire when the runtime BOOTS (not just parses) ----
+    "CMP112": "DSL exit active but position-tracking wiring is missing/broken (position_tracker scanner + POSITION_TRACKER action wired).",
+    "CMP113": "A scanner or action `name` is duplicated (names must be unique within one runtime).",
+    "CMP114": "An action `decision_prompt` references a `{{placeholder}}` no context entry or param resolves.",
+    "CMP115": "An unbound `${VAR}` env placeholder would resolve to empty at install (only `${..._WALLET}` is ops-bound).",
+    "CMP120": "Unmanaged strategy with no exit and no explicit `unmanaged` opt-out (composer policy).",
+    "CMP199": "The runtime.yaml failed the Zod schema for another reason.",
+    # ---- A2 install verb: preflight + copy + wallet-bind of a staged unit onto a box ----
+    "CMP200": "The install target is not a staged unit (no manifest.json / staged tree not found).",
+    "CMP201": "A staged artifact's content does not match its manifest hash (corrupt or hand-edited staging).",
+    "CMP202": "The staged unit is not installable — its recorded oracle verdict is INVALID (not GREEN).",
+    "CMP203": "A file copied into the canonical hash dir does not match its manifest hash (tamper / IO fault).",
+    "CMP204": "The canonical hash dir is already bound to a DIFFERENT wallet (phase-1: one wallet per content dir).",
+    "CMP205": "The `--wallet` argument is missing or not a 0x… address.",
+    "CMP206": "Install `--wallet` omitted and no ACTIVE funded wallet.json to auto-bind (missing / pending / stale).",
+    # ---- A2 install verb: mapped installRuntime (frozen consumer) failure classes ----
+    "CMP210": "Install rejected — a runtime with this id already exists on the box.",
+    "CMP211": "Install rejected — a runtime for this wallet is already running (one running runtime per wallet).",
+    "CMP212": "Install rejected — the strategy wallet is not ACTIVE (or not found in your Senpi account).",
+    "CMP213": "Install rejected — the runtime YAML was invalid/incomplete at load.",
+    "CMP214": "Install rejected — the external-scanner entrypoint (scan.py) was not found on disk.",
+    "CMP219": "Install rejected — `openclaw senpi runtime create` failed for another reason.",
+    # ---- B1 close verb: safe teardown (stop runtime → confirm gone → trigger strategy_close) ----
+    "CMP220": "Close aborted — `openclaw senpi runtime delete` failed; strategy_close withheld.",
+    "CMP221": "Close aborted — the runtime is still present after delete (teardown unconfirmed); strategy_close withheld.",
+    "CMP222": "Close failed — MCP `strategy_close` submit failed.",
+    "CMP223": "MCP credentials missing (SENPI_AUTH_TOKEN / SENPI_API_KEY) — close/fund need the MCP server.",
+    "CMP224": "Close failed — resolved a wallet but no strategyId (nothing to close, or MCP unreachable).",
+    "CMP225": "Close refused — the target could not be resolved to any strategy.",
+    # ---- B3 fund verb: create + fund a strategy's wallet as a first-class composer step ----
+    "CMP230": "Fund refused — `--budget` is missing, non-numeric, or below the $100 platform minimum.",
+    "CMP231": "Fund refused — the recorded wallet.json is stale (its strategy is closed or not found).",
+    "CMP232": "Fund refused — the visible balance is short of the requested budget (states shortfall + bridged-funds lag).",
+    "CMP233": "Fund failed — MCP `strategy_create_custom_strategy` submit failed or returned no strategyId.",
+}
+
+
+@dataclass(frozen=True)
+class Location:
+    """Where an error is, as precisely as the document allows.
+
+    ``node``/``port``/``line`` locate a graph defect; ``path`` locates a runtime.yaml defect
+    as the Zod/DSL dot-path (e.g. ``exit.dsl_preset.phase1.consecutive_breaches_required``) —
+    the CMP1xx runtime-unit errors (slice 9) carry it verbatim so the fix is pin-pointable."""
+
+    node: Optional[str] = None
+    port: Optional[str] = None
+    line: Optional[int] = None
+    path: Optional[str] = None
+
+    def render(self) -> str:
+        parts: list[str] = []
+        if self.node is not None:
+            parts.append(f"node {self.node!r}")
+        if self.port is not None:
+            parts.append(f"port {self.port!r}")
+        if self.path is not None:
+            parts.append(f"runtime.yaml {self.path or '(root)'}")
+        if self.line is not None:
+            parts.append(f"line {self.line}")
+        return ", ".join(parts) if parts else "document"
+
+    def to_dict(self) -> dict:
+        return {"node": self.node, "port": self.port, "line": self.line, "path": self.path}
+
+    @property
+    def _sort_key(self) -> tuple:
+        # Order by line first (defects the author sees top-to-bottom), then node/port/path.
+        return (
+            self.line if self.line is not None else 1_000_000,
+            self.node or "",
+            self.port or "",
+            self.path or "",
+        )
+
+
+@dataclass(frozen=True)
+class TeachingError:
+    """A single located, actionable validation error."""
+
+    code: str
+    message: str
+    fix_hint: str
+    location: Location = field(default_factory=Location)
+
+    def __post_init__(self) -> None:
+        if self.code not in ERROR_CODES:
+            raise KeyError(
+                f"unknown error code {self.code!r}; add it to ERROR_CODES in "
+                f"composer/validator/errors.py so every code has a documented class"
+            )
+
+    @property
+    def sort_key(self) -> tuple:
+        return self.location._sort_key + (self.code,)
+
+    def render(self) -> str:
+        return (
+            f"[{self.code}] {self.location.render()}: {self.message}\n"
+            f"        fix: {self.fix_hint}"
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "fix_hint": self.fix_hint,
+            "location": self.location.to_dict(),
+        }
+
+
+@dataclass
+class ValidationResult:
+    """The outcome of one validation run: every error, collected and reportable together."""
+
+    source: str  # a label for the validated document (path or "<text>")
+    errors: list[TeachingError] = field(default_factory=list)
+
+    def add(self, error: TeachingError) -> None:
+        self.errors.append(error)
+
+    def extend(self, errors: list[TeachingError]) -> None:
+        self.errors.extend(errors)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def sorted_errors(self) -> list[TeachingError]:
+        return sorted(self.errors, key=lambda e: e.sort_key)
+
+    def render(self) -> str:
+        """Plain-text verdict + every error, ordered by location — for an LLM to read."""
+        if self.ok:
+            return f"OK: {self.source} is a valid strategy graph ({0} errors)."
+        n = len(self.errors)
+        lines = [
+            f"INVALID: {self.source} has {n} error{'s' if n != 1 else ''}.",
+            "",
+        ]
+        for err in self.sorted_errors():
+            lines.append(err.render())
+            lines.append("")
+        return "\n".join(lines).rstrip() + "\n"
+
+    def to_json(self) -> dict:
+        return {
+            "source": self.source,
+            "ok": self.ok,
+            "error_count": len(self.errors),
+            "errors": [e.to_dict() for e in self.sorted_errors()],
+        }