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

package/dist/composer/authoring/__init__.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 from .answers import (
     Answers,
+    ExitSignals,
     Indicator,
     Risk,
     Scoring,
@@ -34,6 +35,7 @@ from .strategy_manifest import render_strategy_yaml
 
 __all__ = [
     "Answers",
+    "ExitSignals",
     "Indicator",
     "Risk",
     "Scoring",

package/dist/composer/authoring/answers.py

@@ -56,6 +56,29 @@ class Risk(BaseModel):
     max_consecutive_losses: Optional[int] = None    # stop after N losses
     cooldown_seconds: Optional[int] = None          # post-loss cooldown (>= 60)
     max_entries_per_day: Optional[int] = None        # per-day entry cap (>= 1)
+    # post-close per-asset re-entry cooldown (guard_rails.per_asset_cooldown_seconds, floor 300);
+    # None -> preset default, OR (for a signal-exit pair) the exit_signals.reentry_cooldown_seconds
+    # default. An explicit value here ALWAYS wins (RISK_OVERRIDE_KEYS carries it into guard_rails).
+    per_asset_cooldown_seconds: Optional[int] = None
+
+
+class ExitSignals(BaseModel):
+    """OPTIONAL thesis-exit knobs — the hysteresis dead band + post-close re-entry cooldown for a
+    signal-driven (thesis) exit (exit-composition slice). Absent (the default ``None`` on
+    :class:`Answers`) => byte-identical output EVERYWHERE (the hard regression constraint): no exit
+    scanner, no CLOSE_POSITION action, no per-asset cooldown guard rail. Present => the composer
+    additionally emits the exit scanner + CLOSE action pair and the per-asset cooldown (design §1.2).
+
+    ``interval_seconds`` is the exit scanner's poll cadence; ``enter_threshold`` / ``exit_threshold``
+    are the net-score hysteresis band the compiled predicate uses; ``reentry_cooldown_seconds`` is
+    the post-close per-asset re-entry cooldown (schema floor 300)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    interval_seconds: int = 300
+    enter_threshold: float = 3.0
+    exit_threshold: float = 2.0
+    reentry_cooldown_seconds: int = 1800
 
 
 class Universe(BaseModel):
@@ -154,9 +177,12 @@ class Answers(BaseModel):
     intervals: tuple[str, ...] = ("4h",)
     max_positions: int = 1          # cardinality -> ranker choice (single-best vs pool-cap)
     ttl_seconds: int = 240          # memory -> ttl_dedup_state dedup window
-    # LIVE: emitted as the runtime.yaml exit: section. Default None = "unset"; `composer new`
-    # BINDS protected_standard unless overridden (protection-by-default). A graph reaching
-    # `check` with exit_preset unset AND unmanaged False is the RED CMP120 contradiction.
+    # LIVE: emitted as the runtime.yaml exit: section. Default None = "unset" (unset-vs-explicit
+    # semantics): `composer new` RESOLVES an unset preset at build time — protected_standard when
+    # there is no exit_signals (today's default, byte-identical), protected_wide when exit_signals
+    # is present (the DSL demotes to a WIDE safety net so it never front-runs the thesis exit). An
+    # EXPLICIT value ALWAYS wins. A graph reaching `check` with exit_preset unset AND unmanaged
+    # False is the RED CMP120 contradiction.
     exit_preset: Optional[str] = None
     unmanaged: bool = False         # explicit opt-out: no exit section (else CMP120 RED at check)
     risk: Risk = Field(default_factory=Risk)
@@ -167,6 +193,10 @@ class Answers(BaseModel):
     # registry indicator nodes (indicators) mechanically, no hand edit. See the two submodels.
     scoring: Optional[Scoring] = None
     indicators: tuple[Indicator, ...] = ()
+    # exit-composition — OPTIONAL thesis-exit surface. Absent (None) => byte-identical to today
+    # (no exit scanner / CLOSE action / per-asset cooldown). Present => the composer emits the
+    # entry/exit scanner pair. See :class:`ExitSignals` and the PRESET POLICY on exit_preset.
+    exit_signals: Optional[ExitSignals] = None
 
     @field_validator("exit_preset")
     @classmethod
@@ -232,6 +262,11 @@ class Answers(BaseModel):
                 {"name": c.name, "kind": c.kind, "need": c.need} for c in self.requires
             ],
         }
+        # per_asset_cooldown_seconds joins the risk block ONLY when set — the sibling knobs above
+        # always emit (None -> null), but this one is exit-composition-era and must stay ABSENT for
+        # exit-less answers to keep the metadata byte-identical (round-trips via Answers(**block)).
+        if self.risk.per_asset_cooldown_seconds is not None:
+            block["risk"]["per_asset_cooldown_seconds"] = self.risk.per_asset_cooldown_seconds
         # F1: emit the optional surface ONLY when set, so answers without it round-trip
         # byte-identically to the pre-F1 metadata block (the HARD regression constraint).
         # Both survive `Answers(**block)` deterministically (the deploy metadata re-derive path).
@@ -250,6 +285,15 @@ class Answers(BaseModel):
                  "source": i.source}
                 for i in self.indicators
             ]
+        # exit-composition: the thesis-exit knobs, emitted ONLY when set (same F1 discipline) so
+        # exit-less answers round-trip byte-identically. Survives Answers(**block) as ExitSignals.
+        if self.exit_signals is not None:
+            block["exit_signals"] = {
+                "interval_seconds": self.exit_signals.interval_seconds,
+                "enter_threshold": self.exit_signals.enter_threshold,
+                "exit_threshold": self.exit_signals.exit_threshold,
+                "reentry_cooldown_seconds": self.exit_signals.reentry_cooldown_seconds,
+            }
         return block
 
 

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

@@ -12,15 +12,32 @@ Each module exposes ``build(answers) -> GraphBuilder`` and a ``BANNER`` header.
 
 from __future__ import annotations
 
-from . import breakout, classifier, skeleton, thesis_fund, trend_momentum
+from . import breakout, classifier, relative_value, skeleton, thesis_fund, trend_momentum
 
 ARCHETYPES = {
     "trend_momentum": trend_momentum,
     "breakout": breakout,
     "classifier": classifier,
     "thesis_fund": thesis_fund,
+    "relative_value": relative_value,
 }
 
 SKELETON = skeleton
 
-__all__ = ["ARCHETYPES", "SKELETON"]
+
+def archetype_names() -> list[str]:
+    """The recognised archetype names (a `describe <archetype>` namespace)."""
+    return sorted(ARCHETYPES)
+
+
+def render_describe_archetype(name: str) -> str | None:
+    """The describe reference for ONE archetype (its ``DESCRIBE`` block — the single home for
+    the archetype's shape), or None if the name is not a recognised archetype. The skeleton
+    fallback is deliberately excluded: "no matching archetype" is its trigger, not a name."""
+    module = ARCHETYPES.get(name)
+    if module is None:
+        return None
+    return "\n".join(module.DESCRIBE) + "\n"
+
+
+__all__ = ["ARCHETYPES", "SKELETON", "archetype_names", "render_describe_archetype"]

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

@@ -20,6 +20,24 @@ from ..answers import Answers
 from ..builder import GraphBuilder
 from . import _common
 
+DESCRIBE = [
+    "# breakout  (archetype)",
+    "",
+    "Thesis shape: a directional range-break (breakout_detect) is the HARD gate; 4h trend",
+    "structure, a volume surge, and smart-money lean are weighted contributors; single-best",
+    "(or pool-cap) emission with TTL signal-dedup. Universe is a fixed basket OR discovered",
+    "each tick from the live instrument board.",
+    "",
+    "Emits: clearinghouse_state, ttl_dedup_state, (instrument_list + universe_discover when",
+    "discovering), held_asset_exclusion, recent_signal_ttl_dedup, candles_fetch, sm_lean,",
+    "breakout_detect, trend_structure, volume_surge_ratio, hard_gates_all (THE EDGE slot),",
+    "a ranker, signal_envelope.",
+    "",
+    "Answers that matter: universe.whitelist OR universe.discover (+ dex / name_prefix /",
+    "max_leverage_cap / min_day_volume), intervals, max_positions, ttl_seconds, risk.*, and",
+    "scoring / indicators (e.g. the four-hard-gate discovery variant).",
+]
+
 BANNER = [
     "breakout strategy — machine-generated anchor (composer new).",
     "",

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

@@ -15,6 +15,22 @@ from ..answers import Answers
 from ..builder import GraphBuilder
 from . import _common
 
+DESCRIBE = [
+    "# classifier  (archetype)",
+    "",
+    "Thesis shape: trend structure at 4h + 1h feeds a per-graph pure_fn CLASSIFIER that fixes",
+    "the side and confirms with smart money (magpie pre-listing shape). Universe is discovered",
+    "each tick from the live board (funding / leverage / volume signature) or a fixed whitelist.",
+    "",
+    "Emits: clearinghouse_state, ttl_dedup_state, (instrument_list + classifier_predicate +",
+    "universe_discover when discovering), held_asset_exclusion, recent_signal_ttl_dedup,",
+    "candles_fetch, sm_lean, trend_structure x2, a `classify` pure_fn (THE EDGE slot — edit the",
+    "body), a ranker, signal_envelope.",
+    "",
+    "Answers that matter: universe.discover (+ dex / name_prefix / max_leverage_cap /",
+    "min_day_volume) OR universe.whitelist, intervals, max_positions, ttl_seconds, risk.*.",
+]
+
 BANNER = [
     "classifier strategy — machine-generated anchor (composer new).",
     "",

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

@@ -0,0 +1,354 @@
+"""relative_value — the pairwise cross-asset relative-value shape (design-models §11 family).
+
+The routing incident this closes: a pairwise thesis ("HYPE mean-reverts vs BTC — when BTC
+outperforms, buy HYPE") was generated as per-asset ``trend_momentum``, which scores each name
+from its OWN features only and structurally cannot reach across the asset key to compare BTC
+vs HYPE, guaranteeing the edit path. `relative_value` is that missing shape: a FIXED pair
+whose benchmark leg is pinned in the universe (never discovered, never held/dedup-narrowed —
+narrowing could prune the benchmark and silently break the comparison) and whose cross-asset
+comparison lives in ONE two-output signed-net-score pure_fn (D2 kind 2).
+
+This builder builds the PAIRWISE member first (design-models §11: `relative_value.pairwise`,
+with `cross_sectional` — long the strongest vs short the weakest of N — the designed
+follow-up member). One pure_fn produces BOTH tails from the same signed net score:
+
+  * entry_scores — LONG the target when the benchmark has out-returned it (target is
+    relatively cheap) by net >= enter_threshold AND the target is NOT already held.
+  * exit_scores  — CLOSE the target when the thesis has flipped (target now out-returns the
+    benchmark) by net <= -exit_threshold AND the target IS held.
+
+Between the two thresholds is the hysteresis DEAD BAND (emit nothing) that kills mixed-window
+thrash; held-exclusion lives INSIDE the fn via an ``open_positions`` input (entry only when
+flat, exit only when held) so complementarity is by construction.
+
+Exit topology is answer-driven (design-models §11 — orthogonal axis, relative_value defaults
+to entry+exit): 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 safety net, never front-running the thesis exit). When it is ABSENT
+the graph is ENTRY-ONLY: it still carries ``open_positions`` and the held-exclusion inside the
+fn (so the entry stream is silenced while held), the fn still computes exit_scores (unwired —
+a single-module compile), no close emitter is added, and protection stays ``protected_standard``
+per the slice-3 policy. (Documented choice: entry-only keeps positions rather than dropping
+held-exclusion — an entry that fires into an already-held pair would double the position, which
+the no-pyramiding default forbids.)
+
+Mechanically bound from the answers (D7 step 3): universe.whitelist -> the fixed [target,
+benchmark] pair (FIRST = the traded target, SECOND = the reference benchmark; the least-new-
+surface convention — no new answers field); intervals[0] -> the candle interval AND the
+per-window bar counts (days x bars-per-interval); exit_signals -> the fn's enter/exit
+thresholds and whether the exit tail is emitted. The lookback windows (3d/7d/30d) and their
+weights (1.0/2.0/3.0 — a longer window is a more durable read) are the archetype's shape.
+"""
+
+from __future__ import annotations
+
+from ..answers import Answers
+from ..builder import GraphBuilder
+from ._common import GenerationError
+
+DESCRIBE = [
+    "# relative_value  (archetype)",
+    "",
+    "Thesis shape: a CROSS-ASSET, PAIRWISE relative-value comparison — 'X always beats Y',",
+    "'buy the laggard when the benchmark runs ahead'. A FIXED pair [target, benchmark] is fetched",
+    "every tick (the benchmark leg is a REFERENCE only — never traded, never pruned); N lookback",
+    "returns (3d/7d/30d, longer = heavier weight) feed ONE two-output signed-net-score pure_fn.",
+    "The net score votes: benchmark out-returns target -> +weight (target is cheap, a BUY vote);",
+    "target out-returns benchmark -> -weight (the thesis flipped, a CLOSE vote).",
+    "",
+    "The two-scanner exit pair (when answers.exit_signals is set): the SAME pure_fn emits",
+    "entry_scores (LONG when net >= enter_threshold and the target is FLAT) and exit_scores",
+    "(CLOSE when net <= -exit_threshold and the target is HELD); between them a hysteresis DEAD",
+    "BAND emits nothing. Held-exclusion is inside the fn via an open_positions input, so the",
+    "entry and exit streams cannot both fire. The composer splits this into an entry scanner",
+    "(signal_envelope) and a reduce-only exit scanner (close_signal_envelope) and keeps a WIDE",
+    "DSL preset as the always-on safety net (the signal exit is the thesis close, not protection).",
+    "Omit exit_signals for an ENTRY-ONLY variant (single module, DSL-managed exits).",
+    "",
+    "When to use vs trend_momentum (THE ROUTING TEST): if the signal is a RELATION between two",
+    "assets ('HYPE vs BTC', 'the laggard of the pair'), it is relative_value — trend_momentum",
+    "scores each name from its OWN features and structurally cannot see the other leg (this is",
+    "the incident that motivated the family). If the signal is one asset's own trend/momentum in",
+    "isolation, it is trend_momentum.",
+    "",
+    "Members: `pairwise` (this builder — the fixed two-asset pair) is the first; `cross_sectional`",
+    "(long the strongest vs short the weakest across N names) is the designed follow-up.",
+    "",
+    "Emits: clearinghouse_state (equity for sizing — NO held-exclusion on the entry universe),",
+    "open_positions (held + direction, for in-fn held-exclusion and the exit direction stamp),",
+    "candles_fetch (the fixed pair), pct_change x3 (3d/7d/30d), a `score` pure_fn (THE EDGE slot,",
+    "TWO outputs), emit_single_best + signal_envelope (entry tail), and close_signal_envelope",
+    "(exit tail — only when exit_signals is set).",
+    "",
+    "Answers that matter: universe.whitelist = [target, benchmark] (EXACTLY two — no discover),",
+    "intervals (the candle interval + window bar counts), exit_signals.{enter_threshold,",
+    "exit_threshold, interval_seconds, reentry_cooldown_seconds} (present => the exit tail),",
+    "exit_preset (unset => protected_wide with a signal exit, protected_standard entry-only),",
+    "risk.*.",
+]
+
+BANNER = [
+    "relative_value strategy (pairwise member) — machine-generated anchor (composer new).",
+    "",
+    "A FIXED pair [target, benchmark] compared cross-asset: N lookback returns (3d/7d/30d) feed",
+    "ONE two-output signed-net-score pure_fn. The benchmark leg is a REFERENCE only — always",
+    "fetched, never traded, never pruned (narrowing could drop it and break the comparison). The",
+    "fn LONGs the target when the benchmark runs ahead (target is cheap) and CLOSEs it when the",
+    "pair flips, with a hysteresis dead band and held-exclusion built in. Edit ONLY the pure_fn",
+    "body (the EDGE slot) to move this toward your edge; every intermediate state stays valid",
+    "(`composer check`).",
+]
+
+# The archetype's shape: three lookback windows in DAYS with their vote weights (a longer
+# window is a more durable read, so it carries more weight). Fixed at three for the pairwise
+# member; the cross_sectional follow-up may vary this. Bar counts are days x bars-per-interval.
+WINDOWS: tuple[tuple[int, float], ...] = ((3, 1.0), (7, 2.0), (30, 3.0))
+
+# candle bars per day, per supported interval (Hyperliquid candle grid). Used to turn a window
+# expressed in DAYS into the pct_change `lookback` bar count for the chosen interval.
+_BARS_PER_DAY: dict[str, int] = {
+    "1m": 1440, "5m": 288, "15m": 96, "30m": 48,
+    "1h": 24, "2h": 12, "4h": 6, "8h": 3, "12h": 2, "1d": 1,
+}
+
+_DEFAULT_ENTER = 3.0
+_DEFAULT_EXIT = 2.0
+_SIGNAL_STRENGTH = 1.0
+
+# The two-output signed-net-score comparison (D2 kind 2). Generic over the bound pair/weights/
+# thresholds (all passed as params); emitted verbatim AND executed in _relative_value_tests to
+# synthesize inline fixtures that pass by construction. Deterministic, math-only (purity-checked).
+RELATIVE_VALUE_FN = '''\
+def score_relative_value(ret_3d, ret_7d, ret_30d, positions, benchmark, target, w_3d, w_7d, w_30d, enter_threshold, exit_threshold, signal_strength):
+    # TODO(edit): the PAIRWISE relative-value edge (a WORKING DEFAULT). For each lookback window
+    # compare the TARGET's return to the BENCHMARK's: the benchmark OUT-returning the target means
+    # the target is relatively cheap -> +weight (a BUY vote); the target OUT-returning the benchmark
+    # means the thesis has FLIPPED -> -weight (a CLOSE vote). The signed weighted sum is the net
+    # score. ENTER LONG the target when net >= enter_threshold AND it is NOT already held; CLOSE the
+    # target when net <= -exit_threshold AND it IS held; between the thresholds (the hysteresis dead
+    # band) emit NOTHING. Held-exclusion lives here (via positions) so entry and exit never both fire.
+    # A window missing either leg simply abstains (no vote), never raises. The benchmark is a
+    # REFERENCE leg only — never scored, never emitted. 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.
+    windows = [(ret_3d, w_3d, "3d"), (ret_7d, w_7d, "7d"), (ret_30d, w_30d, "30d")]
+    net = 0.0
+    enter_reasons = []
+    exit_reasons = []
+    for series, weight, label in windows:
+        bench_ret = series.get(benchmark)
+        target_ret = series.get(target)
+        if bench_ret is None or target_ret is None:
+            continue
+        if bench_ret > target_ret:
+            net = net + weight * signal_strength
+            enter_reasons.append("bench_outperf_" + label)
+        elif target_ret > bench_ret:
+            net = net - weight * signal_strength
+            exit_reasons.append("target_outperf_" + label)
+    held_direction = None
+    for position in positions or []:
+        if position.get("coin") == target:
+            held_direction = position.get("direction") or "LONG"
+            break
+    is_held = held_direction is not None
+    entry_scores = {}
+    exit_scores = {}
+    if net >= enter_threshold and not is_held:
+        entry_scores[target] = {"score": round(net, 4), "direction": "LONG", "reasons": enter_reasons}
+    elif net <= -exit_threshold and is_held:
+        exit_scores[target] = {"score": round(-net, 4), "direction": held_direction, "reasons": exit_reasons}
+    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 _relative_value_tests(
+    target: str, benchmark: str, weights: tuple[float, ...], enter: float, exit_threshold: float
+) -> tuple[dict, ...]:
+    """Five inline fixtures whose expected values are computed from the default body itself with
+    the BOUND pair / weights / thresholds, so they pass by construction (emitted body == executed
+    body). The five semantic cases: all-windows entry, flip exit, dead band, held-exclusion
+    suppresses entry, flat-no-exit. Held positions are the open_positions record shape."""
+    fn = _exec_fn(RELATIVE_VALUE_FN)
+    w3, w7, w30 = weights
+    held = [{
+        "coin": target, "direction": "LONG", "szi": 1.0,
+        "entry_px": 100.0, "unrealized_pnl_pct": 2.5, "margin_used": 10.0,
+    }]
+
+    def call(r3, r7, r30, positions):
+        entry, ex = fn(r3, r7, r30, positions, benchmark, target,
+                       w3, w7, w30, enter, exit_threshold, _SIGNAL_STRENGTH)
+        return {"entry_scores": entry, "exit_scores": ex}
+
+    # bench out-returns target in every window -> max +net.
+    all_bench = {benchmark: 5.0, target: 1.0}
+    # target out-returns bench in every window -> max -net.
+    all_target = {benchmark: 1.0, target: 5.0}
+
+    cases = (
+        ("all_windows_entry",
+         all_bench, all_bench, all_bench, []),
+        ("thesis_flip_exit_when_held",
+         all_target, all_target, all_target, held),
+        # +1 (3d bench) -2 (7d target) and a 30d window missing its target leg (abstains):
+        # net = -1, inside (-exit, +enter) -> the dead band emits nothing (also flat).
+        ("dead_band_emits_nothing",
+         all_bench, all_target, {benchmark: 3.0}, []),
+        # entry conditions met but the pair is already held -> held-exclusion suppresses entry.
+        ("held_exclusion_suppresses_entry",
+         all_bench, all_bench, all_bench, held),
+        # exit conditions met but the pair is FLAT -> nothing to close (no phantom exit).
+        ("flat_no_exit",
+         all_target, all_target, all_target, []),
+    )
+    return tuple(
+        {"name": name, "inputs": {"ret_3d": r3, "ret_7d": r7, "ret_30d": r30, "positions": pos},
+         "expect": call(r3, r7, r30, pos)}
+        for name, r3, r7, r30, pos in cases
+    )
+
+
+def build(answers: Answers) -> GraphBuilder:
+    b = GraphBuilder()
+    u = answers.universe
+    iv = answers.intervals[0] if answers.intervals else "4h"
+
+    # relative_value.pairwise is a FIXED-PAIR shape: no discovery (that would prune the benchmark
+    # from a live-board narrowing) and EXACTLY two assets. Reject anything else LOUDLY rather than
+    # silently emit a broken universe (mirrors trend_momentum's discover guard).
+    if u.discover:
+        raise GenerationError(
+            "archetype 'relative_value' (pairwise member) is a FIXED-PAIR shape and cannot "
+            "discover a universe from the live board — discovery could prune the benchmark leg. "
+            "Set universe.whitelist to exactly [target, benchmark]. (A discovered cross-sectional "
+            "long-strongest/short-weakest variant is the designed cross_sectional follow-up member, "
+            "not yet built.)"
+        )
+    pair = list(u.whitelist)
+    if len(pair) != 2:
+        raise GenerationError(
+            "archetype 'relative_value' (pairwise member) needs EXACTLY two assets in "
+            f"universe.whitelist as [target, benchmark]; got {pair}. The FIRST is the traded "
+            "target, the SECOND is the reference benchmark (never traded)."
+        )
+    target, benchmark = pair[0], pair[1]
+
+    bars = _BARS_PER_DAY.get(iv)
+    if bars is None:
+        raise GenerationError(
+            f"archetype 'relative_value' cannot map interval {iv!r} to a bars-per-day count "
+            f"(supported: {sorted(_BARS_PER_DAY)}). Choose a standard candle interval so the "
+            f"lookback windows (3d/7d/30d) resolve to bar counts."
+        )
+
+    es = answers.exit_signals
+    enter_threshold = es.enter_threshold if es is not None else _DEFAULT_ENTER
+    exit_threshold = es.exit_threshold if es is not None else _DEFAULT_EXIT
+
+    # --- sources ---
+    b.add("account", "clearinghouse_state",
+          header=("sources: account equity for sizing. NO held-exclusion on the entry universe —",
+                  "the fixed pair must ALWAYS include the benchmark leg (never prune it).",))
+    b.add("positions", "open_positions",
+          header=("open positions (held + direction): held-exclusion INSIDE the pure_fn and the",
+                  "exit tail's REAL held-direction stamp. Kept even in the entry-only variant.",))
+
+    # --- candles over the FIXED pair (both legs every tick, never narrowed) ---
+    b.add("candles", "candles_fetch",
+          {"whitelist": [target, benchmark], "intervals": [iv]},
+          header=("candle reads over the FIXED pair [target, benchmark] — no discovery, no",
+                  "held/dedup narrowing (narrowing could prune the benchmark and break the compare).",))
+
+    # --- N lookback returns (days -> bars at the chosen interval), each a per-asset feature_map ---
+    window_ids: list[str] = []
+    for i, (days, _weight) in enumerate(WINDOWS):
+        wid = f"ret_{days}d"
+        b.add(wid, "pct_change", {"lookback": days * bars, "interval": iv},
+              header=(f"lookback returns at {iv} ({days}d = {days * bars} x {iv}).",) if i == 0 else ())
+        window_ids.append(wid)
+
+    # --- the two-output signed-net-score comparison (THE EDGE slot; D2 kind 2) ---
+    weights = tuple(w for _d, w in WINDOWS)
+    b.add_pure_fn(
+        "score",
+        inputs=tuple(
+            {"name": wid, "type": "feature_map",
+             "doc": f"Per-asset {days}d ({days * bars} x {iv}) percent return."}
+            for wid, (days, _w) in zip(window_ids, WINDOWS)
+        ) + (
+            {"name": "positions", "type": "record_list",
+             "doc": "Open positions (from open_positions) — held-exclusion + exit direction."},
+        ),
+        outputs=(
+            {"name": "entry_scores", "type": "score_map",
+             "doc": "LONG the target when net >= enter_threshold and the target is FLAT."},
+            {"name": "exit_scores", "type": "score_map",
+             "doc": "CLOSE the target when net <= -exit_threshold and the target is HELD."},
+        ),
+        params=(
+            {"name": "benchmark", "type": "str", "default": benchmark,
+             "doc": "Reference leg (never traded); fetched only to compare against the target."},
+            {"name": "target", "type": "str", "default": target,
+             "doc": "The only tradeable name (bought when it lags the benchmark)."},
+            {"name": "w_3d", "type": "float", "default": weights[0], "doc": "Weight of the 3d window."},
+            {"name": "w_7d", "type": "float", "default": weights[1],
+             "doc": "Weight of the 7d window (longer = stronger)."},
+            {"name": "w_30d", "type": "float", "default": weights[2],
+             "doc": "Weight of the 30d window (longest = strongest)."},
+            {"name": "enter_threshold", "type": "float", "default": enter_threshold,
+             "doc": "Net score to ENTER LONG (top of the hysteresis dead band)."},
+            {"name": "exit_threshold", "type": "float", "default": exit_threshold,
+             "doc": "Net score (as -exit_threshold) to CLOSE (bottom of the dead band)."},
+            {"name": "signal_strength", "type": "float", "default": _SIGNAL_STRENGTH,
+             "doc": "Per-window vote unit multiplier."},
+        ),
+        fn=RELATIVE_VALUE_FN,
+        tests=_relative_value_tests(target, benchmark, weights, enter_threshold, exit_threshold),
+        header=("pure_fn signed-net-score comparison — THE EDGE SLOT (edit the body; see the EDGE",
+                "block above). TWO outputs: entry_scores (entry tail) + exit_scores (exit tail).",),
+    )
+    b.set_edge_anchor("score")
+
+    # --- entry tail: single-best (only the target is ever scored) -> signal_envelope ---
+    b.add("best", "emit_single_best", {"min_score": 0},
+          header=("entry tail: the target is the only scored name, so single-best emits it.",))
+    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 (signal) 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 ---
+    # candles over the FIXED pair fan out to the lookback returns
+    for i, wid in enumerate(window_ids):
+        b.connect("candles", "candles", wid, "candles",
+                  section="candles over the fixed pair fan out to the lookback returns" if i == 0 else None)
+    # each return + the positions record wire into ONE declared pure_fn input (single writer)
+    for i, wid in enumerate(window_ids):
+        b.connect(wid, "pct", "score", wid,
+                  section="each lookback return -> its pure_fn input port" if i == 0 else None)
+    b.connect("positions", "positions", "score", "positions")
+    # entry tail: entry_scores -> single-best -> emit (+ equity for sizing)
+    b.connect("score", "entry_scores", "best", "scores", section="entry tail: entry_scores -> rank -> emit")
+    b.connect("best", "selected", "emit", "selected")
+    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

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

@@ -15,6 +15,23 @@ from ..answers import Answers
 from ..builder import GraphBuilder
 from . import _common
 
+DESCRIBE = [
+    "# thesis_fund  (archetype)",
+    "",
+    "Thesis shape: a FIXED long/short basket — each name's direction is fixed by its leg",
+    "(long -> LONG, short -> SHORT) — and a pure_fn scores how strongly the tape CONFIRMS that",
+    "side (dropping a name whose 4h structure opposes its leg). Confirming names are ranked and",
+    "the top (max_positions - held) fill the open slots.",
+    "",
+    "Emits: clearinghouse_state, ttl_dedup_state, instrument_list, held_asset_exclusion,",
+    "recent_signal_ttl_dedup, live_instrument_validation, candles_fetch, own_return_24h,",
+    "trend_structure x2, rsi, a `score` pure_fn (THE EDGE slot), rank_pool_cap_to_open_slots,",
+    "signal_envelope.",
+    "",
+    "Answers that matter: universe.long_basket / universe.short_basket (the two legs),",
+    "intervals, max_positions (the pool cap), ttl_seconds, risk.*.",
+]
+
 BANNER = [
     "thesis_fund strategy — machine-generated anchor (composer new).",
     "",

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

@@ -14,6 +14,22 @@ from ..answers import Answers
 from ..builder import GraphBuilder
 from . import _common
 
+DESCRIBE = [
+    "# trend_momentum  (archetype)",
+    "",
+    "Thesis shape: a FIXED universe scanned each tick; candles fan out to trend / momentum /",
+    "volume / acceleration indicators whose per-asset features merge into a hard-gates +",
+    "weighted-sum scorer, then single-best (or pool-cap) emission with TTL signal-dedup.",
+    "",
+    "Emits: clearinghouse_state, ttl_dedup_state, held_asset_exclusion, recent_signal_ttl_dedup,",
+    "candles_fetch, sm_lean, sma, recent_high_bars_ago, pct_change, volume_surge_ratio,",
+    "acceleration, hard_gates_all (THE EDGE slot), a ranker, signal_envelope.",
+    "",
+    "Answers that matter: universe.whitelist (REQUIRED — fixed-universe only; discover is",
+    "rejected), intervals, max_positions, ttl_seconds, risk.*, and scoring / indicators to",
+    "retune the scorer's hard-gate vs weighted split.",
+]
+
 BANNER = [
     "trend_momentum strategy — machine-generated anchor (composer new).",
     "",

package/dist/composer/authoring/generate.py

@@ -52,13 +52,20 @@ class NewResult:
 
 
 def _bind_protection_default(answers: Answers) -> Answers:
-    """PROTECTION BY DEFAULT (slice 9 policy): `composer new` BINDS ``protected_standard`` when
-    the author left ``exit_preset`` unset and did not opt out via ``unmanaged``. Overriding
-    (a chosen preset) or opting out (``unmanaged=true``) are both honoured untouched. Returns a
-    (possibly) updated copy so the emitted graph metadata carries the bound value."""
+    """PROTECTION BY DEFAULT (slice 9 policy) + the exit-composition unset-vs-explicit refinement:
+    `composer new` RESOLVES an unset ``exit_preset`` at build time and binds it into the graph
+    metadata. Resolution when the author left ``exit_preset`` unset and did not opt out:
+
+      * no exit_signals  -> ``protected_standard`` (today's default — BYTE-IDENTICAL to before).
+      * exit_signals set -> ``protected_wide`` (the DSL demotes to a WIDE safety net so it never
+        front-runs the thesis exit; the signal exit is primary, the DSL is the net).
+
+    Overriding (an explicit chosen preset) or opting out (``unmanaged=true``) are both honoured
+    untouched — an explicit value ALWAYS wins. Returns a (possibly) updated copy."""
     from .presets import DEFAULT_PRESET
     if not answers.unmanaged and answers.exit_preset is None:
-        return answers.model_copy(update={"exit_preset": DEFAULT_PRESET})
+        resolved = "protected_wide" if answers.exit_signals is not None else DEFAULT_PRESET
+        return answers.model_copy(update={"exit_preset": resolved})
     return answers
 
 

package/dist/composer/authoring/presets.py

@@ -146,6 +146,9 @@ RISK_OVERRIDE_KEYS = {
     "max_consecutive_losses": "max_consecutive_losses",
     "cooldown_seconds": "cooldown_seconds",
     "max_entries_per_day": "max_entries_per_day",
+    # post-close per-asset re-entry cooldown (schema floor 300). An explicit answers override wins;
+    # a signal-exit pair otherwise supplies exit_signals.reentry_cooldown_seconds (runtime_emit).
+    "per_asset_cooldown_seconds": "per_asset_cooldown_seconds",
 }