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

package/dist/composer/registry/nodes.py

@@ -0,0 +1,1297 @@
+"""nodes — the 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: 27 source, 10 indicator, 4 filter, 1 scorer, 2 ranker, 1 emitter, 3 stateful = 48.
+The 27th source (mcp_read) is the escape hatch (Wave D, 2026-07-16) — the ONE generic source,
+wrapping no specific tool (mcp_tool=None): it reads an arbitrary snapshot-listed, non-mutating
+MCP tool and emits its unwrapped payload as the `raw` port type (the 10th, escape-only type),
+consumable ONLY by a pure_fn normalizer. It closes the "unwrapped MCP reads" wall without
+letting any wire bypass typing; the closure check ignores it (no tool claimed).
+The 9th indicator (threshold_gate) is the one sanctioned C1b vocabulary addition — a
+thresholded gate whose need was demonstrated twice in one real dev transcript (see its doc).
+The 10th indicator (aggregate_bias) is the one sanctioned fn->primitive PROMOTION (wave C):
+the cross-trader net/gross cohort bias shared near-verbatim by whalehunter + 4 cohort packages.
+The first 6 sources are the corpus reads; the next 7 (batch C) are the first world-coverage
+reads off the evidenced MCP surface (recon §2); the next 6 (wave A, 2026-07-16) close the
+corpus-evidenced scanner-usable reads against a live prod tools/list enumeration (funding
+regime/history, top-traders, batch trader-state, cross-asset flows, leaderboard trader
+positions) and add the ``label`` port type; the last 7 (wave B, 2026-07-16) close the
+remaining scanner-usable Senpi MCP read surface — momentum events, top copy-strategies
+(real pagination), the Arena leaderboard, the fast 4h smart-money leaderboard + single-
+trader headline, batch banked-realized-PnL, and own-account bucketed history — making the
+read vocabulary FULLY mapped over the live catalog (the CI closure check in
+``composer/registry/mcp_closure.py`` proves it continuously). Every source declaration
+carries the MCP tool it wraps in a machine-readable ``mcp_tool`` field (None for the pure/
+derived sources) so that closure check needs no prose parsing. whalehunter's cohort read gap
+closed in wave A (top_traders_fetch + trader_states_fetch); wave C (2026-07-16) closes its
+REMAINING gap to zero — the two stateful primitives it needed (snapshot_diff_state for the
+daily equity/net-growth ledger, cohort_cache_state for the hours-pinned cohort) plus the one
+sanctioned compute PROMOTION (aggregate_bias), making the whalehunter thesis composer-buildable.
+
+``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 (27)
+
+_SOURCES = [
+    NodeDef(
+        name="candles_fetch",
+        kind="source",
+        mcp_tool="market_get_asset_data",
+        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",
+        mcp_tool="strategy_get_clearinghouse_state",
+        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",
+        mcp_tool="leaderboard_get_markets",
+        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",
+        mcp_tool="market_list_instruments",
+        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",
+        mcp_tool="market_get_prices",
+        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",
+        mcp_tool="strategy_list",
+        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",
+        mcp_tool="strategy_get_open_orders",
+        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",
+        mcp_tool="discovery_get_trader_history",
+        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",
+        mcp_tool="strategy_get_asset_trading_limits",
+        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",
+        mcp_tool="strategy_get_pnl_and_account_value_history",
+        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",
+        mcp_tool="discovery_get_trader_state",
+        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.",
+    ),
+    # ---- wave A: remaining scanner-usable MCP read surface (2026-07-16) ---------------
+    NodeDef(
+        name="funding_regime_fetch",
+        kind="source",
+        mcp_tool="market_get_funding_regime",
+        summary="Market-wide funding regime (crowding) label plus its numeric companions.",
+        doc=(
+            "market_get_funding_regime (zero params). Emits TWO outputs: `regime` — a market-"
+            "wide `label` (LONG_CROWDED | SHORT_CROWDED | NEUTRAL), the whole board's crowding "
+            "state, not a per-asset value — and `companions`, a one-row record_list carrying the "
+            "numeric context (long_funding_assets, short_funding_assets, avg_funding_annualized, "
+            "extreme_funding_count, regime_duration_hours, timestamp) for a pure_fn that wants "
+            "the magnitudes behind the label. Used to veto entries into crowded funding that "
+            "can precede a liquidation cascade (dog and ~13 other packages read the regime).\n\n"
+            "POLARITY TRAP (documented server-side and here): LONG_CROWDED means longs PAY "
+            "(most assets have positive funding; the crowd is long and bleeding funding) — this "
+            "is the OPPOSITE of funding_history_fetch's `funding_direction`, where LONG means "
+            "longs COLLECT. Do not equate the two enums: a LONG_CROWDED regime favours FADING "
+            "the crowd (or collecting funding on the short side), it does NOT mean 'go long'."
+        ),
+        outputs=(
+            _p("regime", PortType.label, "Market-wide crowding regime: LONG_CROWDED | SHORT_CROWDED | NEUTRAL."),
+            _p("companions", PortType.record_list,
+               "One-row record of the numeric companions (counts, avg annualized funding, "
+               "extreme count, regime duration hours, timestamp)."),
+        ),
+        example="node: funding_regime_fetch\n",
+        cost="One market_get_funding_regime MCP call per tick.",
+    ),
+    NodeDef(
+        name="top_traders_fetch",
+        kind="source",
+        mcp_tool="discovery_get_top_traders",
+        summary="Ranked best-track-record Hyperliquid traders (paginated).",
+        doc=(
+            "discovery_get_top_traders — THE ranking of Hyperliquid traders by track record, "
+            "reduced to a record_list of trader rows (address, roi, pnl, realized_pnl, win_rate, "
+            "max_drawdown, gain_to_pain, last_trade_ts). `time_frame` is REQUIRED by the "
+            "advertised schema and is always sent. The adapter PAGINATES via an offset loop "
+            "(the response has NO page_info): it fetches up to `max_pages` pages of `limit` rows "
+            "and TERMINATES when a page returns fewer than `limit` rows. Rows are deduped by "
+            "address across pages. Feeds a cohort-build pure_fn, or wires straight into "
+            "trader_states_fetch to pull the cohort's live books (the whalehunter pattern)."
+        ),
+        outputs=(_p("traders", PortType.record_list, "Ranked top-trader rows (deduped by address)."),),
+        params=(
+            Param(name="time_frame", type="str", default=None,
+                  choices=("DAILY", "WEEKLY", "MONTHLY", "ALL_TIME"),
+                  doc="Performance window (REQUIRED by the advertised schema; always sent)."),
+            Param(name="sort_by", type="str", default="RETURN_ON_INVESTMENT",
+                  choices=("RETURN_ON_INVESTMENT", "PROFIT_AND_LOSS", "PROFIT_AND_LOSS_REALIZED",
+                           "PROFIT_AND_LOSS_UNREALIZED", "WIN_RATE", "MAX_DRAWDOWN",
+                           "GAIN_TO_PAIN_RATIO", "TRADER_AGE"),
+                  doc="Ranking metric (default RETURN_ON_INVESTMENT)."),
+            Param(name="bias", type="str", default="ALL", choices=("LONG", "SHORT", "ALL"),
+                  doc="Directional-bias filter (default ALL)."),
+            Param(name="limit", type="int", default=100, minimum=1, maximum=1000,
+                  doc="Rows per page (1-1000); also the pagination page size."),
+            Param(name="max_pages", type="int", default=1, minimum=1,
+                  doc="Max offset-pagination pages; stop early on a short page (no page_info)."),
+            Param(name="open_position_filter", type="bool", default=False,
+                  doc="Only include traders with at least one open position."),
+            Param(name="activity_labels", type="list[str]", default=(),
+                  doc="Filter by activity class (DEGEN|ACTIVE|TACTICAL|PATIENT); empty = no filter."),
+            Param(name="consistency", type="list[str]", default=(),
+                  doc="Filter by consistency class (ELITE|RELIABLE|STREAKY|CHOPPY); empty = no filter."),
+            Param(name="risk_labels", type="list[str]", default=(),
+                  doc="Filter by risk class (CONSERVATIVE|BALANCED|AGGRESSIVE|SNIPER); empty = no filter."),
+        ),
+        example='node: top_traders_fetch\nwith:\n  time_frame: "MONTHLY"\n  sort_by: "PROFIT_AND_LOSS_REALIZED"\n  limit: 1000\n  max_pages: 6\n',
+        cost="One discovery_get_top_traders MCP call per page (up to max_pages per tick).",
+    ),
+    NodeDef(
+        name="trader_states_fetch",
+        kind="source",
+        mcp_tool="discovery_get_trader_state",
+        summary="Full current books for a batch of traders (chunked at 50).",
+        doc=(
+            "discovery_get_trader_state in BATCH — the full per-trader records the single-wallet "
+            "trader_state node discards. Addresses come from the wired `traders` record_list "
+            "(each row's `address` field — e.g. straight from top_traders_fetch, or a filtering "
+            "pure_fn) when present, else from the static `wallets` param. The adapter CHUNKS at "
+            "the server-enforced max of 50 addresses per call and concatenates. Output `traders` "
+            "is a record_list of full TraderState records: address, marginSummary, "
+            "marginPercentage, and openPositions[] (coin, szi, entryPx, positionValue, "
+            "unrealizedPnl, leverage, marginUsed, returnOnEquity, liquidationPx, cumFunding). All "
+            "string|number unions are coerced to float. Each record carries `data_source`: when "
+            "it is 'hyperliquid_clearinghouse_state' (the fallback when the discovery service is "
+            "transiently down) openOrders is ALWAYS [] — a consumer must not read absence of "
+            "orders as signal in that mode."
+        ),
+        inputs=(_p("traders", PortType.record_list,
+                    "Trader rows to read books for (each carrying an `address`); omit to use the "
+                    "`wallets` param.", required=False),),
+        outputs=(_p("traders", PortType.record_list, "Full TraderState records (numerics coerced to float)."),),
+        params=(
+            Param(name="wallets", type="list[str]", default=(),
+                  doc="Static trader addresses to read when no `traders` input is wired."),
+            Param(name="latest", type="bool", default=False,
+                  doc="Force-fresh from Hyperliquid (true) vs prefer cached (false)."),
+            Param(name="include_position_age", type="bool", default=False,
+                  doc="Include per-position startTime + durationInSeconds."),
+            Param(name="sort_open_positions_by", type="str", default="",
+                  doc="Sort each book by POSITION_VALUE|UNREALIZED_PNL|ENTRY_PRICE|COIN|LEVERAGE|"
+                      "RETURN_ON_EQUITY; empty = server default."),
+            Param(name="sort_open_positions_direction", type="str", default="DESC",
+                  choices=("ASC", "DESC"),
+                  doc="Direction for the open-position sort (only applied when a sort field is set)."),
+        ),
+        example='node: trader_states_fetch\nwith:\n  wallets: ["0xAAA", "0xBBB"]\n  latest: true\n',
+        cost="One discovery_get_trader_state MCP call per 50-address chunk per tick.",
+    ),
+    NodeDef(
+        name="funding_history_fetch",
+        kind="source",
+        mcp_tool="market_get_funding_history",
+        summary="Per-asset extreme-funding history with direction + trend enums.",
+        doc=(
+            "market_get_funding_history, reduced to a record_list of per-asset funding rows. "
+            "Omit `asset` to return ALL assets with extreme funding; set it for one. Each row "
+            "carries BOTH enums, kept SEPARATE (the earlier single-'trend' feature_map idea is "
+            "superseded by the real two-enum shape): `funding_direction` (LONG | SHORT — which "
+            "side COLLECTS funding; LONG collects when the rate is negative) AND `funding_trend` "
+            "(INTENSIFYING | STABLE | DECAYING — the enum is preserved verbatim, NOT remapped) — "
+            "plus current_funding_8h, funding_annualized_pct, persistence_hours, and the embedded "
+            "funding_history_24h hourly series (carried through as-is). NOTE the double-nested "
+            "envelope: rows live at data.data[] (a known server quirk). Contrast the "
+            "funding_direction polarity with funding_regime_fetch's regime (see that node's doc)."
+        ),
+        outputs=(_p("assets", PortType.record_list, "Per-asset extreme-funding rows (both enums + 24h series)."),),
+        params=(
+            Param(name="asset", type="str", default="",
+                  doc="Single asset symbol; empty = all assets with extreme funding."),
+            Param(name="min_annualized_pct", type="float", default=20.0, minimum=0.0,
+                  doc="Minimum absolute annualized funding rate to include (default 20%)."),
+            Param(name="min_persistence_hours", type="float", default=0.0, minimum=0.0,
+                  doc="Minimum hours funding has persisted in the same direction (default 0)."),
+        ),
+        example='node: funding_history_fetch\nwith:\n  min_annualized_pct: 20\n  min_persistence_hours: 3\n',
+        cost="One market_get_funding_history MCP call per tick.",
+    ),
+    NodeDef(
+        name="cross_asset_flows_fetch",
+        kind="source",
+        mcp_tool="market_get_cross_asset_flows",
+        summary="Leader move + correlated laggards that haven't followed yet.",
+        doc=(
+            "market_get_cross_asset_flows — cross-asset momentum transfer: when a leader (default "
+            "BTC) makes a significant move, the correlated alts ('laggards') that historically "
+            "follow but haven't yet. The response is a HEADER plus a LIST, not flat, so this "
+            "emits TWO outputs: `laggards` — a record_list of laggard rows (asset, follow_rate, "
+            "confidence, gap_pct, expected_move, actual_move, correlation, avg_lag_minutes, "
+            "lag_stddev_minutes, sm_starting_to_rotate) — and `leader`, a one-row record_list "
+            "header (asset, move_pct, direction, sm_aligned). Empty laggards is the documented-"
+            "normal 'leader hasn't moved enough' state (BTC is typically the only asset with "
+            "pre-computed lag data). Feeds a momentum-following pure_fn (mantis/osprey)."
+        ),
+        outputs=(
+            _p("laggards", PortType.record_list, "Ranked laggard rows that haven't followed the leader yet."),
+            _p("leader", PortType.record_list, "One-row leader header (asset, move_pct, direction, sm_aligned)."),
+        ),
+        params=(
+            Param(name="leader_asset", type="str", default="BTC",
+                  doc="The asset that moved first (default BTC — usually the only one with lag data)."),
+            Param(name="min_move_pct", type="float", default=2.0, minimum=0.0,
+                  doc="Minimum leader move percent to trigger detection (default 2%)."),
+            Param(name="window", type="str", default="4h",
+                  doc="Window to check for the leader move (default '4h')."),
+        ),
+        example='node: cross_asset_flows_fetch\nwith:\n  leader_asset: "BTC"\n  min_move_pct: 2\n',
+        cost="One market_get_cross_asset_flows MCP call per tick.",
+    ),
+    NodeDef(
+        name="trader_positions_fetch",
+        kind="source",
+        mcp_tool="leaderboard_get_trader_positions",
+        summary="One leaderboard trader's per-position 4h PnL breakdown.",
+        doc=(
+            "leaderboard_get_trader_positions — the per-position breakdown of what is driving one "
+            "leaderboard trader's recent (4h-window) gains. NESTING TRAP: the position rows live "
+            "at data.positions.positions[] and the header (rank, window, total_delta_pnl) at "
+            "data.positions.* — one level deeper than the naive shape (handled here, both shapes "
+            "tolerated). Emits `positions` — a record_list of rows (coin, direction, szi, entry, "
+            "leverage, notional, account_value, delta_pnl) with direction NORMALIZED to uppercase "
+            "LONG/SHORT (the server returns lowercase 'long'/'short'; szi sign is the fallback, "
+            "consistent with the rest of the registry) — and `header`, a one-row record_list "
+            "(rank, window, total_delta_pnl). delta_pnl is the 4h-window delta, NOT cumulative."
+        ),
+        outputs=(
+            _p("positions", PortType.record_list, "Per-position 4h rows (direction normalized to LONG/SHORT)."),
+            _p("header", PortType.record_list, "One-row header (rank, window, total_delta_pnl)."),
+        ),
+        params=(
+            Param(name="trader_id", type="str", default=None,
+                  doc="The leaderboard trader's Ethereum address (required)."),
+        ),
+        example='node: trader_positions_fetch\nwith:\n  trader_id: "0xTRADER"\n',
+        cost="One leaderboard_get_trader_positions MCP call per tick.",
+    ),
+    # ---- wave B: the last scanner-usable Senpi MCP reads (2026-07-16) ------------------
+    NodeDef(
+        name="momentum_events_fetch",
+        kind="source",
+        mcp_tool="leaderboard_get_momentum_events",
+        summary="Recent momentum threshold-crossing events (traders crossing profit tiers).",
+        doc=(
+            "leaderboard_get_momentum_events — traders that crossed a profit threshold within a "
+            "time range, tiered by significance (tier 1 = lowest/most-frequent early signals, "
+            "tier 3 = rarest/high-conviction). The response is a HEADER + LIST, so this emits TWO "
+            "outputs: `events` — a record_list of event rows (trader_address, tier, timestamp, "
+            "top_positions[]) — and `header`, a one-row record_list (query echo + total_count). "
+            "`from_time`/`to_time` are OPTIONAL ISO-8601 bounds mapping to the tool's `from`/`to` "
+            "(renamed because `from` is a Python keyword); leaving them unset omits them so the "
+            "server default window (last 4h -> now) applies. `tier` = 0 omits the tier filter "
+            "(all tiers). Feeds a momentum-cohort pure_fn."
+        ),
+        outputs=(
+            _p("events", PortType.record_list, "Momentum threshold-crossing event rows (most recent first)."),
+            _p("header", PortType.record_list, "One-row header (query echo, total_count)."),
+        ),
+        params=(
+            Param(name="limit", type="int", default=50, minimum=1, maximum=200,
+                  doc="Maximum events to return, most recent first (1-200, default 50)."),
+            Param(name="tier", type="int", default=0, minimum=0, maximum=3,
+                  doc="Filter by notification tier (1|2|3); 0 = all tiers (omitted server-side)."),
+            Param(name="asset", type="str", default="",
+                  doc="Filter by asset symbol (case-insensitive); empty = all assets."),
+            Param(name="from_time", type="str", default="",
+                  doc="ISO-8601 start (maps to the tool's `from`); empty = server default (4h ago)."),
+            Param(name="to_time", type="str", default="",
+                  doc="ISO-8601 end (maps to the tool's `to`); empty = server default (now)."),
+        ),
+        example='node: momentum_events_fetch\nwith:\n  tier: 2\n  limit: 100\n',
+        cost="One leaderboard_get_momentum_events MCP call per tick.",
+    ),
+    NodeDef(
+        name="top_strategies_fetch",
+        kind="source",
+        mcp_tool="discovery_get_top_strategies",
+        summary="Ranked Senpi copy-trading strategies (paginated) sorted by total PnL.",
+        doc=(
+            "discovery_get_top_strategies — the ranking of Senpi-managed MIRROR/copy strategies "
+            "(NOT individual Hyperliquid traders; use top_traders_fetch for those), sorted by "
+            "total PnL (realized + unrealized) DESC. Reduced to a record_list of strategy rows "
+            "(strategy_wallet, user_id, copied_trader, total_pnl, unrealized_pnl, realized_pnl, "
+            "return_pct, total_funded, age_seconds, followers), deduped by strategy_wallet across "
+            "pages. Unlike top_traders_fetch this endpoint has REAL pagination "
+            "(page_info{totalCount, hasNextPage, nextOffset}): the adapter follows hasNextPage up "
+            "to `max_pages`, using nextOffset as the cursor. Feeds a 'which copy strategy to "
+            "mirror' pure_fn."
+        ),
+        outputs=(_p("strategies", PortType.record_list, "Ranked copy-strategy rows (deduped by wallet)."),),
+        params=(
+            Param(name="limit", type="int", default=20, minimum=1,
+                  doc="Rows per page (>=1, NO server max; default 20); also the pagination page size."),
+            Param(name="offset", type="int", default=0, minimum=0,
+                  doc="Starting rank offset for pagination (default 0)."),
+            Param(name="force_fetch", type="bool", default=False,
+                  doc="Bypass the server cache and fetch fresh leaderboard data."),
+            Param(name="max_pages", type="int", default=1, minimum=1,
+                  doc="Max pages to follow via page_info.hasNextPage (default 1)."),
+        ),
+        example='node: top_strategies_fetch\nwith:\n  limit: 50\n  max_pages: 3\n',
+        cost="One discovery_get_top_strategies MCP call per page (up to max_pages per tick).",
+    ),
+    NodeDef(
+        name="arena_leaderboard_fetch",
+        kind="source",
+        mcp_tool="arena_leaderboard",
+        summary="Senpi Arena prize-competition leaderboard (AI agents, not HL traders).",
+        doc=(
+            "arena_leaderboard — the leaderboard for the SENPI ARENA ONLY: a small opt-in prize "
+            "competition among AI agents built on Senpi. This is NOT a ranking of Hyperliquid "
+            "traders ('monthly'/'weekly'/'top trader' do NOT imply Arena — use top_traders_fetch "
+            "for the best trader across Hyperliquid). Reduced to a record_list of `entries` rows "
+            "(rank, senpi_user_id, senpi_user_name, wallet, roi, pnl, qualified), server rank "
+            "order preserved. `period_type` is WEEK|MONTH (default WEEK); `period_number` = 0 "
+            "queries the current active period; `qualified` (only sent when true) restricts to "
+            "prize-eligible agents."
+        ),
+        outputs=(_p("entries", PortType.record_list, "Arena leaderboard entry rows (server rank order)."),),
+        params=(
+            Param(name="period_type", type="str", default="WEEK", choices=("WEEK", "MONTH"),
+                  doc="Arena period type (WEEK or MONTH; default WEEK)."),
+            Param(name="period_number", type="int", default=0, minimum=0,
+                  doc="Week/month number to query; 0 = current active period (omitted server-side)."),
+            Param(name="limit", type="int", default=100, minimum=1, maximum=500,
+                  doc="Maximum entries to return (1-500, default 100)."),
+            Param(name="offset", type="int", default=0, minimum=0,
+                  doc="Entries to skip for pagination (default 0)."),
+            Param(name="qualified", type="bool", default=False,
+                  doc="Only return prize-eligible (qualified) agents; false = all enrolled."),
+        ),
+        example='node: arena_leaderboard_fetch\nwith:\n  period_type: "MONTH"\n  limit: 50\n',
+        cost="One arena_leaderboard MCP call per tick.",
+    ),
+    NodeDef(
+        name="leaderboard_top_fetch",
+        kind="source",
+        mcp_tool="leaderboard_get_top",
+        summary="FAST 4h-window smart-money leaderboard (delta-PnL 'Predators').",
+        doc=(
+            "leaderboard_get_top — the LIVE 4-hour-rolling-window ranking of Hyperliquid traders "
+            "by delta PnL (the Senpi Hyperfeed 'Predators' feed): 'who is hot RIGHT NOW'. Emits "
+            "TWO outputs: `traders` — a record_list of trader rows (rank, trader_id, "
+            "unrealized_pnl, pnl_percentage, ath_delta, top_markets[], trader_tags[]) — and "
+            "`header`, a one-row record_list (window, timestamp, total_traders).\n\n"
+            "CONTRAST with top_traders_fetch (the SLOW discovery leaderboard): that one ranks by "
+            "multi-window track record (ROI / win-rate / drawdown over DAILY..ALL_TIME) — durable "
+            "'who is consistently good'. THIS one is a fast 4h momentum snapshot — transient 'who "
+            "is spiking now', with no track-record fields. Use leaderboard_top_fetch for current "
+            "momentum cohorts, top_traders_fetch for consistent-performer cohorts."
+        ),
+        outputs=(
+            _p("traders", PortType.record_list, "Fast 4h-window trader rows (rank order)."),
+            _p("header", PortType.record_list, "One-row header (window, timestamp, total_traders)."),
+        ),
+        params=(
+            Param(name="limit", type="int", default=100, minimum=1, maximum=500,
+                  doc="Top traders to return by 4h delta-PnL DESC (1-500, default 100)."),
+        ),
+        example='node: leaderboard_top_fetch\nwith:\n  limit: 50\n',
+        cost="One leaderboard_get_top MCP call per tick.",
+    ),
+    NodeDef(
+        name="leaderboard_trader_fetch",
+        kind="source",
+        mcp_tool="leaderboard_get_trader",
+        summary="One trader's live 4h-window leaderboard headline scalars.",
+        doc=(
+            "leaderboard_get_trader — a SINGLE trader's live leaderboard headline within the 4h "
+            "rolling window: current rank, delta PnL, top markets, and active position count. "
+            "The single-trader companion of leaderboard_top_fetch (the whole board). NOT the "
+            "per-coin delta-PnL breakdown of what is DRIVING those gains — that is "
+            "trader_positions_fetch.\n\n"
+            "Output is a one-row `trader` record_list (record_list, not scalars: the row carries "
+            "a nested `pnl` object and array fields — top_markets[] — that don't reduce to a flat "
+            "scalar set): fields trader_id, rank, window, timestamp, pnl{...} (numeric map, "
+            "coerced), ath_delta, top_markets[], position_count. Empty/failed read -> []."
+        ),
+        outputs=(_p("trader", PortType.record_list, "One-row trader headline (rank, window, pnl, top_markets, ...)."),),
+        params=(
+            Param(name="trader_id", type="str", default=None,
+                  doc="The trader's Ethereum address (required)."),
+        ),
+        example='node: leaderboard_trader_fetch\nwith:\n  trader_id: "0xTRADER"\n',
+        cost="One leaderboard_get_trader MCP call per tick.",
+    ),
+    NodeDef(
+        name="open_positions_realized_pnl_fetch",
+        kind="source",
+        mcp_tool="discovery_get_open_position_realized_pnl",
+        summary="Realized (banked) PnL already taken on STILL-OPEN positions, batched.",
+        doc=(
+            "discovery_get_open_position_realized_pnl — profit a trader has ALREADY BOOKED "
+            "(take-profit fills, partial closes, size reductions) on a position that is STILL "
+            "OPEN, per (walletAddress, coin) pair. The (wallet, coin) pairs come from the wired "
+            "`positions` record_list — each row projecting `wallet_address`(+`walletAddress`/"
+            "`address`) and `coin` — mirroring trader_states_fetch's record_list-projection "
+            "precedent (e.g. wire the open_positions of a cohort). The adapter CHUNKS at the "
+            "server max of 100 pairs per call and concatenates. Output `realized` is a "
+            "record_list of {wallet_address, coin, realized_pnl, total_fees} (numerics coerced). "
+            "Unwired `positions` -> no call, empty result. `latest` busts the 10-min cache."
+        ),
+        inputs=(_p("positions", PortType.record_list,
+                    "Rows projecting wallet_address + coin to query; omit for no call.",
+                    required=False),),
+        outputs=(_p("realized", PortType.record_list, "Per-position banked realized PnL + fees rows."),),
+        params=(
+            Param(name="latest", type="bool", default=False,
+                  doc="Bust the 10-min cache and fetch fresh from ClickHouse."),
+        ),
+        example="node: open_positions_realized_pnl_fetch\nwith:\n  latest: true\n",
+        cost="One discovery_get_open_position_realized_pnl MCP call per 100-pair chunk per tick.",
+    ),
+    NodeDef(
+        name="account_history_fetch",
+        kind="source",
+        mcp_tool="account_get_historical_info",
+        summary="Own-account bucketed PnL / account-value history across timeframes.",
+        doc=(
+            "account_get_historical_info — the strategy account's own PnL history across four "
+            "timeframes (day/week/month/allTime), each with total PnL by value + by percentage "
+            "and a time-series of cumulative PnL and account value.\n\n"
+            "OUTPUT DESIGN (justified): one `periods` record_list of period-rows (one row per "
+            "timeframe: period, total_pnl_value, total_pnl_pct, pnl_history[], "
+            "account_value_history[]), sorted by a fixed timeframe order (day, week, month, "
+            "allTime). Scalar outputs were rejected — that would need EIGHT scalars (2 per "
+            "timeframe) AND still could not carry the two per-timeframe time-series (a scalar is "
+            "a single number); a per-timeframe record_list carries the scalars AND the series in "
+            "one honest shape, uniform with the other record_list sources, and a pure_fn indexes "
+            "by the `period` field. Distinct from strategy_pnl_snapshot (TODAY's single snapshot)."
+        ),
+        outputs=(_p("periods", PortType.record_list,
+                    "Per-timeframe rows (day/week/month/allTime) with PnL totals + series."),),
+        params=(
+            Param(name="bucket_duration_ms", type="int", default=3600000, minimum=60000, maximum=604800000,
+                  doc="History bucket granularity in ms (1h=3600000 default; 6h=21600000; 24h=86400000)."),
+        ),
+        example="node: account_history_fetch\nwith:\n  bucket_duration_ms: 21600000\n",
+        cost="One account_get_historical_info MCP call per tick.",
+    ),
+    # -- the escape hatch (2026-07-16): the ONE generic source ---------------------------
+    # mcp_read wraps NO specific tool (mcp_tool=None — like the pure/derived sources, so the
+    # closure check ignores it): the `tool` PARAM names the tool at author time. It emits the
+    # unwrapped payload as `raw`, which ONLY a pure_fn normalizer may consume (CMP039). It is a
+    # deliberate LAST RESORT — a first-class source node is always preferred where one exists
+    # (the check stage annotates when a wrapped tool is used). Read-only: the `tool` MUST be in
+    # the committed snapshot and MUST NOT be a mutation (CMP060/CMP061); the scaffold's own
+    # MUTATION_TOOLS blocklist double-guards at runtime.
+    NodeDef(
+        name="mcp_read",
+        kind="source",
+        mcp_tool=None,
+        summary="Escape hatch: read any MCP tool, emitting its unwrapped payload as `raw`.",
+        doc=(
+            "The ONE generic source — the escape hatch for reads the curated source vocabulary "
+            "has not wrapped (or does not expose the fields you need). Calls the MCP `tool` with "
+            "`args` passed VERBATIM (snake_case, as the tool's schema expects) and emits the "
+            "unwrapped `data` envelope as its `payload` output, of type `raw`. There is NO "
+            "normalization here — that is the job of the `kind: pure_fn` node you MUST wire the "
+            "`payload` into (a `raw` wire may feed nothing else; the validator enforces this with "
+            "CMP039). That pure_fn is the NORMALIZER: it declares TYPED outputs and carries inline "
+            "tests, so the opaque payload is pinned to a real shape by author-owned fixtures.\n\n"
+            "PREFER A FIRST-CLASS NODE. Run `composer catalog` first — a curated source node is "
+            "tested, legible, and self-documenting. Reach for mcp_read only when no source node "
+            "expresses what you need; the `composer check` verdict ANNOTATES every mcp_read use "
+            "(and flags when the tool already has a first-class node) so the usage is visible and "
+            "greppable. READ-ONLY: the `tool` must exist in the committed MCP snapshot and must "
+            "not be a mutation — check refuses both with a teaching error (the scaffold's "
+            "MUTATION_TOOLS blocklist double-guards at runtime). NEVER invent a tool: if the read "
+            "does not exist, it cannot be faked here."
+        ),
+        outputs=(_p("payload", PortType.raw,
+                     "The tool's unwrapped `data`, untouched — wire into a pure_fn to normalize."),),
+        params=(
+            Param(name="tool", type="str",
+                  doc="MCP read tool name; must be in the committed snapshot and not a mutation."),
+            Param(name="args", type="map_str_json", default={},
+                  doc="Arguments passed verbatim (snake_case) to the tool; {} for a zero-arg read."),
+            Param(name="timeout_seconds", type="float", default=0.0, minimum=0.0, maximum=120.0,
+                  doc="Advisory per-read timeout hint; 0 = use the client default (transport "
+                      "timeouts are owned by the scaffold MCP client)."),
+        ),
+        example='node: mcp_read\nwith:\n  tool: "account_get_portfolio"\n',
+        cost="One MCP call per tick for the named `tool` (plus the pure_fn that normalizes it).",
+    ),
+]
+
+# ----------------------------------------------------------------------- indicators (10)
+# Every indicator: candles -> feature_map, pure compute, no MCP calls — EXCEPT threshold_gate
+# (reads a feature_map: a raw indicator output to threshold) and aggregate_bias (reads a
+# record_list of cohort trader-state records) — each with its own compiler emission branch.
+
+_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="threshold_gate",
+        kind="indicator",
+        summary="Compare a per-asset feature against a threshold, emitting a 1.0/0.0 gate.",
+        doc=(
+            "Takes a feature_map (a RAW indicator output) and emits 1.0 where "
+            "value `op` threshold holds, else 0.0 — a truthy/falsy gate the scorer's "
+            "required_gates can consume. `op` is one of lt|lte|gt|gte. Unlike every other "
+            "indicator this reads a feature_map, not candles: wire its `values` input from a "
+            "feature node's output (answers `indicators[].source`). Need demonstrated TWICE "
+            "in ONE real dev transcript (D2 known-need bar): the 'fresh entry <= 5 bars' gate "
+            "over recent_high_bars_ago (a truthiness gate INVERTED it — a fresh 0-bars-ago high "
+            "read falsy and FAILED), and the 'don't chase if own_return_24h >= 15%' runaway "
+            "filter. A raw-bars-ago-as-hard-gate has no correct truthiness reading; this node is "
+            "the missing thresholded gate."
+        ),
+        inputs=(_p("values", PortType.feature_map, "Per-asset numeric feature to threshold."),),
+        outputs=(_p("passed", PortType.feature_map, "Per-asset 1.0 (pass) / 0.0 (fail) gate."),),
+        params=(
+            Param(name="op", type="str", default="lt", choices=("lt", "lte", "gt", "gte"),
+                  doc="Comparison operator: value `op` threshold (lt|lte|gt|gte)."),
+            Param(name="value", type="float", default=0.0,
+                  doc="The threshold the per-asset feature is compared against."),
+        ),
+        example='node: threshold_gate\nwith:\n  op: "lte"\n  value: 5\n',
+        cost="Pure compute over the feature map.",
+    ),
+    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.",
+    ),
+    NodeDef(
+        name="aggregate_bias",
+        kind="indicator",
+        summary="Cross-trader net/gross cohort bias per coin.",
+        doc=(
+            "The ONE sanctioned promote-loop primitive (fn->primitive): the cross-trader "
+            "net/gross bias per coin, shared near-verbatim by whalehunter and the "
+            "chimp/gibbon/gorilla/orangutan cohort packages. Takes a record_list of TraderState "
+            "records (from trader_states_fetch — each row's openPositions[] carrying coin, szi, "
+            "positionValue/entry_px) and sums each coin's SIGNED notional across every trader, "
+            "emitting a per-coin feature_map: {net, gross, bias, n_long, n_short, direction} where "
+            "bias = net/gross in [-1,+1] (+1 all long, -1 all short) and direction = "
+            "LONG|SHORT|NEUTRAL from the sign of net. A feature_map (the indicator output "
+            "contract) rather than a scorer's score_map, so kind=indicator; its non-candle "
+            "record_list input mirrors threshold_gate's non-candle feature_map input.\n\n"
+            "COMMON-CORE ONLY: the concentration/consensus cohort packages (oxpecker, remora) "
+            "score per-candidate top positions instead of net/gross cohort bias and genuinely "
+            "diverge — that scoring stays a pure_fn. No params: every threshold whalehunter uses "
+            "(biasThreshold, crowdDivergenceMin, requireGrowing) lives in its DOWNSTREAM cohort-"
+            "scoring pure_fn, not in this aggregation."
+        ),
+        inputs=(_p("traders", PortType.record_list,
+                    "Cohort TraderState records (from trader_states_fetch)."),),
+        outputs=(_p("bias", PortType.feature_map,
+                     "Per-coin {net, gross, bias, n_long, n_short, direction}."),),
+        example="node: aggregate_bias\n",
+        cost="Pure compute over the cohort's trader-state records; no MCP call.",
+    ),
+]
+
+# --------------------------------------------------------------------------- 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 (3)
+
+_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.",
+    ),
+    NodeDef(
+        name="snapshot_diff_state",
+        kind="stateful",
+        summary="Rolling per-key snapshots; growth vs the window's oldest.",
+        doc=(
+            "A bounded rolling window of per-key numeric snapshots in ctx.state, exposing the "
+            "GROWTH (latest−oldest) between the current snapshot and the oldest one still in the "
+            "window. Ported from whalehunter scoring.update_ledger, which tracks each smart "
+            "cohort's per-coin NET positioning across ~10 UTC-daily buckets to derive the "
+            "'adding daily' signal its cohort scoring reads.\n\n"
+            "Wire aggregate_bias's `bias` feature_map into `snapshot` and set value_field to the "
+            "sub-field to track (whalehunter tracks 'net'); leave value_field empty when the "
+            "snapshot values are plain floats. Emits `growth` (feature_map: per-key latest−oldest) "
+            "and `deltas` (record_list: per-key {key, current, oldest, growth}). Declares the "
+            "state in/out pair (D2), split READ (prologue) / WRITE (epilogue) like ttl_dedup.\n\n"
+            "HONEST BOUNDARY: `growth` is PRIOR-tick (latest STORED vs oldest STORED) — the read "
+            "half runs before this tick's fresh snapshot is appended by the write half, exactly "
+            "the ttl_dedup split. The one-tick lag is negligible against a multi-bucket window, "
+            "and `growth` is empty until ≥2 buckets exist (a short warmup, like whalehunter's "
+            "requireGrowing blocking until ~day 2). STATE IS BOUNDED: hard-capped at "
+            "max_snapshots buckets (prune oldest beyond the cap) — an unbounded fleet-box state "
+            "series is an ops hazard — with per-bucket overwrite within bucket_seconds "
+            "(whalehunter's per-UTC-day ledger key, made clock-free). Survives restarts (ctx.state)."
+        ),
+        inputs=(
+            _p("snapshot", PortType.feature_map,
+               "Current per-key numeric snapshot to record (e.g. aggregate_bias `bias`)."),
+            _p("state_in", PortType.state, "Incoming ctx.state (D2 state port).", required=False),
+        ),
+        outputs=(
+            _p("growth", PortType.feature_map, "Per-key growth = latest−oldest in the window."),
+            _p("deltas", PortType.record_list, "Per-key {key, current, oldest, growth} rows."),
+            _p("state_out", PortType.state, "Updated ctx.state after the window fold (D2 state port)."),
+        ),
+        params=(
+            Param(name="value_field", type="str", default="",
+                  doc="Numeric sub-field to track when snapshot values are records "
+                      "(whalehunter tracks 'net'); '' reads the value as a float directly."),
+            Param(name="bucket_seconds", type="int", default=86400, minimum=1,
+                  doc="Snapshot coarsening: overwrite the current bucket until it is older than "
+                      "this, then open a new one (whalehunter's per-UTC-day key; 86400 = 1 day)."),
+            Param(name="max_snapshots", type="int", default=12, minimum=2,
+                  doc="Retain at most this many buckets; prune the oldest beyond it — THE state "
+                      "bound (whalehunter keep=10)."),
+        ),
+        example="node: snapshot_diff_state\nwith:\n  value_field: \"net\"\n  max_snapshots: 10\n",
+        cost="Reads/writes ctx.state; no MCP call.",
+    ),
+    NodeDef(
+        name="cohort_cache_state",
+        kind="stateful",
+        summary="Cache a cohort in ctx.state behind a TTL + version.",
+        doc=(
+            "Caches an expensive upstream fetch's result across ticks behind a TTL and a config "
+            "VERSION, pinning a STABLE cohort for hours so it does not churn every tick and poison "
+            "a multi-day ledger. Ported from whalehunter scan._build_cohorts. Wire the fresh fetch "
+            "(e.g. top_traders_fetch.traders) into `fresh`; wire the pinned `cohort` output into "
+            "the downstream consumer (e.g. trader_states_fetch.traders). Declares the state in/out "
+            "pair (D2), split READ (prologue) / WRITE (epilogue) like ttl_dedup.\n\n"
+            "HONEST BOUNDARY: sources fire EVERY tick — the compiler emits the upstream fetch "
+            "unconditionally and the scaffold has no conditional-fetch machinery, so this node "
+            "does NOT skip the fetch (skipping would need compiler conditional-emission, out of "
+            "scope). It is REUSE-AND-REFRESH: the read half serves the last-known-good cohort "
+            "(smoothing fetch gaps/failures and pinning stability — whalehunter's ACTUAL need, "
+            "cohort stability not rate-limiting), and the write half refreshes the stored cohort "
+            "only when the TTL lapsed, the version changed, or the cache was empty — and only when "
+            "the fresh fetch returned rows (a failed fetch keeps the old cohort). Uses ctx.state "
+            "(not a per-process cache) precisely because it SURVIVES RESTARTS. Cold start serves "
+            "an empty cohort for one warmup tick while the write half populates it."
+        ),
+        inputs=(
+            _p("fresh", PortType.record_list,
+               "This tick's freshly-fetched cohort rows (e.g. top_traders_fetch.traders)."),
+            _p("state_in", PortType.state, "Incoming ctx.state (D2 state port).", required=False),
+        ),
+        outputs=(
+            _p("cohort", PortType.record_list, "The pinned last-known-good cohort rows."),
+            _p("state_out", PortType.state, "Updated ctx.state after the refresh decision (D2 state port)."),
+        ),
+        params=(
+            Param(name="ttl_hours", type="float", default=24.0, minimum=0.0,
+                  doc="Refresh the stored cohort when it is older than this (whalehunter 24h)."),
+            Param(name="version", type="int", default=1, minimum=0,
+                  doc="Config/logic version; a change busts the cache (whalehunter CACHE_VERSION)."),
+        ),
+        example="node: cohort_cache_state\nwith:\n  ttl_hours: 24\n  version: 1\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))