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

package/dist/composer/compiler/compile.py

@@ -0,0 +1,739 @@
+"""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
+
+    # ---- wave A: remaining world-coverage sources (2026-07-16) ----------------------
+    if ntype == "funding_regime_fetch":
+        lines.append(
+            f"{_var(node_id, 'regime')}, {_var(node_id, 'companions')} = "
+            f"sources.funding_regime(src.funding_regime())"
+        )
+        return lines
+
+    if ntype == "top_traders_fetch":
+        kw = _kwargs(g, node_id, ["time_frame", "sort_by", "bias", "limit", "max_pages",
+                                  "open_position_filter", "activity_labels", "consistency",
+                                  "risk_labels"])
+        lines.append(
+            f"{_var(node_id, 'traders')} = sources.top_traders(src.top_traders({kw}))"
+        )
+        return lines
+
+    if ntype == "trader_states_fetch":
+        records_expr = _resolve_input(
+            g, node_id, next(p for p in nd.inputs if p.name == "traders"))
+        kw = _kwargs(g, node_id, ["wallets", "latest", "include_position_age",
+                                  "sort_open_positions_by", "sort_open_positions_direction"])
+        lines.append(
+            f"{_var(node_id, 'traders')} = sources.trader_states("
+            f"src.trader_states(records={records_expr}, {kw}))"
+        )
+        return lines
+
+    if ntype == "funding_history_fetch":
+        kw = _kwargs(g, node_id, ["asset", "min_annualized_pct", "min_persistence_hours"])
+        lines.append(
+            f"{_var(node_id, 'assets')} = sources.funding_history(src.funding_history({kw}))"
+        )
+        return lines
+
+    if ntype == "cross_asset_flows_fetch":
+        kw = _kwargs(g, node_id, ["leader_asset", "min_move_pct", "window"])
+        lines.append(
+            f"{_var(node_id, 'laggards')}, {_var(node_id, 'leader')} = "
+            f"sources.cross_asset_flows(src.cross_asset_flows({kw}))"
+        )
+        return lines
+
+    if ntype == "trader_positions_fetch":
+        tid = g.param(node_id, "trader_id")
+        lines.append(
+            f"{_var(node_id, 'positions')}, {_var(node_id, 'header')} = "
+            f"sources.trader_positions(src.trader_positions(trader_id={_pyliteral(tid)}))"
+        )
+        return lines
+
+    # ---- wave B: the last scanner-usable world-coverage sources (2026-07-16) --------
+    if ntype == "momentum_events_fetch":
+        kw = _kwargs(g, node_id, ["limit", "tier", "asset", "from_time", "to_time"])
+        lines.append(
+            f"{_var(node_id, 'events')}, {_var(node_id, 'header')} = "
+            f"sources.momentum_events(src.momentum_events({kw}))"
+        )
+        return lines
+
+    if ntype == "top_strategies_fetch":
+        kw = _kwargs(g, node_id, ["limit", "offset", "force_fetch", "max_pages"])
+        lines.append(
+            f"{_var(node_id, 'strategies')} = sources.top_strategies(src.top_strategies({kw}))"
+        )
+        return lines
+
+    if ntype == "arena_leaderboard_fetch":
+        kw = _kwargs(g, node_id, ["period_type", "period_number", "limit", "offset", "qualified"])
+        lines.append(
+            f"{_var(node_id, 'entries')} = sources.arena_leaderboard(src.arena_leaderboard({kw}))"
+        )
+        return lines
+
+    if ntype == "leaderboard_top_fetch":
+        kw = _kwargs(g, node_id, ["limit"])
+        lines.append(
+            f"{_var(node_id, 'traders')}, {_var(node_id, 'header')} = "
+            f"sources.leaderboard_top(src.leaderboard_top({kw}))"
+        )
+        return lines
+
+    if ntype == "leaderboard_trader_fetch":
+        tid = g.param(node_id, "trader_id")
+        lines.append(
+            f"{_var(node_id, 'trader')} = "
+            f"sources.leaderboard_trader(src.leaderboard_trader(trader_id={_pyliteral(tid)}))"
+        )
+        return lines
+
+    if ntype == "open_positions_realized_pnl_fetch":
+        records_expr = _resolve_input(
+            g, node_id, next(p for p in nd.inputs if p.name == "positions"))
+        kw = _kwargs(g, node_id, ["latest"])
+        lines.append(
+            f"{_var(node_id, 'realized')} = sources.open_positions_realized_pnl("
+            f"src.open_positions_realized_pnl(records={records_expr}, {kw}))"
+        )
+        return lines
+
+    if ntype == "account_history_fetch":
+        kw = _kwargs(g, node_id, ["bucket_duration_ms"])
+        lines.append(
+            f"{_var(node_id, 'periods')} = sources.account_history(src.account_history({kw}))"
+        )
+        return lines
+
+    if ntype == "mcp_read":
+        # the escape hatch: a generic passthrough read. tool + verbatim args (snake_case) ->
+        # the adapter unwraps the standard envelope and returns the raw `data` payload, which a
+        # pure_fn normalizer downstream turns back into a typed shape.
+        tool = g.param(node_id, "tool")
+        args = g.param(node_id, "args") or {}
+        timeout = g.param(node_id, "timeout_seconds")
+        tail = ""
+        if isinstance(timeout, (int, float)) and not isinstance(timeout, bool) and timeout > 0:
+            tail = f", timeout_seconds={_pyliteral(timeout)}"
+        lines.append(
+            f"{_var(node_id, 'payload')} = src.raw_read("
+            f"{_pyliteral(tool)}, {_pyliteral(args)}{tail})"
+        )
+        return lines
+
+    if ntype == "threshold_gate":
+        # feature_map -> feature_map (not candles): its `values` input is wired from another
+        # feature node's output (answers indicators[].source), so it can't use the generic
+        # candles-fed indicator path below.
+        values_expr = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "values"))
+        kw = _kwargs(g, node_id, ["op", "value"])
+        lines.append(f"{_var(node_id, 'passed')} = indicators.threshold_gate({values_expr}, {kw})")
+        return lines
+
+    if ntype == "aggregate_bias":
+        # record_list -> feature_map (not candles): its `traders` input is a cohort's TraderState
+        # records (from trader_states_fetch), so it can't use the generic candles-fed path below.
+        traders_expr = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "traders"))
+        lines.append(f"{_var(node_id, 'bias')} = indicators.aggregate_bias({traders_expr})")
+        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]:
+    """READ half of a stateful node (runs BEFORE the body): load prior-tick state and expose the
+    node's prior-tick output ports + a working-state var carried to the epilogue. Dispatched by
+    node name; each stateful node appends its own self-contained single-key fragment to the shared
+    ctx.state series, so multiple stateful nodes coexist (stateful.py `_read_key` scans back)."""
+    nd = g.nodedef(node_id)
+    read = [f"# node: {node_id} ({nd.name}) [read] — {nd.summary}"]
+
+    if nd.name == "ttl_dedup_state":
+        kw = _kwargs(g, node_id, ["ttl_seconds", "prune_factor"])
+        statemap = f"_statemap_{_sanitize(node_id)}"
+        read.append(
+            f"{_var(node_id, 'recent')}, {statemap} = stateful.ttl_dedup_state_read("
+            f"ctx.state, {kw}, now=_now)")
+        return read
+
+    if nd.name == "snapshot_diff_state":
+        kw = _kwargs(g, node_id, ["value_field", "bucket_seconds", "max_snapshots"])
+        working = f"_snapwindow_{_sanitize(node_id)}"
+        read.append(
+            f"{_var(node_id, 'growth')}, {_var(node_id, 'deltas')}, {working} = "
+            f"stateful.snapshot_diff_state_read(ctx.state, {kw}, now=_now)")
+        return read
+
+    if nd.name == "cohort_cache_state":
+        kw = _kwargs(g, node_id, ["ttl_hours", "version"])
+        working = f"_cohortcache_{_sanitize(node_id)}"
+        read.append(
+            f"{_var(node_id, 'cohort')}, {working} = "
+            f"stateful.cohort_cache_state_read(ctx.state, {kw}, now=_now)")
+        return read
+
+    raise CompileError(f"stateful node {node_id!r} has unknown type {nd.name!r} (no prologue emitter)")
+
+
+def _emit_stateful_epilogue(g: _Graph, node_id: str) -> list[str]:
+    """WRITE half of a stateful node (runs AFTER the body): fold THIS tick's late input into the
+    working state and persist a self-contained fragment. Dispatched by node name."""
+    nd = g.nodedef(node_id)
+
+    if nd.name == "ttl_dedup_state":
+        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)",
+        ]
+
+    if nd.name == "snapshot_diff_state":
+        snapshot = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "snapshot"))
+        kw = _kwargs(g, node_id, ["value_field", "bucket_seconds", "max_snapshots"])
+        working = f"_snapwindow_{_sanitize(node_id)}"
+        return [
+            f"# node: {node_id} ({nd.name}) [write] — fold this tick's snapshot into ctx.state",
+            f"stateful.snapshot_diff_state_write(ctx.state, {working}, snapshot={snapshot}, "
+            f"{kw}, now=_now)",
+        ]
+
+    if nd.name == "cohort_cache_state":
+        fresh = _resolve_input(g, node_id, next(p for p in nd.inputs if p.name == "fresh"))
+        kw = _kwargs(g, node_id, ["ttl_hours", "version"])
+        working = f"_cohortcache_{_sanitize(node_id)}"
+        return [
+            f"# node: {node_id} ({nd.name}) [write] — refresh-or-pin the cohort in ctx.state",
+            f"stateful.cohort_cache_state_write(ctx.state, {working}, fresh={fresh}, "
+            f"{kw}, now=_now)",
+        ]
+
+    raise CompileError(f"stateful node {node_id!r} has unknown type {nd.name!r} (no epilogue emitter)")
+
+
+# --------------------------------------------------------------------------- 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)