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

package/dist/composer/registry/models.py

@@ -0,0 +1,417 @@
+"""models — pydantic v2 node-definition models; the registry's typed vocabulary (D4, D8).
+
+A ``NodeDef`` is a single declaration in the registry: a name, a ``kind``, typed
+input/output ports drawn from a small closed :class:`PortType` vocabulary, a typed and
+bounded parameter schema, a docstring, a one-line YAML example, and a cost note. These
+models are the ONLY source of truth (D4): the graph JSON Schema, the catalog index, the
+per-node describe text, the validator's type rules, and (later) the compiler's emission
+all derive from ``NODES``. Nothing downstream is hand-maintained, so nothing can drift.
+
+Invalid declarations fail **at model construction** (this is the slice-1 oracle), not at
+use: an unknown port type, duplicate port names, a stateful node missing its state
+in/out pair, a numeric default outside its bounds, or an example ``with:`` key naming a
+param the node does not declare all raise ``ValidationError`` when ``NODES`` is built at
+import time.
+
+Port-type vocabulary (kept deliberately small; every type is justified by a real corpus
+usage — see the per-member comments):
+
+    asset_list   — a set of tradeable assets / instruments.
+    candles      — multi-interval OHLCV candle data keyed by asset.
+    feature_map  — a per-asset computed feature (float / bool / direction), keyed by asset.
+    score_map    — a per-asset {score, reasons[], ...} record.
+    signals      — the emitted signal-envelope list; the ``scan()`` return value.
+    scalar       — a single account-level numeric value (equity).
+    state        — the ``ctx.state`` carrier; stateful nodes only (D2).
+    record_list  — an ORDERED list of typed dict records with NO asset-keying invariant
+                   (strategy metadata / open orders / closed-trade rows). Distinct from
+                   ``asset_list`` (whose entries are coin symbols every consumer relies on,
+                   e.g. ``held_asset_exclusion``): a ``record_list`` is generic tabular data
+                   whose only intended consumer is a ``kind: pure_fn`` node that declares a
+                   ``record_list`` input and reads the record fields itself.
+    label        — a market-wide categorical string: a SINGLE enum value describing the whole
+                   board, NOT a value per asset (the funding-regime vocabulary addition, 2026-
+                   07-16 — see the enum member's justification memo).
+    raw          — the ONE escape type: a generic opaque payload consumable ONLY by a
+                   ``kind: pure_fn`` node (never a curated node). The single boundary type that
+                   makes every reachable MCP shape consumable without letting a wire bypass
+                   typing — see the enum member's justification memo (2026-07-16).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal, Optional, Union
+
+import yaml
+from pydantic import BaseModel, ConfigDict, model_validator
+
+SCHEMA_VERSION = 1
+
+
+class PortType(str, Enum):
+    """Closed vocabulary of data types that can flow along an edge (D1 typed ports).
+
+    Small by design: every member cites the corpus strategy that forces its existence.
+    An edge port declared with any value outside this enum fails at construction.
+    """
+
+    # stag's fixed whitelist BTC/ETH/SOL/HYPE; magpie's discovered IPOP universe;
+    # the held-position set from clearinghouse_state (all five packages exclude held).
+    asset_list = "asset_list"
+    # candles_fetch output; consumed by every indicator (stag 4h, hawk 1h+4h, bison 15m/1h/4h).
+    candles = "candles"
+    # per-asset indicator outputs (sma/pct_change/trend_structure/rsi/...), sm_lean tilt,
+    # own_return_24h — every indicator in stag/hawk/bison emits a per-asset feature.
+    feature_map = "feature_map"
+    # scorer output: weighted-sum score + reasons[] per asset (stag/hawk/bison/thesis-fund).
+    score_map = "score_map"
+    # signal_envelope output — the scan() list[dict] return (all five packages).
+    signals = "signals"
+    # clearinghouse_state dual-DEX max() account equity (stag/hawk/bison read it).
+    scalar = "scalar"
+    # ctx.state carrier owned by the stateful ttl_dedup_state node's in/out pair (D2);
+    # the dedup pattern is universal across the corpus.
+    state = "state"
+    # list of non-asset-keyed dict records (strategy_list / open_orders / trader_history
+    # rows) — the world-coverage read surface (batch C) exposes tabular reads that are not
+    # asset-keyed; a pure_fn declaring a record_list input is the intended consumer.
+    record_list = "record_list"
+    # JUSTIFICATION MEMO (the 9th sanctioned port type; additions remain rare, deliberate,
+    # maintainer-owned decisions — the 10th, the generic `raw` escape type, landed 2026-07-16
+    # below; the vocabulary is closed and deliberately so). A market-wide CATEGORICAL string: one
+    # enum value describing the WHOLE board, not a value per asset. market_get_funding_regime's
+    # `regime` (LONG_CROWDED | SHORT_CROWDED | NEUTRAL) is the first and motivating case — a
+    # single string for the entire market, read once per tick. Why not an existing type:
+    #   * feature_map is per-asset KEYED — a regime has no asset key (a single-key {"_": ...}
+    #     map is a lie about the shape and every feature consumer joins on the asset key);
+    #   * scalar is a single NUMBER (account equity) — a regime is categorical, not arithmetic
+    #     (widening scalar to carry strings breaks its documented numeric invariant);
+    #   * record_list is a LIST of dict records — a single categorical value forced into a
+    #     one-row list is the awkwardness the funding-regime audit explicitly flagged.
+    # CONSUMER EXPECTATIONS (what any node declaring a `label` input may assume): the value is
+    # a bare string from a small, tool-documented enum (or "" when the read failed/degraded);
+    # there is NO per-asset structure to index and NO arithmetic to do. The intended consumer
+    # is a `kind: pure_fn` node (which reads the string and branches on it — e.g. veto entries
+    # while the regime is crowded); any other node declaring a `label` input treats it as an
+    # opaque category. The regime's numeric companions ride a SEPARATE record_list output, so
+    # `label` stays a pure categorical.
+    label = "label"
+    # JUSTIFICATION MEMO (the 10th port type — the ONE escape type; 2026-07-16). A generic,
+    # OPAQUE payload: the unwrapped `data` of an arbitrary MCP read, carried untyped along a
+    # single wire. It exists to close the "unwrapped MCP reads" wall — the mcp_read source node
+    # emits `raw` so any reachable shape the curated source vocabulary hasn't wrapped is still
+    # consumable — WITHOUT letting a wire bypass typing. The mechanism that makes that safe:
+    #   * `raw` is consumable ONLY by a `kind: pure_fn` node (enforced in the validator, CMP039:
+    #     "raw may only feed a pure_fn — write a normalizer"). No curated node may declare a
+    #     `raw` input; every curated port stays one of the 9 real shapes.
+    #   * the consuming pure_fn is a NORMALIZER: it declares TYPED outputs (feature_map /
+    #     record_list / score_map / ...) and carries inline fixture tests, so the opaque payload
+    #     is pinned to a real shape by AUTHOR-OWNED fixtures at the moment it re-enters the typed
+    #     graph. Nothing downstream of the normalizer ever sees `raw`.
+    # This is the deliberate division of labour the whole registry rests on: AGENTS BUILD NODES
+    # AND NORMALIZERS, NEVER TYPES. `raw` is the single boundary type a maintainer sanctions so
+    # that agents never need to (the type vocabulary stays closed at 10). CONSUMER EXPECTATIONS:
+    # there are none — `raw` is arbitrary JSON-ish data (or None on a failed/degraded read); a
+    # pure_fn normalizer must defensively read it and is the only place that may.
+    raw = "raw"
+
+
+class NodeKind(str, Enum):
+    """The node kinds (D2). ``pure_fn`` is reserved for slice 4 and has no slice-1 entry.
+
+    ``stateful`` also carries a cycle-detection semantic (D4, moved off the validator in
+    slice 2.5): a stateful node's outputs carry PRIOR-tick data (the ctx.state boundary),
+    so edges leaving a stateful node's outputs do not count as forward dependencies when
+    the validator's DFS looks for cycles — that is what lets the universal ttl-dedup
+    feedback loop (``recent`` -> filter -> ... -> ``ttl_dedup_state`` -> ``recent``) wire up
+    without tripping CMP035. This is keyed off ``kind``, not a per-port flag, because it is
+    a property of the whole node's tick semantics, not of any one port.
+    """
+
+    source = "source"
+    indicator = "indicator"
+    filter = "filter"
+    scorer = "scorer"
+    ranker = "ranker"
+    emitter = "emitter"
+    stateful = "stateful"
+    pure_fn = "pure_fn"
+
+
+# Closed param-type vocabulary. Scalars + a string list (whitelists/intervals) + a
+# str->float map (every scorer in the corpus is a weighted sum, so weight/tier maps are
+# a first-class shape, not free-form JSON) + a str-keyed JSON map (map_str_json). The last
+# was added 2026-07-16 for the mcp_read escape hatch ONLY: an MCP tool's argument object is
+# genuinely arbitrary JSON (mixed str/number/bool/list values, e.g.
+# {"time_frame": "ALL_TIME", "limit": 100}), which NO existing param type can hold —
+# map_str_float is number-valued, list[str] is string-valued, and there is no other free-form
+# param shape in the registry. It is BOUNDED (str keys; JSON-primitive/list/dict values only,
+# passed verbatim to the tool) and is the sole map_str_json param in the vocabulary.
+ParamType = Literal[
+    "int", "float", "str", "bool", "list[str]", "map_str_float", "map_str_json"
+]
+
+# The JSON value types a map_str_json param's values may take (bounded: no arbitrary objects).
+_JSON_VALUE_TYPES = (str, int, float, bool, list, dict, type(None))
+
+ParamDefault = Union[int, float, str, bool, tuple, dict, None]
+
+
+class Port(BaseModel):
+    """A named, typed input or output port on a node (D1).
+
+    ``required`` and ``merge`` are INPUT-port semantics (D4): the registry is the single
+    source of truth for both, so the validator reads them off the port rather than
+    special-casing port names or types. ``NodeDef._check_port_flags`` rejects either flag
+    set to a non-default value on an OUTPUT port, since neither concept applies there.
+
+        required — False marks an input that may be left unwired: the strategy's
+            configured universe / preset supplies it at runtime instead of a graph edge
+            (e.g. an ``asset_list`` input named ``assets``/``candidates``, the
+            ``signal_envelope.equity`` sizing input, or a stateful node's ``state`` input,
+            which is wired by the runtime tick boundary — ctx.state — not a graph edge).
+            Defaults to True (unwired = CMP036).
+        merge — True marks an input that legally accepts more than one writer (a
+            key-union merge across writers), rather than the default single-writer rule
+            (a second writer = CMP037). Currently only the scorer/gate ``features``
+            (feature_map) inputs, since every indicator in the corpus emits one feature
+            and scorers consume the merged record. Defaults to False.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    type: PortType
+    doc: str
+    required: bool = True
+    merge: bool = False
+
+    @model_validator(mode="after")
+    def _check(self) -> "Port":
+        if not self.name.strip():
+            raise ValueError("port name must be non-empty")
+        if not self.doc.strip():
+            raise ValueError(f"port {self.name!r} must have a doc string")
+        return self
+
+
+class Param(BaseModel):
+    """A typed, bounded parameter with an optional corpus-median default.
+
+    A ``None`` default means the param is required in the graph document; any other value
+    makes it optional and is emitted into the JSON Schema as the ``default``.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    type: ParamType
+    doc: str
+    default: ParamDefault = None
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+    choices: Optional[tuple[str, ...]] = None
+
+    @model_validator(mode="after")
+    def _check(self) -> "Param":
+        if not self.name.strip():
+            raise ValueError("param name must be non-empty")
+        if not self.doc.strip():
+            raise ValueError(f"param {self.name!r} must have a doc string")
+
+        numeric = self.type in ("int", "float")
+        if not numeric and (self.minimum is not None or self.maximum is not None):
+            raise ValueError(
+                f"param {self.name!r}: bounds only valid on int/float, not {self.type}"
+            )
+        if (
+            self.minimum is not None
+            and self.maximum is not None
+            and self.minimum > self.maximum
+        ):
+            raise ValueError(
+                f"param {self.name!r}: minimum {self.minimum} > maximum {self.maximum}"
+            )
+        if self.choices is not None and self.type != "str":
+            raise ValueError(f"param {self.name!r}: choices only valid on str params")
+
+        if self.default is not None:
+            self._check_default_type()
+            if numeric:
+                d = float(self.default)  # type: ignore[arg-type]
+                if self.minimum is not None and d < self.minimum:
+                    raise ValueError(
+                        f"param {self.name!r}: default {self.default} < minimum {self.minimum}"
+                    )
+                if self.maximum is not None and d > self.maximum:
+                    raise ValueError(
+                        f"param {self.name!r}: default {self.default} > maximum {self.maximum}"
+                    )
+            if self.choices is not None and self.default not in self.choices:
+                raise ValueError(
+                    f"param {self.name!r}: default {self.default!r} not in choices {self.choices}"
+                )
+        return self
+
+    def _check_default_type(self) -> None:
+        d = self.default
+        is_bool = type(d) is bool
+        if self.type == "int":
+            if not (isinstance(d, int) and not is_bool):
+                raise ValueError(f"param {self.name!r}: default must be int, got {d!r}")
+        elif self.type == "float":
+            if is_bool or not isinstance(d, (int, float)):
+                raise ValueError(f"param {self.name!r}: default must be a number, got {d!r}")
+        elif self.type == "str":
+            if not isinstance(d, str):
+                raise ValueError(f"param {self.name!r}: default must be str, got {d!r}")
+        elif self.type == "bool":
+            if not is_bool:
+                raise ValueError(f"param {self.name!r}: default must be bool, got {d!r}")
+        elif self.type == "list[str]":
+            if not (isinstance(d, tuple) and all(isinstance(x, str) for x in d)):
+                raise ValueError(
+                    f"param {self.name!r}: default must be a tuple[str, ...], got {d!r}"
+                )
+        elif self.type == "map_str_float":
+            ok = isinstance(d, dict) and all(
+                isinstance(k, str) and isinstance(v, (int, float)) and type(v) is not bool
+                for k, v in d.items()
+            )
+            if not ok:
+                raise ValueError(
+                    f"param {self.name!r}: default must be a dict[str, float], got {d!r}"
+                )
+        elif self.type == "map_str_json":
+            ok = isinstance(d, dict) and all(
+                isinstance(k, str) and isinstance(v, _JSON_VALUE_TYPES) for k, v in d.items()
+            )
+            if not ok:
+                raise ValueError(
+                    f"param {self.name!r}: default must be a str-keyed JSON map "
+                    f"(str keys, JSON-primitive/list/dict values), got {d!r}"
+                )
+
+
+class NodeDef(BaseModel):
+    """A single node declaration — the atom of the registry."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    kind: NodeKind
+    summary: str  # one-liner for the catalog index
+    doc: str  # full description for `composer describe`
+    inputs: tuple[Port, ...] = ()
+    outputs: tuple[Port, ...] = ()
+    params: tuple[Param, ...] = ()
+    example: str  # a single-node YAML snippet
+    cost: str  # cost note (MCP calls / pure compute)
+    # For kind=source: the MCP read tool this node wraps, declared MACHINE-READABLY so the
+    # CI closure check (composer/registry/mcp_closure.py) can prove the source vocabulary
+    # still fully covers the scanner-usable read surface without parsing prose docs. None for
+    # a pure/derived source (universe_discover, own_return_24h — no MCP read) and for every
+    # non-source node. Two source nodes may legally wrap the SAME tool (the single-wallet and
+    # batch discovery_get_trader_state readers).
+    mcp_tool: Optional[str] = None
+
+    @model_validator(mode="after")
+    def _check(self) -> "NodeDef":
+        if not self.name.strip():
+            raise ValueError("node name must be non-empty")
+        for label, text in (("summary", self.summary), ("doc", self.doc), ("cost", self.cost)):
+            if not text.strip():
+                raise ValueError(f"node {self.name!r}: {label} must be non-empty")
+
+        self._check_unique(self.inputs, "input port")
+        self._check_unique(self.outputs, "output port")
+        self._check_unique(self.params, "param")
+
+        self._check_state_ports()
+        self._check_port_flags()
+        self._check_example()
+        self._check_mcp_tool()
+        return self
+
+    def _check_mcp_tool(self) -> None:
+        # mcp_tool is a SOURCE-only declaration (the closure check scans sources). A non-source
+        # node carrying it is an authoring error; a blank string is never a valid tool name.
+        if self.mcp_tool is None:
+            return
+        if not self.mcp_tool.strip():
+            raise ValueError(f"node {self.name!r}: mcp_tool must be a non-empty tool name")
+        if self.kind != NodeKind.source:
+            raise ValueError(
+                f"node {self.name!r}: mcp_tool is only valid on kind=source "
+                f"(the closure check scans sources); {self.kind.value} node declares one"
+            )
+
+    def _check_unique(self, items: tuple, label: str) -> None:
+        seen: set[str] = set()
+        for item in items:
+            if item.name in seen:
+                raise ValueError(f"node {self.name!r}: duplicate {label} {item.name!r}")
+            seen.add(item.name)
+
+    def _check_state_ports(self) -> None:
+        state_ins = [p for p in self.inputs if p.type == PortType.state]
+        state_outs = [p for p in self.outputs if p.type == PortType.state]
+        if self.kind == NodeKind.stateful:
+            # D2: a stateful node declares exactly one state in/out port pair.
+            if len(state_ins) != 1 or len(state_outs) != 1:
+                raise ValueError(
+                    f"node {self.name!r}: a stateful node must declare exactly one "
+                    f"state input and one state output (the ctx.state in/out pair, D2); "
+                    f"got {len(state_ins)} in / {len(state_outs)} out"
+                )
+        else:
+            if state_ins or state_outs:
+                raise ValueError(
+                    f"node {self.name!r}: only kind=stateful may use the 'state' port "
+                    f"type (D2); {self.kind.value} node declares a state port"
+                )
+
+    def _check_port_flags(self) -> None:
+        # required/merge are input-port concepts (see Port docstring); an output setting
+        # either to its non-default value is a registry authoring error, not a real state.
+        for port in self.outputs:
+            if not port.required:
+                raise ValueError(
+                    f"node {self.name!r}: output port {port.name!r} cannot set "
+                    f"required=False (required only applies to input ports)"
+                )
+            if port.merge:
+                raise ValueError(
+                    f"node {self.name!r}: output port {port.name!r} cannot set "
+                    f"merge=True (merge only applies to input ports)"
+                )
+
+    def _check_example(self) -> None:
+        try:
+            parsed = yaml.safe_load(self.example)
+        except yaml.YAMLError as exc:  # pragma: no cover - defensive
+            raise ValueError(f"node {self.name!r}: example is not valid YAML: {exc}")
+        if not isinstance(parsed, dict):
+            raise ValueError(f"node {self.name!r}: example must be a single YAML mapping")
+        if parsed.get("node") != self.name:
+            raise ValueError(
+                f"node {self.name!r}: example 'node:' must equal {self.name!r}, "
+                f"got {parsed.get('node')!r}"
+            )
+        param_names = {p.name for p in self.params}
+        with_block = parsed.get("with", {}) or {}
+        if not isinstance(with_block, dict):
+            raise ValueError(f"node {self.name!r}: example 'with:' must be a mapping")
+        for key in with_block:
+            if key not in param_names:
+                raise ValueError(
+                    f"node {self.name!r}: example references unknown param {key!r} "
+                    f"(declared params: {sorted(param_names)})"
+                )
+        extra = set(parsed) - {"node", "with", "id"}
+        if extra:
+            raise ValueError(
+                f"node {self.name!r}: example has unexpected keys {sorted(extra)} "
+                f"(allowed: id, node, with)"
+            )