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

package/dist/composer/AUTHORING.md

@@ -0,0 +1,233 @@
+# Authoring a strategy with the Strategy Composer
+
+Quickstart for a fresh Claude Code session (or a human) turning a strategy idea into a
+deployable trading-strategy graph. This is the same teaching surface the eval harness
+gives Qwen (`composer/eval/prompt.py`), adapted for an interactive session instead of a
+scripted transcript.
+
+## 1. Mental model
+
+An idea becomes a strategy in four moves: write an **answers file** (a typed interview —
+archetype, universe, intervals, cardinality, risk, and your EDGE in plain words) → run
+`composer new` to generate a **COMPLETE, VALID graph** for that archetype, with the
+mechanically-bindable values already filled in and the bespoke slots marked
+`TODO(edit)` with a working default → **edit only what needs editing** (the TODO slots,
+and nothing else unless you have a reason) → run `composer check` for **one GREEN/RED
+verdict** with located, actionable teaching errors → iterate until GREEN → `composer
+compile` (materialize `scan.py`) or `composer deploy --out <dir>` (stage the COMPLETE
+standalone unit — runtime.yaml + scanners/ + strategy.yaml + manifest). The spec file (the graph YAML) **is** the state — there is no separate
+journal — so at any point `composer status <file>` tells you exactly where you are in
+`new → check → deploy` and names the next verb to run.
+
+If the idea doesn't fit a known archetype, `composer new` falls back to a minimal valid
+skeleton (still GREEN, still a real starting point). If the idea needs a capability the
+registry doesn't have, `composer new` refuses to write anything and instead prints a
+**gap report** — that is the correct, honest outcome for something not yet buildable, not
+a bug to work around.
+
+## 2. Setup
+
+Run everything from the worktree root:
+
+```bash
+cd /Users/duncan/Senpi/worktrees/trading_runtime/strategy-composer-poc
+```
+
+The composer has no installed console script; invoke it as a module through `uvx` with
+its runtime deps pinned inline (no venv setup needed):
+
+```bash
+uvx --with pydantic --with jinja2 --with pyyaml --with jsonschema python -m composer.cli <verb> ...
+```
+
+Write your working answers files and generated graphs to `drafts/` (untracked, gitignored
+scratch space) — never into `composer/examples/` (those are the committed corpus
+fixtures) or `composer/generated/` (registry-derived, do-not-edit).
+
+```bash
+mkdir -p drafts
+```
+
+## 3. Verb reference
+
+Every verb takes `--json` for machine-readable output; omit it for a human-readable
+report.
+
+| Verb | What it does | Example |
+|---|---|---|
+| `new` | Interview answers in, a COMPLETE VALID graph out (or a gap report). Refuses to overwrite a hand-edited graph without `--force`. | `uvx --with pydantic --with jinja2 --with pyyaml --with jsonschema python -m composer.cli new my_strat --archetype trend_momentum --answers drafts/my_strat.answers.yaml -o drafts` |
+| `validate` | Schema + graph-semantic teaching-error report (exit 0 iff clean). | `... python -m composer.cli validate drafts/my_strat.graph.yaml` |
+| `check` | ONE verdict: validate + pure_fn inline tests + compile + one-tick smoke, staged so a failing stage skips the rest. | `... python -m composer.cli check drafts/my_strat.graph.yaml` |
+| `compile` | Materialize the graph into `scan.py` on the `external_scanner` contract. | `... python -m composer.cli compile drafts/my_strat.graph.yaml -o drafts/scan.py` |
+| `deploy` | Stage the COMPLETE standalone unit as a package tree (`strategy.yaml`, `main/runtime.yaml`, `main/scanners/scan.py`, `main/<id>.graph.yaml`, `manifest.json`, `deploy.json`); HARD-gated on a GREEN `check`. Does not install. | `... python -m composer.cli deploy drafts/my_strat.graph.yaml -o drafts/dist` |
+| `status` | Derives your lifecycle position (`absent` / `invalid` / `valid_undeployed` / `deployed_stale` / `deployed_current`) from the file + check + staged manifest, and names the next verb. No journal — the file is the state. | `... python -m composer.cli status drafts/my_strat.graph.yaml -o drafts/dist` |
+| `catalog` | The progressive-disclosure node index (names + one-liners + param summary) — level 1. Reference it; don't inline the whole thing into a prompt. | `... python -m composer.cli catalog` |
+| `describe` | Full ports/params/example/cost for ONE node — level 2, on-demand deep-dive. | `... python -m composer.cli describe candles_fetch` |
+
+When in doubt about what a node actually does or which ports it exposes, run `describe`
+rather than guessing from the catalog one-liner.
+
+## 4. The answers-file format
+
+The answers file is the interview output: it captures the 7 decisions that are the
+type-signature of `scan()` — archetype, universe, intervals, cardinality, memory
+(dedup TTL), risk knobs, and the EDGE (free text, carried verbatim; the machine never
+interprets it) — plus any `requires:` capabilities. Full field definitions live in
+`composer/authoring/answers.py`; the shape:
+
+```yaml
+archetype: trend_momentum      # trend_momentum | thesis_fund | classifier
+strategy: my_strat             # short id -> <id>.graph.yaml
+universe:
+  whitelist: ["BTC", "ETH", "SOL"]   # fixed asset list (trend_momentum)
+  long_basket: []                    # thesis_fund LONG leg (use instead of whitelist)
+  short_basket: []                   # thesis_fund SHORT leg
+  discover: false                    # classifier: derive the universe from the live board
+  dex: ""                            # classifier discovery: venue filter
+  name_prefix: ""                    # classifier discovery: instrument name prefix
+  max_leverage_cap: 5.0              # classifier discovery: leverage ceiling
+  min_day_volume: 0.0                # classifier discovery: daily-volume floor
+intervals: ["4h"]               # candle intervals, e.g. ["1h", "4h"]
+max_positions: 1                # 1 = single best; >1 = rank a pool, cap to open slots
+ttl_seconds: 240                # signal-dedup memory window
+exit_preset: null                # LIVE: protected_standard | protected_tight | protected_wide.
+                                  # null -> `composer new` BINDS protected_standard (PROTECTION BY DEFAULT).
+unmanaged: false                 # explicit opt-out of exit protection; without it, an exit-less unit is RED (CMP120)
+risk:
+  margin_pct: 5.0                 # PERCENT of withdrawable (0,100], never a fraction/USD
+  leverage: 3.0                   # signal_envelope also exposes clamp_leverage_to_venue (real venue-max clamp when the board is wired), valid_for_seconds, signal_type
+  drawdown_halt_pct: null         # guard rail: halt the strategy at this equity drawdown % (else preset default)
+  max_consecutive_losses: null    # guard rail: pause after N losses
+  cooldown_seconds: null          # guard rail: post-loss cooldown seconds (>= 60)
+  max_entries_per_day: null       # guard rail: per-day entry cap (>= 1)
+edge: >
+  Your edge in plain words — the actual thesis (e.g. "ride assets breaking to fresh highs
+  with accelerating momentum, volume confirmation, and smart money leaning the same way").
+  This is carried verbatim into the graph; nothing parses it, so be as specific as you want.
+requires: []                    # [{name, kind, need}] — a capability that may not exist yet;
+                                  # a name the registry lacks becomes a gap report, nothing written
+```
+
+**Universe modes**: `whitelist` is a fixed list you already know (trend_momentum,
+trend_conviction shapes). `long_basket`/`short_basket` are the two legs of a fixed macro
+basket (thesis_fund — a relative-value long/short). `discover: true` (+ `dex`,
+`name_prefix`, `max_leverage_cap`, `min_day_volume`) derives the tradeable set each tick
+from the live instrument board by a signature instead of a fixed list (classifier).
+
+An `archetype` the composer doesn't recognize (i.e. not `trend_momentum` /
+`thesis_fund` / `classifier`) falls back to the **off-map skeleton** — still a valid,
+generated starting graph, just minimal; expect to do more hand-editing from there.
+
+Get a blank skeleton for any archetype with `composer describe`-adjacent tooling, or just
+copy the block above and strip fields you don't need — every field has a sane default via
+`Answers()`, so a short file (just `archetype`, `strategy`, `universe`, `edge`) is enough
+to get started.
+
+## 5. Editing the generated graph
+
+`composer new` writes `# TODO(edit): ...` comments at every slot that needs a real
+decision (already filled with a working default so the graph validates unedited) — these
+are the minimum you should look at, not the limit of what you may change. You have full
+edit rights over the whole graph: add/remove nodes, rewire edges, retune any param.
+
+Two ways to express bespoke logic:
+
+- **Registry nodes** (`node: <name>`, see `catalog`) — parameterized, pre-built pipeline
+  steps: sources, indicators, filters, scorers, rankers, the emitter, and the
+  `ttl_dedup_state` stateful node. Wire per-asset features into a scorer's `features`
+  input to MERGE them (keyed by producing node id).
+- **`kind: pure_fn` nodes** — how you write bespoke scoring/classification math the
+  registry vocabulary can't express (e.g. the cross-feature conviction waterfall in
+  `composer/examples/conviction_scorer.graph.yaml`, corpus_origin: bison). Rules, statically
+  enforced before anything runs:
+  - declare typed `inputs:` and `outputs:` (and optional `params:`) — no merge record, each
+    input is a single wired writer;
+  - the `fn:` block is **exactly one** synchronous top-level `def`, whose signature is
+    exactly the declared inputs then params, in order;
+  - only `math` and `statistics` may be imported; only a small safe-builtin set (numeric/
+    collection work) is allowed — no I/O, no `eval`/`exec`/`open`, no `ctx`/MCP access, no
+    dunder/reflection escapes, no `global`/`nonlocal`;
+  - it must `return` exactly its declared outputs;
+  - include `tests:` (inline fixture cases: `inputs:` → `expect:`) — these run as part of
+    `composer check`'s `pure_fn_tests` stage.
+
+**Teaching errors are actionable, not decorative.** Every error from `validate`/`check`
+carries a stable code (`CMPxxx`), a location (node id / port / line), what's wrong in one
+sentence, and a concrete fix hint — a name to use, a bound to respect, or a command to
+run. When a hint names a `describe <node>` command, run it before guessing; when it names
+the nearest valid node/param, use that name rather than inventing one. Fix the errors it
+names, re-run `check`, repeat until GREEN — don't rewrite unrelated parts of the graph.
+
+## 6. Worked micro-example
+
+Idea: *"Long BTC and ETH when 4h price is above its 200-period average and 1h RSI is not
+overbought; take the single best signal, moderate risk."*
+
+`drafts/momo_micro.answers.yaml`:
+
+```yaml
+archetype: trend_momentum
+strategy: momo_micro
+universe:
+  whitelist: ["BTC", "ETH"]
+intervals: ["1h", "4h"]
+max_positions: 1
+ttl_seconds: 240
+risk:
+  margin_pct: 5.0
+  leverage: 3.0
+edge: >
+  Go long BTC/ETH when 4h price is above its 200-period SMA and 1h RSI is not overbought
+  (< 70) — trend confirmation with a momentum-exhaustion guard.
+```
+
+Three commands:
+
+```bash
+uvx --with pydantic --with jinja2 --with pyyaml --with jsonschema python -m composer.cli \
+  new momo_micro --archetype trend_momentum --answers drafts/momo_micro.answers.yaml -o drafts
+
+uvx --with pydantic --with jinja2 --with pyyaml --with jsonschema python -m composer.cli \
+  check drafts/momo_micro.graph.yaml
+
+uvx --with pydantic --with jinja2 --with pyyaml --with jsonschema python -m composer.cli \
+  deploy drafts/momo_micro.graph.yaml -o drafts/dist
+```
+
+After `new`, open `drafts/momo_micro.graph.yaml` and adjust the `TODO(edit)` gate/scorer
+slot to actually express "above SMA-200 AND RSI < 70" (the generated default is a working
+placeholder, not necessarily your exact edge) — the `sma` and `rsi` indicator nodes and a
+`hard_gates_all` scorer (see `composer/examples/trend_momentum_majors.graph.yaml` for the
+pattern) are
+what you'd wire in. Re-run `check` after each edit until GREEN.
+
+## 7. Honest boundaries
+
+- **Gap reports, not silent failures.** If the answers (or an edit) reference a data
+  source or capability the registry doesn't have — named under `requires:`, or a
+  hand-authored node type that doesn't exist — `composer new`/`check` will not fabricate
+  it. `new` prints a structured gap report (what was asked for, what kind, why, and the
+  nearest registry alternatives) and writes nothing. That's the correct outcome for
+  something not yet buildable; the fix is adding the capability to the registry, not
+  working around it in the graph.
+- **Ambiguous ideas need answers first, not invented specifics.** If a brief is missing
+  information you can't responsibly guess (which assets, long/short/both, how much risk),
+  ask the user rather than pick something plausible-sounding. Pin down the answers file,
+  then generate.
+- **Protection by default.** Every strategy the composer emits is a COMPLETE standalone
+  runtime with a DSL `exit:` section (the two-phase trailing stop / time-cuts) — protection
+  is ON unless you deliberately pass `unmanaged: true`. The runtime schema legally allows an
+  exit-less config, so the composer enforces protection itself: an exit-less unit with no
+  `unmanaged` opt-out is RED at `check` (CMP120), and opting out prints a loud warning. Pick a
+  preset by shape — `protected_standard` (balanced, default), `protected_tight` (cut failures
+  fast), `protected_wide` (let a runner breathe). Tune only the `# TODO(edit)` slots
+  (phase-2 tier ladder, `max_loss_pct`) in the emitted `runtime.yaml`.
+- **`deploy` stages a COMPLETE unit; it does not install.** `composer deploy` is hard-gated on
+  a GREEN `check` (which now includes the `runtime_validate` stage — the real Zod + DSL oracle)
+  and stages a standalone strategy PACKAGE TREE, idempotent and side-effect-free:
+  `strategy.yaml` (catalog + funding manifest), `main/runtime.yaml` (the complete runtime:
+  strategy/scanners/actions/**exit**/risk), `main/scanners/scan.py`, `main/<id>.graph.yaml`, and
+  `manifest.json` (hashing all three, with the runtime's Zod verdict). There is no host
+  `runtime.yaml` to borrow — the staged unit is complete on its own. Install is `senpi-strategy-ops`:
+  it reads `strategy.yaml.instances[]`, mints one funded wallet per instance, and renders each
+  `runtime.yaml` onto its wallet. The composer never creates wallets, moves money, or installs.

package/dist/composer/__init__.py

@@ -0,0 +1,29 @@
+"""composer — the agent-facing whole for building trading strategies from typed graphs.
+
+The composer turns a chat-stated idea into a running, verified strategy with no dead
+ends: the LLM decides (interview, edge logic) and the machine composes, validates,
+compiles, deploys, verifies, and issues every success claim. It is the union of a
+registry-generated catalog, a teaching validator, a deterministic compiler, a primitive
+library, archetype templates, and a status CLI — never a DSL (the exit-DSL legibility
+lesson stands). Authored artifacts are typed dataflow DAGs (YAML) of nodes; the compiler
+emits straight-line Python onto the existing external_scanner contract. This package is
+importable to tests and to emitted scanners via the scaffold ``sys.path`` (no packaging
+in the POC); the ``senpi_ta`` packaging/versioning question stays open, post-POC.
+
+Subpackages:
+    registry   — pydantic node registry; the single source of truth (D4/D8).
+    validator  — schema + graph typecheck with located, fix-hinted errors.
+    compiler   — deterministic graph -> scan.py materializer (D5/D6/D8).
+    primitives — runtime-owned Python implementations of primitive nodes.
+    templates  — per-node emission templates + archetype templates-as-code (D7).
+    cli        — the ``composer`` verbs (new/check/deploy/status/catalog/describe).
+"""
+
+__all__ = [
+    "registry",
+    "validator",
+    "compiler",
+    "primitives",
+    "templates",
+    "cli",
+]

package/dist/composer/authoring/__init__.py

@@ -0,0 +1,49 @@
+"""authoring — `composer new`, the machine-generated anchor (D7).
+
+Typed interview answers in, a COMPLETE, VALID, COMPILING strategy graph out, with
+mechanically-bindable values bound and bespoke slots TODO-marked WITH WORKING DEFAULTS so
+the emitted graph validates and compiles before any edit (the anchoring principle: small
+models edit a valid example far more reliably than they generate from a schema, and here the
+anchor is machine-generated per-strategy rather than a copied file). The edge free-text is
+carried verbatim as a comment above the scoring slot; the machine never interprets it.
+
+Public API:
+    Answers / load_answers   — the typed elicitation contract (file + flag overrides).
+    compose_new / NewResult  — plan a `composer new` (gap check, build, no-clobber); no write.
+    detect_gaps / GapReport  — feasibility at `new` time (D4 made mechanical).
+    ARCHETYPES               — the CI-checked archetype templates (build(answers)->graph).
+"""
+
+from __future__ import annotations
+
+from .answers import Answers, Risk, Universe, load_answers, load_answers_file
+from .archetypes import ARCHETYPES, SKELETON
+from .gaps import Gap, GapReport, detect_gaps
+from .generate import NewResult, compose_new, render_graph
+from .presets import DEFAULT_PRESET, EXIT_PRESETS, ExitPreset, preset_names, resolve_guard_rails
+from .runtime_emit import answers_from_metadata, render_runtime_yaml
+from .strategy_manifest import render_strategy_yaml
+
+__all__ = [
+    "Answers",
+    "Risk",
+    "Universe",
+    "load_answers",
+    "load_answers_file",
+    "ARCHETYPES",
+    "SKELETON",
+    "Gap",
+    "GapReport",
+    "detect_gaps",
+    "NewResult",
+    "compose_new",
+    "render_graph",
+    "EXIT_PRESETS",
+    "ExitPreset",
+    "DEFAULT_PRESET",
+    "preset_names",
+    "resolve_guard_rails",
+    "render_runtime_yaml",
+    "answers_from_metadata",
+    "render_strategy_yaml",
+]

package/dist/composer/authoring/answers.py

@@ -0,0 +1,226 @@
+"""answers — the typed interview-answers object (D7 step 1; the elicitation contract).
+
+The 7 decisions are the *type signature of* ``scan(...)`` (HLD "Elicitation"): archetype,
+universe, intervals, cardinality, memory, exit preset, and risk knobs, plus the user's
+EDGE carried verbatim as free text the machine never interprets. This module is the typed
+form of that contract. It is deliberately entry-mode agnostic — a structured authoring
+session and an ambient "make a strategy from this" both land here; ``composer new`` does
+not care where the answers came from.
+
+Two acceptance paths, one contract (D7):
+  * an answers-file (YAML or JSON) parsed into a dict, and/or
+  * individual CLI flags that OVERRIDE the file field-by-field.
+Both feed :func:`load_answers`, which deep-merges (flags win) and constructs :class:`Answers`.
+
+Answer domains are registry-derived where possible (D4): a strategy that names a source or
+capability the registry does not have is not a crash — it is turned into a structured GAP
+REPORT before anything is written (see ``composer.authoring.gaps``). The
+:attr:`Answers.requires` field is how an answer references registry capability names: each
+entry is checked against the registry and, if absent, named in the gap report.
+
+Exit / protection (slice 9 — PROTECTION BY DEFAULT). ``exit_preset`` is now LIVE (default
+``protected_standard``): the composer emits a complete standalone ``runtime.yaml`` whose
+``exit:`` section is the resolved preset (``composer.authoring.presets``). ``unmanaged=True``
+is the explicit, deliberate opt-out (no exit section); leaving it False without an exit is a
+RED check (CMP120). The ``Risk`` model also carries the guard-rail / pause knobs the composer
+owns (drawdown halt, post-loss cooldown, entry cap) — declarative ``runtime.yaml`` fields the
+runtime enforces (design §4).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class Risk(BaseModel):
+    """Sizing knobs + the guard-rail / pause knobs the composer owns (D7 step 3; design §4).
+
+    ``margin_pct``/``leverage`` size the emitted signal. The four pause knobs are optional
+    overrides onto the preset's ``risk.guard_rails`` default — ``None`` means "use the
+    preset default" (``composer.authoring.presets.resolve_guard_rails``). These are
+    declarative ``runtime.yaml`` fields the runtime enforces (auto-halt / post-loss cooldown /
+    per-day entry cap); a LIVE operational pause (stopping the box) is an ops action, not the
+    composer's (design §4)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    margin_pct: float = 5.0   # PERCENT of withdrawable, (0,100] (never a fraction/USD)
+    leverage: float = 3.0
+    # guard_rails overrides (None -> preset default); see presets.resolve_guard_rails.
+    drawdown_halt_pct: Optional[float] = None       # equity-drawdown circuit breaker (halt %)
+    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)
+
+
+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):
+
+      * ``whitelist``               — a fixed asset list (stag/hawk/bison shape).
+      * ``long_basket``/``short_basket`` — the two legs of a fixed macro basket (thesis-fund).
+      * ``discover`` (+ params)     — derive the universe each tick from the live instrument
+                                      board by a funding/leverage/volume signature (magpie).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    whitelist: tuple[str, ...] = ()
+    long_basket: tuple[str, ...] = ()
+    short_basket: tuple[str, ...] = ()
+    discover: bool = False
+    dex: str = ""
+    name_prefix: str = ""
+    max_leverage_cap: float = 5.0
+    min_day_volume: float = 0.0
+
+
+class RequiredCapability(BaseModel):
+    """A registry capability an answer says the strategy needs (D4 feasibility surface).
+
+    ``name`` is matched against the registry; a name the registry lacks becomes a gap-report
+    entry. ``kind`` and ``need`` are carried into the report so the boundary reads honestly
+    ("``top_traders_discovery`` (source): rank traders by realized PnL") rather than as a
+    bare missing symbol.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    kind: str = "node"
+    need: str = ""
+
+
+class Answers(BaseModel):
+    """The typed interview answers — a COMPLETE, VALID graph's input (D7 step 1)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    archetype: str
+    strategy: str = "unnamed"
+    universe: Universe = Field(default_factory=Universe)
+    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.
+    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)
+    edge: str = ""                  # the user's EDGE, verbatim; the machine never interprets it
+    requires: tuple[RequiredCapability, ...] = ()
+
+    @field_validator("exit_preset")
+    @classmethod
+    def _known_preset(cls, value: Optional[str]) -> Optional[str]:
+        """Reject an unknown exit preset early (a typo, not a crash). ``None`` is allowed (unset
+        -> `composer new` binds the default, or `check` flags CMP120). Names live in
+        ``composer.authoring.presets.EXIT_PRESETS`` (protection-by-default policy)."""
+        if value is None:
+            return None
+        from .presets import EXIT_PRESETS  # local import: presets is answers-independent
+        if value not in EXIT_PRESETS:
+            raise ValueError(
+                f"unknown exit_preset {value!r}; choose one of {sorted(EXIT_PRESETS)} "
+                f"(or pass unmanaged=true to deliberately run with NO exit protection)."
+            )
+        return value
+
+    @field_validator("requires", mode="before")
+    @classmethod
+    def _coerce_requires(cls, value: Any) -> Any:
+        """Accept `requires:` entries as bare strings or full mappings."""
+        if value is None:
+            return ()
+        out = []
+        for item in value:
+            if isinstance(item, str):
+                out.append({"name": item})
+            else:
+                out.append(item)
+        return out
+
+    def metadata_block(self) -> dict:
+        """The answers as an ordered plain-dict for the emitted graph's metadata (D7:
+        the spec file IS the state; interview answers live in the metadata block)."""
+        return {
+            "archetype": self.archetype,
+            "strategy": self.strategy,
+            "universe": {
+                "whitelist": list(self.universe.whitelist),
+                "long_basket": list(self.universe.long_basket),
+                "short_basket": list(self.universe.short_basket),
+                "discover": self.universe.discover,
+                "dex": self.universe.dex,
+                "name_prefix": self.universe.name_prefix,
+                "max_leverage_cap": self.universe.max_leverage_cap,
+                "min_day_volume": self.universe.min_day_volume,
+            },
+            "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
+            "unmanaged": self.unmanaged,        # explicit protection opt-out
+            "risk": {
+                "margin_pct": self.risk.margin_pct,
+                "leverage": self.risk.leverage,
+                "drawdown_halt_pct": self.risk.drawdown_halt_pct,
+                "max_consecutive_losses": self.risk.max_consecutive_losses,
+                "cooldown_seconds": self.risk.cooldown_seconds,
+                "max_entries_per_day": self.risk.max_entries_per_day,
+            },
+            "edge": self.edge,
+            "requires": [
+                {"name": c.name, "kind": c.kind, "need": c.need} for c in self.requires
+            ],
+        }
+
+
+def _deep_merge(base: dict, over: dict) -> dict:
+    """Field-by-field merge (``over`` wins); nested dicts merge, scalars/lists replace."""
+    out = dict(base)
+    for key, val in over.items():
+        if isinstance(val, dict) and isinstance(out.get(key), dict):
+            out[key] = _deep_merge(out[key], val)
+        else:
+            out[key] = val
+    return out
+
+
+def load_answers_file(path: str | Path) -> dict:
+    """Parse a YAML or JSON answers-file into a plain dict (raises on non-mapping)."""
+    text = Path(path).read_text(encoding="utf-8")
+    data = yaml.safe_load(text)          # YAML is a JSON superset, so this reads both (D6)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(f"answers file {path} must be a mapping, got {type(data).__name__}")
+    return data
+
+
+def load_answers(
+    file_data: Optional[dict] = None,
+    overrides: Optional[dict] = None,
+) -> Answers:
+    """Build :class:`Answers` from an optional answers-file dict + CLI-flag overrides.
+
+    Overrides win field-by-field (D7: "individual flag overrides"). Unknown keys raise a
+    pydantic ``ValidationError`` (``extra="forbid"``) so a typo is caught, not silently
+    dropped.
+    """
+    merged = _deep_merge(file_data or {}, overrides or {})
+    return Answers(**merged)
+
+
+def dumps_answers_template(archetype: str) -> str:
+    """A blank answers-file skeleton for an archetype (used by `composer new --help`-style
+    scaffolding and the docs); deterministic."""
+    return yaml.safe_dump(
+        Answers(archetype=archetype).metadata_block(), sort_keys=False
+    )

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

@@ -0,0 +1,25 @@
+"""archetypes — the CI-checked archetype templates (D7 step 2; HLD "templates are derived").
+
+Each archetype is CODE that builds a graph from the same registry types (see
+``composer.authoring.builder``), so a template that names a nonexistent node/port fails at
+construction — the CI guarantee that templates cannot drift from the vocabulary. Only the
+archetypes the POC graphs need are here (trend_momentum / classifier / thesis_fund); an
+unrecognised archetype falls to the minimal ``skeleton`` (D7 step 5), which is NOT in
+``ARCHETYPES`` because "no matching archetype" is its trigger.
+
+Each module exposes ``build(answers) -> GraphBuilder`` and a ``BANNER`` header.
+"""
+
+from __future__ import annotations
+
+from . import classifier, skeleton, thesis_fund, trend_momentum
+
+ARCHETYPES = {
+    "trend_momentum": trend_momentum,
+    "classifier": classifier,
+    "thesis_fund": thesis_fund,
+}
+
+SKELETON = skeleton
+
+__all__ = ["ARCHETYPES", "SKELETON"]