@senpi/runtime 3.0.9-dev.feat-strategy-compos.20260721003344 → 3.0.9-dev.feat-strategy-compos.20260722213012

package/dist/composer/authoring/answers.py

@@ -130,6 +130,44 @@ class CopyTrading(BaseModel):
     min_traders: int = 2                      # per-coin cohort-thickness gate (agreement needs >= this)
 
 
+class ContrarianFade(BaseModel):
+    """OPTIONAL contrarian-fade knobs — the ``contrarian_fade`` archetype family's ingredient
+    surface (slice JA; capability-regression audit §E3).
+
+    Absent (the default ``None`` on :class:`Answers`) => byte-identical output EVERYWHERE (the hard
+    regression constraint): the block is emitted into ``metadata.spec`` ONLY when set (same additive
+    pattern as ``copy_trading`` / ``exit_signals`` / ``group``), so every existing answers file
+    round-trips unchanged.
+
+    The MEMBER of the ``contrarian_fade`` family is INFERRED from the ingredients (no ``member``
+    field — the least-new-surface convention shared with relative_value's whitelist length,
+    copy_trading's trader_addresses, and trend_momentum's discover flag). The discriminant is
+    ``use_crowd`` — the genuine INGREDIENT difference between the two clusters the corpus splits into:
+
+      * ``use_crowd = True``  -> the **fade_crowd** member: fade a crowded/overextended move where the
+        crowd is read from smart-money lean (sm_lean) gated by the market-wide funding regime
+        (funding_regime_fetch). Mirrors dog / lemon / owl / egret (sm_crowding) + hyena
+        (risk_off_rotation, funding-regime master gate). SHORT an overbought rip the crowd is long;
+        LONG an oversold flush the crowd is short.
+      * ``use_crowd = False`` -> the **fade_price** member: fade pure PRICE overextension (RSI +
+        recent return), no positioning data. Mirrors salmon (mean_reversion) + bald-eagle
+        (xyz_overextended). SHORT overbought/overextended-up; LONG oversold/overextended-down.
+
+    ``overbought_rsi`` / ``oversold_rsi`` are the RSI extremes that mark exhaustion; ``min_extension_pct``
+    is the recent-return magnitude that qualifies a move as overextended (dog: 3%+ in ~4h);
+    ``crowd_threshold`` is the smart-money lean deviation from neutral (0.5) that counts as crowded
+    (dog: SM concentration ~15%+) and is INERT for fade_price. The universe is a FIXED whitelist OR a
+    discovered board (``universe.whitelist`` / ``universe.discover``) — the family reads whichever."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    use_crowd: bool = True             # member: True => fade_crowd (sm+funding), False => fade_price (RSI)
+    overbought_rsi: float = 70.0       # RSI at/above which an up-move is exhausted (fade SHORT)
+    oversold_rsi: float = 30.0         # RSI at/below which a down-move is exhausted (fade LONG)
+    min_extension_pct: float = 3.0     # |recent return %| that qualifies as overextended (dog 3%+/4h)
+    crowd_threshold: float = 0.15      # SM lean deviation from 0.5 that counts as crowded (fade_crowd)
+
+
 class Protection(BaseModel):
     """The MATERIALIZED exit-protection spec — the FULL resolved protection carried IN the graph
     (F1 "the graph IS the spec"). Before F1 the exit values were resolved from a named preset only
@@ -308,6 +346,10 @@ class Answers(BaseModel):
     # Absent (None) => byte-identical to today (no copy_trading key in the metadata block). Present
     # => the copy_trading archetype reads the followed-cohort ingredients from it. See :class:`CopyTrading`.
     copy_trading: Optional[CopyTrading] = None
+    # contrarian_fade — OPTIONAL ingredient surface for the contrarian_fade archetype family (slice JA).
+    # Absent (None) => byte-identical to today (no contrarian_fade key in the metadata block). Present
+    # => the contrarian_fade archetype reads the fade ingredients from it. See :class:`ContrarianFade`.
+    contrarian_fade: Optional[ContrarianFade] = None
 
     @field_validator("exit_preset")
     @classmethod
@@ -460,6 +502,16 @@ class Answers(BaseModel):
                 "consistency": list(self.copy_trading.consistency),
                 "min_traders": self.copy_trading.min_traders,
             }
+        # contrarian_fade: the fade ingredients, emitted ONLY when set (same F1 discipline) so answers
+        # without it round-trip byte-identically. Survives Answers(**block) as ContrarianFade.
+        if self.contrarian_fade is not None:
+            block["contrarian_fade"] = {
+                "use_crowd": self.contrarian_fade.use_crowd,
+                "overbought_rsi": self.contrarian_fade.overbought_rsi,
+                "oversold_rsi": self.contrarian_fade.oversold_rsi,
+                "min_extension_pct": self.contrarian_fade.min_extension_pct,
+                "crowd_threshold": self.contrarian_fade.crowd_threshold,
+            }
         return block
 
 

