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

package/dist/composer/registry/nodes.py

@@ -0,0 +1,673 @@
+"""nodes — the 30 primitives with KNOWN need, declared once (D4).
+
+Scope is fixed by the settled build stance (Duncan, 2026-07-15): we build only primitives
+with demonstrated need. Sources are EXHAUSTIVE over the evidenced scanner-facing MCP read
+surface (batch C, world coverage) — every method with a concrete call-site + schema in the
+MCP-surface recon is a source node, and nothing speculative; structural + standard-math
+indicators/filters/rankers/emitter/stateful are justified by corpus duplication. ALL
+bespoke scoring/classification defaults to a pure_fn node (D2 kind 2) — the one generic
+scorer ``hard_gates_all`` covers the simple gate-and-weigh case. The three speculative
+scorers the recon once sketched (conviction_margin_tier, direction_waterfall_then_score,
+fixed_direction_confirmation) were never implemented and were REMOVED 2026-07-15; the
+fn->primitive promote loop is enabled-by, but not part of, the MVP.
+
+Union set: 13 source, 8 indicator, 4 filter, 1 scorer, 2 ranker, 1 emitter, 1 stateful = 30.
+The first 6 sources are the corpus reads; the next 7 (batch C) are the world-coverage reads
+off the evidenced MCP surface (recon §2). Every declaration cites the strategy or MCP method
+that motivates it. whalehunter's remaining tier-3 primitives are deliberately NOT here
+(paper exercise; slice-6 gap report), though batch C's trader_state_fetch closes one.
+
+``NODES`` is built at import time, so any invalid declaration raises immediately (the
+slice-1 construction oracle). ``NODES_BY_NAME`` and ``KIND_ORDER`` support deterministic
+generation downstream.
+"""
+
+from __future__ import annotations
+
+from .models import NodeDef, Param, Port, PortType
+
+# Stable presentation order for every generated artifact (never alphabetical-by-kind).
+KIND_ORDER = (
+    "source",
+    "indicator",
+    "filter",
+    "scorer",
+    "ranker",
+    "emitter",
+    "stateful",
+    "pure_fn",
+)
+
+
+def _p(
+    name: str,
+    type: PortType,
+    doc: str,
+    *,
+    required: bool = True,
+    merge: bool = False,
+) -> Port:
+    return Port(name=name, type=type, doc=doc, required=required, merge=merge)
+
+
+# --------------------------------------------------------------------------- sources (6)
+
+_SOURCES = [
+    NodeDef(
+        name="candles_fetch",
+        kind="source",
+        summary="Fetch multi-interval OHLCV candles for a universe of assets.",
+        doc=(
+            "Reads market_get_asset_data for each asset across one or more intervals. The "
+            "universe comes from the wired `assets` input; when no input is wired the static "
+            "`whitelist` param supplies it (stag's fixed BTC/ETH/SOL/HYPE). Optionally pulls "
+            "funding and asset_context (markPx/prevDayPx) alongside candles."
+        ),
+        inputs=(_p("assets", PortType.asset_list, "Universe to fetch; omit to use the `whitelist` param.",
+                    required=False),),
+        outputs=(_p("candles", PortType.candles, "Per-asset OHLCV keyed by interval."),),
+        params=(
+            Param(name="whitelist", type="list[str]", default=(),
+                  doc="Static universe used when no `assets` input is wired (stag whitelist)."),
+            Param(name="intervals", type="list[str]", default=("4h",),
+                  doc="Candle intervals to fetch (stag 4h; hawk 1h+4h; bison 15m/1h/4h)."),
+            Param(name="include_funding", type="bool", default=False,
+                  doc="Also fetch funding series (bison funding-alignment)."),
+            Param(name="include_asset_context", type="bool", default=False,
+                  doc="Also fetch markPx/prevDayPx asset_context (thesis-fund 24h return)."),
+        ),
+        example='node: candles_fetch\nwith:\n  whitelist: ["BTC", "ETH", "SOL", "HYPE"]\n  intervals: ["4h"]\n',
+        cost="One market_get_asset_data MCP call per asset x interval per tick.",
+    ),
+    NodeDef(
+        name="clearinghouse_state",
+        kind="source",
+        summary="Read account equity and the set of currently-held positions.",
+        doc=(
+            "strategy_get_clearinghouse_state for the strategy wallet. Returns the dual-DEX "
+            "max() account equity and the held-asset set. The 'margin-in-use but empty "
+            "positions' read-sanity skip (hawk) is built in — no param exposes it."
+        ),
+        outputs=(
+            _p("held", PortType.asset_list, "Assets with an open position (for held-exclusion)."),
+            _p("equity", PortType.scalar, "Dual-DEX max() account value."),
+        ),
+        example="node: clearinghouse_state\n",
+        cost="One strategy_get_clearinghouse_state MCP call per tick.",
+    ),
+    NodeDef(
+        name="sm_lean",
+        kind="source",
+        summary="Smart-money net long/short lean per asset from the leaderboard.",
+        doc=(
+            "leaderboard_get_markets per asset, reduced to a net long/short tilt in [0,1]. The "
+            "agreement band is a PARAMETER, not a new node per strategy (stag 0.60, hawk 0.55, "
+            "bison 0.58) — one primitive, three thresholds."
+        ),
+        inputs=(_p("assets", PortType.asset_list, "Assets to read leaderboard lean for.",
+                    required=False),),
+        outputs=(_p("lean", PortType.feature_map, "Per-asset SM tilt in [0,1] plus alignment flag."),),
+        params=(
+            Param(name="agree_threshold", type="float", default=0.55, minimum=0.0, maximum=1.0,
+                  doc="Fraction of aligned SM required to count as agreeing (corpus 0.55-0.60)."),
+        ),
+        example="node: sm_lean\nwith:\n  agree_threshold: 0.6\n",
+        cost="One leaderboard_get_markets MCP call per asset per tick.",
+    ),
+    NodeDef(
+        name="instrument_list",
+        kind="source",
+        summary="List live tradeable instruments with venue metadata.",
+        doc=(
+            "market_list_instruments, used two ways in the corpus: venue-meta lookup "
+            "(max_leverage, is_delisted — thesis-fund) and, filtered through a predicate, "
+            "dynamic-universe discovery (magpie)."
+        ),
+        outputs=(_p("instruments", PortType.asset_list, "Live instruments with venue metadata."),),
+        params=(
+            Param(name="dex", type="str", default="",
+                  doc="Venue filter (e.g. 'xyz'); empty means all venues (magpie uses 'xyz')."),
+        ),
+        example='node: instrument_list\nwith:\n  dex: "xyz"\n',
+        cost="One market_list_instruments MCP call per tick.",
+    ),
+    NodeDef(
+        name="universe_discover",
+        kind="source",
+        summary="Derive a tradeable universe by filtering live instruments on a predicate.",
+        doc=(
+            "Applies a field predicate over instrument_list output to derive the tradeable set "
+            "(magpie's IPOP funding-signature). Generalizes thesis-fund's 'is this on the live "
+            "board' check as the identity predicate. Pure compute over the instrument list."
+        ),
+        inputs=(_p("instruments", PortType.asset_list, "Candidate instruments from instrument_list."),),
+        outputs=(_p("universe", PortType.asset_list, "Instruments passing the membership predicate."),),
+        params=(
+            Param(name="min_day_volume", type="float", default=0.0, minimum=0.0,
+                  doc="Minimum dayNtlVlm floor (magpie liquidity gate)."),
+            Param(name="max_leverage_cap", type="float", default=5.0, minimum=1.0,
+                  doc="Reject instruments whose max leverage exceeds this (magpie <=5)."),
+            Param(name="name_prefix", type="str", default="",
+                  doc="Require instrument name to start with this prefix (magpie 'xyz:')."),
+        ),
+        example='node: universe_discover\nwith:\n  name_prefix: "xyz:"\n  max_leverage_cap: 5\n',
+        cost="Pure compute over instrument_list output; no extra MCP call.",
+    ),
+    NodeDef(
+        name="own_return_24h",
+        kind="source",
+        summary="Per-asset 24h return derived from markPx/prevDayPx asset_context.",
+        doc=(
+            "Derives a 24h percent return per asset from the asset_context (markPx/prevDayPx) "
+            "carried on candles_fetch. thesis-fund consumes this as a distinct momentum feature; "
+            "kept a source per the recon (it is a market read, not a candle transform)."
+        ),
+        inputs=(_p("candles", PortType.candles, "Candles carrying asset_context markPx/prevDayPx."),),
+        outputs=(_p("return_24h", PortType.feature_map, "Per-asset 24h percent return."),),
+        example="node: own_return_24h\n",
+        cost="Derived from candles asset_context; no extra MCP call.",
+    ),
+    # ---- batch C: world coverage over the evidenced MCP read surface (recon §2) -------
+    NodeDef(
+        name="market_prices_fetch",
+        kind="source",
+        summary="Latest per-asset mark prices for a venue.",
+        doc=(
+            "market_get_prices for a venue, reduced to a per-asset price feature_map. The "
+            "response is filtered to the wired `assets` universe (unwired = the base "
+            "whitelist) and keyed as wired so it JOINS the candle/indicator feature_maps on "
+            "one asset key. A live price read distinct from the candle close (no candle "
+            "history), useful as a spot reference for a pure_fn."
+        ),
+        inputs=(_p("assets", PortType.asset_list, "Universe to key prices by; omit to use the base whitelist.",
+                    required=False),),
+        outputs=(_p("prices", PortType.feature_map, "Per-asset latest price."),),
+        params=(
+            Param(name="dex", type="str", default="",
+                  doc="Venue filter (e.g. 'xyz'); empty means the default venue."),
+        ),
+        example='node: market_prices_fetch\nwith:\n  dex: "xyz"\n',
+        cost="One market_get_prices MCP call per tick (all prices for the venue).",
+    ),
+    NodeDef(
+        name="strategy_list_fetch",
+        kind="source",
+        summary="List strategy-metadata records (id, wallet, status, type, funded).",
+        doc=(
+            "strategy_list, reduced to a record_list of strategy metadata "
+            "(id/wallet/trader/status/strategy_type/name/created_at/total_funded). NOT asset-"
+            "keyed — a record_list, whose only consumer is a pure_fn reading the record "
+            "fields. Optionally filtered by status / strategy_type."
+        ),
+        outputs=(_p("strategies", PortType.record_list, "Strategy-metadata records."),),
+        params=(
+            Param(name="status", type="str", default="",
+                  doc="Filter by strategy status (e.g. 'ACTIVE'); empty means all."),
+            Param(name="strategy_type", type="str", default="",
+                  doc="Filter by strategy type; empty means all."),
+        ),
+        example='node: strategy_list_fetch\nwith:\n  status: "ACTIVE"\n',
+        cost="One strategy_list MCP call per tick.",
+    ),
+    NodeDef(
+        name="open_orders_fetch",
+        kind="source",
+        summary="Open resting orders for the strategy's own wallet.",
+        doc=(
+            "strategy_get_open_orders for the strategy wallet, reduced to a record_list of "
+            "order rows (order_id/coin/side/size/price/order_type/status/timestamp). A "
+            "record_list (not asset-keyed) because multiple orders can rest on one coin; the "
+            "consumer is a pure_fn reading the order fields."
+        ),
+        outputs=(_p("orders", PortType.record_list, "Open-order records."),),
+        example="node: open_orders_fetch\n",
+        cost="One strategy_get_open_orders MCP call per tick.",
+    ),
+    NodeDef(
+        name="trader_history_fetch",
+        kind="source",
+        summary="Closed-trade history for an arbitrary trader address.",
+        doc=(
+            "discovery_get_trader_history for a given trader, reduced to a record_list of "
+            "closed-position rows (coin/dex/type/entry_px/exit_px/szi/realized_pnl/"
+            "total_fees/close_time/open_time; times are Unix SECONDS). Enables a "
+            "fade/follow-this-trader's-realized-track-record edge in a pure_fn."
+        ),
+        outputs=(_p("closed_positions", PortType.record_list, "Closed-trade records (Unix-seconds times)."),),
+        params=(
+            Param(name="trader_address", type="str", default=None,
+                  doc="The trader wallet whose closed-trade history to read (required)."),
+            Param(name="limit", type="int", default=100, minimum=1, maximum=1000,
+                  doc="Maximum closed positions to return (most recent first)."),
+        ),
+        example='node: trader_history_fetch\nwith:\n  trader_address: "0xTRADER"\n  limit: 100\n',
+        cost="One discovery_get_trader_history MCP call per tick.",
+    ),
+    NodeDef(
+        name="asset_trading_limits_fetch",
+        kind="source",
+        summary="Per-asset venue max-leverage limit for the own wallet.",
+        doc=(
+            "strategy_get_asset_trading_limits fanned out per-asset over the wired universe "
+            "(one single-asset MCP call each, like candles_fetch), reduced to a max_leverage "
+            "feature_map. Distinct from instrument_list's board-wide max_leverage in that it "
+            "is the account-and-venue-specific tradeable limit."
+        ),
+        inputs=(_p("assets", PortType.asset_list, "Universe to read per-asset limits for; omit to use the base whitelist.",
+                    required=False),),
+        outputs=(_p("max_leverage", PortType.feature_map, "Per-asset venue max leverage."),),
+        params=(
+            Param(name="dex", type="str", default="",
+                  doc="Venue filter (e.g. 'xyz'); empty means the default venue."),
+        ),
+        example='node: asset_trading_limits_fetch\nwith:\n  dex: "xyz"\n',
+        cost="One strategy_get_asset_trading_limits MCP call per asset per tick.",
+    ),
+    NodeDef(
+        name="strategy_pnl_snapshot",
+        kind="source",
+        summary="Today's PnL / account-value / drawdown snapshot for the own wallet.",
+        doc=(
+            "strategy_get_pnl_and_account_value_history for the strategy wallet, decomposed "
+            "into three account-level scalars from today_snapshot (today_pnl, "
+            "today_account_value, today_drawdown). The nested multi-period history_by_period "
+            "is NOT exposed (it would need a record_list; deferred until a consumer needs it)."
+        ),
+        outputs=(
+            _p("today_pnl", PortType.scalar, "Today's realized+unrealized PnL."),
+            _p("today_account_value", PortType.scalar, "Today's account value."),
+            _p("today_drawdown", PortType.scalar, "Today's drawdown."),
+        ),
+        params=(
+            Param(name="period", type="str", default="",
+                  doc="History period hint passed through to the MCP call; empty = default."),
+            Param(name="drawdown_reset_on_day_rollover", type="bool", default=False,
+                  doc="Reset drawdown at the day boundary (passed through to the MCP call)."),
+        ),
+        example="node: strategy_pnl_snapshot\n",
+        cost="One strategy_get_pnl_and_account_value_history MCP call per tick.",
+    ),
+    NodeDef(
+        name="trader_state_fetch",
+        kind="source",
+        summary="An arbitrary trader's current book: held set + account equity.",
+        doc=(
+            "discovery_get_trader_state for a given wallet, reduced to (held, equity) — the "
+            "same contract as clearinghouse_state but generalized OFF the strategy's own "
+            "wallet to ANY trader (a leaderboard entry / smart-money address). Enables copy-"
+            "trading and leaderboard-following archetypes. Same read-sanity guard as "
+            "clearinghouse_state (notional-in-use but empty positions -> corrupt read)."
+        ),
+        outputs=(
+            _p("held", PortType.asset_list, "Assets the trader currently holds."),
+            _p("equity", PortType.scalar, "The trader's account value."),
+        ),
+        params=(
+            Param(name="trader_address", type="str", default=None,
+                  doc="The trader wallet whose current book to read (required)."),
+        ),
+        example='node: trader_state_fetch\nwith:\n  trader_address: "0xTRADER"\n',
+        cost="One discovery_get_trader_state MCP call per tick.",
+    ),
+]
+
+# ------------------------------------------------------------------------ indicators (8)
+# Every indicator: candles -> feature_map. Pure compute, no MCP calls.
+
+_INDICATORS = [
+    NodeDef(
+        name="sma",
+        kind="indicator",
+        summary="Simple moving average of close and an above/below flag.",
+        doc="Simple moving average over `period` closes at `interval`, plus a close>SMA flag (stag SMA-200 trend gate).",
+        inputs=(_p("candles", PortType.candles, "Source candles."),),
+        outputs=(
+            _p("value", PortType.feature_map, "Per-asset SMA of close."),
+            _p("above", PortType.feature_map, "Per-asset boolean: close above the SMA."),
+        ),
+        params=(
+            Param(name="period", type="int", default=200, minimum=1, maximum=1000,
+                  doc="Lookback in bars (stag uses 200)."),
+            Param(name="interval", type="str", default="4h", doc="Candle interval to read."),
+        ),
+        example='node: sma\nwith:\n  period: 200\n  interval: "4h"\n',
+        cost="Pure compute over candles.",
+    ),
+    NodeDef(
+        name="pct_change",
+        kind="indicator",
+        summary="Percent change of close over a lookback window.",
+        doc="Percent change of close over `lookback` bars (stag 7d trend %; bison/thesis-fund price momentum — same shape, different window).",
+        inputs=(_p("candles", PortType.candles, "Source candles."),),
+        outputs=(_p("pct", PortType.feature_map, "Per-asset percent change over the window."),),
+        params=(
+            Param(name="lookback", type="int", default=42, minimum=1,
+                  doc="Bars to look back (stag 7d ~= 42 x 4h)."),
+            Param(name="interval", type="str", default="4h", doc="Candle interval to read."),
+        ),
+        example='node: pct_change\nwith:\n  lookback: 42\n  interval: "4h"\n',
+        cost="Pure compute over candles.",
+    ),
+    NodeDef(
+        name="recent_high_bars_ago",
+        kind="indicator",
+        summary="Bars elapsed since the highest high in a window (fresh-high check).",
+        doc="Counts bars since the highest high within `window` (stag's fresh-high freshness check).",
+        inputs=(_p("candles", PortType.candles, "Source candles."),),
+        outputs=(_p("bars_ago", PortType.feature_map, "Per-asset bars since the window high."),),
+        params=(
+            Param(name="window", type="int", default=60, minimum=2, doc="Bars in the high-water window."),
+            Param(name="interval", type="str", default="4h", doc="Candle interval to read."),
+        ),
+        example='node: recent_high_bars_ago\nwith:\n  window: 60\n',
+        cost="Pure compute over candles.",
+    ),
+    NodeDef(
+        name="volume_surge_ratio",
+        kind="indicator",
+        summary="Recent-window mean volume divided by a baseline-window mean.",
+        doc=(
+            "Unifies stag's volume_surge, hawk's volume_ratio, and bison's volume_trend into one "
+            "parameterized primitive: mean(recent_window) / mean(baseline_window) volume."
+        ),
+        inputs=(_p("candles", PortType.candles, "Source candles."),),
+        outputs=(_p("ratio", PortType.feature_map, "Per-asset recent/baseline volume ratio."),),
+        params=(
+            Param(name="recent_window", type="int", default=6, minimum=1, doc="Recent window (stag 6)."),
+            Param(name="baseline_window", type="int", default=42, minimum=1, doc="Baseline window (stag 42)."),
+            Param(name="interval", type="str", default="4h", doc="Candle interval to read."),
+        ),
+        example='node: volume_surge_ratio\nwith:\n  recent_window: 6\n  baseline_window: 42\n',
+        cost="Pure compute over candles.",
+    ),
+    NodeDef(
+        name="acceleration",
+        kind="indicator",
+        summary="Whether a short-window move is at least half a long-window move.",
+        doc="stag's acceleration test: short-window move >= half the long-window move (a boolean gate).",
+        inputs=(_p("candles", PortType.candles, "Source candles."),),
+        outputs=(_p("accelerating", PortType.feature_map, "Per-asset boolean acceleration flag."),),
+        params=(
+            Param(name="short_window", type="int", default=3, minimum=1, doc="Short move window."),
+            Param(name="long_window", type="int", default=6, minimum=2, doc="Long move window."),
+            Param(name="interval", type="str", default="4h", doc="Candle interval to read."),
+        ),
+        example='node: acceleration\nwith:\n  short_window: 3\n  long_window: 6\n',
+        cost="Pure compute over candles.",
+    ),
+    NodeDef(
+        name="trend_structure",
+        kind="indicator",
+        summary="Higher-lows / lower-highs trend direction over a lookback.",
+        doc=(
+            "Classifies LONG (higher lows) / SHORT (lower highs) / NEUTRAL over `lookback` bars. "
+            "This is the single highest-value dedup target: literally duplicated across hawk, "
+            "bison (x2), magpie, and thesis-fund — 6 corpus call-sites, one primitive."
+        ),
+        inputs=(_p("candles", PortType.candles, "Source candles."),),
+        outputs=(_p("direction", PortType.feature_map, "Per-asset LONG / SHORT / NEUTRAL."),),
+        params=(
+            Param(name="lookback", type="int", default=6, minimum=2, doc="Swing lookback in bars."),
+            Param(name="interval", type="str", default="4h", doc="Candle interval (called at 4h and 1h)."),
+        ),
+        example='node: trend_structure\nwith:\n  lookback: 6\n  interval: "4h"\n',
+        cost="Pure compute over candles.",
+    ),
+    NodeDef(
+        name="breakout_detect",
+        kind="indicator",
+        summary="Directional breakout of the prior-window high/low.",
+        doc="hawk's breakout: LONG if the latest close breaks the prior-`window` high, SHORT if it breaks the low, else NEUTRAL.",
+        inputs=(_p("candles", PortType.candles, "Source candles."),),
+        outputs=(_p("direction", PortType.feature_map, "Per-asset LONG / SHORT / NEUTRAL breakout."),),
+        params=(
+            Param(name="window", type="int", default=168, minimum=2, doc="Prior-close window (hawk 168h)."),
+            Param(name="interval", type="str", default="1h", doc="Candle interval to read."),
+        ),
+        example='node: breakout_detect\nwith:\n  window: 168\n  interval: "1h"\n',
+        cost="Pure compute over candles.",
+    ),
+    NodeDef(
+        name="rsi",
+        kind="indicator",
+        summary="Relative Strength Index over the last N bars.",
+        doc="Trailing-window RSI over the last `period` gains/losses (duplicated verbatim in bison and thesis-fund).",
+        inputs=(_p("candles", PortType.candles, "Source candles."),),
+        outputs=(_p("rsi", PortType.feature_map, "Per-asset RSI in [0,100]."),),
+        params=(
+            Param(name="period", type="int", default=14, minimum=2, maximum=100, doc="RSI lookback (default 14)."),
+            Param(name="interval", type="str", default="1h", doc="Candle interval to read."),
+        ),
+        example='node: rsi\nwith:\n  period: 14\n  interval: "1h"\n',
+        cost="Pure compute over candles.",
+    ),
+]
+
+# --------------------------------------------------------------------------- filters (4)
+# Each filter narrows an asset_list -> asset_list. Pure compute.
+
+_FILTERS = [
+    NodeDef(
+        name="held_asset_exclusion",
+        kind="filter",
+        summary="Drop candidates already held in the account.",
+        doc="Removes any candidate present in the held-position set (all five packages do this).",
+        inputs=(
+            _p("candidates", PortType.asset_list, "Candidate assets.", required=False),
+            _p("held", PortType.asset_list, "Currently-held assets from clearinghouse_state."),
+        ),
+        outputs=(_p("kept", PortType.asset_list, "Candidates not currently held."),),
+        example="node: held_asset_exclusion\n",
+        cost="Pure compute; no MCP call.",
+    ),
+    NodeDef(
+        name="recent_signal_ttl_dedup",
+        kind="filter",
+        summary="Drop candidates signaled within the dedup TTL.",
+        doc=(
+            "Removes candidates that appear in the recently-signaled set produced by "
+            "ttl_dedup_state (all five packages dedup this way). The TTL itself is owned by the "
+            "stateful node; this filter only applies the resulting exclusion set."
+        ),
+        inputs=(
+            _p("candidates", PortType.asset_list, "Candidate assets.", required=False),
+            _p("recent", PortType.asset_list, "Assets signaled within TTL (from ttl_dedup_state)."),
+        ),
+        outputs=(_p("kept", PortType.asset_list, "Candidates not recently signaled."),),
+        example="node: recent_signal_ttl_dedup\n",
+        cost="Pure compute; no MCP call.",
+    ),
+    NodeDef(
+        name="live_instrument_validation",
+        kind="filter",
+        summary="Keep only candidates still live on the venue board.",
+        doc="Intersects candidates with the live instrument board (thesis-fund explicit; magpie implicit via universe_discover).",
+        inputs=(
+            _p("candidates", PortType.asset_list, "Candidate assets.", required=False),
+            _p("instruments", PortType.asset_list, "Live board from instrument_list."),
+        ),
+        outputs=(_p("kept", PortType.asset_list, "Candidates still tradeable."),),
+        example="node: live_instrument_validation\n",
+        cost="Pure compute; no MCP call.",
+    ),
+    NodeDef(
+        name="classifier_predicate",
+        kind="filter",
+        summary="Gate universe membership on a set of instrument-field predicates.",
+        doc=(
+            "magpie's funding-signature IPOP test generalized: a named boolean predicate over "
+            "instrument fields (funding magnitude, max leverage, delisting). Distinct from "
+            "universe_discover in that it classifies an existing candidate set rather than "
+            "deriving one."
+        ),
+        inputs=(_p("candidates", PortType.asset_list, "Candidate instruments with venue fields.",
+                    required=False),),
+        outputs=(_p("kept", PortType.asset_list, "Candidates passing every field predicate."),),
+        params=(
+            Param(name="max_funding_abs", type="float", default=1e-7, minimum=0.0,
+                  doc="Reject if |funding| exceeds this (magpie 1e-7)."),
+            Param(name="max_leverage", type="float", default=5.0, minimum=1.0,
+                  doc="Reject if venue max leverage exceeds this (magpie <=5)."),
+            Param(name="exclude_delisted", type="bool", default=True, doc="Drop delisted instruments."),
+        ),
+        example="node: classifier_predicate\nwith:\n  max_funding_abs: 0.0000001\n  max_leverage: 5\n",
+        cost="Pure compute; no MCP call.",
+    ),
+]
+
+# --------------------------------------------------------------------------- scorers (1)
+# `hard_gates_all` is the ONE generic scorer we build: weighted-sum + reasons[] behind a
+# set of hard gates (stag/hawk + the trend_momentum archetype). Everything more bespoke —
+# waterfall direction, fixed-direction confirmation, conviction-tiered sizing — is a pure_fn
+# node, not a primitive (settled stance 2026-07-15; three speculative scorers removed).
+
+_SCORERS = [
+    NodeDef(
+        name="hard_gates_all",
+        kind="scorer",
+        summary="Require all named gates to pass, then score the survivors.",
+        doc=(
+            "stag's 5/5 hard gates and hawk's 2 required gates + 3 score-only contributors. "
+            "`required_gates` names feature keys that must all be truthy; `weights` scores the "
+            "remaining contributors into a weighted sum with reasons[]."
+        ),
+        inputs=(_p("features", PortType.feature_map, "Merged per-asset feature record.", merge=True),),
+        outputs=(_p("scores", PortType.score_map, "Per-asset {score, reasons[]} for gate-passers."),),
+        params=(
+            Param(name="required_gates", type="list[str]", default=(),
+                  doc="Feature keys that must ALL be truthy (stag's 5 gates)."),
+            Param(name="weights", type="map_str_float", default={},
+                  doc="Feature-key -> weight for the weighted-sum score (bespoke edge slot)."),
+            Param(name="min_score", type="float", default=0.0, minimum=0.0,
+                  doc="Minimum score to keep the candidate."),
+        ),
+        example='node: hard_gates_all\nwith:\n  required_gates: ["above", "accelerating"]\n  min_score: 3\n',
+        cost="Pure compute over the feature map.",
+    ),
+]
+
+# ---------------------------------------------------------------------------- rankers (2)
+
+_RANKERS = [
+    NodeDef(
+        name="emit_single_best",
+        kind="ranker",
+        summary="Sort by score and select the single best candidate.",
+        doc="stag/hawk/bison (and magpie implicitly, since its universe is tiny): sort descending, keep the top 1 above `min_score`.",
+        inputs=(_p("scores", PortType.score_map, "Scored candidates."),),
+        outputs=(_p("selected", PortType.score_map, "The single highest-scoring candidate."),),
+        params=(
+            Param(name="min_score", type="float", default=0.0, doc="Floor below which nothing is emitted."),
+        ),
+        example="node: emit_single_best\nwith:\n  min_score: 3\n",
+        cost="Pure compute over the score map.",
+    ),
+    NodeDef(
+        name="rank_pool_cap_to_open_slots",
+        kind="ranker",
+        summary="Sort by score and take the top (max_slots - held) candidates.",
+        doc="thesis-fund's rank-pool-then-cap: sort all confirming candidates descending, emit the top N where N = max_slots minus the count currently held.",
+        inputs=(
+            _p("scores", PortType.score_map, "Scored candidates."),
+            _p("held", PortType.asset_list, "Held assets, to compute open slots."),
+        ),
+        outputs=(_p("selected", PortType.score_map, "Top (max_slots - held) candidates."),),
+        params=(
+            Param(name="max_slots", type="int", default=5, minimum=1, maximum=50, doc="Maximum concurrent positions."),
+            Param(name="min_score", type="float", default=0.0, doc="Floor below which a candidate is dropped."),
+        ),
+        example="node: rank_pool_cap_to_open_slots\nwith:\n  max_slots: 5\n",
+        cost="Pure compute over the score map.",
+    ),
+]
+
+# ---------------------------------------------------------------------------- emitter (1)
+
+_EMITTERS = [
+    NodeDef(
+        name="signal_envelope",
+        kind="emitter",
+        summary="Build the scan() signal list from selected candidates.",
+        doc=(
+            "Maps selected candidates to the scan contract's return shape: "
+            "{asset, direction, marginPct(0,100], leverage, data{score, reasons[], ...}} "
+            "plus the optional scaffold-recognized keys valid_for_seconds (TTL override) and "
+            "signal_type. Every scanner-settable signal field is expressible — statically via "
+            "params, or dynamically per-asset via the score_map `selected` entry (marginPct, "
+            "leverage, valid_for_seconds, signal_type, data). When `clamp_leverage_to_venue` is "
+            "true AND the live board is wired into `instruments`, each signal's leverage is "
+            "clamped to that instrument's venue max exactly as the corpus clamp_leverage does "
+            "(byte-identical across magpie/thesis-fund); no `instruments` wire = no-op passthrough."
+        ),
+        inputs=(
+            _p("selected", PortType.score_map, "Ranked/selected candidates to emit."),
+            _p("equity", PortType.scalar, "Account equity for sizing (optional wiring).",
+               required=False),
+            _p("instruments", PortType.asset_list,
+               "Live venue board (instrument_list records) for the real per-asset leverage "
+               "clamp; unwired leaves clamp_leverage_to_venue a no-op.", required=False),
+        ),
+        outputs=(_p("signals", PortType.signals, "The scan() return: list of signal dicts."),),
+        params=(
+            Param(name="margin_pct", type="float", default=5.0, minimum=0.0001, maximum=100.0,
+                  doc="Percent of withdrawable to allocate, (0,100] (never a fraction or USD)."),
+            Param(name="leverage", type="float", default=3.0, minimum=1.0, maximum=50.0,
+                  doc="Requested leverage before any venue clamp."),
+            Param(name="clamp_leverage_to_venue", type="bool", default=True,
+                  doc="Clamp leverage down to the instrument's venue max (magpie/thesis-fund)."),
+            Param(name="valid_for_seconds", type="int", default=0, minimum=0,
+                  doc="Per-signal TTL override in seconds; 0 = inherit the runtime default TTL."),
+            Param(name="signal_type", type="str", default="",
+                  doc="Optional signal_type label carried on every emitted signal ('' = none)."),
+        ),
+        example="node: signal_envelope\nwith:\n  margin_pct: 5\n  leverage: 3\n",
+        cost="Pure compute; produces the scan() return value.",
+    ),
+]
+
+# --------------------------------------------------------------------------- stateful (1)
+
+_STATEFUL = [
+    NodeDef(
+        name="ttl_dedup_state",
+        kind="stateful",
+        summary="Track recently-signaled assets in ctx.state with a TTL and pruning.",
+        doc=(
+            "The universal signal-dedup pattern (all five packages): appends each tick's emitted "
+            "signals to ctx.state, prunes entries older than prune_factor x TTL, and exposes the "
+            "assets still within TTL as the `recent` exclusion set consumed by "
+            "recent_signal_ttl_dedup. Declares the state in/out port pair (D2)."
+        ),
+        inputs=(
+            _p("emitted", PortType.signals, "Signals emitted this tick, to record."),
+            _p("state_in", PortType.state, "Incoming ctx.state (D2 state port).", required=False),
+        ),
+        outputs=(
+            _p("recent", PortType.asset_list, "Assets signaled within TTL (exclusion set)."),
+            _p("state_out", PortType.state, "Updated ctx.state after append + prune (D2 state port)."),
+        ),
+        params=(
+            Param(name="ttl_seconds", type="int", default=240, minimum=1,
+                  doc="Dedup window in seconds (stag/hawk 240, bison/thesis-fund 180, magpie 720)."),
+            Param(name="prune_factor", type="int", default=4, minimum=1,
+                  doc="Prune entries older than prune_factor x TTL (hawk prunes at 4x)."),
+        ),
+        example="node: ttl_dedup_state\nwith:\n  ttl_seconds: 240\n",
+        cost="Reads/writes ctx.state; no MCP call.",
+    ),
+]
+
+NODES: tuple[NodeDef, ...] = tuple(
+    _SOURCES + _INDICATORS + _FILTERS + _SCORERS + _RANKERS + _EMITTERS + _STATEFUL
+)
+
+NODES_BY_NAME: dict[str, NodeDef] = {}
+for _node in NODES:
+    if _node.name in NODES_BY_NAME:
+        raise ValueError(f"duplicate node name in registry: {_node.name!r}")
+    NODES_BY_NAME[_node.name] = _node
+
+
+def sorted_nodes() -> list[NodeDef]:
+    """NODES in deterministic (kind-order, then name) order for generation."""
+    return sorted(NODES, key=lambda n: (KIND_ORDER.index(n.kind.value), n.name))