@senpi/runtime 3.0.9-dev.feat-strategy-compos.20260718011320 → 3.0.9-dev.feat-strategy-compos.20260719221425

package/dist/composer/authoring/__init__.py

@@ -20,6 +20,7 @@ from .answers import (
     Answers,
     ExitSignals,
     Indicator,
+    Protection,
     Risk,
     Scoring,
     Universe,
@@ -38,6 +39,7 @@ __all__ = [
     "Answers",
     "ExitSignals",
     "Indicator",
+    "Protection",
     "Risk",
     "Scoring",
     "Universe",

package/dist/composer/authoring/answers.py

@@ -90,6 +90,31 @@ class ExitSignals(BaseModel):
     min_divergence: float = 0.0   # per-window vote noise gate (0.0 = no-op); relative_value only
 
 
+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
+    at EMIT time, invisible in the graph and un-editable (a hand-edit of the emitted runtime.yaml
+    breaks the content-addressed install hash). Now ``composer new`` RESOLVES the seeding preset's
+    ``dsl_preset`` (time-cuts + phase1 floor + the phase2 tier ladder) and the risk-overridden
+    ``guard_rails`` into ``metadata.spec.protection``, so every tunable exit knob lives in the graph
+    and survives regeneration. Edit it there, then ``composer check`` (which re-validates the
+    ladder through the LIVE Zod+DSL oracle over the emitted runtime.yaml) + ``deploy``.
+
+    ``seeded_from`` is PROVENANCE only — the preset name that seeded these values at generation
+    (an edit does not change it; it never re-resolves from the preset). ``dsl_preset`` and
+    ``guard_rails`` are kept as plain dicts, NOT re-typed here: the single authority on ladder
+    validity is the live oracle over the emitted runtime.yaml (a re-typed twin would drift from the
+    real Zod schema). A structurally-malformed hand-edit is caught pure-Python (CMP124) before emit;
+    a value-level one (tier order, ranges, breaches) is caught by the oracle (CMP110)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    seeded_from: str
+    interval_seconds: int = 60
+    dsl_preset: dict = Field(default_factory=dict)
+    guard_rails: dict = Field(default_factory=dict)
+
+
 class Universe(BaseModel):
     """How the tradeable set is chosen. A superset of the corpus shapes; each archetype
     reads the fields it needs (D4 — the answer stays declarative, the template binds it):
@@ -196,6 +221,14 @@ class Answers(BaseModel):
     unmanaged: bool = False         # explicit opt-out: no exit section (else CMP120 RED at check)
     risk: Risk = Field(default_factory=Risk)
     edge: str = ""                  # the user's EDGE, verbatim; the machine never interprets it
+    # F1 — the MATERIALIZED protection spec + a free-prose thesis, both carried in metadata.spec.
+    # ``protection`` is None on directly-constructed answers (byte-identical to before) and is set by
+    # `composer new` (generate._materialize_protection) so the resolved exit ladder lives IN the graph
+    # and survives regeneration + edit. ``thesis`` is an optional one-line intent summary generation
+    # derives from the edge (never blocking). Both emit into metadata.spec ONLY when set (round-trip
+    # discipline: an answers object without them round-trips byte-identically).
+    protection: Optional[Protection] = None
+    thesis: str = ""
     requires: tuple[RequiredCapability, ...] = ()
     # F1 — OPTIONAL expressiveness surface. Absent (the defaults below) => byte-identical to
     # the pre-F1 output; present => the archetype re-selects gates/weights (scoring) and adds
@@ -243,6 +276,9 @@ class Answers(BaseModel):
         block: dict = {
             "archetype": self.archetype,
             "strategy": self.strategy,
+            # F1: a one-line intent thesis, emitted ONLY when generation derived one (round-trip
+            # discipline — an answers object with thesis="" carries no key and round-trips as before).
+            **({"thesis": self.thesis} if self.thesis else {}),
             "universe": {
                 "whitelist": list(self.universe.whitelist),
                 "long_basket": list(self.universe.long_basket),
@@ -256,8 +292,25 @@ class Answers(BaseModel):
             "intervals": list(self.intervals),
             "max_positions": self.max_positions,
             "ttl_seconds": self.ttl_seconds,
-            "exit_preset": self.exit_preset,   # LIVE: the emitted runtime.yaml exit preset
+            "exit_preset": self.exit_preset,   # LIVE: the emitted runtime.yaml exit preset (SEED)
             "unmanaged": self.unmanaged,        # explicit protection opt-out
+            # F1: the MATERIALIZED protection block — the resolved exit ladder + guard rails carried
+            # IN the graph so they are visible + editable + survive regeneration. Emitted ONLY when
+            # set (a directly-constructed answers has protection=None and round-trips byte-identically;
+            # `composer new` materializes it — generate._materialize_protection). runtime_emit reads
+            # this when present; the preset is only the SEED at generation time.
+            **(
+                {
+                    "protection": {
+                        "seeded_from": self.protection.seeded_from,
+                        "interval_seconds": self.protection.interval_seconds,
+                        "dsl_preset": self.protection.dsl_preset,
+                        "guard_rails": self.protection.guard_rails,
+                    }
+                }
+                if self.protection is not None
+                else {}
+            ),
             "risk": {
                 "margin_pct": self.risk.margin_pct,
                 "leverage": self.risk.leverage,

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

@@ -89,6 +89,7 @@ def build(answers: Answers) -> GraphBuilder:
         fn=_common.CLASSIFIER_FN,
         tests=_common.classifier_tests(_MIN_SCORE),
         header=("pure_fn classifier — THE EDGE SLOT (edit the body; see the EDGE block above).",),
+        title="direction classifier from 4h/1h trend + smart-money lean",
     )
     b.set_edge_anchor("classify")
 

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

@@ -337,6 +337,7 @@ def build(answers: Answers) -> GraphBuilder:
                                     min_divergence),
         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).",),
+        title="signed net-score: target vs benchmark across lookbacks",
     )
     b.set_edge_anchor("score")
 

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

@@ -84,6 +84,7 @@ def build(answers: Answers) -> GraphBuilder:
         fn=_common.THESIS_FN,
         tests=_common.thesis_tests(list(u.long_basket), list(u.short_basket), _MIN_SCORE),
         header=("pure_fn confirmation scorer — THE EDGE SLOT (edit the body; see the EDGE block above).",),
+        title="per-leg thesis confirmation score",
     )
     b.set_edge_anchor("score")
 

package/dist/composer/authoring/builder.py

@@ -41,6 +41,7 @@ class BuiltNode:
     pure_params: tuple[dict, ...] = ()
     fn: Optional[str] = None
     tests: tuple[dict, ...] = ()
+    title: Optional[str] = None           # pure_fn OPTIONAL one-line title (one semantic unit)
     # presentation
     header: tuple[str, ...] = ()          # comment lines emitted above the node
     param_comments: dict = field(default_factory=dict)   # param -> trailing comment
@@ -117,9 +118,13 @@ class GraphBuilder:
         fn: str,
         tests: tuple[dict, ...] = (),
         header: tuple[str, ...] = (),
+        title: Optional[str] = None,
     ) -> "GraphBuilder":
         """Add a per-graph pure_fn node (D2 kind 2). Its declared ports must use the closed
-        PortType vocabulary — a bad type is a ``ValueError`` (CI catches template drift)."""
+        PortType vocabulary — a bad type is a ``ValueError`` (CI catches template drift).
+
+        ``title`` is the OPTIONAL one-line "one titled semantic unit" label. Generation SHOULD
+        pass it for every pure_fn it emits (a missing title is a non-blocking check annotation)."""
         for side, ports in (("input", inputs), ("output", outputs)):
             for p in ports:
                 try:
@@ -139,6 +144,7 @@ class GraphBuilder:
                 fn=fn,
                 tests=tuple(tests),
                 header=tuple(header),
+                title=title,
             )
         )
         return self

