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

package/dist/composer/compiler/compile.py

@@ -0,0 +1,550 @@
+"""compile — the deterministic materializer: graph -> straight-line scan.py (D5, D8).
+
+Pipeline (HLD D8, no IR, no optimization):
+
+    validate (reuse composer.validator)  ->  a hard gate; refuse to compile an invalid
+                                             graph, surfacing the teaching-error report.
+    load + desugar                        ->  canonical nodes + edges (the graph IS the IR).
+    topo-sort (non-stateful nodes)        ->  a stable straight-line order.
+    Jinja2 template walk                  ->  a single self-contained-except-primitives
+                                             scan.py on the external_scanner contract.
+
+Determinism is a hard requirement (the recompile oracle): stable node iteration
+(topo order with an id tie-break), sorted keys in every emitted literal, no timestamps
+in the artifact. Same graph -> byte-identical scan.py.
+
+Stateful nodes are compiled onto ctx.state and SPLIT into a prologue (read prior-tick
+state -> the `recent` exclusion set) and an epilogue (append this tick's emitted
+signals). Data-source nodes compile onto the ctx MCP surface via the thin
+``primitives.adapter`` (the golden-test stubbing seam). Emitted code is readable:
+every block is commented with its node id.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader
+
+from composer.pure_fn import is_pure_fn_entry, parse_pure_fn
+from composer.registry import NODES_BY_NAME, NodeKind, PortType
+from composer.validator import validate_text
+from composer.validator.desugar import desugar, has_pipeline
+from composer.validator.loader import load_graph
+
+_TEMPLATE_DIR = Path(__file__).resolve().parent.parent / "templates"
+
+
+class CompileError(Exception):
+    """Raised when a graph cannot be compiled (invalid graph, or a structural gap)."""
+
+
+# --------------------------------------------------------------------------- literals
+
+def _pyliteral(value) -> str:
+    """Deterministic Python-literal rendering: dict keys sorted, tuples -> lists."""
+    if isinstance(value, dict):
+        items = ", ".join(f"{_pyliteral(k)}: {_pyliteral(v)}" for k, v in sorted(value.items()))
+        return "{" + items + "}"
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(_pyliteral(v) for v in value) + "]"
+    if isinstance(value, bool):
+        return "True" if value else "False"
+    return repr(value)
+
+
+def _sanitize(node_id: str) -> str:
+    return "".join(ch if (ch.isalnum() or ch == "_") else "_" for ch in node_id)
+
+
+def _var(node_id: str, port: str) -> str:
+    return f"{_sanitize(node_id)}__{port}"
+
+
+# --------------------------------------------------------------------------- model
+
+class _Graph:
+    """The parsed, validated graph in the shape the emitter walks."""
+
+    def __init__(self, doc: dict):
+        self.nodes = doc.get("nodes") or []
+        self.edges = doc.get("edges") or []
+        self.metadata = doc.get("metadata") or {}
+        self.id_to_type: dict[str, str] = {}
+        self.with_of: dict[str, dict] = {}
+        self.pure_fns: dict[str, object] = {}   # id -> PureFnNode (open extension, D2 kind 2)
+        for n in self.nodes:
+            nid = n["id"]
+            if is_pure_fn_entry(n):
+                self.pure_fns[nid] = parse_pure_fn(n)
+            else:
+                self.id_to_type[nid] = n["node"]
+                self.with_of[nid] = n.get("with") or {}
+        # incoming[(to_id, to_port)] = [(from_id, from_port), ...]
+        self.incoming: dict[tuple[str, str], list[tuple[str, str]]] = {}
+        for e in self.edges:
+            fid, fport = e["from"].split(".", 1)
+            tid, tport = e["to"].split(".", 1)
+            self.incoming.setdefault((tid, tport), []).append((fid, fport))
+
+    def nodedef(self, node_id: str):
+        if node_id in self.pure_fns:
+            return self.pure_fns[node_id]
+        return NODES_BY_NAME[self.id_to_type[node_id]]
+
+    def param(self, node_id: str, param_name: str):
+        """The `with:` value for a param, else its (registry / pure_fn) default."""
+        if node_id in self.pure_fns:
+            for p in self.pure_fns[node_id].params:
+                if p.name == param_name:
+                    return p.default
+            return None
+        w = self.with_of[node_id]
+        if param_name in w:
+            return w[param_name]
+        for p in self.nodedef(node_id).params:
+            if p.name == param_name:
+                return p.default
+        return None
+
+    def base_universe(self) -> list:
+        """The candles_fetch whitelist (there is one in the POC graphs), for the
+        _BASE_UNIVERSE constant and unwired asset_list defaults."""
+        for nid, ntype in self.id_to_type.items():
+            if ntype == "candles_fetch":
+                wl = self.param(nid, "whitelist") or ()
+                return [str(a).upper() for a in wl]
+        return []
+
+
+# --------------------------------------------------------------------------- topo sort
+
+def _topo_order(g: _Graph) -> list[str]:
+    """Deterministic topo order over the NON-stateful nodes.
+
+    Edges out of a stateful node carry prior-tick data (its `recent` output is
+    prologue-provided), and edges into a stateful node are handled in the epilogue, so
+    neither constrains the body order. Ties broken by node id for byte-stability.
+    """
+    body = [n["id"] for n in g.nodes if g.nodedef(n["id"]).kind != NodeKind.stateful]
+    body_set = set(body)
+    deps: dict[str, set] = {nid: set() for nid in body}
+    for (tid, _tport), writers in g.incoming.items():
+        if tid not in body_set:
+            continue
+        for fid, _fport in writers:
+            if fid in body_set and g.nodedef(fid).kind != NodeKind.stateful:
+                deps[tid].add(fid)
+    order: list[str] = []
+    done: set = set()
+    remaining = set(body)
+    while remaining:
+        ready = sorted(nid for nid in remaining if deps[nid] <= done)
+        if not ready:
+            raise CompileError(f"cycle among body nodes: {sorted(remaining)}")
+        pick = ready[0]
+        order.append(pick)
+        done.add(pick)
+        remaining.discard(pick)
+    return order
+
+
+# --------------------------------------------------------------------------- inputs
+
+def _resolve_input(g: _Graph, node_id: str, port) -> str:
+    """A Python expression for the value flowing into ``node_id.port.name``."""
+    writers = g.incoming.get((node_id, port.name), [])
+    if port.merge:
+        # merge_features keyed by SOURCE NODE ID (see scorers.merge_features).
+        items = ", ".join(
+            f"{_pyliteral(fid)}: {_var(fid, fport)}"
+            for fid, fport in sorted(writers)
+        )
+        return "{" + items + "}"
+    if writers:
+        fid, fport = writers[0]
+        return _var(fid, fport)
+    # unwired optional input
+    if port.type == PortType.asset_list:
+        return "base_universe"
+    return "None"
+
+
+# --------------------------------------------------------------------------- emitters
+
+def _kwargs(g: _Graph, node_id: str, param_names) -> str:
+    parts = []
+    for name in param_names:
+        parts.append(f"{name}={_pyliteral(g.param(node_id, name))}")
+    return ", ".join(parts)
+
+
+def _emit_pure_fn(g: _Graph, node_id: str) -> list[str]:
+    """Materialize a pure_fn node: its declared `def` verbatim (readable, node-id
+    commented), then a call binding its declared outputs. The def is emitted nested inside
+    scan() at the node's topological position and called like any other node. Determinism
+    is preserved: the body is emitted byte-for-byte as authored and args are resolved in
+    declared port/param order.
+    """
+    pfn = g.pure_fns[node_id]
+    fd = pfn.function_def()
+    fn_name = fd.name  # purity guaranteed exactly one def by the time we compile
+    lines = [
+        f"# node: {node_id} (pure_fn) — LLM-written, purity-checked "
+        f"(no ctx/MCP/I/O; math/statistics only)",
+    ]
+    # the authored def, verbatim (each line is indented +4 by the template -> nested).
+    lines.extend(pfn.fn_src.strip("\n").split("\n"))
+    port_exprs = [_resolve_input(g, node_id, p) for p in pfn.inputs]
+    param_vals = [_pyliteral(g.param(node_id, p.name)) for p in pfn.params]
+    args = ", ".join(port_exprs + param_vals)
+    outs = ", ".join(_var(node_id, p.name) for p in pfn.outputs)
+    lines.append(f"{outs} = {fn_name}({args})")
+    return lines
+
+
+def _emit_body_node(g: _Graph, node_id: str) -> list[str]:
+    nd = g.nodedef(node_id)
+    if nd.kind == NodeKind.pure_fn:
+        return _emit_pure_fn(g, node_id)
+    ntype = nd.name
+    lines = [f"# node: {node_id} ({ntype}) — {nd.summary}"]
+
+    if ntype == "candles_fetch":
+        assets_input = next(p for p in nd.inputs if p.name == "assets")
+        assets_expr = _resolve_input(g, node_id, assets_input)
+        intervals = list(g.param(node_id, "intervals") or ())
+        inc_f = bool(g.param(node_id, "include_funding"))
+        inc_ac = bool(g.param(node_id, "include_asset_context"))
+        raw = f"_raw_{_sanitize(node_id)}"
+        lines.append(
+            f"{raw} = {{_a: src.asset_data(_a, {_pyliteral(intervals)}, "
+            f"include_funding={_pyliteral(inc_f)}, "
+            f"include_asset_context={_pyliteral(inc_ac)}) for _a in {assets_expr}}}"
+        )
+        lines.append(
+            f"{_var(node_id, 'candles')} = sources.candles_fetch({raw}, "
+            f"intervals={_pyliteral(intervals)})"
+        )
+        return lines
+
+    if ntype == "clearinghouse_state":
+        lines.append(
+            f"{_var(node_id, 'held')}, {_var(node_id, 'equity')} = "
+            f"sources.clearinghouse_state(src.clearinghouse())"
+        )
+        return lines
+
+    if ntype == "sm_lean":
+        assets_input = next(p for p in nd.inputs if p.name == "assets")
+        assets_expr = _resolve_input(g, node_id, assets_input)
+        thr = g.param(node_id, "agree_threshold")
+        lines.append(
+            f"{_var(node_id, 'lean')} = sources.sm_lean(src.leaderboard_markets(), "
+            f"assets={assets_expr}, agree_threshold={_pyliteral(thr)})"
+        )
+        return lines
+
+    if ntype == "instrument_list":
+        dex = g.param(node_id, "dex") or ""
+        lines.append(
+            f"{_var(node_id, 'instruments')} = sources.instrument_list("
+            f"src.instruments(dex={_pyliteral(dex)}))"
+        )
+        return lines
+
+    if ntype == "universe_discover":
+        insts = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "instruments"))
+        kw = _kwargs(g, node_id, ["min_day_volume", "max_leverage_cap", "name_prefix"])
+        lines.append(
+            f"{_var(node_id, 'universe')} = sources.universe_discover({insts}, {kw})"
+        )
+        return lines
+
+    if ntype == "own_return_24h":
+        candles_expr = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "candles"))
+        lines.append(
+            f"{_var(node_id, 'return_24h')} = sources.own_return_24h({candles_expr})"
+        )
+        return lines
+
+    # ---- batch C: world-coverage sources (recon §2) ---------------------------------
+    if ntype == "market_prices_fetch":
+        assets_expr = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "assets"))
+        dex = g.param(node_id, "dex") or ""
+        lines.append(
+            f"{_var(node_id, 'prices')} = sources.market_prices("
+            f"src.market_prices(dex={_pyliteral(dex)}), assets={assets_expr})"
+        )
+        return lines
+
+    if ntype == "strategy_list_fetch":
+        status = g.param(node_id, "status") or ""
+        stype = g.param(node_id, "strategy_type") or ""
+        lines.append(
+            f"{_var(node_id, 'strategies')} = sources.strategy_list("
+            f"src.strategy_list(status={_pyliteral(status)}, strategy_type={_pyliteral(stype)}))"
+        )
+        return lines
+
+    if ntype == "open_orders_fetch":
+        lines.append(
+            f"{_var(node_id, 'orders')} = sources.open_orders(src.open_orders())"
+        )
+        return lines
+
+    if ntype == "trader_history_fetch":
+        ta = g.param(node_id, "trader_address")
+        limit = g.param(node_id, "limit")
+        lines.append(
+            f"{_var(node_id, 'closed_positions')} = sources.trader_history("
+            f"src.trader_history(trader_address={_pyliteral(ta)}, limit={_pyliteral(limit)}))"
+        )
+        return lines
+
+    if ntype == "asset_trading_limits_fetch":
+        assets_expr = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "assets"))
+        dex = g.param(node_id, "dex") or ""
+        raw = f"_raw_{_sanitize(node_id)}"
+        lines.append(
+            f"{raw} = {{_a: src.asset_trading_limits(_a, dex={_pyliteral(dex)}) "
+            f"for _a in {assets_expr}}}"
+        )
+        lines.append(
+            f"{_var(node_id, 'max_leverage')} = sources.asset_trading_limits({raw})"
+        )
+        return lines
+
+    if ntype == "strategy_pnl_snapshot":
+        period = g.param(node_id, "period") or ""
+        dd = bool(g.param(node_id, "drawdown_reset_on_day_rollover"))
+        lines.append(
+            f"{_var(node_id, 'today_pnl')}, {_var(node_id, 'today_account_value')}, "
+            f"{_var(node_id, 'today_drawdown')} = sources.strategy_pnl_snapshot("
+            f"src.pnl_snapshot(period={_pyliteral(period)}, "
+            f"drawdown_reset_on_day_rollover={_pyliteral(dd)}))"
+        )
+        return lines
+
+    if ntype == "trader_state_fetch":
+        ta = g.param(node_id, "trader_address")
+        lines.append(
+            f"{_var(node_id, 'held')}, {_var(node_id, 'equity')} = "
+            f"sources.trader_state(src.trader_state(trader_address={_pyliteral(ta)}))"
+        )
+        return lines
+
+    if nd.kind == NodeKind.indicator:
+        candles_expr = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "candles"))
+        outs = ", ".join(_var(node_id, p.name) for p in nd.outputs)
+        kw = _kwargs(g, node_id, [p.name for p in nd.params])
+        lines.append(f"{outs} = indicators.{ntype}({candles_expr}, {kw})")
+        return lines
+
+    if ntype == "held_asset_exclusion":
+        cand = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "candidates"))
+        held = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "held"))
+        lines.append(
+            f"{_var(node_id, 'kept')} = filters.held_asset_exclusion("
+            f"candidates={cand}, held={held})"
+        )
+        return lines
+
+    if ntype == "recent_signal_ttl_dedup":
+        cand = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "candidates"))
+        recent = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "recent"))
+        lines.append(
+            f"{_var(node_id, 'kept')} = filters.recent_signal_ttl_dedup("
+            f"candidates={cand}, recent={recent})"
+        )
+        return lines
+
+    if ntype == "classifier_predicate":
+        cand = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "candidates"))
+        kw = _kwargs(g, node_id, ["max_funding_abs", "max_leverage", "exclude_delisted"])
+        lines.append(
+            f"{_var(node_id, 'kept')} = filters.classifier_predicate(candidates={cand}, {kw})"
+        )
+        return lines
+
+    if ntype == "live_instrument_validation":
+        cand = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "candidates"))
+        insts = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "instruments"))
+        lines.append(
+            f"{_var(node_id, 'kept')} = filters.live_instrument_validation("
+            f"candidates={cand}, instruments={insts})"
+        )
+        return lines
+
+    if ntype == "hard_gates_all":
+        feats = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "features"))
+        merged = f"_features_{_sanitize(node_id)}"
+        kw = _kwargs(g, node_id, ["required_gates", "weights", "min_score"])
+        lines.append(f"{merged} = scorers.merge_features({feats})")
+        lines.append(f"{_var(node_id, 'scores')} = scorers.hard_gates_all({merged}, {kw})")
+        return lines
+
+    if ntype == "emit_single_best":
+        scores = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "scores"))
+        kw = _kwargs(g, node_id, ["min_score"])
+        lines.append(f"{_var(node_id, 'selected')} = rankers.emit_single_best({scores}, {kw})")
+        return lines
+
+    if ntype == "rank_pool_cap_to_open_slots":
+        scores = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "scores"))
+        held = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "held"))
+        kw = _kwargs(g, node_id, ["max_slots", "min_score"])
+        lines.append(
+            f"{_var(node_id, 'selected')} = rankers.rank_pool_cap_to_open_slots("
+            f"{scores}, held={held}, {kw})"
+        )
+        return lines
+
+    if ntype == "signal_envelope":
+        selected = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "selected"))
+        equity = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "equity"))
+        kw = _kwargs(g, node_id, ["margin_pct", "leverage", "clamp_leverage_to_venue"])
+        # Optional parity kwargs are appended ONLY when used, so graphs that set none of them
+        # emit byte-identically to the pre-batch-D compiler (existing goldens unchanged):
+        #  - instruments (live board) is emitted only when a graph wires it (the real clamp);
+        #  - valid_for_seconds only when a positive TTL override is set;
+        #  - signal_type only when a non-empty label is set.
+        extra: list[str] = []
+        if g.incoming.get((node_id, "instruments")):
+            insts = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "instruments"))
+            extra.append(f"instruments={insts}")
+        vfs = g.param(node_id, "valid_for_seconds")
+        if isinstance(vfs, int) and not isinstance(vfs, bool) and vfs > 0:
+            extra.append(f"valid_for_seconds={_pyliteral(vfs)}")
+        st = g.param(node_id, "signal_type")
+        if isinstance(st, str) and st:
+            extra.append(f"signal_type={_pyliteral(st)}")
+        tail = (", " + ", ".join(extra)) if extra else ""
+        lines.append(
+            f"{_var(node_id, 'signals')} = emitters.signal_envelope({selected}, "
+            f"equity={equity}, {kw}{tail})"
+        )
+        return lines
+
+    raise CompileError(
+        f"node {node_id!r} has type {ntype!r} which the compiler cannot emit. Every registry "
+        f"primitive is emittable; bespoke scoring/classification is not a primitive — express "
+        f"that edge as a pure_fn node, as bison/magpie/thesis-fund do."
+    )
+
+
+def _emit_stateful_prologue(g: _Graph, node_id: str) -> list[str]:
+    nd = g.nodedef(node_id)
+    kw = _kwargs(g, node_id, ["ttl_seconds", "prune_factor"])
+    statemap = f"_statemap_{_sanitize(node_id)}"
+    return [
+        f"# node: {node_id} ({nd.name}) [read] — {nd.summary}",
+        f"{_var(node_id, 'recent')}, {statemap} = stateful.ttl_dedup_state_read("
+        f"ctx.state, {kw}, now=_now)",
+    ]
+
+
+def _emit_stateful_epilogue(g: _Graph, node_id: str) -> list[str]:
+    nd = g.nodedef(node_id)
+    emitted = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "emitted"))
+    statemap = f"_statemap_{_sanitize(node_id)}"
+    return [
+        f"# node: {node_id} ({nd.name}) [write] — record this tick's signals in ctx.state",
+        f"stateful.ttl_dedup_state_write(ctx.state, {statemap}, emitted={emitted}, now=_now)",
+    ]
+
+
+# --------------------------------------------------------------------------- driver
+
+def _pure_fn_imports(g: _Graph) -> list[str]:
+    """The sorted set of allow-listed modules (math/statistics) any pure_fn body uses."""
+    allowed = {"math", "statistics"}
+    used: set[str] = set()
+    for pfn in g.pure_fns.values():
+        fd = pfn.function_def()
+        if fd is None:
+            continue
+        for node in ast.walk(fd):
+            if isinstance(node, ast.Name) and node.id in allowed:
+                used.add(node.id)
+    return sorted(used)
+
+
+def _return_var(g: _Graph) -> str:
+    emitters_ids = [nid for nid in g.id_to_type if g.nodedef(nid).kind == NodeKind.emitter]
+    if len(emitters_ids) != 1:
+        raise CompileError(
+            f"a graph must have exactly one emitter (the scan() return); got {emitters_ids}"
+        )
+    return _var(emitters_ids[0], "signals")
+
+
+def compile_text(text: str, source_name: str = "<graph>") -> str:
+    """Validate then compile graph YAML text into scan.py source (a str)."""
+    result = validate_text(text, source=source_name)
+    if not result.ok:
+        raise CompileError(
+            f"refusing to compile an invalid graph ({source_name}):\n{result.render()}"
+        )
+
+    data, _line_index = load_graph(text)
+    if has_pipeline(data):
+        data, _errs = desugar(data)
+    g = _Graph(data)
+
+    stateful_ids = sorted(
+        nid for nid in g.id_to_type if g.nodedef(nid).kind == NodeKind.stateful
+    )
+
+    prologue: list[str] = []
+    for sid in stateful_ids:
+        prologue.extend(_emit_stateful_prologue(g, sid))
+
+    body: list[str] = []
+    for nid in _topo_order(g):
+        block = _emit_body_node(g, nid)
+        if body:
+            body.append("")
+        body.extend(block)
+
+    epilogue: list[str] = []
+    for sid in stateful_ids:
+        if epilogue:
+            epilogue.append("")
+        epilogue.extend(_emit_stateful_epilogue(g, sid))
+
+    # Allow-listed modules any pure_fn body references (math / statistics) become
+    # module-level imports so the nested pure_fn defs can reach them. Sorted for
+    # determinism; empty (and thus absent) for pure-primitive graphs like stag/hawk.
+    extra_imports = _pure_fn_imports(g)
+
+    env = Environment(
+        loader=FileSystemLoader(str(_TEMPLATE_DIR)),
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+    )
+    template = env.get_template("scan.py.j2")
+    node_ids = ", ".join(n["id"] for n in g.nodes)
+    rendered = template.render(
+        source_name=source_name,
+        strategy=g.metadata.get("strategy", "unnamed"),
+        archetype=g.metadata.get("archetype", "unknown"),
+        node_count=len(g.nodes),
+        node_ids=node_ids,
+        base_universe=_pyliteral(g.base_universe()),
+        extra_imports=extra_imports,
+        prologue=prologue,
+        body=body,
+        epilogue=epilogue,
+        return_var=_return_var(g),
+    )
+    # normalize any trailing whitespace introduced by the template loop, keep 1 newline.
+    lines = [ln.rstrip() for ln in rendered.split("\n")]
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+def compile_file(path, source_name: str | None = None) -> str:
+    p = Path(path)
+    return compile_text(p.read_text(encoding="utf-8"), source_name or p.name)

package/dist/composer/examples/breakout_swing.graph.yaml

@@ -0,0 +1,121 @@
+# breakout_swing — breakout swing-trading strategy (tier 1) over a 3-asset basket, as a
+# typed dataflow DAG.
+#
+# Hand-authored from the corpus-recon inventory (hawk section): a BTC/ETH/SOL basket
+# scanned on 1h + 4h candles. Two HARD gates in the corpus (a directional breakout of the
+# prior-7d closes, and smart-money agreement); the 4h trend-structure and volume ratio are
+# score contributors. Single-best emission, universal TTL signal-dedup on ctx.state.
+# Re-expression of corpus package hawk; semantics cited to skills/strategies/hawk/...
+#
+# Re-expression notes (correctness = the slice-3 goldens, not the original's bit output):
+#  - breakout_detect.direction is the sole hard gate (required_gates: [brk]); it is also
+#    the emitted trade direction (the scorer's direction detector reads the LONG/SHORT
+#    feature). Smart-money is a weighted contributor here rather than a second hard,
+#    direction-matched gate — the generic scorer gates on truthiness, not cross-feature
+#    agreement (documented deviation; corpus fidelity is the slice-8 oracle).
+#  - trend_structure emits BULLISH/BEARISH/NEUTRAL, so it can be wired into the same scorer
+#    as breakout_detect (both would otherwise be a "direction" port) without colliding.
+#  - feature/gate/weight keys are SOURCE NODE IDS (the compiler merges keyed by node id).
+
+version: 1
+
+metadata:
+  archetype: breakout
+  strategy: breakout_swing
+  corpus_origin: hawk                # provenance only, for fidelity replay — not user-facing
+  exit_preset: protected_tight       # slice 9: emitted as runtime.yaml exit: (hawk = cut failed breakouts fast)
+  # EDGE (verbatim, machine never interprets): "buy the liquid majors the moment price
+  # breaks a week of range with smart money leaning the same way; ride it with the DSL."
+
+nodes:
+  # --- sources ---
+  - id: account
+    node: clearinghouse_state          # dual-DEX max() equity + held-position set
+
+  - id: dedup_state
+    node: ttl_dedup_state              # ctx.state TTL dedup; `recent` = assets within TTL
+    with:
+      ttl_seconds: 240
+
+  # --- universe narrowing (held-exclusion then recent-signal dedup) ---
+  - id: exclude_held
+    node: held_asset_exclusion         # candidates default to the basket (candles whitelist)
+
+  - id: exclude_recent
+    node: recent_signal_ttl_dedup
+
+  # --- candle + leaderboard reads over the narrowed basket ---
+  - id: candles
+    node: candles_fetch
+    with:
+      whitelist: ["BTC", "ETH", "SOL"]
+      intervals: ["1h", "4h"]
+
+  - id: lean
+    node: sm_lean
+    with:
+      agree_threshold: 0.55            # breakout_swing's own 55% band (not conviction_scorer's 58/42)
+
+  # --- indicators ---
+  - id: brk
+    node: breakout_detect              # HARD gate: prior-168h close high/low break
+    with:
+      window: 168
+      interval: "1h"
+
+  - id: trend4h
+    node: trend_structure              # 4h higher-lows/lower-highs (score contributor)
+    with:
+      lookback: 6
+      interval: "4h"
+
+  - id: vol
+    node: volume_surge_ratio           # 1h recent/baseline volume (score contributor)
+    with:
+      recent_window: 1
+      baseline_window: 10
+      interval: "1h"
+
+  # --- scorer: breakout is the only hard gate; trend/vol/SM contribute ---
+  - id: gates
+    node: hard_gates_all
+    with:
+      required_gates: ["brk"]          # a decisive breakout (LONG/SHORT, not NEUTRAL)
+      # TODO(edge): tune these weights — the strategy's real edge lives here.
+      weights: { brk: 2.0, trend4h: 2.0, vol: 1.0, lean: 0.05 }
+      min_score: 5
+
+  # --- ranker + emitter ---
+  - id: best
+    node: emit_single_best
+    with:
+      min_score: 5
+
+  - id: emit
+    node: signal_envelope
+    with:
+      margin_pct: 20                   # PERCENT of withdrawable (breakout_swing's flat 20%)
+      leverage: 5
+
+edges:
+  # universe narrowing chain
+  - { from: account.held, to: exclude_held.held }
+  - { from: exclude_held.kept, to: exclude_recent.candidates }
+  - { from: dedup_state.recent, to: exclude_recent.recent }
+  - { from: exclude_recent.kept, to: candles.assets }
+  - { from: exclude_recent.kept, to: lean.assets }
+  # candles fan out to indicators
+  - { from: candles.candles, to: brk.candles }
+  - { from: candles.candles, to: trend4h.candles }
+  - { from: candles.candles, to: vol.candles }
+  # per-asset features MERGE into the scorer (keyed by source node id)
+  - { from: brk.direction, to: gates.features }
+  - { from: trend4h.direction, to: gates.features }
+  - { from: vol.ratio, to: gates.features }
+  - { from: lean.lean, to: gates.features }
+  # score -> rank -> emit
+  - { from: gates.scores, to: best.scores }
+  - { from: best.selected, to: emit.selected }
+  - { from: account.equity, to: emit.equity }
+  # close the dedup loop: this tick's signals are recorded in ctx.state
+  - { from: emit.signals, to: dedup_state.emitted }