package/dist/composer/authoring/archetypes/__init__.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 from . import (
     breakout,
     classifier,
+    contrarian_fade,
     copy_trading,
     relative_value,
     skeleton,
@@ -29,6 +30,7 @@ ARCHETYPES = {
     "thesis_fund": thesis_fund,
     "relative_value": relative_value,
     "copy_trading": copy_trading,
+    "contrarian_fade": contrarian_fade,
 }
 
 SKELETON = skeleton

package/dist/composer/authoring/archetypes/contrarian_fade.py

@@ -0,0 +1,493 @@
+"""contrarian_fade — the fade-the-overextension thesis shape (capability-regression audit §E3).
+
+The routing incident this closes: "fade the crowd", "short the exhausted rip", "buy the oversold
+flush", "mean-revert the majors" had NO archetype and NO routing row (audit §A.4 #3: 8-10 corpus
+packages, all escape-hatch-only), so the agent found no route — even though every source node
+already existed (sm_lean, funding_regime_fetch, rsi, pct_change). `contrarian_fade` is that missing
+shape: it detects an OVEREXTENDED move (an RSI extreme confirmed by a recent price run) and enters
+the OPPOSITE direction — SHORT an overbought rip, LONG an oversold flush — betting on mean reversion.
+
+This is a FAMILY with two members (taxonomy: family = thesis shape, members = ingredient combos),
+selected mechanically from the answers ingredients (the least-new-surface convention — no member
+field; mirrors relative_value's whitelist length, copy_trading's trader_addresses, and
+trend_momentum's discover flag). The discriminant is ``contrarian_fade.use_crowd`` — the genuine
+INGREDIENT difference between the two clusters the 10 contrarian_fade corpus packages split into:
+
+  * ``fade_crowd`` (use_crowd=True, the DEFAULT) — fade a move the CROWD is piling into. The crowd
+    is read from smart-money lean (sm_lean) and gated by the market-wide funding regime
+    (funding_regime_fetch): SHORT an overbought rip ONLY when smart money is crowded-long and the
+    regime is not SHORT_CROWDED; LONG an oversold flush ONLY when crowded-short and not LONG_CROWDED.
+    Defaults MIRROR ``dog`` (Contrarian Pup: 3%+ move in ~4h + SM concentration ~15%+ -> fade) and
+    ``lemon`` / ``owl`` / ``egret`` (sm_crowding); the funding-regime master gate is ``hyena``'s
+    (risk_off_rotation). All source nodes exist.
+  * ``fade_price`` (use_crowd=False) — fade PURE price overextension (RSI + recent return), no
+    positioning data. Defaults MIRROR ``salmon`` (RSI Mean-Reversion) and ``bald-eagle``
+    (xyz_overextended macro fader). All source nodes exist.
+
+Both members share the SCORING half's SHAPE — ONE two-output signed-fade pure_fn (D2 kind 2):
+
+  * entry_scores — ENTER the FADE (opposite the exhausted move) when the overextension test fires
+    (and, for fade_crowd, the crowd is aligned + the regime permits) AND the asset is NOT held.
+  * exit_scores  — CLOSE a held fade when MEAN REVERSION IS COMPLETE (RSI has crossed back through
+    the 50 midline — the snap-back the fade was betting on) OR the THESIS IS INVALIDATED (the move
+    extended FURTHER against the fade — the crowd kept pushing; cut it).
+
+Held-exclusion + the real held direction live INSIDE the fn (via an ``open_positions`` input) so the
+entry and exit streams can never both fire — the relative_value / copy_trading complementarity
+pattern. Exit topology is answer-driven (design orthogonal axis): when ``answers.exit_signals`` is
+present the graph carries the exit tail (``close_signal_envelope`` wired to exit_scores + positions),
+the compiler splits it into an entry scanner + a reduce-only exit scanner, and the resolved DSL
+preset demotes to ``protected_wide`` (the WIDE safety net, never front-running the reversion exit).
+When it is ABSENT the graph is ENTRY-ONLY (single module, DSL-managed exits); the fn still computes
+exit_scores (unwired) and still applies held-exclusion (an entry firing into an already-held asset
+would double the position, which the no-pyramiding default forbids). The DSL preset is ALWAYS
+retained alongside a signal exit — the reversion signal is the thesis close, the DSL floor stays the
+safety net for the case where the fade is simply wrong.
+"""
+
+from __future__ import annotations
+
+from ..answers import Answers, ContrarianFade
+from ..builder import GraphBuilder
+from . import _common
+from ._common import GenerationError
+
+DESCRIBE = [
+    "# contrarian_fade  (archetype family)",
+    "",
+    "Thesis shape: FADE an overextended move — 'short the exhausted rip', 'buy the oversold flush',",
+    "'fade the crowd', 'mean-revert the majors'. Detect an RSI extreme confirmed by a recent price",
+    "run and enter the OPPOSITE direction (SHORT an overbought rip, LONG an oversold flush), betting",
+    "on the snap back toward the mean. Universe is a FIXED whitelist OR a discovered board.",
+    "",
+    "Two MEMBERS, chosen from the ingredients you give (no member field — contrarian_fade.use_crowd):",
+    "  * fade_crowd (use_crowd=true, DEFAULT) — fade what the CROWD is piling into: smart-money lean",
+    "    (sm_lean) gated by the market-wide funding regime (funding_regime_fetch). SHORT an overbought",
+    "    rip only when smart money is crowded-long and the regime is not SHORT_CROWDED (and mirror for",
+    "    the LONG side). Mirrors dog / lemon / owl / egret (sm_crowding) + hyena (funding-regime gate).",
+    "  * fade_price (use_crowd=false) — fade PURE price overextension (RSI + recent return), no",
+    "    positioning data. Mirrors salmon (RSI mean-reversion) + bald-eagle (macro fader).",
+    "",
+    "The scoring half is ONE two-output signed-fade pure_fn (THE EDGE slot). ENTER the fade when the",
+    "overextension test fires and the asset is FLAT. EXIT a held fade when MEAN REVERSION IS COMPLETE",
+    "(RSI crossed back through the 50 midline) OR the THESIS IS INVALIDATED (the move extended further",
+    "against the fade). Held-exclusion + the real held direction live inside the fn.",
+    "",
+    "Exit topology (orthogonal axis): with answers.exit_signals the composer emits the two-scanner",
+    "pair (entry signal_envelope + reduce-only close_signal_envelope) and keeps a WIDE DSL preset as",
+    "the always-on safety net (the reversion signal is the thesis close, not protection). Omit",
+    "exit_signals for an ENTRY-ONLY variant (single module, DSL-managed exits).",
+    "",
+    "When to use vs breakout/trend_momentum (THE ROUTING TEST): if the thesis is 'the move is",
+    "EXHAUSTED, bet on it REVERSING' it is contrarian_fade (it inverts direction). If the thesis is",
+    "'the move CONTINUES' (ride the breakout/trend), it is breakout or trend_momentum.",
+    "",
+    "Emits: clearinghouse_state (equity for sizing), open_positions (held-exclusion + exit-direction",
+    "stamp), candles_fetch, rsi + pct_change (the overextension read), and for fade_crowd also sm_lean",
+    "+ funding_regime_fetch (the crowd read + market gate) and (when discovering) instrument_list +",
+    "universe_discover; a `score` pure_fn (THE EDGE slot, TWO outputs), a ranker (single-best or",
+    "pool-cap by max_positions) + signal_envelope (entry tail), and close_signal_envelope (exit tail",
+    "— only when exit_signals is set).",
+    "",
+    "Answers that matter: universe.whitelist OR universe.discover (+ dex / name_prefix /",
+    "max_leverage_cap / min_day_volume); contrarian_fade.{use_crowd, overbought_rsi, oversold_rsi,",
+    "min_extension_pct, crowd_threshold}; intervals; max_positions (single-best vs pool-cap);",
+    "exit_signals (present => the reversion exit tail); exit_preset; risk.*.",
+]
+
+BANNER = [
+    "contrarian_fade strategy — machine-generated anchor (composer new).",
+    "",
+    "Fade an overextended move: detect an RSI extreme confirmed by a recent price run and enter the",
+    "OPPOSITE direction (SHORT an overbought rip, LONG an oversold flush), betting on mean reversion.",
+    "fade_crowd additionally requires the crowd (smart-money lean) to be piling in AND the market-wide",
+    "funding regime to permit the fade; fade_price fades pure price. A hysteresis-free reversion exit",
+    "closes when RSI crosses back through the midline or the move invalidates the fade, with",
+    "held-exclusion built in. Edit ONLY the pure_fn body (the EDGE slot) to move it toward your edge;",
+    "every intermediate state stays valid (`composer check`).",
+]
+
+# Archetype shape constants (NOT answers fields).
+# The RSI window and the recent-extension window are the family's fixed shape (like relative_value's
+# WINDOWS). RSI 14 is the corpus-universal period; the extension is a short recent run (dog's "3% in
+# ~4h" is roughly this window at 4h) expressed in bars at the chosen interval.
+_RSI_PERIOD = 14
+_EXTENSION_LOOKBACK = 6
+# A held fade is INVALIDATED (the crowd kept pushing) when the move extends beyond this multiple of
+# the entry extension threshold while the RSI extreme is unresolved. A shape constant, not an answer.
+_INVALIDATION_FACTOR = 2.0
+_SIGNAL_STRENGTH = 1.0
+
+# The two-output signed-fade CROWD scorer (D2 kind 2). Generic over the bound thresholds (all passed
+# as params); emitted verbatim AND executed in _contrarian_fade_tests to synthesize inline fixtures
+# that pass by construction. Deterministic, math-only (purity-checked).
+FADE_CROWD_FN = '''\
+def score_fade_crowd(rsi, move, sm, regime, positions, overbought_rsi, oversold_rsi, min_extension_pct, crowd_threshold, invalidation_factor, signal_strength):
+    # TODO(edit): the CROWD-FADE edge (a WORKING DEFAULT; dog/lemon/egret/owl + hyena regime gate).
+    # For each asset, an OVEREXTENSION is an RSI extreme confirmed by a recent price run: overbought =
+    # rsi >= overbought_rsi AND move (recent % return) >= min_extension_pct; oversold is the mirror.
+    # Fade it ONLY when the CROWD is aligned WITH the exhausted move (smart-money tilt in [0,1], 0.5
+    # neutral: crowded-long = tilt >= 0.5+crowd_threshold) AND the market-wide funding regime PERMITS
+    # the fade (LONG_CROWDED -> only SHORT fades; SHORT_CROWDED -> only LONG fades; NEUTRAL/"" -> both).
+    # ENTER the OPPOSITE direction when FLAT. EXIT a held fade when MEAN REVERSION IS COMPLETE (RSI
+    # crossed back through the 50 midline) OR the THESIS IS INVALIDATED (the move extended further
+    # against the fade). Held-exclusion + the real held direction live here (via positions) so entry
+    # and exit can never both fire. A missing leg simply abstains (no vote), never raises. Encode YOUR
+    # edge by editing this body — it is purity-checked (no ctx/MCP/I/O, math only) and its inline tests
+    # run at validate time.
+    reg = (regime or "").upper()
+    allow_short = reg != "SHORT_CROWDED"
+    allow_long = reg != "LONG_CROWDED"
+    held = {}
+    for record in positions or []:
+        coin = str(record.get("coin", "")).upper()
+        if coin:
+            held[coin] = record.get("direction") or "LONG"
+    entry_scores = {}
+    exit_scores = {}
+    for asset in sorted(set(rsi) | set(move)):
+        r = rsi.get(asset)
+        mv = move.get(asset)
+        if r is None or mv is None:
+            continue
+        raw = sm.get(asset, 0.5)
+        tilt = raw.get("tilt", raw.get("lean", 0.5)) if isinstance(raw, dict) else raw
+        crowd_long = tilt >= 0.5 + crowd_threshold
+        crowd_short = tilt <= 0.5 - crowd_threshold
+        overbought = r >= overbought_rsi and mv >= min_extension_pct
+        oversold = r <= oversold_rsi and mv <= -min_extension_pct
+        held_direction = held.get(str(asset).upper())
+        if held_direction is None:
+            if overbought and crowd_long and allow_short:
+                score = signal_strength * (abs(r - overbought_rsi) + abs(mv))
+                entry_scores[asset] = {"score": round(score, 4), "direction": "SHORT",
+                                       "reasons": ["overbought_rip", "crowd_long"]}
+            elif oversold and crowd_short and allow_long:
+                score = signal_strength * (abs(oversold_rsi - r) + abs(mv))
+                entry_scores[asset] = {"score": round(score, 4), "direction": "LONG",
+                                       "reasons": ["oversold_flush", "crowd_short"]}
+        else:
+            if held_direction == "SHORT":
+                reverted = r <= 50.0
+                invalidated = r >= overbought_rsi and mv >= min_extension_pct * invalidation_factor
+            else:
+                reverted = r >= 50.0
+                invalidated = r <= oversold_rsi and mv <= -min_extension_pct * invalidation_factor
+            if reverted or invalidated:
+                exit_scores[asset] = {"score": round(abs(mv), 4), "direction": held_direction,
+                                      "reasons": ["reversion_complete" if reverted else "thesis_invalidated"]}
+    return entry_scores, exit_scores
+'''
+
+# The two-output signed-fade PRICE scorer — fade_price member (RSI + recent return, no positioning).
+FADE_PRICE_FN = '''\
+def score_fade_price(rsi, move, positions, overbought_rsi, oversold_rsi, min_extension_pct, invalidation_factor, signal_strength):
+    # TODO(edit): the PRICE-FADE edge (a WORKING DEFAULT; salmon RSI mean-reversion + bald-eagle).
+    # For each asset an OVEREXTENSION is an RSI extreme confirmed by a recent price run: overbought =
+    # rsi >= overbought_rsi AND move (recent % return) >= min_extension_pct; oversold is the mirror.
+    # Fade it (SHORT an overbought rip, LONG an oversold flush) when FLAT — no positioning data, pure
+    # price. EXIT a held fade when MEAN REVERSION IS COMPLETE (RSI crossed back through the 50 midline)
+    # OR the THESIS IS INVALIDATED (the move extended further against the fade). Held-exclusion + the
+    # real held direction live here (via positions). A missing leg abstains, never raises. Encode YOUR
+    # edge by editing this body — it is purity-checked (no ctx/MCP/I/O, math only) and its inline tests
+    # run at validate time.
+    held = {}
+    for record in positions or []:
+        coin = str(record.get("coin", "")).upper()
+        if coin:
+            held[coin] = record.get("direction") or "LONG"
+    entry_scores = {}
+    exit_scores = {}
+    for asset in sorted(set(rsi) | set(move)):
+        r = rsi.get(asset)
+        mv = move.get(asset)
+        if r is None or mv is None:
+            continue
+        overbought = r >= overbought_rsi and mv >= min_extension_pct
+        oversold = r <= oversold_rsi and mv <= -min_extension_pct
+        held_direction = held.get(str(asset).upper())
+        if held_direction is None:
+            if overbought:
+                score = signal_strength * (abs(r - overbought_rsi) + abs(mv))
+                entry_scores[asset] = {"score": round(score, 4), "direction": "SHORT",
+                                       "reasons": ["overbought_rip"]}
+            elif oversold:
+                score = signal_strength * (abs(oversold_rsi - r) + abs(mv))
+                entry_scores[asset] = {"score": round(score, 4), "direction": "LONG",
+                                       "reasons": ["oversold_flush"]}
+        else:
+            if held_direction == "SHORT":
+                reverted = r <= 50.0
+                invalidated = r >= overbought_rsi and mv >= min_extension_pct * invalidation_factor
+            else:
+                reverted = r >= 50.0
+                invalidated = r <= oversold_rsi and mv <= -min_extension_pct * invalidation_factor
+            if reverted or invalidated:
+                exit_scores[asset] = {"score": round(abs(mv), 4), "direction": held_direction,
+                                      "reasons": ["reversion_complete" if reverted else "thesis_invalidated"]}
+    return entry_scores, exit_scores
+'''
+
+
+def _exec_fn(fn_src: str):
+    ns: dict = {}
+    exec(fn_src, ns)  # noqa: S102 - trusted, in-repo reference body used only for test-gen
+    for name, obj in ns.items():
+        if callable(obj) and name != "__builtins__":
+            return obj
+    raise RuntimeError("no function found in reference body")
+
+
+def _crowd_tests(cf: ContrarianFade) -> tuple[dict, ...]:
+    """Six inline fixtures whose expected values are computed from the default CROWD body itself with
+    the BOUND thresholds, so they pass by construction (emitted body == executed body). Semantic cases:
+    crowd-long overbought entry (SHORT), crowd-short oversold entry (LONG), regime veto (LONG_CROWDED
+    blocks a LONG fade), crowd-not-aligned no-entry, reversion-complete exit (held), thesis-invalidated
+    exit (held)."""
+    fn = _exec_fn(FADE_CROWD_FN)
+    ob, os_, ext, ct = cf.overbought_rsi, cf.oversold_rsi, cf.min_extension_pct, cf.crowd_threshold
+    inv = _INVALIDATION_FACTOR
+    held_short = [{"coin": "BTC", "direction": "SHORT", "szi": -1.0,
+                   "entry_px": 100.0, "unrealized_pnl_pct": 1.0, "margin_used": 10.0}]
+
+    def call(rsi, move, sm, regime, pos):
+        e, x = fn(rsi, move, sm, regime, pos, ob, os_, ext, ct, inv, _SIGNAL_STRENGTH)
+        return {"entry_scores": e, "exit_scores": x}
+
+    hot = ob + 5.0            # clearly overbought
+    cold = os_ - 5.0          # clearly oversold
+    big_up = ext + 2.0        # a real up-move
+    big_dn = -(ext + 2.0)     # a real down-move
+    crowd_long = 0.5 + ct + 0.1
+    crowd_short = 0.5 - ct - 0.1
+    cases = (
+        # overbought rip + crowd long + neutral regime + FLAT -> ENTER SHORT (fade the crowd).
+        ("crowd_long_overbought_fade_short",
+         {"BTC": hot}, {"BTC": big_up}, {"BTC": crowd_long}, "NEUTRAL", []),
+        # oversold flush + crowd short + neutral regime + FLAT -> ENTER LONG (fade the crowd).
+        ("crowd_short_oversold_fade_long",
+         {"ETH": cold}, {"ETH": big_dn}, {"ETH": crowd_short}, "NEUTRAL", []),
+        # oversold + crowd short but regime is LONG_CROWDED (only SHORT fades allowed) -> VETO.
+        ("regime_vetoes_long_fade",
+         {"ETH": cold}, {"ETH": big_dn}, {"ETH": crowd_short}, "LONG_CROWDED", []),
+        # overbought rip but the crowd is NOT long (tilt neutral) -> no entry (crowding is the gate).
+        ("crowd_not_aligned_no_entry",
+         {"BTC": hot}, {"BTC": big_up}, {"BTC": 0.5}, "NEUTRAL", []),
+        # HELD SHORT + RSI back below the midline -> EXIT (mean reversion complete).
+        ("reversion_complete_exit_when_held",
+         {"BTC": 45.0}, {"BTC": 0.0}, {"BTC": 0.5}, "NEUTRAL", held_short),
+        # HELD SHORT + RSI still overbought AND move extended 2x further -> EXIT (thesis invalidated).
+        ("thesis_invalidated_exit_when_held",
+         {"BTC": hot}, {"BTC": ext * inv + 1.0}, {"BTC": crowd_long}, "NEUTRAL", held_short),
+    )
+    return tuple(
+        {"name": name,
+         "inputs": {"rsi": rsi, "move": move, "sm": sm, "regime": regime, "positions": pos},
+         "expect": call(rsi, move, sm, regime, pos)}
+        for name, rsi, move, sm, regime, pos in cases
+    )
+
+
+def _price_tests(cf: ContrarianFade) -> tuple[dict, ...]:
+    """Five inline fixtures computed from the default PRICE body itself with the BOUND thresholds:
+    overbought entry (SHORT), oversold entry (LONG), in-band no-entry, reversion-complete exit (held),
+    held-exclusion suppresses a fresh entry."""
+    fn = _exec_fn(FADE_PRICE_FN)
+    ob, os_, ext = cf.overbought_rsi, cf.oversold_rsi, cf.min_extension_pct
+    inv = _INVALIDATION_FACTOR
+    held_short = [{"coin": "SOL", "direction": "SHORT", "szi": -1.0,
+                   "entry_px": 100.0, "unrealized_pnl_pct": 1.0, "margin_used": 10.0}]
+
+    def call(rsi, move, pos):
+        e, x = fn(rsi, move, pos, ob, os_, ext, inv, _SIGNAL_STRENGTH)
+        return {"entry_scores": e, "exit_scores": x}
+
+    hot = ob + 5.0
+    cold = os_ - 5.0
+    big_up = ext + 2.0
+    big_dn = -(ext + 2.0)
+    cases = (
+        # overbought rip + FLAT -> ENTER SHORT (pure price fade).
+        ("overbought_fade_short", {"SOL": hot}, {"SOL": big_up}, []),
+        # oversold flush + FLAT -> ENTER LONG.
+        ("oversold_fade_long", {"AVAX": cold}, {"AVAX": big_dn}, []),
+        # RSI mid-range + small move -> nothing overextended.
+        ("in_band_no_entry", {"SOL": 55.0}, {"SOL": 0.5}, []),
+        # HELD SHORT + RSI back below the midline -> EXIT (reversion complete).
+        ("reversion_complete_exit_when_held", {"SOL": 45.0}, {"SOL": 0.0}, held_short),
+        # overbought rip but the asset is already held -> held-exclusion suppresses a fresh entry.
+        ("held_exclusion_suppresses_entry", {"SOL": hot}, {"SOL": big_up}, held_short),
+    )
+    return tuple(
+        {"name": name, "inputs": {"rsi": rsi, "move": move, "positions": pos},
+         "expect": call(rsi, move, pos)}
+        for name, rsi, move, pos in cases
+    )
+
+
+def build(answers: Answers) -> GraphBuilder:
+    b = GraphBuilder()
+    cf = answers.contrarian_fade or ContrarianFade()
+    iv = answers.intervals[0] if answers.intervals else "4h"
+    u = answers.universe
+
+    # The universe is a FIXED whitelist OR a discovered board — reject a mis-shaped universe LOUDLY
+    # (mirrors the other archetypes' guards) so a bad answer never silently emits a broken graph.
+    if u.long_basket or u.short_basket:
+        raise GenerationError(
+            "archetype 'contrarian_fade' derives each asset's fade direction from its own "
+            "overextension (not a fixed leg); it does not take long_basket/short_basket. Use "
+            "universe.whitelist (a fixed basket) or universe.discover."
+        )
+    if not u.discover and not u.whitelist:
+        raise GenerationError(
+            "archetype 'contrarian_fade' needs a universe to fade: set universe.whitelist to a fixed "
+            "basket (dog/egret/lemon shape) OR universe.discover=true to fade a discovered board "
+            "(salmon/owl/pangolin shape)."
+        )
+
+    member = "fade_crowd" if cf.use_crowd else "fade_price"
+
+    es = answers.exit_signals
+
+    # --- sources shared by both members ---
+    b.add("account", "clearinghouse_state",
+          header=("sources: account equity for sizing. NO held-exclusion at the universe level —",
+                  "it lives in the pure_fn (fade only when flat, exit only when held).",))
+    b.add("positions", "open_positions",
+          header=("open positions (held + direction): in-fn held-exclusion + the exit tail's REAL",
+                  "held-direction stamp. Kept even in the entry-only variant (no-pyramiding).",))
+
+    # --- universe: fixed whitelist OR discovered board ---
+    if u.discover:
+        b.add("board", "instrument_list", {"dex": u.dex},
+              header=("dynamic universe discovery: live board -> leverage/volume/prefix signature.",))
+        b.add("universe", "universe_discover",
+              {"name_prefix": u.name_prefix, "max_leverage_cap": u.max_leverage_cap,
+               "min_day_volume": u.min_day_volume})
+        b.add("candles", "candles_fetch", {"intervals": list(answers.intervals)},
+              header=("candle reads over the discovered universe.",))
+    else:
+        b.add("candles", "candles_fetch",
+              {"whitelist": list(u.whitelist), "intervals": list(answers.intervals)},
+              header=("candle reads over the fixed fade basket.",))
+
+    # --- the overextension read: RSI extreme + a recent price run ---
+    b.add("rsi", "rsi", {"period": _RSI_PERIOD, "interval": iv},
+          header=("overextension read: RSI extreme + a recent price run.",))
+    b.add("move", "pct_change", {"lookback": _EXTENSION_LOOKBACK, "interval": iv})
+
+    # --- fade_crowd only: the crowd read (smart-money lean) + the market-wide funding-regime gate ---
+    if member == "fade_crowd":
+        b.add("lean", "sm_lean", {"agree_threshold": 0.6},
+              param_comments={"agree_threshold": "TODO(edit): smart-money agreement band (fade corpus 0.55-0.60)."},
+              slots=("agree_threshold",),
+              header=("crowd read: smart-money lean (fade only WITH the crowd) + the funding regime gate.",))
+        b.add("regime", "funding_regime_fetch")
+
+    # --- the two-output signed-fade scorer (THE EDGE slot; D2 kind 2) ---
+    common_params = (
+        {"name": "overbought_rsi", "type": "float", "default": cf.overbought_rsi,
+         "doc": "RSI at/above which an up-move is exhausted (fade SHORT)."},
+        {"name": "oversold_rsi", "type": "float", "default": cf.oversold_rsi,
+         "doc": "RSI at/below which a down-move is exhausted (fade LONG)."},
+        {"name": "min_extension_pct", "type": "float", "default": cf.min_extension_pct,
+         "doc": "|recent return %| that qualifies a move as overextended (dog 3%+/~4h)."},
+    )
+    tail_params = (
+        {"name": "invalidation_factor", "type": "float", "default": _INVALIDATION_FACTOR,
+         "doc": "A held fade is INVALIDATED when the move extends past this multiple of "
+                "min_extension_pct while the RSI extreme is unresolved (the crowd kept pushing)."},
+        {"name": "signal_strength", "type": "float", "default": _SIGNAL_STRENGTH,
+         "doc": "Per-signal score unit multiplier."},
+    )
+    outputs = (
+        {"name": "entry_scores", "type": "score_map",
+         "doc": "ENTER the FADE (opposite the exhausted move) when overextended and FLAT."},
+        {"name": "exit_scores", "type": "score_map",
+         "doc": "CLOSE a held fade when RSI crosses back through the 50 midline OR the move invalidates it."},
+    )
+
+    if member == "fade_crowd":
+        b.add_pure_fn(
+            "score",
+            inputs=(
+                {"name": "rsi", "type": "feature_map", "doc": "Per-asset RSI in [0,100]."},
+                {"name": "move", "type": "feature_map", "doc": "Per-asset recent percent return (extension)."},
+                {"name": "sm", "type": "feature_map", "doc": "Per-asset smart-money tilt in [0,1] (0.5 neutral)."},
+                {"name": "regime", "type": "label",
+                 "doc": "Market-wide funding regime (LONG_CROWDED|SHORT_CROWDED|NEUTRAL): the fade master gate."},
+                {"name": "positions", "type": "record_list",
+                 "doc": "Open positions (from open_positions) — held-exclusion + exit direction."},
+            ),
+            outputs=outputs,
+            params=common_params + (
+                {"name": "crowd_threshold", "type": "float", "default": cf.crowd_threshold,
+                 "doc": "Smart-money lean deviation from 0.5 that counts as crowded (dog ~15%+)."},
+            ) + tail_params,
+            fn=FADE_CROWD_FN,
+            tests=_crowd_tests(cf),
+            header=("pure_fn signed-fade scorer (crowd) — THE EDGE SLOT (edit the body; see the EDGE",
+                    "block above). TWO outputs: entry_scores (entry tail) + exit_scores (exit tail).",),
+            title="crowd fade: RSI/price overextension the smart-money crowd is piling into",
+        )
+    else:
+        b.add_pure_fn(
+            "score",
+            inputs=(
+                {"name": "rsi", "type": "feature_map", "doc": "Per-asset RSI in [0,100]."},
+                {"name": "move", "type": "feature_map", "doc": "Per-asset recent percent return (extension)."},
+                {"name": "positions", "type": "record_list",
+                 "doc": "Open positions (from open_positions) — held-exclusion + exit direction."},
+            ),
+            outputs=outputs,
+            params=common_params + tail_params,
+            fn=FADE_PRICE_FN,
+            tests=_price_tests(cf),
+            header=("pure_fn signed-fade scorer (price) — THE EDGE SLOT (edit the body; see the EDGE",
+                    "block above). TWO outputs: entry_scores (entry tail) + exit_scores (exit tail).",),
+            title="price fade: RSI + recent-return overextension, mean-reversion entry",
+        )
+    b.set_edge_anchor("score")
+
+    # --- entry tail: ranker (single-best vs pool-cap by cardinality) -> emitter ---
+    _common.add_ranker(
+        b, ranker_id="best", scorer_id="score", scorer_port="entry_scores",
+        account_id="account", max_positions=answers.max_positions,
+    )
+    b.add("emit", "signal_envelope",
+          {"margin_pct": answers.risk.margin_pct, "leverage": answers.risk.leverage},
+          header=("entry emitter: build the scan() OPEN signal list.",))
+
+    # --- exit tail: only when a thesis (reversion) exit was requested (answers.exit_signals) ---
+    if es is not None:
+        b.add("close_emit", "close_signal_envelope", {"signal_type": "thesis_exit"},
+              header=("exit emitter: reduce-only CLOSE list (no sizing/equity). The compiler splits",
+                      "this into a second, exit-only scanner; the DSL preset stays as the safety net.",))
+
+    # --- edges ---
+    # universe -> candles (+ sm_lean for the discovered case)
+    if u.discover:
+        b.connect("board", "instruments", "universe", "instruments", section="dynamic universe discovery")
+        b.connect("universe", "universe", "candles", "assets", section="discovered universe -> candle reads")
+        if member == "fade_crowd":
+            b.connect("universe", "universe", "lean", "assets")
+    # candles fan out to the overextension indicators
+    b.connect("candles", "candles", "rsi", "candles", section="candles fan out to the overextension read")
+    b.connect("candles", "candles", "move", "candles")
+    # per-asset features + positions (+ crowd read) wire into the pure_fn (single writer each)
+    b.connect("rsi", "rsi", "score", "rsi", section="overextension + positions -> the fade pure_fn")
+    b.connect("move", "pct", "score", "move")
+    if member == "fade_crowd":
+        b.connect("lean", "lean", "score", "sm")
+        b.connect("regime", "regime", "score", "regime")
+    b.connect("positions", "positions", "score", "positions")
+    # entry tail: entry_scores -> rank (wired inside add_ranker) -> emit (+ equity for sizing)
+    b.connect("best", "selected", "emit", "selected", section="entry tail: entry_scores -> rank -> emit")
+    b.connect("account", "equity", "emit", "equity")
+    # exit tail: exit_scores -> close emitter (+ positions for the real held-direction stamp)
+    if es is not None:
+        b.connect("score", "exit_scores", "close_emit", "selected",
+                  section="exit tail: exit_scores -> close emitter (+ positions for direction)")
+        b.connect("positions", "positions", "close_emit", "positions")
+    return b