package/dist/composer/authoring/emit.py

@@ -158,6 +158,10 @@ def _emit_node(bn: BuiltNode) -> list[str]:
 
     if bn.kind == "pure_fn":
         lines.append("    kind: pure_fn")
+        if bn.title:
+            # OPTIONAL one-line title (one titled semantic unit); emitted only when set so
+            # title-less pure_fns round-trip byte-identically.
+            lines.append(f"    title: {_dq(bn.title)}")
         lines.append("    inputs:")
         for p in bn.inputs:
             lines.append(f"      - {_inline_port(p)}")
@@ -199,13 +203,15 @@ def render(builder: GraphBuilder, answers: Answers, banner: list[str]) -> str:
     lines.append("version: 1")
     lines.append("")
 
-    # --- metadata (D7: the spec file IS the state — answers live here) ---
+    # --- metadata (D7: the spec file IS the state — the interview spec lives under `spec`; F1
+    # renamed the block `answers` -> `spec` since it now carries the MATERIALIZED protection too.
+    # The loader still reads a legacy `answers` block for back-compat) ---
     lines.append("metadata:")
     meta = {
         "archetype": answers.archetype,
         "strategy": answers.strategy,
         "generated": {"by": "composer new", "content_hash": _HASH_PLACEHOLDER},
-        "answers": answers.metadata_block(),
+        "spec": answers.metadata_block(),
     }
     for k, v in meta.items():
         lines.extend(_emit_kv(k, v, 2))

