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

package/dist/composer/primitives/adapter.py

@@ -0,0 +1,363 @@
+"""adapter — the thin, stubbable data-source layer over the scaffold ctx.
+
+This is the ONLY place a compiled scan.py performs I/O: each method makes exactly one
+``ctx.senpi_mcp.call_tool(name, args)`` read and returns the raw response, which the
+pure ``sources`` primitives then normalize. Reads are guarded (a transient/permission
+error on ONE read must not roll back the whole tick — corpus ``_read`` behaviour):
+a failed read returns None and the source primitive drops that asset.
+
+Golden tests stub source data at THIS boundary by handing scan() a ctx whose
+``senpi_mcp`` returns fixture responses — so the compiled graph runs end-to-end over
+fixed data while the real ctx / StateManager frozen semantics are honored.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+# server-enforced maximum trader addresses per discovery_get_trader_state call (batch chunk).
+_TRADER_STATE_BATCH_MAX = 50
+# server-enforced maximum (wallet, coin) pairs per discovery_get_open_position_realized_pnl call.
+_OPEN_POSITION_REALIZED_PNL_MAX = 100
+
+
+def _project_addresses(records) -> list:
+    """Project trader addresses out of a wired record_list (each row's address /
+    trader_address / trader_id field), or pass strings through. Powers trader_states_fetch's
+    wire-from-a-record_list input (e.g. straight off top_traders_fetch.traders)."""
+    out: list = []
+    for r in records or []:
+        if isinstance(r, dict):
+            addr = r.get("address") or r.get("trader_address") or r.get("trader_id")
+            if addr:
+                out.append(str(addr))
+        elif isinstance(r, str) and r:
+            out.append(r)
+    return out
+
+
+def _project_wallet_coin_pairs(records) -> list:
+    """Project (wallet_address, coin) pairs out of a wired record_list for
+    discovery_get_open_position_realized_pnl. Accepts wallet_address / walletAddress / address
+    plus coin; drops rows missing either. Powers open_positions_realized_pnl_fetch's
+    wire-from-a-record_list input (e.g. a cohort's open positions)."""
+    out: list = []
+    for r in records or []:
+        if not isinstance(r, dict):
+            continue
+        wallet = r.get("wallet_address") or r.get("walletAddress") or r.get("address")
+        coin = r.get("coin")
+        if wallet and coin:
+            out.append({"wallet_address": str(wallet), "coin": str(coin)})
+    return out
+
+
+def _top_strategies_next(resp) -> tuple:
+    """(has_next, next_offset) from a discovery_get_top_strategies page's page_info
+    (this endpoint HAS real pagination). No page_info -> (False, None)."""
+    if not isinstance(resp, dict):
+        return False, None
+    data = resp.get("data", resp)
+    pi = data.get("page_info") if isinstance(data, dict) else None
+    if not isinstance(pi, dict):
+        return False, None
+    has_next = bool(pi.get("hasNextPage", pi.get("has_next_page", False)))
+    nxt = pi.get("nextOffset", pi.get("next_offset"))
+    try:
+        nxt = int(nxt) if nxt is not None else None
+    except (TypeError, ValueError):
+        nxt = None
+    return has_next, nxt
+
+
+def _top_traders_page_rows(resp) -> int:
+    """Row count of one discovery_get_top_traders page — the pagination terminator (the
+    response has NO page_info, so a short page ends the offset loop)."""
+    if not isinstance(resp, dict):
+        return 0
+    data = resp.get("data", resp)
+    rows = data.get("traders", []) if isinstance(data, dict) else []
+    return len(rows) if isinstance(rows, list) else 0
+
+
+class McpSourceAdapter:
+    """Wraps a scaffold ``ctx`` and exposes one read method per corpus MCP tool."""
+
+    def __init__(self, ctx: Any) -> None:
+        self._ctx = ctx
+
+    def _read(self, name: str, args: dict):
+        mcp = getattr(self._ctx, "senpi_mcp", None)
+        if mcp is None:
+            return None
+        try:
+            return mcp.call_tool(name, args)
+        except Exception as exc:  # noqa: BLE001 — a read error must not roll back the tick
+            print(f"[composer.adapter] {name} read failed: {exc!r}", file=sys.stderr)
+            return None
+
+    def raw_read(self, tool: str, args: dict | None = None, *,
+                 timeout_seconds: float = 0.0) -> Any:
+        """The escape-hatch generic read (mcp_read source): call an ARBITRARY MCP `tool` with
+        `args` passed verbatim and return its UNWRAPPED payload — the standard ``data`` envelope,
+        untouched — so a pure_fn normalizer can turn it into a typed shape. Read-only by
+        construction: the scaffold client's own MUTATION_TOOLS blocklist rejects any write tool,
+        double-guarding the composer's check-time refusal. A failed read returns None (corpus
+        ``_read`` behaviour), which the normalizer must handle. ``timeout_seconds`` is advisory:
+        the frozen scaffold client owns transport timeouts and exposes no per-call knob, so it is
+        intentionally NOT plumbed into ``call_tool`` (the arg exists for authoring legibility)."""
+        raw = self._read(tool, dict(args or {}))
+        if isinstance(raw, dict):
+            return raw.get("data", raw)
+        return raw
+
+    def asset_data(self, asset: str, intervals: list, *, include_funding: bool = False,
+                   include_asset_context: bool = False, dex: str = "") -> Any:
+        args = {
+            "asset": asset,
+            "candle_intervals": list(intervals),
+            "include_funding": include_funding,
+            "include_order_book": False,
+        }
+        if include_asset_context:
+            args["include_asset_context"] = True
+        if dex:
+            args["dex"] = dex
+        return self._read("market_get_asset_data", args)
+
+    def clearinghouse(self) -> Any:
+        wallet = getattr(self._ctx, "wallet", "") or ""
+        return self._read("strategy_get_clearinghouse_state", {"strategy_wallet": wallet})
+
+    def leaderboard_markets(self) -> Any:
+        return self._read("leaderboard_get_markets", {})
+
+    def instruments(self, *, dex: str = "") -> Any:
+        return self._read("market_list_instruments", {"dex": dex})
+
+    # -------------------------------------------------- world-coverage reads (batch C)
+
+    def market_prices(self, *, dex: str = "") -> Any:
+        """market_get_prices — all latest prices for a venue (omitting `assets` returns
+        the full map; the normalizer filters to the wired universe)."""
+        return self._read("market_get_prices", {"dex": dex})
+
+    def strategy_list(self, *, status: str = "", strategy_type: str = "") -> Any:
+        """strategy_list — strategy-metadata rows, optionally filtered by status / type."""
+        args: dict = {}
+        if status:
+            args["status"] = status
+        if strategy_type:
+            args["strategy_type"] = strategy_type
+        return self._read("strategy_list", args)
+
+    def open_orders(self) -> Any:
+        """strategy_get_open_orders for the strategy's own wallet (like clearinghouse)."""
+        wallet = getattr(self._ctx, "wallet", "") or ""
+        return self._read("strategy_get_open_orders", {"strategy_wallet": wallet})
+
+    def trader_history(self, *, trader_address: str, limit: int = 100) -> Any:
+        """discovery_get_trader_history — closed-trade history for an arbitrary trader."""
+        return self._read(
+            "discovery_get_trader_history",
+            {"trader_address": trader_address, "latest": True, "limit": limit},
+        )
+
+    def asset_trading_limits(self, coin: str, *, dex: str = "") -> Any:
+        """strategy_get_asset_trading_limits — single-asset venue limit for the own wallet
+        (fanned out per-asset by the emitted comprehension, like asset_data)."""
+        wallet = getattr(self._ctx, "wallet", "") or ""
+        args = {"strategy_wallet": wallet, "coin": coin}
+        if dex:
+            args["dex"] = dex
+        return self._read("strategy_get_asset_trading_limits", args)
+
+    def pnl_snapshot(self, *, period: str = "", drawdown_reset_on_day_rollover: bool = False) -> Any:
+        """strategy_get_pnl_and_account_value_history for the own wallet."""
+        wallet = getattr(self._ctx, "wallet", "") or ""
+        args: dict = {"strategy_wallet": wallet}
+        if period:
+            args["period"] = period
+        if drawdown_reset_on_day_rollover:
+            args["drawdown_reset_on_day_rollover"] = True
+        return self._read("strategy_get_pnl_and_account_value_history", args)
+
+    def trader_state(self, *, trader_address: str) -> Any:
+        """discovery_get_trader_state — an arbitrary wallet's current book (clearinghouse
+        twin). The MCP arg is a BATCH (`trader_addresses`); we read the single wired wallet."""
+        return self._read(
+            "discovery_get_trader_state",
+            {"trader_addresses": [trader_address], "latest": True},
+        )
+
+    # ------------------------------------------------------ wave A reads (2026-07-16)
+
+    def funding_regime(self) -> Any:
+        """market_get_funding_regime — the market-wide crowding regime (zero params)."""
+        return self._read("market_get_funding_regime", {})
+
+    def top_traders(self, *, time_frame: str, sort_by: str = "RETURN_ON_INVESTMENT",
+                    bias: str = "ALL", limit: int = 100, max_pages: int = 1,
+                    open_position_filter: bool = False, activity_labels=(),
+                    consistency=(), risk_labels=()) -> list:
+        """discovery_get_top_traders — offset PAGINATION loop (the response has NO page_info):
+        fetch up to `max_pages` pages of `limit` rows and TERMINATE on a page shorter than
+        `limit`. Returns the list of raw page responses (the normalizer concatenates + dedups).
+        time_frame is REQUIRED by the advertised schema and always sent."""
+        pages: list = []
+        offset = 0
+        for _ in range(max(1, int(max_pages))):
+            args: dict = {
+                "time_frame": time_frame, "sort_by": sort_by, "bias": bias,
+                "limit": limit, "offset": offset,
+                "open_position_filter": open_position_filter,
+            }
+            if activity_labels:
+                args["activity_labels"] = list(activity_labels)
+            if consistency:
+                args["consistency"] = list(consistency)
+            if risk_labels:
+                args["risk_labels"] = list(risk_labels)
+            resp = self._read("discovery_get_top_traders", args)
+            if not resp:
+                break
+            pages.append(resp)
+            if _top_traders_page_rows(resp) < limit:
+                break
+            offset += limit
+        return pages
+
+    def trader_states(self, *, records=None, wallets=(), latest: bool = False,
+                      include_position_age: bool = False, sort_open_positions_by: str = "",
+                      sort_open_positions_direction: str = "DESC") -> list:
+        """discovery_get_trader_state in BATCH — addresses from the wired `records`
+        (record_list) when present, else the static `wallets`. CHUNKS at the server-enforced
+        max of 50 addresses per call. Returns the list of raw page responses."""
+        addrs = _project_addresses(records) if records else [str(w) for w in (wallets or [])]
+        seen: set = set()
+        addresses: list = []
+        for a in addrs:
+            if a and a not in seen:
+                seen.add(a)
+                addresses.append(a)
+        pages: list = []
+        for i in range(0, len(addresses), _TRADER_STATE_BATCH_MAX):
+            chunk = addresses[i:i + _TRADER_STATE_BATCH_MAX]
+            args: dict = {"trader_addresses": chunk, "latest": latest}
+            if include_position_age:
+                args["include_position_age"] = True
+            if sort_open_positions_by:
+                args["sort_open_positions_by"] = sort_open_positions_by
+                args["sort_open_positions_direction"] = sort_open_positions_direction
+            resp = self._read("discovery_get_trader_state", args)
+            if resp:
+                pages.append(resp)
+        return pages
+
+    def funding_history(self, *, asset: str = "", min_annualized_pct: float = 20.0,
+                        min_persistence_hours: float = 0.0) -> Any:
+        """market_get_funding_history — exact snake_case (zod .strict()); `asset` sent only
+        when non-empty (omit = all extreme-funding assets)."""
+        args: dict = {
+            "min_annualized_pct": min_annualized_pct,
+            "min_persistence_hours": min_persistence_hours,
+        }
+        if asset:
+            args["asset"] = asset
+        return self._read("market_get_funding_history", args)
+
+    def cross_asset_flows(self, *, leader_asset: str = "BTC", min_move_pct: float = 2.0,
+                          window: str = "4h") -> Any:
+        """market_get_cross_asset_flows — exact snake_case (zod .strict())."""
+        return self._read("market_get_cross_asset_flows", {
+            "leader_asset": leader_asset,
+            "min_move_pct": min_move_pct,
+            "window": window,
+        })
+
+    def trader_positions(self, *, trader_id: str) -> Any:
+        """leaderboard_get_trader_positions — exact snake_case (zod .strict())."""
+        return self._read("leaderboard_get_trader_positions", {"trader_id": trader_id})
+
+    # ------------------------------------------------------ wave B reads (2026-07-16)
+
+    def momentum_events(self, *, limit: int = 50, tier: int = 0, asset: str = "",
+                        from_time: str = "", to_time: str = "") -> Any:
+        """leaderboard_get_momentum_events — `from_time`/`to_time` map to the tool's `from`/`to`
+        (renamed off the Python keyword) and are sent only when set (else the server 4h default
+        window applies); tier 0 / empty asset are omitted (all tiers / all assets)."""
+        args: dict = {"limit": limit}
+        if tier:
+            args["tier"] = tier
+        if asset:
+            args["asset"] = asset
+        if from_time:
+            args["from"] = from_time
+        if to_time:
+            args["to"] = to_time
+        return self._read("leaderboard_get_momentum_events", args)
+
+    def top_strategies(self, *, limit: int = 20, offset: int = 0, force_fetch: bool = False,
+                       max_pages: int = 1) -> list:
+        """discovery_get_top_strategies — REAL pagination: follow page_info.hasNextPage up to
+        `max_pages`, advancing by page_info.nextOffset (fallback offset+limit). Returns the list
+        of raw page responses (the normalizer concatenates + dedups by wallet)."""
+        pages: list = []
+        cur = offset
+        for _ in range(max(1, int(max_pages))):
+            resp = self._read("discovery_get_top_strategies",
+                              {"limit": limit, "offset": cur, "force_fetch": force_fetch})
+            if not resp:
+                break
+            pages.append(resp)
+            has_next, next_offset = _top_strategies_next(resp)
+            if not has_next:
+                break
+            cur = next_offset if next_offset is not None else cur + limit
+        return pages
+
+    def arena_leaderboard(self, *, period_type: str = "WEEK", period_number: int = 0,
+                          limit: int = 100, offset: int = 0, qualified: bool = False) -> Any:
+        """arena_leaderboard — period_number 0 (current period) and qualified=False are omitted
+        (server default: current period / all enrolled agents)."""
+        args: dict = {"period_type": period_type, "limit": limit, "offset": offset}
+        if period_number:
+            args["period_number"] = period_number
+        if qualified:
+            args["qualified"] = True
+        return self._read("arena_leaderboard", args)
+
+    def leaderboard_top(self, *, limit: int = 100) -> Any:
+        """leaderboard_get_top — the fast 4h-window smart-money board."""
+        return self._read("leaderboard_get_top", {"limit": limit})
+
+    def leaderboard_trader(self, *, trader_id: str) -> Any:
+        """leaderboard_get_trader — one trader's 4h-window headline scalars."""
+        return self._read("leaderboard_get_trader", {"trader_id": trader_id})
+
+    def open_positions_realized_pnl(self, *, records=None, latest: bool = False) -> list:
+        """discovery_get_open_position_realized_pnl — (wallet, coin) pairs projected from the
+        wired `records` record_list, CHUNKED at the server max of 100 per call. Returns the list
+        of raw page responses. Unwired records -> [] (no call)."""
+        pairs = _project_wallet_coin_pairs(records)
+        pages: list = []
+        for i in range(0, len(pairs), _OPEN_POSITION_REALIZED_PNL_MAX):
+            chunk = pairs[i:i + _OPEN_POSITION_REALIZED_PNL_MAX]
+            resp = self._read("discovery_get_open_position_realized_pnl",
+                              {"positions": chunk, "latest": latest})
+            if resp:
+                pages.append(resp)
+        return pages
+
+    def account_history(self, *, bucket_duration_ms: int = 3600000) -> Any:
+        """account_get_historical_info — own-account bucketed PnL/value history."""
+        return self._read("account_get_historical_info",
+                          {"bucket_duration_ms": bucket_duration_ms})
+
+
+def make_adapter(ctx: Any) -> McpSourceAdapter:
+    """Factory the compiled scan.py calls. A test may monkeypatch this module attribute
+    to inject a fully synthetic adapter, but the default (a real ctx + fake senpi_mcp)
+    is the primary stubbing seam."""
+    return McpSourceAdapter(ctx)

package/dist/composer/primitives/emitters.py

@@ -0,0 +1,142 @@
+"""emitters — the signal_envelope primitive: selected -> the scan() return list.
+
+Produces the exact top-level shape the scaffold contract expects (see
+``src/scanners/external/scaffold/signal_envelope.py``):
+``{asset, direction, marginPct, leverage, data:{score, reasons, ...}}`` plus the optional
+``valid_for_seconds`` / ``signal_type`` the scaffold also recognizes on a candidate.
+
+Supervisor decision (slice 3): FINAL sizing lives here. ``marginPct`` is emitted as a
+PERCENT of withdrawable in (0, 100] (never a fraction, never USD) — the scaffold
+LOUD-rejects anything outside that band. Conviction/tier scorers only produce inputs
+to a score; the margin decision is the emitter's.
+
+================================================================================
+ENVELOPE SURFACE AUDIT (batch D) — every field a scanner may set on a signal.
+Source of truth: src/scanners/external/scaffold/signal_envelope.py::candidate_to_signal
+(_RECOGNIZED_CANDIDATE_KEYS + its per-field validation). "Covered" = expressible by this
+emitter after batch D.
+
+  field              req/opt   constraint (scaffold reject rule)              covered by
+  -----------------  --------  ---------------------------------------------  -------------------------
+  asset              REQUIRED  non-empty string                              selected keys (dynamic)
+  direction          REQUIRED  long/short (case-normalized -> LONG/SHORT)    entry["direction"] (dynamic)
+  marginPct          opt       number in (0,100]                             margin_pct param OR entry["marginPct"]
+  leverage           opt       positive number                              leverage param, venue-clamped, OR entry["leverage"]
+  valid_for_seconds  opt       positive int (TTL override)                  valid_for_seconds param OR entry["valid_for_seconds"]
+  signal_type        opt       non-empty string                            signal_type param OR entry["signal_type"]
+  data               opt       dict, validated vs signal_data_schema         {score, reasons} + entry["data"] merge (dynamic)
+  signal_id          IGNORED   scaffold owns the dedup key (author cannot set)  n/a (never emitted)
+
+Static values come from params; DYNAMIC per-asset values (the corpus emits a per-signal,
+venue-clamped leverage and a per-thesis data block) come from the score_map `selected`
+entry a pure_fn scorer produces, and from the live venue-max carried on the optional
+`instruments` input port. Every field above is now expressible — full parity with a
+hand-written scanner's signal envelope.
+================================================================================
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+def _clamp_leverage(desired: Any, venue_max: Any):
+    """Clamp desired leverage to an instrument's venue max — ported VERBATIM from the
+    corpus ``clamp_leverage`` helper (byte-identical in thesis-fund/main/scanners/scoring.py
+    and magpie/pre_listing/scanners/scoring.py).
+
+    Fallback semantics (must match the corpus): a ``venue_max`` that is None / non-numeric /
+    <= 0 (i.e. no usable venue metadata) falls back to the *desired* leverage — the signal is
+    still emitted at the requested leverage, never dropped and never clamped to 1. The result
+    is a whole-number leverage (the corpus does ``int(...)`` on both sides), floored at 1.
+    """
+    try:
+        venue = int(venue_max)
+    except (TypeError, ValueError):
+        venue = int(desired)
+    if venue <= 0:
+        venue = int(desired)
+    return max(1, min(int(desired), venue))
+
+
+def _venue_max_map(instruments: Any) -> dict:
+    """Project instrument_list records ([{name, max_leverage, ...}]) into an upper-cased
+    ``{name: max_leverage}`` lookup — the composer analogue of thesis-fund's
+    ``_get_universe_meta`` (name -> max_leverage from market_list_instruments)."""
+    out: dict = {}
+    for rec in instruments or []:
+        if isinstance(rec, dict) and rec.get("name"):
+            out[str(rec["name"]).upper()] = rec.get("max_leverage")
+    return out
+
+
+def signal_envelope(
+    selected: dict,
+    equity=None,
+    *,
+    margin_pct: float,
+    leverage: float,
+    clamp_leverage_to_venue: bool,
+    instruments: Optional[list] = None,
+    valid_for_seconds: int = 0,
+    signal_type: str = "",
+) -> list:
+    """Map selected candidates to the scan() signal list. Port: signals.
+
+    ``selected`` = ``{asset: {score, direction, reasons, ...}}``. A pure_fn scorer may attach
+    per-asset OVERRIDES on each entry (``marginPct``, ``leverage``, ``valid_for_seconds``,
+    ``signal_type``, ``data``); when absent the corresponding param supplies the static value —
+    this is what gives an emitted strategy full parity with a hand-written scanner.
+
+    ``equity`` (optional account scalar) is accepted for wiring parity; flat-margin strategies
+    (stag/hawk) do not consume it. ``instruments`` (optional) carries the live venue board
+    (instrument_list records); when ``clamp_leverage_to_venue`` is True AND ``instruments`` is
+    wired, each signal's leverage is clamped to that instrument's venue max exactly as the
+    corpus ``clamp_leverage`` does. Without an ``instruments`` wire the clamp is a no-op (the
+    requested leverage passes through unchanged — stag/hawk/thesis_fund/magpie today), so
+    existing graphs are byte-unchanged.
+    """
+    venue_max = _venue_max_map(instruments) if instruments is not None else None
+    signals: list = []
+    for asset in sorted(selected):
+        entry = selected[asset]
+
+        sig_margin = entry.get("marginPct", margin_pct)
+        sig_leverage = entry.get("leverage", leverage)
+        # Real venue clamp: only bites when the caller wired the live board (venue_max is not
+        # None). Corpus clamp_leverage semantics + fallback (see _clamp_leverage docstring).
+        if clamp_leverage_to_venue and venue_max is not None:
+            sig_leverage = _clamp_leverage(sig_leverage, venue_max.get(str(asset).upper()))
+
+        data: dict = {
+            "score": entry.get("score", 0),
+            "reasons": entry.get("reasons", []),
+        }
+        # Per-asset data enrichment: a pure_fn scorer can carry a `data` block on the entry
+        # (the corpus packs trend4h/rsi/own24h/... into signal.data). Merged over the base
+        # {score, reasons}; absent for stag/hawk/thesis_fund/magpie -> byte-unchanged.
+        extra = entry.get("data")
+        if isinstance(extra, dict):
+            for k in sorted(extra):
+                data[k] = extra[k]
+
+        sig: dict = {
+            "asset": asset,
+            "direction": entry.get("direction", "LONG"),
+            "marginPct": sig_margin,
+            "leverage": sig_leverage,
+            "data": data,
+        }
+
+        # valid_for_seconds (TTL override) and signal_type are OPTIONAL scaffold-recognized
+        # keys: emitted only when set (per-asset override wins over the static param) so an
+        # unset field never appears on the wire (matches the scaffold's "absent -> use default").
+        vfs = entry.get("valid_for_seconds", valid_for_seconds)
+        if isinstance(vfs, int) and not isinstance(vfs, bool) and vfs > 0:
+            sig["valid_for_seconds"] = vfs
+        st = entry.get("signal_type", signal_type)
+        if isinstance(st, str) and st:
+            sig["signal_type"] = st
+
+        signals.append(sig)
+    return signals

package/dist/composer/primitives/filters.py

@@ -0,0 +1,71 @@
+"""filters — pure asset_list -> asset_list narrowing primitives.
+
+Both preserve input order and compare case-insensitively (assets are upper-cased in
+the corpus). Ported from the held / recently-signaled pre-fetch filters present in
+all five corpus packages (e.g. stag ``scan.scan`` held + recent skip).
+"""
+
+from __future__ import annotations
+
+
+def held_asset_exclusion(*, candidates: list, held: list) -> list:
+    """Drop candidates already held in the account. Port: kept (asset_list)."""
+    held_set = {str(h).upper() for h in held}
+    return [a for a in candidates if str(a).upper() not in held_set]
+
+
+def recent_signal_ttl_dedup(*, candidates: list, recent: list) -> list:
+    """Drop candidates signaled within the dedup TTL. Port: kept (asset_list).
+
+    ``recent`` is the within-TTL exclusion set produced by ttl_dedup_state.
+    """
+    recent_set = {str(a).upper() for a in recent}
+    return [a for a in candidates if str(a).upper() not in recent_set]
+
+
+def _f(v, d: float = 0.0) -> float:
+    try:
+        return float(v if v is not None else d)
+    except (TypeError, ValueError):
+        return d
+
+
+def classifier_predicate(*, candidates: list, max_funding_abs: float,
+                         max_leverage: float, exclude_delisted: bool) -> list:
+    """Gate instrument-record membership on venue-field predicates. Port: kept (asset_list).
+
+    Ported from magpie ``scoring.is_ipop`` / ``ipop_passes_universe`` (the funding-signature
+    portion): keep a candidate iff (not delisted, when excluded) AND ``|funding| <=
+    max_funding_abs`` AND ``max_leverage <= max_leverage``. Operates on the instrument
+    RECORDS from instrument_list and PRESERVES them (so it can chain into universe_discover);
+    a bare-name candidate carrying no venue fields passes the (0-valued) numeric gates, i.e.
+    the generalized identity classifier. Input order is preserved.
+    """
+    out: list = []
+    for inst in candidates or []:
+        rec = inst if isinstance(inst, dict) else {"name": inst}
+        if exclude_delisted and rec.get("is_delisted"):
+            continue
+        if abs(_f(rec.get("funding", 0))) > max_funding_abs:
+            continue
+        lev = _f(rec.get("max_leverage", 0))
+        if lev and lev > max_leverage:
+            continue
+        out.append(inst)
+    return out
+
+
+def live_instrument_validation(*, candidates: list, instruments: list) -> list:
+    """Keep only candidates present on the live instrument board. Port: kept (asset_list).
+
+    Ported from thesis-fund's "only score names live on the instrument board" check
+    (``meta.get(asset) is None -> skip``): intersect candidate names with the live board
+    from instrument_list (case-insensitive), preserving candidate order/case.
+    """
+    names: set = set()
+    for inst in instruments or []:
+        rec = inst if isinstance(inst, dict) else {"name": inst}
+        nm = rec.get("name")
+        if isinstance(nm, str):
+            names.add(nm.upper())
+    return [c for c in (candidates or []) if str(c).upper() in names]