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

package/dist/composer/primitives/sources.py

@@ -0,0 +1,979 @@
+"""sources — pure normalizers for the raw MCP responses the data-source nodes read.
+
+Split of concerns (slice-3 golden design): the ACTUAL MCP read (``ctx.senpi_mcp.
+call_tool``) lives in the thin ``adapter.McpSourceAdapter``; these functions are the
+PURE part — they take the raw response(s) the adapter fetched and reduce them to the
+node's typed output ports. That split is what lets the golden tests stub source data
+at the adapter/MCP boundary and still exercise the real normalization.
+
+Response shapes and reductions are ported from the corpus originals under
+``/Users/duncan/Senpi/skills/strategies/{stag,hawk}/main/scanners/scan.py``.
+"""
+
+from __future__ import annotations
+
+from ._candles import _f
+
+
+def candles_fetch(raw_by_asset: dict, *, intervals: list) -> dict:
+    """Normalize per-asset ``market_get_asset_data`` responses into the candles port.
+
+    Output: ``{asset: {interval: [candle_dict, ...]}}`` (the ``candles`` port type).
+    Ported from stag ``_fetch_candles`` / hawk ``_asset_data``: unwrap ``data`` then
+    ``candles[<interval>]``. A missing / falsy / success:false response drops the asset.
+    """
+    out: dict = {}
+    for asset in sorted(raw_by_asset):
+        raw = raw_by_asset[asset]
+        if not raw:
+            continue
+        if isinstance(raw, dict) and raw.get("success") is False:
+            continue
+        block = raw.get("data", raw) if isinstance(raw, dict) else {}
+        if not isinstance(block, dict):
+            continue
+        cands = block.get("candles", {}) or {}
+        if not isinstance(cands, dict):
+            continue
+        entry = {iv: (cands.get(iv, []) or []) for iv in intervals}
+        # Carry asset_context (markPx/prevDayPx) alongside the candles so own_return_24h
+        # can derive a 24h return without a second read (thesis-fund). Indicators ignore
+        # the extra key (they read candles[asset][interval]); a graph without asset_context
+        # (stag/hawk/bison fixtures) is byte-unchanged since the key is simply absent.
+        ac = block.get("asset_context")
+        if isinstance(ac, dict) and ac:
+            entry["asset_context"] = ac
+        out[asset] = entry
+    return out
+
+
+def instrument_list(raw) -> list:
+    """Normalize ``market_list_instruments`` into a list of instrument RECORDS. Port:
+    instruments (asset_list). Ported from magpie ``_fetch_ipop_universe`` + thesis-fund
+    ``_get_universe_meta``.
+
+    Each record: ``{name, funding (|abs|), max_leverage, is_delisted, day_volume}``. The
+    records (not bare names) are the ``asset_list`` value flowing into universe_discover /
+    classifier_predicate so those predicates can gate on venue fields; universe_discover
+    projects back to bare names for the tradeable universe. Sorted by name for determinism.
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else raw
+    insts = data.get("instruments", data) if isinstance(data, dict) else data
+    if isinstance(insts, dict):
+        insts = insts.get("instruments", [])
+    if not isinstance(insts, list):
+        return []
+    out: list = []
+    for inst in insts:
+        if not isinstance(inst, dict):
+            continue
+        ctxb = inst.get("context", {}) if isinstance(inst.get("context"), dict) else {}
+        name = inst.get("name") or ctxb.get("coin")
+        if not name or not isinstance(name, str):
+            continue
+        out.append({
+            "name": name,
+            "funding": abs(_f(ctxb.get("funding", 0))),
+            "max_leverage": _f(inst.get("max_leverage", inst.get("maxLeverage", 0))),
+            "is_delisted": bool(inst.get("is_delisted", False)),
+            "day_volume": _f(ctxb.get("dayNtlVlm", 0)),
+        })
+    return sorted(out, key=lambda r: r["name"])
+
+
+def universe_discover(instruments: list, *, min_day_volume: float,
+                      max_leverage_cap: float, name_prefix: str) -> list:
+    """Derive the tradeable universe (bare NAMES) by filtering instrument records. Port:
+    universe (asset_list). Ported from magpie ``ipop_passes_universe`` (the prefix /
+    leverage / min-volume portion); the funding portion lives in classifier_predicate, so a
+    faithful magpie discovery chains classifier_predicate -> universe_discover.
+
+    Generalizes thesis-fund's identity "is this on the live board" check: with the default
+    params (no prefix, cap 5, min-volume 0) a plain-name list passes through unchanged.
+    """
+    out: list = []
+    for inst in instruments or []:
+        rec = inst if isinstance(inst, dict) else {"name": inst}
+        name = rec.get("name")
+        if not isinstance(name, str):
+            continue
+        if name_prefix and not name.startswith(name_prefix):
+            continue
+        if rec.get("is_delisted"):
+            continue
+        lev = _f(rec.get("max_leverage", 0))
+        if lev and lev > max_leverage_cap:
+            continue
+        if _f(rec.get("day_volume", 0)) < min_day_volume:
+            continue
+        out.append(name)
+    return sorted(out)
+
+
+def own_return_24h(candles: dict) -> dict:
+    """Per-asset 24h percent return from the asset_context carried on candles. Port:
+    return_24h (feature_map). Ported from thesis-fund ``_asset_market`` ret_24h:
+    ``(markPx - prevDayPx) / prevDayPx * 100`` when both are positive; else omitted.
+    """
+    out: dict = {}
+    for asset in sorted(candles):
+        block = candles[asset] if isinstance(candles[asset], dict) else {}
+        ac = block.get("asset_context")
+        if not isinstance(ac, dict):
+            continue
+        mark = _f(ac.get("markPx", 0))
+        prev = _f(ac.get("prevDayPx", 0))
+        if prev > 0 and mark > 0:
+            out[asset] = ((mark - prev) / prev) * 100.0
+    return out
+
+
+def clearinghouse_state(raw) -> tuple[list, float]:
+    """Reduce a ``strategy_get_clearinghouse_state`` response to (held, equity).
+
+    Ports: held (asset_list), equity (scalar). Ported from hawk ``_get_account`` +
+    stag ``_held_assets``: dual-DEX max() account value across main/xyz (never sum ->
+    no double-count of the shared cross-margin balance); held = coins with a non-zero
+    ``szi`` in either sub-DEX. Includes the read-sanity guard: margin/notional in use
+    but an EMPTY positions list is a corrupt read -> (held=[], equity=0.0).
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict):
+        return [], 0.0
+
+    held: set = set()
+    equity = 0.0
+    for section in ("main", "xyz"):
+        s = data.get(section, {})
+        if not isinstance(s, dict):
+            continue
+        ms = s.get("marginSummary", {}) if isinstance(s.get("marginSummary"), dict) else {}
+        equity = max(equity, _f(ms.get("accountValue", 0)))
+        for ap in s.get("assetPositions", []) or []:
+            pos = ap.get("position", ap) if isinstance(ap, dict) else {}
+            if _f(pos.get("szi", 0)) != 0:
+                coin = str(pos.get("coin", "")).upper()
+                if coin:
+                    held.add(coin)
+
+    in_use = 0.0
+    for section in ("main", "xyz"):
+        s = data.get(section, {}) if isinstance(data, dict) else {}
+        ms = s.get("marginSummary", {}) if isinstance(s, dict) else {}
+        if not isinstance(ms, dict):
+            continue
+        in_use = max(in_use, _f(ms.get("totalMarginUsed", 0)), abs(_f(ms.get("totalNtlPos", 0))))
+    if in_use > 1.0 and not held:
+        return [], 0.0
+
+    return sorted(held), equity
+
+
+def sm_lean(raw, *, assets: list, agree_threshold: float) -> dict:
+    """Reduce ``leaderboard_get_markets`` to a per-asset smart-money lean. Port: lean.
+
+    Ported from stag/hawk ``_sm_direction`` / ``_get_sm_direction``: for each asset,
+    long_ratio = long_pct / (long_pct + short_pct) * 100. Output feature value is the
+    long_ratio percent in [0, 100] (a LONG-side lean; higher = more net-long smart
+    money). Assets not found on the board are omitted; total<=0 -> 50.0 (neutral).
+    ``agree_threshold`` is carried for signature/param parity — the alignment threshold
+    is applied by the scorer that consumes this feature (corpus: stag 0.60, hawk 0.55).
+    """
+    markets = raw.get("data", raw) if isinstance(raw, dict) else raw
+    if isinstance(markets, dict):
+        markets = markets.get("markets", markets.get("leaderboard", markets))
+    if isinstance(markets, dict):
+        markets = markets.get("markets", [])
+    if not isinstance(markets, list):
+        markets = []
+
+    out: dict = {}
+    # Output keys preserve the asset name AS WIRED (not force-upper-cased): matching against
+    # the leaderboard is case-insensitive, but the feature_map must be keyed the same way the
+    # candles/indicator feature_maps are (which preserve case), so a scorer can join them on
+    # one asset key. Dynamic-universe names like "xyz:ACME" would otherwise mismatch.
+    for asset in sorted({str(a) for a in assets}):
+        au = str(asset).upper()
+        long_pct = 0.0
+        short_pct = 0.0
+        found = False
+        for m in markets:
+            if not isinstance(m, dict):
+                continue
+            token = str(m.get("token", m.get("coin", m.get("asset", "")))).upper()
+            if token != au:
+                continue
+            found = True
+            d = str(m.get("direction", "")).upper()
+            pct = _f(m.get("pct_of_top_traders_gain", m.get("longPct", 0)))
+            if d == "LONG":
+                long_pct = pct
+            elif d == "SHORT":
+                short_pct = pct
+        if not found:
+            continue
+        total = long_pct + short_pct
+        out[asset] = 50.0 if total <= 0 else (long_pct / total) * 100.0
+    return out
+
+
+# ============================================================ world-coverage (batch C)
+# Every normalizer below is PURE (raw MCP response -> typed output ports); the adapter does
+# the actual read. Response shapes are ported 1:1 from src/senpi/client.ts call sites cited
+# in /Users/duncan/Senpi/.context/strategy-composer/mcp-surface-recon.md §2, verified against
+# the scaffold surface — no speculative fields.
+
+
+def market_prices(raw, *, assets: list) -> dict:
+    """Reduce a ``market_get_prices`` response to a per-asset price feature_map. Port:
+    prices (feature_map). Response: ``{prices: {<asset-or-"dex:asset">: number}}`` (or a
+    bare map). Mirrors sm_lean's join semantics: the price map is filtered to the wired
+    ``assets`` and keyed AS WIRED (matched case-insensitively), so it joins the case-
+    preserving candle/indicator feature_maps on one asset key. Assets absent from the
+    response are omitted.
+    """
+    prices = raw.get("prices", raw) if isinstance(raw, dict) else raw
+    if not isinstance(prices, dict):
+        return {}
+    by_upper = {str(k).upper(): v for k, v in prices.items()}
+    out: dict = {}
+    for asset in sorted({str(a) for a in assets}):
+        v = by_upper.get(str(asset).upper())
+        if v is None:
+            continue
+        out[asset] = _f(v)
+    return out
+
+
+def strategy_list(raw) -> list:
+    """Normalize ``strategy_list`` into a list of strategy-metadata RECORDS. Port:
+    strategies (record_list). Response: ``{data:{strategies:[{id, strategyWalletAddress,
+    traderAddress, status, strategyType, strategyName, createdAt, totalFunded}]}}``. Fields
+    ported 1:1; ``total_funded`` coerced to float. Sorted by ``id`` for determinism.
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else raw
+    rows = data.get("strategies", data) if isinstance(data, dict) else data
+    if not isinstance(rows, list):
+        return []
+    out: list = []
+    for r in rows:
+        if not isinstance(r, dict):
+            continue
+        out.append({
+            "id": str(r.get("id", "")),
+            "wallet": str(r.get("strategyWalletAddress", "")),
+            "trader": str(r.get("traderAddress", "")),
+            "status": str(r.get("status", "")),
+            "strategy_type": str(r.get("strategyType", "")),
+            "name": str(r.get("strategyName", "")),
+            "created_at": str(r.get("createdAt", "")),
+            "total_funded": _f(r.get("totalFunded", 0)),
+        })
+    return sorted(out, key=lambda x: x["id"])
+
+
+def open_orders(raw) -> list:
+    """Normalize ``strategy_get_open_orders`` into a list of order RECORDS. Port: orders
+    (record_list). Response: ``{orders:[{orderId, coin, side, size, price, orderType,
+    status, timestamp}]}`` (or a bare array). Multiple orders can exist per coin, so this
+    is a record list, not an asset-keyed map. Sorted by (coin, orderId) for determinism.
+    """
+    orders = raw.get("orders", raw) if isinstance(raw, dict) else raw
+    if not isinstance(orders, list):
+        return []
+    out: list = []
+    for o in orders:
+        if not isinstance(o, dict):
+            continue
+        out.append({
+            "order_id": str(o.get("orderId", "")),
+            "coin": str(o.get("coin", "")).upper(),
+            "side": str(o.get("side", "")),
+            "size": _f(o.get("size", 0)),
+            "price": _f(o.get("price", 0)),
+            "order_type": str(o.get("orderType", "")),
+            "status": str(o.get("status", "")),
+            "timestamp": _f(o.get("timestamp", 0)),
+        })
+    return sorted(out, key=lambda x: (x["coin"], x["order_id"]))
+
+
+def trader_history(raw) -> list:
+    """Normalize ``discovery_get_trader_history`` into a list of CLOSED-trade RECORDS.
+    Port: closed_positions (record_list). Response: ``{closed_positions:[{coin, dex?, type,
+    entryPx, exitPx, szi, realizedPnl, closeTime, openTime, totalFees}]}``. ``closeTime`` /
+    ``openTime`` are Unix SECONDS (carried through unchanged). Sorted by (closeTime, coin).
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else raw
+    rows = data.get("closed_positions", data) if isinstance(data, dict) else data
+    if not isinstance(rows, list):
+        return []
+    out: list = []
+    for r in rows:
+        if not isinstance(r, dict):
+            continue
+        out.append({
+            "coin": str(r.get("coin", "")).upper(),
+            "dex": str(r.get("dex", "")),
+            "type": str(r.get("type", "")),
+            "entry_px": _f(r.get("entryPx", 0)),
+            "exit_px": _f(r.get("exitPx", 0)),
+            "szi": _f(r.get("szi", 0)),
+            "realized_pnl": _f(r.get("realizedPnl", 0)),
+            "total_fees": _f(r.get("totalFees", 0)),
+            "close_time": _f(r.get("closeTime", 0)),
+            "open_time": _f(r.get("openTime", 0)),
+        })
+    return sorted(out, key=lambda x: (x["close_time"], x["coin"]))
+
+
+def asset_trading_limits(raw_by_asset: dict) -> dict:
+    """Reduce per-asset ``strategy_get_asset_trading_limits`` responses to a per-asset venue
+    max-leverage feature_map. Port: max_leverage (feature_map). The adapter fans the single-
+    asset MCP call out over the universe (mirroring asset_data's fanout); each response is
+    ``{leverage:{value}}`` or ``{maxLeverage}``. A missing / falsy response drops the asset.
+    """
+    out: dict = {}
+    for asset in sorted(raw_by_asset):
+        raw = raw_by_asset[asset]
+        if not isinstance(raw, dict):
+            continue
+        lev = raw.get("leverage")
+        if isinstance(lev, dict):
+            val = _f(lev.get("value", 0))
+        else:
+            val = _f(raw.get("maxLeverage", raw.get("max_leverage", 0)))
+        if val > 0:
+            out[asset] = val
+    return out
+
+
+def strategy_pnl_snapshot(raw) -> tuple[float, float, float]:
+    """Reduce ``strategy_get_pnl_and_account_value_history`` to today's snapshot scalars.
+    Ports: today_pnl (scalar), today_account_value (scalar), today_drawdown (scalar).
+    Response: ``{history_by_period:{...}, today_snapshot?:{pnl, account_value, drawdown}}``.
+    Only ``today_snapshot`` is decomposed (each field an account-level scalar); the nested
+    multi-period ``history_by_period`` is NOT exposed (it needs record_list — deferred). A
+    missing snapshot yields (0.0, 0.0, 0.0).
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict):
+        return 0.0, 0.0, 0.0
+    snap = data.get("today_snapshot")
+    if not isinstance(snap, dict):
+        return 0.0, 0.0, 0.0
+    return (
+        _f(snap.get("pnl", 0)),
+        _f(snap.get("account_value", 0)),
+        _f(snap.get("drawdown", 0)),
+    )
+
+
+def _trader_held_equity(t: dict) -> tuple[list, float]:
+    """Shared (held, equity) reduction for one TraderState record — the core both the
+    single-wallet ``trader_state`` and (indirectly) the batch ``trader_states`` build on.
+    Mirrors clearinghouse_state's read-sanity guard: notional/margin in use but an EMPTY
+    positions list is a corrupt read -> ([], 0.0).
+    """
+    if not isinstance(t, dict):
+        return [], 0.0
+    ms = t.get("marginSummary", {}) if isinstance(t.get("marginSummary"), dict) else {}
+    equity = _f(ms.get("accountValue", 0))
+
+    held: set = set()
+    for pos in t.get("openPositions", []) or []:
+        if not isinstance(pos, dict):
+            continue
+        if _f(pos.get("szi", 0)) != 0:
+            coin = str(pos.get("coin", "")).upper()
+            if coin:
+                held.add(coin)
+
+    in_use = max(_f(ms.get("totalMarginUsed", 0)), abs(_f(ms.get("totalNtlPos", 0))))
+    if in_use > 1.0 and not held:
+        return [], 0.0
+    return sorted(held), equity
+
+
+def trader_state(raw) -> tuple[list, float]:
+    """Reduce a ``discovery_get_trader_state`` response to (held, equity) for an ARBITRARY
+    wallet. Ports: held (asset_list), equity (scalar). This is clearinghouse_state's twin
+    generalized off the strategy's own wallet (recon §2g / §7) — same (held, equity)
+    contract, enabling copy-trading / leaderboard-following archetypes. Response:
+    ``{traders:[{address, openPositions:[{coin, szi, ...}], marginSummary:{accountValue}}]}``.
+    Shares its (held, equity) + read-sanity core with the batch ``trader_states`` node.
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict):
+        return [], 0.0
+    traders = data.get("traders", [])
+    if not isinstance(traders, list) or not traders:
+        return [], 0.0
+    return _trader_held_equity(traders[0] if isinstance(traders[0], dict) else {})
+
+
+# ================================================================= wave A (2026-07-16)
+# The remaining scanner-usable Senpi MCP read surface, verified against a live prod
+# tools/list enumeration and the server's main-branch handlers/types (cited per fn) plus
+# corpus call sites under ~/Senpi/skills/strategies/. Every normalizer is PURE; the adapter
+# does the I/O (including pagination + 50-address chunking). All string|number unions coerce
+# via _f. Response envelope everywhere: {success, data, meta} (data-only shown below).
+
+
+def _epoch_seconds(v) -> float:
+    """Normalize a timestamp that may arrive as unix-SECONDS (int/float or numeric string)
+    OR an ISO-8601 string into float epoch-seconds; 0.0 on anything unparseable. TopTrader
+    rows carry ``lastTradeTimestamp`` in either form (server-dependent), so it is normalized
+    to one numeric type for the record_list consumer.
+    """
+    if v is None or isinstance(v, bool):
+        return 0.0
+    if isinstance(v, (int, float)):
+        return float(v)
+    s = str(v).strip()
+    if not s:
+        return 0.0
+    try:
+        return float(s)  # numeric string (unix seconds)
+    except (TypeError, ValueError):
+        pass
+    try:
+        from datetime import datetime, timezone
+
+        dt = datetime.fromisoformat(s.replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def funding_regime(raw) -> tuple[str, list]:
+    """Reduce ``market_get_funding_regime`` to (regime_label, [companions_record]). Ports:
+    regime (label), companions (record_list). Response data (leaderboard.tools funding-regime
+    client): ``{regime, long_funding_assets, short_funding_assets, avg_funding_annualized,
+    extreme_funding_count, regime_duration_hours, timestamp}`` — ONE market-wide object (dog
+    reads ``data.regime`` at dog/main/scanners/scan.py:123-125). ``regime`` is a bare label
+    string; the numerics ride a one-row record_list so `label` stays purely categorical.
+    POLARITY (see the NodeDef): LONG_CROWDED = longs PAY (opposite of funding_history's
+    funding_direction where LONG = longs COLLECT). Missing/failed read -> ("", []).
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict) or not data:
+        return "", []
+    regime = str(data.get("regime", "")).upper()
+    companions = [{
+        "long_funding_assets": _f(data.get("long_funding_assets", 0)),
+        "short_funding_assets": _f(data.get("short_funding_assets", 0)),
+        "avg_funding_annualized": _f(data.get("avg_funding_annualized", 0)),
+        "extreme_funding_count": _f(data.get("extreme_funding_count", 0)),
+        "regime_duration_hours": _f(data.get("regime_duration_hours", 0)),
+        "timestamp": _epoch_seconds(data.get("timestamp")),
+    }]
+    return regime, companions
+
+
+def top_traders(raw_pages) -> list:
+    """Normalize the paginated ``discovery_get_top_traders`` pages into a record_list of
+    trader rows. Port: traders (record_list). Each page's data is ``{traders:[...], count,
+    filters}`` (discovery.tools.ts:550-565); the adapter loops offsets (NO page_info — it
+    terminates on a short page) and hands the list of page responses here. Rows are deduped
+    by address ACROSS pages, order preserved (server rank). Address + realized-PnL accessors
+    (multi-key camel/snake) are the corpus-verified shape (whalehunter scoring.realized /
+    trader_address at scoring.py:33-37,70-75); the metric fields mirror the sort_by enum
+    (RETURN_ON_INVESTMENT / PROFIT_AND_LOSS / WIN_RATE / MAX_DRAWDOWN / GAIN_TO_PAIN_RATIO);
+    lastTradeTimestamp is normalized off its unix-sec|ISO union.
+    """
+    out: list = []
+    seen: set = set()
+    for resp in raw_pages or []:
+        if not resp:
+            continue
+        data = resp.get("data", resp) if isinstance(resp, dict) else resp
+        rows = data.get("traders", data) if isinstance(data, dict) else data
+        if isinstance(rows, dict):
+            rows = rows.get("traders", [])
+        if not isinstance(rows, list):
+            continue
+        for t in rows:
+            if not isinstance(t, dict):
+                continue
+            addr = str(t.get("address") or t.get("trader_address") or "").lower()
+            if not addr or addr in seen:
+                continue
+            seen.add(addr)
+            out.append({
+                "address": addr,
+                "roi": _f(t.get("returnOnInvestment", t.get("return_on_investment", t.get("roi", 0)))),
+                "pnl": _f(t.get("profitAndLoss", t.get("profit_and_loss", t.get("pnl", 0)))),
+                "realized_pnl": _f(t.get("realizedProfitAndLoss",
+                                         t.get("realized_profit_and_loss",
+                                               t.get("profit_and_loss_realized",
+                                                     t.get("realizedPnl", t.get("realized_pnl", 0)))))),
+                "win_rate": _f(t.get("winRate", t.get("win_rate", 0))),
+                "max_drawdown": _f(t.get("maxDrawdown", t.get("max_drawdown", 0))),
+                "gain_to_pain": _f(t.get("gainToPainRatio", t.get("gain_to_pain_ratio", 0))),
+                "last_trade_ts": _epoch_seconds(
+                    t.get("lastTradeTimestamp", t.get("last_trade_timestamp", t.get("lastTradeTs")))),
+            })
+    return out
+
+
+def _norm_open_position(p: dict) -> dict:
+    """One TraderState openPositions[] row (discovery.tools.ts:103-128 normalizeFallbackPosition
+    shape) with every string|number union coerced to float. leverage is {type, value}."""
+    lev = p.get("leverage")
+    lev_value = _f(lev.get("value", 0)) if isinstance(lev, dict) else _f(lev)
+    cf = p.get("cumFunding") if isinstance(p.get("cumFunding"), dict) else {}
+    return {
+        "coin": str(p.get("coin", p.get("asset", ""))).upper(),
+        "szi": _f(p.get("szi", p.get("size", 0))),
+        "entry_px": _f(p.get("entryPx", p.get("entry_price", 0))),
+        "position_value": _f(p.get("positionValue", p.get("position_value", 0))),
+        "unrealized_pnl": _f(p.get("unrealizedPnl", p.get("unrealized_pnl", 0))),
+        "leverage": lev_value,
+        "margin_used": _f(p.get("marginUsed", p.get("margin_used", 0))),
+        "return_on_equity": _f(p.get("returnOnEquity", p.get("return_on_equity", 0))),
+        "liquidation_px": _f(p.get("liquidationPx", p.get("liquidation_px", 0))),
+        "cum_funding": _f(cf.get("sinceOpen", cf.get("allTime", 0))),
+    }
+
+
+def _norm_trader_record(t: dict, data_source: str) -> dict:
+    """One full TraderState record (discovery.tools.ts:95-154). marginSummary + a coerced
+    marginPercentage + the full openPositions[] detail. ``data_source`` is stamped onto EACH
+    record so a record_list consumer can see it: when it is 'hyperliquid_clearinghouse_state'
+    (the fallback when the discovery service is transiently down) openOrders is always []."""
+    ms = t.get("marginSummary", {}) if isinstance(t.get("marginSummary"), dict) else {}
+    positions = [
+        _norm_open_position(p)
+        for p in (t.get("openPositions") or t.get("open_positions") or [])
+        if isinstance(p, dict)
+    ]
+    return {
+        "address": str(t.get("address") or t.get("trader_address") or "").lower(),
+        "account_value": _f(ms.get("accountValue", 0)),
+        "total_margin_used": _f(ms.get("totalMarginUsed", 0)),
+        "total_ntl_pos": _f(ms.get("totalNtlPos", 0)),
+        "margin_percentage": _f(t.get("marginPercentage", 0)),
+        "withdrawable": _f(t.get("withdrawable", 0)),
+        "data_source": str(data_source or ""),
+        "open_positions": positions,
+    }
+
+
+def trader_states(raw_pages) -> list:
+    """Normalize the chunked batch ``discovery_get_trader_state`` pages into a record_list of
+    FULL TraderState records — the per-position detail the single-wallet ``trader_state`` node
+    discards. Port: traders (record_list). Each page's data is ``{traders:[...], count,
+    data_source, ...}`` (discovery.tools.ts:295-306); the adapter chunks addresses at the
+    server-enforced max 50 and hands the page responses here. Per-page ``data_source`` is
+    stamped onto every record (see _norm_trader_record). Order preserved (input address order).
+    """
+    out: list = []
+    for resp in raw_pages or []:
+        if not resp:
+            continue
+        data = resp.get("data", resp) if isinstance(resp, dict) else resp
+        if not isinstance(data, dict):
+            continue
+        ds = str(data.get("data_source", ""))
+        traders = data.get("traders", [])
+        if not isinstance(traders, list):
+            continue
+        for t in traders:
+            if isinstance(t, dict):
+                out.append(_norm_trader_record(t, ds))
+    return out
+
+
+def funding_history(raw) -> list:
+    """Normalize ``market_get_funding_history`` into a record_list of per-asset funding rows.
+    Port: assets (record_list). DOUBLE-NESTED envelope: rows live at ``data.data`` (a known
+    server quirk, parsed verbatim from pangolin/main/scanners/scan.py:130-156 and
+    dog/main/scanners/scan.py:131-154). Each row keeps BOTH enums SEPARATE — funding_direction
+    (LONG|SHORT, who COLLECTS) and funding_trend (INTENSIFYING|STABLE|DECAYING, preserved
+    verbatim, NOT remapped) — plus current_funding_8h, funding_annualized_pct, persistence_hours,
+    and the embedded funding_history_24h hourly series (carried through unchanged). Sorted by
+    asset for determinism.
+    """
+    outer = raw.get("data", raw) if isinstance(raw, dict) else raw
+    rows = outer.get("data") if isinstance(outer, dict) else None
+    if not isinstance(rows, list):
+        rows = outer if isinstance(outer, list) else None  # tolerate single-level {data:[...]}
+    if not isinstance(rows, list):
+        return []
+    out: list = []
+    for r in rows:
+        if not isinstance(r, dict):
+            continue
+        out.append({
+            "asset": str(r.get("asset", r.get("coin", ""))).upper(),
+            "funding_direction": str(r.get("funding_direction", r.get("fundingDirection", ""))).upper(),
+            "funding_trend": str(r.get("funding_trend", r.get("trend", ""))).upper(),
+            "current_funding_8h": _f(r.get("current_funding_8h", r.get("currentFunding8h", 0))),
+            "funding_annualized_pct": _f(r.get("funding_annualized_pct",
+                                               r.get("fundingAnnualizedPct", r.get("annualized_pct", 0)))),
+            "persistence_hours": _f(r.get("persistence_hours", r.get("persistenceHours", 0))),
+            "funding_history_24h": r.get("funding_history_24h", r.get("fundingHistory24h", [])) or [],
+        })
+    return sorted(out, key=lambda x: x["asset"])
+
+
+def cross_asset_flows(raw) -> tuple[list, list]:
+    """Reduce ``market_get_cross_asset_flows`` to (laggards, [leader_header]). Ports: laggards
+    (record_list), leader (record_list). Response is a HEADER + LIST, not flat (mantis
+    scoring.unwrap_flow_response at mantis/main/scanners/scoring.py:47-72; osprey leader-block
+    probe at osprey/main/scanners/scan.py:216-226): ``data = {leader:{asset, move_pct,
+    direction, sm_aligned}, laggards:[{asset, follow_rate, confidence, gap_pct, ...}]}``.
+    Laggard order is preserved (server ranks by confidence). Empty/absent leader -> [].
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else raw
+    if not isinstance(data, dict):
+        return [], []
+    leader_blk = data.get("leader", data.get("leader_move"))
+    leader_rows: list = []
+    if isinstance(leader_blk, dict) and leader_blk:
+        leader_rows = [{
+            "asset": str(leader_blk.get("asset", leader_blk.get("coin", ""))).upper(),
+            "move_pct": _f(leader_blk.get("move_pct", leader_blk.get("magnitude", 0))),
+            "direction": str(leader_blk.get("direction", "")).upper(),
+            "sm_aligned": bool(leader_blk.get("sm_aligned", False)),
+        }]
+    laggards: list = []
+    for lag in data.get("laggards", []) or []:
+        if not isinstance(lag, dict):
+            continue
+        laggards.append({
+            "asset": str(lag.get("asset", lag.get("coin", ""))).upper(),
+            "follow_rate": _f(lag.get("follow_rate", 0)),
+            "confidence": _f(lag.get("confidence", 0)),
+            "gap_pct": _f(lag.get("gap_pct", 0)),
+            "expected_move": _f(lag.get("expected_move", 0)),
+            "actual_move": _f(lag.get("actual_move", 0)),
+            "correlation": _f(lag.get("correlation", 0)),
+            "avg_lag_minutes": _f(lag.get("avg_lag_minutes", 0)),
+            "lag_stddev_minutes": _f(lag.get("lag_stddev_minutes", 0)),
+            "sm_starting_to_rotate": bool(lag.get("sm_starting_to_rotate", False)),
+        })
+    return laggards, leader_rows
+
+
+def _norm_leaderboard_positions(rows) -> list:
+    """Normalize leaderboard trader-position rows, uppercasing the LOWERCASE 'long'/'short'
+    direction (szi sign is the fallback, consistent with the rest of the registry — cheetah
+    scan.py:213-229, remora scoring.mirror_direction at scoring.py:92-105)."""
+    out: list = []
+    for p in rows or []:
+        if not isinstance(p, dict):
+            continue
+        coin = str(p.get("coin", p.get("market", p.get("asset", p.get("symbol", ""))))).upper()
+        if not coin:
+            continue
+        szi = _f(p.get("szi", p.get("size", 0)))
+        direction = str(p.get("direction", p.get("side", ""))).upper()
+        if direction not in ("LONG", "SHORT"):
+            direction = "LONG" if szi > 0 else ("SHORT" if szi < 0 else "LONG")
+        out.append({
+            "coin": coin,
+            "direction": direction,
+            "szi": szi,
+            "entry": _f(p.get("entry", p.get("entryPx", p.get("entry_price", 0)))),
+            "leverage": _f(p.get("leverage", 0)),
+            "notional": _f(p.get("notional", p.get("positionValue", p.get("position_value", 0)))),
+            "account_value": _f(p.get("account_value", p.get("accountValue", 0))),
+            "delta_pnl": _f(p.get("delta_pnl", p.get("deltaPnl", 0))),
+        })
+    return out
+
+
+def trader_positions(raw) -> tuple[list, list]:
+    """Reduce ``leaderboard_get_trader_positions`` to (positions, [header]). Ports: positions
+    (record_list), header (record_list). NESTING TRAP (cheetah/main/scanners/scan.py:185-210):
+    rows live at ``data.positions.positions[]`` and the header (rank, window, total_delta_pnl)
+    at ``data.positions.*`` — one level deeper than the naive shape; both shapes tolerated.
+    Row direction is normalized to uppercase LONG/SHORT. delta_pnl is the 4h-window delta.
+    """
+    d = raw.get("data", raw) if isinstance(raw, dict) else raw
+    if not isinstance(d, dict):
+        return [], []
+    block = d.get("positions", d)
+    if isinstance(block, list):  # data.positions is the row list directly
+        return _norm_leaderboard_positions(block), []
+    if not isinstance(block, dict):
+        return [], []
+    raw_positions = block.get("positions", block.get("top_positions", []))
+    if isinstance(raw_positions, list):
+        rows = raw_positions
+    elif isinstance(raw_positions, dict):
+        nested = raw_positions.get("positions", [])
+        rows = nested if isinstance(nested, list) else []
+    else:
+        rows = []
+    header = [{
+        "rank": _f(block.get("rank", 0)),
+        "window": str(block.get("window", "")),
+        "total_delta_pnl": _f(block.get("total_delta_pnl", block.get("totalDeltaPnl", 0))),
+    }]
+    return _norm_leaderboard_positions(rows), header
+
+
+# ================================================================= wave B (2026-07-16)
+# The LAST scanner-usable Senpi MCP reads, closing the read surface to fully-mapped. Response
+# shapes are cited per fn against the server main-branch handlers (mcp-main/tools/*.ts) since
+# these have NO corpus call sites (newly discovered off the live tools/list enumeration).
+# Envelope everywhere: {success, data, meta}; the handler's createResponse payload lands under
+# ``data`` (data-only shown below). All string|number unions coerce via _f.
+
+
+def _norm_momentum_event(e: dict) -> dict:
+    """One leaderboard_get_momentum_events row (leaderboard.tools.ts:221-249 handler +
+    tool description: trader address, tier, timestamps, top_positions). Address lower-cased,
+    tier/timestamp coerced, top_positions[] carried through."""
+    return {
+        "trader_address": str(e.get("trader_address") or e.get("traderAddress")
+                              or e.get("address") or "").lower(),
+        "tier": _f(e.get("tier", 0)),
+        "timestamp": _epoch_seconds(e.get("timestamp", e.get("created_at", e.get("createdAt")))),
+        "top_positions": e.get("top_positions", e.get("topPositions", [])) or [],
+    }
+
+
+def momentum_events(raw) -> tuple[list, list]:
+    """Reduce ``leaderboard_get_momentum_events`` to (events, [header]). Ports: events
+    (record_list), header (record_list). Response data (leaderboard.tools.ts:236-244
+    ``createResponse(tool,'read',{events})``): ``{events:{events:[...], query?, total_count?}}``
+    — rows at data.events.events[], header (query echo + total_count) at data.events.*. A bare
+    data.events list is tolerated (-> no header). Most-recent-first order preserved.
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict):
+        return [], []
+    block = data.get("events", data)
+    if isinstance(block, list):  # data.events is the row list directly
+        return [_norm_momentum_event(e) for e in block if isinstance(e, dict)], []
+    if not isinstance(block, dict):
+        return [], []
+    rows = block.get("events", [])
+    rows = rows if isinstance(rows, list) else []
+    events = [_norm_momentum_event(e) for e in rows if isinstance(e, dict)]
+    header = [{
+        "query": block.get("query"),
+        "total_count": _f(block.get("total_count", block.get("totalCount", len(events)))),
+    }]
+    return events, header
+
+
+def top_strategies(raw_pages) -> list:
+    """Normalize the paginated ``discovery_get_top_strategies`` pages into a record_list of
+    copy-strategy rows. Port: strategies (record_list). Each page's data is ``{strategies:[...],
+    count, page_info:{totalCount, hasNextPage, nextOffset}|null, generated_at, filters}``
+    (discovery.tools.ts:632-642); the adapter follows page_info.hasNextPage (this endpoint has
+    REAL pagination, unlike top_traders) and hands the list of page responses here. Rows deduped
+    by strategy_wallet across pages, server rank order (total PnL DESC) preserved. TopStrategy
+    fields per the tool description (strategy wallet, user id, copied trader, PnLs, return %,
+    funding, age, followers); camel/snake accessors; numerics coerced.
+    """
+    out: list = []
+    seen: set = set()
+    for resp in raw_pages or []:
+        if not resp:
+            continue
+        data = resp.get("data", resp) if isinstance(resp, dict) else resp
+        rows = data.get("strategies", data) if isinstance(data, dict) else data
+        if not isinstance(rows, list):
+            continue
+        for s in rows:
+            if not isinstance(s, dict):
+                continue
+            wallet = str(s.get("strategyWalletAddress") or s.get("strategy_wallet")
+                         or s.get("wallet") or "")
+            key = wallet.lower()
+            if key and key in seen:
+                continue
+            if key:
+                seen.add(key)
+            out.append({
+                "strategy_wallet": wallet,
+                "user_id": str(s.get("userId") or s.get("user_id") or ""),
+                "copied_trader": str(s.get("traderAddress") or s.get("copiedTrader")
+                                     or s.get("copied_trader") or s.get("shortTraderAddress") or ""),
+                "total_pnl": _f(s.get("totalPnl", s.get("total_pnl", 0))),
+                "unrealized_pnl": _f(s.get("unrealizedPnl", s.get("unrealized_pnl", 0))),
+                "realized_pnl": _f(s.get("realizedPnl", s.get("realized_pnl", 0))),
+                "return_pct": _f(s.get("returnPercentage",
+                                       s.get("returnPct", s.get("return_pct", 0)))),
+                "total_funded": _f(s.get("totalFunded", s.get("funding", s.get("total_funded", 0)))),
+                "age_seconds": _f(s.get("ageSeconds", s.get("age", s.get("age_seconds", 0)))),
+                "followers": _f(s.get("followers", s.get("followerCount", 0))),
+            })
+    return out
+
+
+def arena_leaderboard(raw) -> list:
+    """Normalize ``arena_leaderboard`` into a record_list of Arena entry rows. Port: entries
+    (record_list). Response data (arena.tools.ts:113-121 ``{leaderboard:{...,entries:[...]},
+    count}``): rows at data.leaderboard.entries[]; each entry carries senpiUserId + the
+    handler-added senpiUserName. Server rank order preserved. camel/snake accessors; numerics
+    coerced. This is Arena (opt-in AI-agent prize competition), NOT Hyperliquid trader ranking.
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict):
+        return []
+    lb = data.get("leaderboard", data)
+    if isinstance(lb, dict):
+        entries = lb.get("entries", [])
+    elif isinstance(lb, list):
+        entries = lb
+    else:
+        entries = []
+    if not isinstance(entries, list):
+        return []
+    out: list = []
+    for e in entries:
+        if not isinstance(e, dict):
+            continue
+        out.append({
+            "rank": _f(e.get("rank", 0)),
+            "senpi_user_id": str(e.get("senpiUserId") or e.get("senpi_user_id") or ""),
+            "senpi_user_name": str(e.get("senpiUserName") or e.get("senpi_user_name") or ""),
+            "wallet": str(e.get("walletAddress") or e.get("wallet") or "").lower(),
+            "roi": _f(e.get("roi", e.get("returnOnInvestment", 0))),
+            "pnl": _f(e.get("pnl", e.get("profitAndLoss", 0))),
+            "qualified": bool(e.get("qualified", False)),
+        })
+    return out
+
+
+def _norm_leaderboard_top_row(t: dict) -> dict:
+    """One leaderboard_get_top row (leaderboard.tools.ts:34-53; fast 4h delta-PnL 'Predators').
+    trader_id lower-cased; unrealized_pnl / pnl_percentage / ath_delta coerced; top_markets[]
+    and trader_tags[] carried through."""
+    return {
+        "rank": _f(t.get("rank", 0)),
+        "trader_id": str(t.get("trader_id") or t.get("traderId") or t.get("address") or "").lower(),
+        "unrealized_pnl": _f(t.get("unrealized_pnl", t.get("unrealizedPnl", 0))),
+        "pnl_percentage": _f(t.get("pnl_percentage", t.get("pnlPercentage", 0))),
+        "ath_delta": _f(t.get("ath_delta", t.get("athDelta", 0))),
+        "top_markets": t.get("top_markets", t.get("topMarkets", [])) or [],
+        "trader_tags": t.get("trader_tags", t.get("traderTags", [])) or [],
+    }
+
+
+def leaderboard_top(raw) -> tuple[list, list]:
+    """Reduce ``leaderboard_get_top`` to (traders, [header]). Ports: traders (record_list),
+    header (record_list). Response data (leaderboard.tools.ts:45-48 ``{leaderboard, count}``):
+    the leaderboard object carries the rows at ``.data`` plus window/timestamp; the sibling
+    ``count`` is total_traders. Rows normalized via _norm_leaderboard_top_row; header is a
+    one-row (window, timestamp, total_traders). Empty/failed read -> ([], []). This is the FAST
+    4h-window smart-money board — contrast top_traders (slow multi-window track record).
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict) or not data:
+        return [], []
+    lb = data.get("leaderboard", data)
+    if isinstance(lb, list):
+        rows, header_src, count = lb, {}, data.get("count")
+    elif isinstance(lb, dict):
+        rows = lb.get("data", lb.get("traders", []))
+        rows = rows if isinstance(rows, list) else []
+        header_src, count = lb, data.get("count")
+    else:
+        return [], []
+    traders = [_norm_leaderboard_top_row(t) for t in rows if isinstance(t, dict)]
+    total = count if count is not None else header_src.get(
+        "total_traders", header_src.get("totalTraders", len(traders)))
+    header = [{
+        "window": str(header_src.get("window", "4h")),
+        "timestamp": _epoch_seconds(header_src.get("timestamp")),
+        "total_traders": _f(total),
+    }]
+    return traders, header
+
+
+def leaderboard_trader(raw) -> list:
+    """Reduce ``leaderboard_get_trader`` to a ONE-ROW ``trader`` record_list. Port: trader
+    (record_list). Response data (leaderboard.tools.ts:88 ``{trader}``): a single object
+    ``{trader_id, rank?, window, timestamp, pnl{...}, ath_delta, top_markets[], position_count}``.
+    A one-row record_list (not scalars) is honest: the row carries a nested numeric `pnl` map
+    (coerced value-wise) and array fields (top_markets[]) that don't reduce to a flat scalar
+    set. Empty/failed read -> [].
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict):
+        return []
+    t = data.get("trader", data)
+    if not isinstance(t, dict) or not t:
+        return []
+    pnl = t.get("pnl") if isinstance(t.get("pnl"), dict) else {}
+    return [{
+        "trader_id": str(t.get("trader_id") or t.get("traderId") or t.get("address") or "").lower(),
+        "rank": _f(t.get("rank", 0)),
+        "window": str(t.get("window", "4h")),
+        "timestamp": _epoch_seconds(t.get("timestamp")),
+        "pnl": {str(k): _f(v) for k, v in pnl.items()},
+        "ath_delta": _f(t.get("ath_delta", t.get("athDelta", 0))),
+        "top_markets": t.get("top_markets", t.get("topMarkets", [])) or [],
+        "position_count": _f(t.get("position_count", t.get("positionCount", 0))),
+    }]
+
+
+def open_positions_realized_pnl(raw_pages) -> list:
+    """Normalize the chunked ``discovery_get_open_position_realized_pnl`` pages into a
+    record_list of banked-realized-PnL rows. Port: realized (record_list). Each page's data is
+    ``{positions_requested, latest, realized_pnl:[{walletAddress, coin, realizedPnl, totalFees}],
+    count, fetched_at}`` (discovery.tools.ts:741-747); the adapter chunks the (wallet, coin)
+    pairs at the server max of 100 and hands the page responses here. walletAddress lower-cased,
+    coin upper-cased, PnL/fees coerced. Order preserved (input pair order).
+    """
+    out: list = []
+    for resp in raw_pages or []:
+        if not resp:
+            continue
+        data = resp.get("data", resp) if isinstance(resp, dict) else resp
+        rows = data.get("realized_pnl", data.get("realizedPnl", [])) if isinstance(data, dict) else data
+        if not isinstance(rows, list):
+            continue
+        for r in rows:
+            if not isinstance(r, dict):
+                continue
+            out.append({
+                "wallet_address": str(r.get("walletAddress") or r.get("wallet_address") or "").lower(),
+                "coin": str(r.get("coin", "")).upper(),
+                "realized_pnl": _f(r.get("realizedPnl", r.get("realized_pnl", 0))),
+                "total_fees": _f(r.get("totalFees", r.get("total_fees", 0))),
+            })
+    return out
+
+
+_ACCOUNT_HISTORY_PERIODS = ("day", "week", "month", "allTime")
+
+
+def account_history(raw) -> list:
+    """Reduce ``account_get_historical_info`` to a ``periods`` record_list (one row per
+    timeframe). Port: periods (record_list). Response data (account.tools.ts:159-183):
+    ``{historical_info:{day, week, month, allTime}}`` where each timeframe carries
+    totalPnlByValue / totalPnlByPercentage / pnlHistory[] / accountValueHistory[]. Emits one
+    row per PRESENT timeframe in a fixed order (day, week, month, allTime), each row keeping the
+    two PnL totals (coerced) AND the two time-series (carried through). Missing/failed -> [].
+    """
+    data = raw.get("data", raw) if isinstance(raw, dict) else {}
+    if not isinstance(data, dict):
+        return []
+    info = data.get("historical_info", data.get("historicalInfo"))
+    if not isinstance(info, dict):
+        return []
+    out: list = []
+    for period in _ACCOUNT_HISTORY_PERIODS:
+        blk = info.get(period)
+        if not isinstance(blk, dict):
+            continue
+        out.append({
+            "period": period,
+            "total_pnl_value": _f(blk.get("totalPnlByValue", blk.get("total_pnl_by_value", 0))),
+            "total_pnl_pct": _f(blk.get("totalPnlByPercentage", blk.get("total_pnl_by_percentage", 0))),
+            "pnl_history": blk.get("pnlHistory", blk.get("pnl_history", [])) or [],
+            "account_value_history": blk.get("accountValueHistory",
+                                             blk.get("account_value_history", [])) or [],
+        })
+    return out