package/dist/composer/authoring/generate.py

@@ -21,7 +21,7 @@ from pathlib import Path
 from typing import Optional
 
 from . import emit
-from .answers import Answers, defaulted_interview_fields
+from .answers import Answers, Protection, defaulted_interview_fields
 from .archetypes import ARCHETYPES, SKELETON
 from .gaps import GapReport, detect_gaps
 
@@ -73,6 +73,50 @@ def _bind_protection_default(answers: Answers) -> Answers:
     return answers
 
 
+def _materialize_protection(answers: Answers) -> Answers:
+    """F1 — MATERIALIZE the resolved protection into the graph spec (the graph IS the spec).
+
+    Before F1 the exit ladder was resolved from a named preset only at EMIT time — invisible in the
+    graph, un-editable (a hand-edit of the emitted runtime.yaml breaks the content-addressed install
+    hash). Now generation writes the FULL resolved block into ``metadata.spec.protection``: the
+    seeding preset's ``dsl_preset`` (deep-copied so a later graph edit never mutates the shared
+    preset) and the guard_rails resolved through the SAME helper the emit path uses (byte-identity),
+    with ``seeded_from`` recording the provenance preset. Only a PROTECTED unit materializes — an
+    unmanaged opt-out has no exit block, and an explicit ``protection`` (a re-generation over an
+    already-materialized answers) is left untouched. Returns a (possibly) updated copy."""
+    import copy
+
+    from .presets import EXIT_PRESETS
+    from .runtime_emit import resolve_emit_guard_rails
+
+    if answers.unmanaged or answers.exit_preset is None or answers.protection is not None:
+        return answers
+    preset = EXIT_PRESETS[answers.exit_preset]
+    protection = Protection(
+        seeded_from=preset.name,
+        interval_seconds=preset.interval_seconds,
+        dsl_preset=copy.deepcopy(preset.dsl_preset),
+        guard_rails=resolve_emit_guard_rails(answers, preset),
+    )
+    return answers.model_copy(update={"protection": protection})
+
+
+def _derive_thesis(answers: Answers) -> Answers:
+    """F1 — write a short, deterministic intent thesis into the graph spec when none was supplied.
+
+    Derived from the interview intent (the verbatim edge, normalized to one line and capped); when
+    there is no edge, a generic archetype descriptor. Purely descriptive graph metadata — it never
+    reaches the runtime.yaml and never blocks generation. An explicit thesis is left untouched."""
+    if answers.thesis:
+        return answers
+    edge = " ".join((answers.edge or "").split()).strip()
+    if edge:
+        thesis = edge if len(edge) <= 200 else edge[:197].rstrip() + "..."
+    else:
+        thesis = f"A {answers.archetype} strategy ({answers.strategy})."
+    return answers.model_copy(update={"thesis": thesis})
+
+
 def _fmt_default_value(value) -> str:
     """Render a baked default value for the DEFAULTED echo: ``None`` (a preset-default knob like
     drawdown_halt_pct) reads as ``none`` so the reader sees it was never offered."""
