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

package/dist/composer/primitives/__init__.py

@@ -0,0 +1,239 @@
+"""primitives — the runtime-owned pure Python implementing the registry nodes (D2 §1).
+
+Primitive nodes are the parameterized building blocks where all I/O and effects live
+(sources, indicators, filters, rankers, emitters) plus the stateful TTL-dedup variant
+whose state is a typed in/out port pair compiled onto ``ctx.state`` (D2). Their
+implementations live here so both the compiled ``scan.py`` and, later, hand-written
+tier-3 scanners can import them; the emitted scanner reaches this package through the
+scaffold ``sys.path`` (recorded POC decision: no packaging yet, ``senpi_ta`` versioning
+stays open post-POC).
+
+Slice-3 scope: real implementations for every node the stag AND hawk graphs use —
+3 sources, 7 indicators, 2 filters, 1 scorer, 1 ranker, 1 emitter, 1 stateful = 16.
+Each is a pure function (or, for the sources, a pure normalizer paired with the thin
+``adapter`` that does the I/O) over plain data structures. Semantics are ported from
+the corpus originals (cited in each module); per-primitive golden vectors under
+python-tests/composer define correctness.
+
+``IMPLEMENTATIONS`` is the machine-checkable bridge between the registry declarations
+and these functions: the registry<->implementation signature-agreement test asserts,
+for every implemented node, that the callable's signature and the params/ports it
+consumes match the registry NodeDef exactly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from . import emitters, filters, indicators, rankers, scorers, sources, stateful
+from .adapter import McpSourceAdapter, make_adapter
+
+
+@dataclass(frozen=True)
+class ImplSpec:
+    """How one registry node maps onto its Python implementation.
+
+    fn_args        — the callable's exact ordered parameter names (pins the signature).
+    param_args     — registry param names the callable consumes.
+    adapter_params — registry param names consumed by the adapter / emitted code, not fn.
+    port_args      — registry (non-state) input-port names the callable consumes.
+    out_ports      — registry (non-state) output-port names the callable returns, in order.
+    write_fn/args  — the WRITE half of a split stateful node (epilogue), if any.
+    """
+
+    node: str
+    fn: Callable
+    fn_args: tuple = ()
+    param_args: tuple = ()
+    adapter_params: tuple = ()
+    port_args: tuple = ()
+    out_ports: tuple = ()
+    write_fn: Optional[Callable] = None
+    write_args: tuple = ()
+
+
+IMPLEMENTATIONS: dict[str, ImplSpec] = {
+    # ---- sources (pure normalizer + adapter-fetched raw) --------------------
+    "candles_fetch": ImplSpec(
+        node="candles_fetch", fn=sources.candles_fetch,
+        fn_args=("raw_by_asset", "intervals"),
+        param_args=("intervals",),
+        adapter_params=("whitelist", "include_funding", "include_asset_context"),
+        port_args=(), out_ports=("candles",),
+    ),
+    "clearinghouse_state": ImplSpec(
+        node="clearinghouse_state", fn=sources.clearinghouse_state,
+        fn_args=("raw",), out_ports=("held", "equity"),
+    ),
+    "sm_lean": ImplSpec(
+        node="sm_lean", fn=sources.sm_lean,
+        fn_args=("raw", "assets", "agree_threshold"),
+        param_args=("agree_threshold",), port_args=("assets",), out_ports=("lean",),
+    ),
+    "instrument_list": ImplSpec(
+        node="instrument_list", fn=sources.instrument_list,
+        fn_args=("raw",), adapter_params=("dex",), out_ports=("instruments",),
+    ),
+    "universe_discover": ImplSpec(
+        node="universe_discover", fn=sources.universe_discover,
+        fn_args=("instruments", "min_day_volume", "max_leverage_cap", "name_prefix"),
+        param_args=("min_day_volume", "max_leverage_cap", "name_prefix"),
+        port_args=("instruments",), out_ports=("universe",),
+    ),
+    "own_return_24h": ImplSpec(
+        node="own_return_24h", fn=sources.own_return_24h,
+        fn_args=("candles",), port_args=("candles",), out_ports=("return_24h",),
+    ),
+    # ---- batch C: world-coverage sources ------------------------------------
+    "market_prices_fetch": ImplSpec(
+        node="market_prices_fetch", fn=sources.market_prices,
+        fn_args=("raw", "assets"),
+        adapter_params=("dex",), port_args=("assets",), out_ports=("prices",),
+    ),
+    "strategy_list_fetch": ImplSpec(
+        node="strategy_list_fetch", fn=sources.strategy_list,
+        fn_args=("raw",), adapter_params=("status", "strategy_type"),
+        out_ports=("strategies",),
+    ),
+    "open_orders_fetch": ImplSpec(
+        node="open_orders_fetch", fn=sources.open_orders,
+        fn_args=("raw",), out_ports=("orders",),
+    ),
+    "trader_history_fetch": ImplSpec(
+        node="trader_history_fetch", fn=sources.trader_history,
+        fn_args=("raw",), adapter_params=("trader_address", "limit"),
+        out_ports=("closed_positions",),
+    ),
+    "asset_trading_limits_fetch": ImplSpec(
+        node="asset_trading_limits_fetch", fn=sources.asset_trading_limits,
+        fn_args=("raw_by_asset",), adapter_params=("dex",),
+        out_ports=("max_leverage",),
+    ),
+    "strategy_pnl_snapshot": ImplSpec(
+        node="strategy_pnl_snapshot", fn=sources.strategy_pnl_snapshot,
+        fn_args=("raw",), adapter_params=("period", "drawdown_reset_on_day_rollover"),
+        out_ports=("today_pnl", "today_account_value", "today_drawdown"),
+    ),
+    "trader_state_fetch": ImplSpec(
+        node="trader_state_fetch", fn=sources.trader_state,
+        fn_args=("raw",), adapter_params=("trader_address",),
+        out_ports=("held", "equity"),
+    ),
+    # ---- indicators ---------------------------------------------------------
+    "sma": ImplSpec(
+        node="sma", fn=indicators.sma,
+        fn_args=("candles", "period", "interval"),
+        param_args=("period", "interval"), port_args=("candles",),
+        out_ports=("value", "above"),
+    ),
+    "pct_change": ImplSpec(
+        node="pct_change", fn=indicators.pct_change,
+        fn_args=("candles", "lookback", "interval"),
+        param_args=("lookback", "interval"), port_args=("candles",), out_ports=("pct",),
+    ),
+    "recent_high_bars_ago": ImplSpec(
+        node="recent_high_bars_ago", fn=indicators.recent_high_bars_ago,
+        fn_args=("candles", "window", "interval"),
+        param_args=("window", "interval"), port_args=("candles",), out_ports=("bars_ago",),
+    ),
+    "volume_surge_ratio": ImplSpec(
+        node="volume_surge_ratio", fn=indicators.volume_surge_ratio,
+        fn_args=("candles", "recent_window", "baseline_window", "interval"),
+        param_args=("recent_window", "baseline_window", "interval"),
+        port_args=("candles",), out_ports=("ratio",),
+    ),
+    "acceleration": ImplSpec(
+        node="acceleration", fn=indicators.acceleration,
+        fn_args=("candles", "short_window", "long_window", "interval"),
+        param_args=("short_window", "long_window", "interval"),
+        port_args=("candles",), out_ports=("accelerating",),
+    ),
+    "trend_structure": ImplSpec(
+        node="trend_structure", fn=indicators.trend_structure,
+        fn_args=("candles", "lookback", "interval"),
+        param_args=("lookback", "interval"), port_args=("candles",), out_ports=("direction",),
+    ),
+    "breakout_detect": ImplSpec(
+        node="breakout_detect", fn=indicators.breakout_detect,
+        fn_args=("candles", "window", "interval"),
+        param_args=("window", "interval"), port_args=("candles",), out_ports=("direction",),
+    ),
+    "rsi": ImplSpec(
+        node="rsi", fn=indicators.rsi,
+        fn_args=("candles", "period", "interval"),
+        param_args=("period", "interval"), port_args=("candles",), out_ports=("rsi",),
+    ),
+    # ---- filters ------------------------------------------------------------
+    "held_asset_exclusion": ImplSpec(
+        node="held_asset_exclusion", fn=filters.held_asset_exclusion,
+        fn_args=("candidates", "held"), port_args=("candidates", "held"), out_ports=("kept",),
+    ),
+    "recent_signal_ttl_dedup": ImplSpec(
+        node="recent_signal_ttl_dedup", fn=filters.recent_signal_ttl_dedup,
+        fn_args=("candidates", "recent"), port_args=("candidates", "recent"), out_ports=("kept",),
+    ),
+    "classifier_predicate": ImplSpec(
+        node="classifier_predicate", fn=filters.classifier_predicate,
+        fn_args=("candidates", "max_funding_abs", "max_leverage", "exclude_delisted"),
+        param_args=("max_funding_abs", "max_leverage", "exclude_delisted"),
+        port_args=("candidates",), out_ports=("kept",),
+    ),
+    "live_instrument_validation": ImplSpec(
+        node="live_instrument_validation", fn=filters.live_instrument_validation,
+        fn_args=("candidates", "instruments"),
+        port_args=("candidates", "instruments"), out_ports=("kept",),
+    ),
+    # ---- scorer -------------------------------------------------------------
+    "hard_gates_all": ImplSpec(
+        node="hard_gates_all", fn=scorers.hard_gates_all,
+        fn_args=("features", "required_gates", "weights", "min_score"),
+        param_args=("required_gates", "weights", "min_score"),
+        port_args=("features",), out_ports=("scores",),
+    ),
+    # ---- ranker -------------------------------------------------------------
+    "emit_single_best": ImplSpec(
+        node="emit_single_best", fn=rankers.emit_single_best,
+        fn_args=("scores", "min_score"),
+        param_args=("min_score",), port_args=("scores",), out_ports=("selected",),
+    ),
+    "rank_pool_cap_to_open_slots": ImplSpec(
+        node="rank_pool_cap_to_open_slots", fn=rankers.rank_pool_cap_to_open_slots,
+        fn_args=("scores", "held", "max_slots", "min_score"),
+        param_args=("max_slots", "min_score"), port_args=("scores", "held"),
+        out_ports=("selected",),
+    ),
+    # ---- emitter ------------------------------------------------------------
+    "signal_envelope": ImplSpec(
+        node="signal_envelope", fn=emitters.signal_envelope,
+        fn_args=("selected", "equity", "margin_pct", "leverage", "clamp_leverage_to_venue",
+                 "instruments", "valid_for_seconds", "signal_type"),
+        param_args=("margin_pct", "leverage", "clamp_leverage_to_venue",
+                    "valid_for_seconds", "signal_type"),
+        port_args=("selected", "equity", "instruments"), out_ports=("signals",),
+    ),
+    # ---- stateful (split read/write halves) ---------------------------------
+    "ttl_dedup_state": ImplSpec(
+        node="ttl_dedup_state", fn=stateful.ttl_dedup_state_read,
+        fn_args=("state", "ttl_seconds", "prune_factor", "now"),
+        param_args=("ttl_seconds", "prune_factor"),
+        port_args=(), out_ports=("recent",),
+        write_fn=stateful.ttl_dedup_state_write,
+        write_args=("state", "working_map", "emitted", "now"),
+    ),
+}
+
+__all__ = [
+    "sources",
+    "indicators",
+    "filters",
+    "scorers",
+    "rankers",
+    "emitters",
+    "stateful",
+    "adapter",
+    "McpSourceAdapter",
+    "make_adapter",
+    "ImplSpec",
+    "IMPLEMENTATIONS",
+]

package/dist/composer/primitives/_candles.py

@@ -0,0 +1,76 @@
+"""_candles — shared candle-field coercion helpers for the indicator primitives.
+
+These reproduce the dual-key float coercion used verbatim across the corpus
+originals (``_f`` / ``_close`` / ``_high`` / ``_low`` / ``_vol``); see
+``/Users/duncan/Senpi/skills/strategies/hawk/main/scanners/scoring.py`` and
+``/Users/duncan/Senpi/skills/strategies/stag/main/scanners/scoring.py``. A candle
+is a dict carrying either the long key (``close``) or the short key (``c``); the
+list branch ``[t, o, h, l, c, v]`` is defensive and never fires on dict candles.
+
+The goldens WE author (python-tests/composer) define correctness — these helpers
+follow the originals' coercion so the compiled graphs behave the same way on the
+same candle series, but bit-level parity with the originals is not the oracle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _f(v: Any, d: float = 0.0) -> float:
+    """Float coercion (corpus ``scoring._f``): non-numeric / None -> default."""
+    try:
+        return float(v if v is not None else d)
+    except (TypeError, ValueError):
+        return d
+
+
+def _close(c: Any) -> float:
+    if isinstance(c, dict):
+        return _f(c.get("close", c.get("c", 0)))
+    if isinstance(c, (list, tuple)) and len(c) >= 5:
+        return _f(c[4])
+    return 0.0
+
+
+def _high(c: Any) -> float:
+    if isinstance(c, dict):
+        return _f(c.get("high", c.get("h", 0)))
+    if isinstance(c, (list, tuple)) and len(c) >= 5:
+        return _f(c[2])
+    return 0.0
+
+
+def _low(c: Any) -> float:
+    if isinstance(c, dict):
+        return _f(c.get("low", c.get("l", 0)))
+    if isinstance(c, (list, tuple)) and len(c) >= 5:
+        return _f(c[3])
+    return 0.0
+
+
+def _vol(c: Any) -> float:
+    if isinstance(c, dict):
+        return _f(c.get("volume", c.get("v", c.get("vlm", 0))))
+    if isinstance(c, (list, tuple)) and len(c) >= 6:
+        return _f(c[5])
+    return 0.0
+
+
+def _closes(series: list) -> list[float]:
+    return [_close(c) for c in series]
+
+
+def _pct_change(closes: list[float], lookback: int):
+    """% change of the latest close vs the close ``lookback`` bars ago.
+
+    Verbatim shape from stag ``scoring.pct_change`` (cited file above): None on
+    insufficient data or a non-positive reference price.
+    """
+    if not closes or len(closes) <= lookback:
+        return None
+    ref = closes[-(lookback + 1)]
+    latest = closes[-1]
+    if ref is None or ref <= 0:
+        return None
+    return ((latest - ref) / ref) * 100.0

package/dist/composer/primitives/adapter.py

@@ -0,0 +1,120 @@
+"""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
+
+
+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 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},
+        )
+
+
+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]