@@ -107,6 +151,8 @@ def _defaulted_message(lines: list[str]) -> str:
 def render_graph(answers: Answers) -> tuple[str, bool]:
     """Build + render the graph for these answers; returns (yaml_text, used_skeleton)."""
     answers = _bind_protection_default(answers)
+    answers = _materialize_protection(answers)   # F1: resolved protection INTO the graph spec
+    answers = _derive_thesis(answers)            # F1: a one-line intent thesis in the graph spec
     module = ARCHETYPES.get(answers.archetype)
     used_skeleton = module is None
     if used_skeleton:

package/dist/composer/authoring/runtime_emit.py

@@ -6,12 +6,14 @@ The composer no longer stages a bare scanner (entry-less, exit-less — the inco
 (NOT nodes in the DAG — they are consumed by the DslPlugin / ActionRegistry at runtime boot,
 a different lifecycle than the ``nodes``/``edges`` compiled into ``scan.py``; design §6).
 
-Everything derives from the graph's ``metadata.answers`` (the single source of truth both
-artifacts share, D7), so recompiling regenerates ``scan.py`` AND ``runtime.yaml``
-byte-identically. LIVE bindings: strategy sizing, the scanner cadence, the exit preset
-SELECTION and its phase1 / time-cut scalars, the guard_rails. TODO(edit) slots (working
-default in place, still valid): ``exit.dsl_preset.phase1.max_loss_pct`` and each
-``exit.dsl_preset.phase2.tiers`` entry (the ratchet is the most thesis-specific knob).
+Everything derives from the graph's ``metadata.spec`` (the single source of truth both
+artifacts share, D7; the legacy ``metadata.answers`` key is still read for back-compat), so
+recompiling regenerates ``scan.py`` AND ``runtime.yaml`` byte-identically. The exit ``dsl_preset``
+(time-cuts + phase1 floor + the phase2 tier ladder) and ``risk.guard_rails`` are rendered from
+``spec.protection`` when the graph carries it (F1 — the graph IS the spec; the emitted file is
+INSPECT-ONLY build output). An older graph with no materialized ``spec.protection`` falls back to
+resolving them live from the named preset (byte-identical). To tune protection, edit
+``spec.protection`` in the GRAPH, then ``composer check`` + ``deploy`` — never hand-edit this file.
 
 ``unmanaged=True`` emits NO ``exit`` section plus a loud warning banner — the deliberate,
 explicit opt-out of protection (a graph that reaches here with ``unmanaged=False`` and no
@@ -42,6 +44,28 @@ _UNMANAGED_BANNER = [
 ]
 
 
+def resolve_emit_guard_rails(answers: Answers, preset) -> dict:
+    """The guard_rails dict the runtime.yaml ``risk:`` section renders — the preset's guard_rails
+    with the answers ``risk.*`` overrides layered on, plus the signal-exit-derived per-asset cooldown
+    (an explicit risk override always wins; else a signal-exit pair supplies its reentry cooldown;
+    else absent). Extracted so BOTH generation (materialize into ``spec.protection.guard_rails``) and
+    the emit-time fallback (an older graph with no materialized protection) compute the SAME dict —
+    the guarantee that a freshly-materialized graph emits a BYTE-IDENTICAL runtime.yaml."""
+    per_asset_cooldown = answers.risk.per_asset_cooldown_seconds
+    if per_asset_cooldown is None and answers.exit_signals is not None:
+        per_asset_cooldown = answers.exit_signals.reentry_cooldown_seconds
+    return resolve_guard_rails(
+        preset,
+        {
+            "drawdown_halt_pct": answers.risk.drawdown_halt_pct,
+            "max_consecutive_losses": answers.risk.max_consecutive_losses,
+            "cooldown_seconds": answers.risk.cooldown_seconds,
+            "max_entries_per_day": answers.risk.max_entries_per_day,
+            "per_asset_cooldown_seconds": per_asset_cooldown,
+        },
+    )
+
+
 def _env_wallet(strategy: str) -> str:
     slug = re.sub(r"[^0-9a-zA-Z]+", "_", strategy).strip("_").upper() or "STRATEGY"
     return "${" + f"{slug}_WALLET" + "}"
@@ -121,12 +145,15 @@ def render_runtime_yaml(answers: Answers) -> str:
             lines.append(f"# {b}")
     elif has_exit:
         preset = EXIT_PRESETS[answers.exit_preset]
+        seeded = answers.protection.seeded_from if answers.protection is not None else answers.exit_preset
         lines.append(f"# {strategy} — complete standalone strategy runtime (composer deploy).")
         lines.append("#")
-        lines.append("# PROTECTED BY DEFAULT: the exit: section below is the resolved preset")
-        lines.append(f"# '{answers.exit_preset}' — {preset.intent}")
+        lines.append("# PROTECTED BY DEFAULT: the exit: / risk: sections below are BUILD OUTPUT, rendered")
+        lines.append(f"# from the graph's metadata.spec.protection (seeded from preset '{seeded}').")
         lines.append("# A standalone runtime in its own funded wallet; ops mints the wallet + installs")
-        lines.append("# (one wallet per instance). Edit ONLY the TODO(edit) slots to tune the exit.")
+        lines.append("# (one wallet per instance). This file is INSPECT-ONLY: to tune protection, edit")
+        lines.append("# spec.protection in the graph, then re-run composer check + deploy + update. Do")
+        lines.append("# NOT hand-edit this file — a content-addressed install verifies its hash.")
     else:
         # exit_preset unset AND not opted out — the CMP120 contradiction (check flags it RED).
         lines.append(f"# {strategy} — runtime with NO exit preset set and NO unmanaged opt-out.")
@@ -215,14 +242,23 @@ def render_runtime_yaml(answers: Answers) -> str:
         lines.append(f"        execution_timeout_seconds: {_ENTRY_EXECUTION_TIMEOUT}")
     lines.append("")
 
-    # --- exit: the resolved DSL preset (LIVE scalars; tiers + max_loss are TODO slots) ---
+    # --- exit: the resolved DSL protection (materialized from metadata.spec.protection when present;
+    # else seeded live from the named preset — an older graph with no materialized block). The values
+    # are BUILD OUTPUT; the editable source is spec.protection in the graph, not this file. ---
     if has_exit:
         preset = EXIT_PRESETS[answers.exit_preset]
-        dp = preset.dsl_preset
-        lines.append(f"# EXIT — DSL preset '{preset.name}': {preset.intent}")
+        if answers.protection is not None:
+            dp = answers.protection.dsl_preset
+            exit_interval = answers.protection.interval_seconds
+            seeded_from = answers.protection.seeded_from
+        else:
+            dp = preset.dsl_preset
+            exit_interval = preset.interval_seconds
+            seeded_from = preset.name
+        lines.append(f"# EXIT — from spec.protection (seeded '{seeded_from}': {preset.intent})")
         lines.append("exit:")
         lines.append("  engine: dsl")
-        lines.append(f"  interval_seconds: {preset.interval_seconds}")
+        lines.append(f"  interval_seconds: {exit_interval}")
         lines.append("  order_type: FEE_OPTIMIZED_LIMIT")
         lines.append("  fee_optimized_limit_options:")
         lines.append("    ensure_execution_as_taker: true")   # exit closes MUST happen
@@ -240,17 +276,16 @@ def render_runtime_yaml(answers: Answers) -> str:
         lines.append(f"      enabled: {_num(p1['enabled'])}")
         lines.append(
             f"      max_loss_pct: {_num(p1['max_loss_pct'])}"
-            "   # TODO(edit): phase-1 hard-floor loss cap (%). Preset default; tighten/loosen for your edge."
+            "   # from spec.protection.dsl_preset.phase1.max_loss_pct (edit in the graph, not here)."
         )
         lines.append(f"      retrace_threshold: {_num(p1['retrace_threshold'])}")
         lines.append(f"      consecutive_breaches_required: {_num(p1['consecutive_breaches_required'])}")
         p2 = dp["phase2"]
         lines.append("    phase2:")
         lines.append(f"      enabled: {_num(p2['enabled'])}")
-        lines.append("      tiers:                                # TODO(edit): the phase-2 ratchet — trigger_pct -> lock_hw_pct.")
-        for i, tier in enumerate(p2["tiers"]):
-            note = "  # TODO(edit): tier — lock-in floor at this ROE" if i == 0 else ""
-            lines.append(f"        - {_tier_inline(tier)}{note}")
+        lines.append("      tiers:                                # from spec.protection.dsl_preset.phase2.tiers (edit in the graph).")
+        for tier in p2["tiers"]:
+            lines.append(f"        - {_tier_inline(tier)}")
         lines.append("")
 
     # --- risk.guard_rails: the automated pause / circuit breaker (design §4) ---
@@ -260,19 +295,16 @@ def render_runtime_yaml(answers: Answers) -> str:
     # signal-exit pair supplies exit_signals.reentry_cooldown_seconds. None (exit-less, no override)
     # => absent from guard_rails => byte-identical to today. resolve_guard_rails only adds a key
     # whose value is not None, so the emit loop below stays silent for the exit-less case.
-    per_asset_cooldown = answers.risk.per_asset_cooldown_seconds
-    if per_asset_cooldown is None and answers.exit_signals is not None:
-        per_asset_cooldown = answers.exit_signals.reentry_cooldown_seconds
-    guard_rails = resolve_guard_rails(
-        EXIT_PRESETS[answers.exit_preset or DEFAULT_PRESET],
-        {
-            "drawdown_halt_pct": answers.risk.drawdown_halt_pct,
-            "max_consecutive_losses": answers.risk.max_consecutive_losses,
-            "cooldown_seconds": answers.risk.cooldown_seconds,
-            "max_entries_per_day": answers.risk.max_entries_per_day,
-            "per_asset_cooldown_seconds": per_asset_cooldown,
-        },
-    )
+    # A materialized protection block carries the ALREADY-resolved guard_rails (generation ran the
+    # SAME resolve_emit_guard_rails, so this is byte-identical); an older graph with no materialized
+    # block falls back to resolving live from the seeding preset. unmanaged (has_exit False, never
+    # materialized) always falls back — the drawdown circuit breaker ships from the default preset.
+    if answers.protection is not None and has_exit:
+        guard_rails = answers.protection.guard_rails
+    else:
+        guard_rails = resolve_emit_guard_rails(
+            answers, EXIT_PRESETS[answers.exit_preset or DEFAULT_PRESET]
+        )
     lines.append("# RISK guard rails — the automated pause / circuit breaker (composer owns policy; ops owns manual stop).")
     lines.append("risk:")
     lines.append(f"  data_retention_seconds: {_DATA_RETENTION_SECONDS}")
@@ -298,13 +330,17 @@ def answers_from_metadata(metadata: dict) -> Answers:
     from). Used by ``check``/``deploy`` to emit runtime.yaml from the graph.
 
     Two shapes are accepted:
-      * ``composer new`` output carries a full ``metadata.answers`` block -> construct from it.
+      * ``composer new`` output carries a full ``metadata.spec`` block -> construct from it.
+        BACK-COMPAT: an older graph carries the same block under the legacy key ``metadata.answers``
+        (the writer now always emits ``spec``); it is read identically when ``spec`` is absent.
       * A hand-authored example carries only top-level ``metadata`` keys (archetype, strategy,
         and optionally ``exit_preset`` / ``unmanaged``) -> construct a minimal Answers, letting
         the exit_preset default to protected_standard (PROTECTION BY DEFAULT).
     """
     metadata = metadata or {}
-    block = metadata.get("answers")
+    block = metadata.get("spec")
+    if not (isinstance(block, dict) and block):
+        block = metadata.get("answers")   # BACK-COMPAT: legacy `answers` key on older graphs
     if isinstance(block, dict) and block:
         return Answers(**block)
     kwargs: dict = {

package/dist/composer/generated/catalog.md

@@ -4,9 +4,11 @@ Schema version: 1. Generated from composer/registry/nodes.py — do not edit by
 
 Progressive-disclosure index (D4): node names, one-liners, param summaries. `composer describe <node>` gives full ports/params/examples.
 
-## scoring
+## compute
 
-Bespoke scoring/classification is a `kind: pure_fn` node (typed ports, one `def`, math/statistics only, inline tests), never a primitive; `hard_gates_all` covers simple gate-and-weigh. Repeated shapes promote post-MVP. Run `composer describe pure_fn` for the authoring contract.
+Compute is yours to write: a `kind: pure_fn` node — typed inputs in, ONE titled semantic unit out, inline tests. That is the first-class way to express any indicator / score / classification / normalization math (`hard_gates_all` covers simple gate-and-weigh). Wire sources, stateful nodes, and emitters from the catalog below. Run `composer describe pure_fn` for the authoring contract + reference formulas.
+
+A curated library of common indicator formulas (sma, rsi, pct_change, trend_structure, …) also exists: add one BY NAME under an answers `indicators:` entry when a formula fits EXACTLY. Run `composer describe indicators` to list them (`composer describe <name>` for one) — prefer a `pure_fn` unless a curated formula fits exactly.
 
 ## source
 
@@ -62,28 +64,6 @@ Bespoke scoring/classification is a `kind: pure_fn` node (typed ports, one `def`
 - **universe_discover** — Derive a tradeable universe by filtering live instruments on a predicate.
   - params: min_day_volume (float=0.0, 0.0..); max_leverage_cap (float=5.0, 1.0..); name_prefix (str='')
 
-## indicator
-
-- **acceleration** — Whether a short-window move is at least half a long-window move.
-  - params: short_window (int=3, 1..); long_window (int=6, 2..); interval (str='4h')
-- **aggregate_bias** — Cross-trader net/gross cohort bias per coin.
-- **breakout_detect** — Directional breakout of the prior-window high/low.
-  - params: window (int=168, 2..); interval (str='1h')
-- **pct_change** — Percent change of close over a lookback window.
-  - params: lookback (int=42, 1..); interval (str='4h')
-- **recent_high_bars_ago** — Bars elapsed since the highest high in a window (fresh-high check).
-  - params: window (int=60, 2..); interval (str='4h')
-- **rsi** — Relative Strength Index over the last N bars.
-  - params: period (int=14, 2..100); interval (str='1h')
-- **sma** — Simple moving average of close and an above/below flag.
-  - params: period (int=200, 1..1000); interval (str='4h')
-- **threshold_gate** — Compare a per-asset feature against a threshold, emitting a 1.0/0.0 gate.
-  - params: op (str='lt'); value (float=0.0)
-- **trend_structure** — Higher-lows / lower-highs trend direction over a lookback.
-  - params: lookback (int=6, 2..); interval (str='4h')
-- **volume_surge_ratio** — Recent-window mean volume divided by a baseline-window mean.
-  - params: recent_window (int=6, 1..); baseline_window (int=42, 1..); interval (str='4h')
-
 ## filter
 
 - **classifier_predicate** — Gate universe membership on a set of instrument-field predicates.

package/dist/composer/generated/describe.md

@@ -701,6 +701,8 @@ with:
   long_window: 6
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## aggregate_bias  (indicator)
 
 The ONE sanctioned promote-loop primitive (fn->primitive): the cross-trader net/gross bias per coin, shared near-verbatim by whalehunter and the chimp/gibbon/gorilla/orangutan cohort packages. Takes a record_list of TraderState records (from trader_states_fetch — each row's openPositions[] carrying coin, szi, positionValue/entry_px) and sums each coin's SIGNED notional across every trader, emitting a per-coin feature_map: {net, gross, bias, n_long, n_short, direction} where bias = net/gross in [-1,+1] (+1 all long, -1 all short) and direction = LONG|SHORT|NEUTRAL from the sign of net. A feature_map (the indicator output contract) rather than a scorer's score_map, so kind=indicator; its non-candle record_list input mirrors threshold_gate's non-candle feature_map input.
@@ -723,6 +725,8 @@ Example:
 node: aggregate_bias
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## breakout_detect  (indicator)
 
 hawk's breakout: LONG if the latest close breaks the prior-`window` high, SHORT if it breaks the low, else NEUTRAL.
@@ -747,6 +751,8 @@ with:
   interval: "1h"
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## pct_change  (indicator)
 
 Percent change of close over `lookback` bars (stag 7d trend %; bison/thesis-fund price momentum — same shape, different window).
@@ -771,6 +777,8 @@ with:
   interval: "4h"
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## recent_high_bars_ago  (indicator)
 
 Counts bars since the highest high within `window` (stag's fresh-high freshness check).
@@ -794,6 +802,8 @@ with:
   window: 60
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## rsi  (indicator)
 
 Trailing-window RSI over the last `period` gains/losses (duplicated verbatim in bison and thesis-fund).
@@ -818,6 +828,8 @@ with:
   interval: "1h"
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## sma  (indicator)
 
 Simple moving average over `period` closes at `interval`, plus a close>SMA flag (stag SMA-200 trend gate).
@@ -843,6 +855,8 @@ with:
   interval: "4h"
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## threshold_gate  (indicator)
 
 Takes a feature_map (a RAW indicator output) and emits 1.0 where value `op` threshold holds, else 0.0 — a truthy/falsy gate the scorer's required_gates can consume. `op` is one of lt|lte|gt|gte. Unlike every other indicator this reads a feature_map, not candles: wire its `values` input from a feature node's output (answers `indicators[].source`). Need demonstrated TWICE in ONE real dev transcript (D2 known-need bar): the 'fresh entry <= 5 bars' gate over recent_high_bars_ago (a truthiness gate INVERTED it — a fresh 0-bars-ago high read falsy and FAILED), and the 'don't chase if own_return_24h >= 15%' runaway filter. A raw-bars-ago-as-hard-gate has no correct truthiness reading; this node is the missing thresholded gate.
@@ -867,6 +881,8 @@ with:
   value: 5
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## trend_structure  (indicator)
 
 Classifies LONG (higher lows) / SHORT (lower highs) / NEUTRAL over `lookback` bars. This is the single highest-value dedup target: literally duplicated across hawk, bison (x2), magpie, and thesis-fund — 6 corpus call-sites, one primitive.
@@ -891,6 +907,8 @@ with:
   interval: "4h"
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## volume_surge_ratio  (indicator)
 
 Unifies stag's volume_surge, hawk's volume_ratio, and bison's volume_trend into one parameterized primitive: mean(recent_window) / mean(baseline_window) volume.
@@ -916,6 +934,8 @@ with:
   baseline_window: 42
 ```
 
+> Note: compute is normally yours to write as a `kind: pure_fn` (typed inputs in, one titled semantic unit, inline tests — `composer describe pure_fn`). This curated formula remains available: add it by name under an answers `indicators:` entry when it fits exactly (`composer describe indicators` lists the library).
+
 ## classifier_predicate  (filter)
 
 magpie's funding-signature IPOP test generalized: a named boolean predicate over instrument fields (funding magnitude, max leverage, delisting). Distinct from universe_discover in that it classifies an existing candidate set rather than deriving one.

package/dist/composer/generated/graph.schema.json

@@ -1963,6 +1963,10 @@
             },
             "type": "array"
           },
+          "title": {
+            "description": "pure_fn OPTIONAL one-line title: what this compute unit computes, as one titled semantic unit. Generation writes it; a missing title on a hand-authored pure_fn is a non-blocking `composer check` annotation, never an error.",
+            "type": "string"
+          },
           "with": {
             "description": "Node parameters.",
             "type": "object"

package/dist/composer/pure_fn/models.py

@@ -91,6 +91,10 @@ class PureFnNode:
     fn_src: str
     tests: tuple[dict, ...] = ()
     line: Optional[int] = None
+    # OPTIONAL one-line title: what this compute unit computes, as one titled semantic unit.
+    # Generation writes it; a missing title is a non-blocking `composer check` annotation
+    # (see composer.verbs.check._pure_fn_title_annotations), never a validation error.
+    title: Optional[str] = None
 
     # -- registry-NodeDef duck surface ------------------------------------------------
     @property
@@ -166,6 +170,9 @@ def parse_pure_fn(entry: dict, line: Optional[int] = None) -> PureFnNode:
 
     tests = tuple(t for t in (entry.get("tests") or []) if isinstance(t, dict))
 
+    title = entry.get("title")
+    title = title.strip() if isinstance(title, str) and title.strip() else None
+
     return PureFnNode(
         id=node_id,
         inputs=inputs,
@@ -174,4 +181,5 @@ def parse_pure_fn(entry: dict, line: Optional[int] = None) -> PureFnNode:
         fn_src=fn_src,
         tests=tests,
         line=line,
+        title=title,
     )