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

package/dist/composer/AUTHORING.md

@@ -0,0 +1,435 @@
+# 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
+```
+
+**`scaffold` resolves itself — never set a manual `PYTHONPATH` for it.** `check`/`deploy` run
+the emitted `scan.py` under the runtime's `scaffold` harness. The composer finds `scaffold`
+automatically in BOTH layouts — a dev checkout (`src/scanners/external`) and a claw dist install
+(`dist/scanners/external`, no `src/` segment) — so you do not export any path. If it genuinely
+cannot be found, the `smoke` stage fails RED with a teaching error naming the fix: on a claw run
+`npm run build` (its `copy:external-scanners` step stages the harness), or set
+`COMPOSER_SCAFFOLD_DIR` to the dir that CONTAINS `scaffold/`. Do **not** `pip install scaffold` —
+that is an unrelated PyPI package and will not satisfy the import (the harness ships with the
+runtime, never from PyPI).
+
+## 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/scanners/strategy_primitives/` — the vendored primitives snapshot — `main/<id>.graph.yaml`, `manifest.json`, `deploy.json`); HARD-gated on a GREEN `check`. Does not install. The verdict always reports the ABSOLUTE staged dir (a relative `-o` resolves under your current working dir), and a re-deploy of unchanged bytes is `UNCHANGED` — "already staged at `<abs>`, nothing rewritten". | `... python -m composer.cli deploy drafts/my_strat.graph.yaml -o drafts/dist` |
+| `fund` | Create + fund the strategy's ONE wallet via MCP `strategy_create_custom_strategy`. `--budget <usd>` is REQUIRED and EXPLICIT (≥ $100) — agree it with the user; it is NEVER derived or split. Preflights the visible balance (free Hyperliquid + EVM USDC), creates, records `wallet.json` BEFORE polling, then polls briefly to ACTIVE. Idempotent + safe to re-run while funds settle (re-run IS the poll): existing ACTIVE wallet → `FUNDED` no-op; still initializing → `PENDING`; stale → CMP231. Short balance → CMP232 (states the shortfall + the bridged-funds visibility lag). Teaching errors CMP230-233 (+ CMP223 for missing creds). | `... python -m composer.cli fund drafts/dist/my_strat --budget 250` |
+| `install` | Bind a staged unit onto THIS box: preflight (manifest verify + GREEN oracle verdict) → copy to a content-addressed immutable dir `<senpi-state>/strategies/<id>/<hash8>/` (temp+verify+atomic-rename) → bind the wallet into the COPIED `runtime.yaml` (staged source stays pristine) → invoke the frozen `openclaw senpi runtime create -p …` consumer. Pass `--wallet 0x…` explicitly, OR omit it to AUTO-BIND the funded `wallet.json` from `composer fund` (only if MCP confirms the strategy is ACTIVE; explicit `--wallet` always wins). Failures map to teaching errors (CMP200-219, + CMP206 when there is no ACTIVE wallet to auto-bind). Resumable-by-artifact. | `... python -m composer.cli fund drafts/dist/my_strat --budget 250` then `... install drafts/dist/my_strat` |
+| `close` | SAFE TEARDOWN of a running strategy: STOP the runtime first (`openclaw senpi runtime delete`), CONFIRM it is gone, and only THEN trigger MCP `strategy_close` (flattens all positions, returns funds). Idempotent — re-running IS the poll to `CLOSED`. Target is a strategy name / canonical hash dir / runtime id / `0x…` wallet / strategyId; on-box artifacts resolve first, else legacy `strategy_list` attribution (skillName / strategyId). Failures map to teaching errors (CMP220-225). | `... python -m composer.cli close my_strat --state-dir ~/.openclaw/senpi-state` |
+| `status` | Derives your lifecycle position (`absent` / `invalid` / `valid_undeployed` / `deployed_stale` / `deployed_current`) from the file + check + staged manifest, and names the next verb. Pass `--state-dir` to EXTEND the chain onto a box: `installable` → `installed_unregistered` → `installed_stopped` → `installed_running`, distinguishing which hash is installed/running vs merely a prior landed version. Functional liveness (scan() has actually ticked) is reported honestly as NOT-checked — `runtime list` only proves the process is up. No journal — the file is the state. | `... python -m composer.cli status drafts/my_strat.graph.yaml -o drafts/dist --state-dir ~/.openclaw/senpi-state` |
+| `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 | breakout | thesis_fund | classifier
+strategy: my_strat             # short id -> <id>.graph.yaml
+universe:
+  whitelist: ["BTC", "ETH", "SOL"]   # fixed asset list (trend_momentum / breakout)
+  long_basket: []                    # thesis_fund LONG leg (use instead of whitelist)
+  short_basket: []                   # thesis_fund SHORT leg
+  discover: false                    # classifier / breakout: derive the universe from the live board
+  dex: ""                            # discovery: venue filter
+  name_prefix: ""                    # discovery: instrument name prefix
+  max_leverage_cap: 5.0              # discovery: leverage ceiling
+  min_day_volume: 0.0                # 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
+# --- OPTIONAL expressiveness (omit both for the archetype's working defaults) ---
+indicators:                     # ADD registry indicator nodes and wire them into the scorer,
+                                #   so they become addressable by id from `scoring` below.
+  - id: fresh_raw               #   the node's graph id (a feature key = SOURCE NODE ID)
+    node: recent_high_bars_ago  #   any registry indicator (see `composer catalog`)
+    with: { window: 24, interval: "1h" }   # the node's params
+    # port: bars_ago            #   optional: which output feeds the scorer (default: the node's sole output)
+  - id: fresh                   #   a THRESHOLDED gate over the raw feature above (C1b)
+    node: threshold_gate        #   compare a per-asset feature vs a threshold -> 1.0/0.0
+    with: { op: lte, value: 5 } #   op is lt|lte|gt|gte; here: bars_ago <= 5 means "fresh"
+    source: fresh_raw           #   CHAIN the input off fresh_raw's output (not candles)
+scoring:                        # RE-SELECT the scorer's hard-vs-weighted split over the feature
+                                #   nodes (built-in + any `indicators` above). Each field omitted
+                                #   -> keep the archetype default; set -> override it.
+  required_gates: ["brk", "fresh", "vol", "lean"]   # feature ids that must ALL pass (hard gates)
+  weights: { mom: 2.0, vol: 1.0, lean: 0.05 }       # feature id -> weighted-sum weight
+  min_score: 0                  # minimum score to emit
+```
+
+**Universe modes**: `whitelist` is a fixed list you already know (trend_momentum,
+breakout, 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 and
+breakout). `trend_momentum` is fixed-universe only — a `discover: true` answer is rejected
+with a teaching error pointing at `breakout` / `classifier` (it never silently emits an
+empty universe).
+
+**Archetypes**: `trend_momentum` (fixed universe → indicators → hard-gates + weighted-sum
+scorer), `breakout` (a directional range-break as the hard gate, fixed basket OR discovered
+universe — the hawk shape), `classifier` (a pure_fn direction classifier on a discovered or
+fixed universe), `thesis_fund` (fixed long/short basket, direction fixed per leg). An
+`archetype` the composer doesn't recognize falls back to the **off-map skeleton** — still a
+valid, generated starting graph, just minimal; expect to do more hand-editing from there.
+
+**Expressiveness (`scoring` / `indicators`)**: both are OPTIONAL and default to the
+archetype's built-in scorer. `scoring` re-selects which feature nodes are HARD gates
+(`required_gates`) versus weighted contributors (`weights`) and the score floor
+(`min_score`), addressing feature nodes by their SOURCE NODE ID. `indicators` adds
+registry indicator nodes (e.g. `breakout_detect` with a `window`) and wires them into the
+scorer so they become addressable from `scoring`. A `scoring` name that matches no feature
+node, or an `indicators` node the registry lacks, is a loud generation error — never a
+silent drop. This is how, e.g., the `breakout` archetype expresses a four-hard-gate
+discovery variant without any hand editing.
+
+**Thresholded gates (`threshold_gate` + `source`)**: a hard gate must be TRUTHY, so a raw
+numeric feature (e.g. `recent_high_bars_ago`, whose output is bars-since-the-high) can't be
+gated directly — 0 (a high set this bar) reads falsy, a stale 40 reads truthy, exactly
+inverted. Add a `threshold_gate` indicator (`op` one of `lt|lte|gt|gte`, `value` the
+threshold) and CHAIN it off the raw feature with `source:` — its input then reads that node's
+output instead of candles, emitting a real `1.0`/`0.0` gate. So a "fresh entry within 5 bars"
+gate is `fresh = threshold_gate(op: lte, value: 5, source: fresh_raw)` over `fresh_raw =
+recent_high_bars_ago(...)`; a "don't chase a runaway" filter is `threshold_gate(op: lt, value:
+15, source: own_ret)` over an `own_return_24h` feature. `source` names an EARLIER `indicators`
+entry or a built-in feature node of the archetype; an unknown source, or one whose output
+type doesn't match the consumer's input, is a loud generation error.
+
+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 three stateful
+  nodes (`ttl_dedup_state` for signal dedup; `snapshot_diff_state` for a bounded rolling
+  per-key growth ledger; `cohort_cache_state` to pin an expensive fetch across ticks). Wire
+  per-asset features into a scorer's `features` input to MERGE them (keyed by producing node
+  id). The cohort/cross-trader vocabulary (the whalehunter thesis) is now expressible end to
+  end: `top_traders_fetch` → `cohort_cache_state` → `trader_states_fetch` → `aggregate_bias`
+  (the one sanctioned fn→primitive promotion: cross-trader net/gross bias per coin) +
+  `snapshot_diff_state` → a bespoke cohort-scoring `pure_fn` → emit. The **world-coverage sources** span the
+  whole scanner-usable Senpi MCP read surface (proven fully-mapped by the closure check, see
+  below): market signals (funding regime/history, cross-asset flows, prices, momentum events),
+  trader intelligence (top-traders + batch trader-state, the fast 4h smart-money leaderboard
+  `leaderboard_top_fetch` and its single-trader companion `leaderboard_trader_fetch`, leaderboard
+  trader positions, copy-strategy ranking `top_strategies_fetch`, the Arena leaderboard), and
+  own-account reads (order/PnL/clearinghouse/history, banked realized-PnL on open positions).
+  They emit `record_list` outputs — ordered lists of typed dict records — and, for
+  `funding_regime_fetch`, a `label` output (a market-wide categorical string like `LONG_CROWDED`).
+  Neither type is asset-keyed: their intended consumer is a `kind: pure_fn` node that declares a
+  `record_list`/`label` input and reads the fields itself (e.g. project addresses out of
+  `top_traders_fetch.traders` and wire that record_list straight into `trader_states_fetch.traders`
+  to pull the cohort's live books; or project `{wallet_address, coin}` pairs into
+  `open_positions_realized_pnl_fetch.positions`). Prefer `leaderboard_top_fetch` for CURRENT-
+  momentum cohorts (transient 4h delta-PnL) and `top_traders_fetch` for CONSISTENT-performer
+  cohorts (multi-window track record) — the two are deliberately different reads.
+- **`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.
+- **The escape hatch (`mcp_read` + the `raw` port)** — the LAST RESORT for a read the curated
+  source vocabulary doesn't wrap (or doesn't expose the fields you need). `mcp_read` calls a
+  named MCP tool with `args` passed verbatim and emits the unwrapped payload as the `raw` type;
+  you MUST wire that payload into a `kind: pure_fn` node — the NORMALIZER — which reads it and
+  returns TYPED outputs (with inline tests). What it's for: closing a genuine gap without
+  waiting for a registry add. What it is NOT: a way to bypass typing (a `raw` wire may feed
+  nothing but a pure_fn — CMP039), a general-purpose tool caller (READ-ONLY: the `tool` must be
+  in the committed snapshot and must not be a mutation — CMP060/CMP061), or a substitute for a
+  first-class node. **Reach for the registry/answers path FIRST** (`composer catalog` /
+  `composer describe`); use the hatch only when nothing fits, and be explicit in the `edge:`
+  about WHAT you're fetching and WHY the curated path can't express it. Never invent a tool —
+  if the read doesn't exist, it can't be faked here. `composer check` ANNOTATES every hatch use
+  (and flags when the tool already has a first-class node) so the usage stays visible; recurring
+  hatch use of the same shape is the maintainer's signal to wrap it as a real source node.
+
+**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.
+- **Stateful nodes carry PRIOR-tick data, and the cohort cache does NOT skip the fetch.**
+  Every stateful node is split READ (prologue) / WRITE (epilogue): its outputs are read
+  BEFORE the pipeline runs and reflect the LAST persisted tick, while its late input is
+  recorded AFTER. Two consequences to author around: (1) `snapshot_diff_state.growth` is the
+  delta between the latest STORED snapshot and the oldest in the window — one tick behind this
+  tick's fresh input, and empty until ≥2 buckets have accumulated (a short warmup, exactly like
+  whalehunter's `requireGrowing` blocking until ~day 2). (2) `cohort_cache_state` does NOT
+  rate-limit — sources fire every tick and the compiler emits the upstream fetch
+  unconditionally (there is no conditional-fetch machinery). What it buys is COHORT STABILITY:
+  the read half serves the last-known-good cohort (pinned for `ttl_hours`, smoothing a transient
+  fetch failure, surviving process restarts via `ctx.state`), and the write half refreshes only
+  when the TTL lapses, the `version` changes, or the cache was empty. Cold start serves an empty
+  cohort for one warmup tick. State is BOUNDED by design (dedup prune, `max_snapshots` cap, one
+  cached cohort) — an unbounded fleet-box state series is a real ops hazard.
+- **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/scanners/strategy_primitives/` (a vendored SNAPSHOT of `composer/primitives/`, a sibling
+  package of `scan.py`), `main/<id>.graph.yaml`, and `manifest.json` (hashing every artifact
+  including each vendored primitives file, with the runtime's Zod verdict). The emitted `scan.py`
+  imports `strategy_primitives`, NEVER `composer.*`, so the unit is self-contained: it runs on a
+  box that has none of the composer checkout — the scaffold puts the scanner dir on `sys.path` and
+  the vendored package resolves as a sibling of `scan.py`. The snapshot freezes the primitives at
+  deploy time (later `composer/primitives/` changes never mutate an already-staged strategy). 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.
+- **`install` puts ONE instance of a staged unit onto a box — without touching the frozen runtime.**
+  `composer install <staged-dir> --wallet 0x…` (or a graph file plus `-o <staging-dir>`) is the box-side
+  step deploy stops short of. It (a) PREFLIGHTS — resolves the staged tree, verifies every artifact's
+  bytes against `manifest.json` (CMP201, tamper/hand-edit detection), and requires the recorded oracle
+  verdict to be GREEN (`VALID`; a `SKIPPED` verdict on an oracle-less box is allowed, `INVALID` is CMP202);
+  (b) COPIES the unit to a CONTENT-ADDRESSED, IMMUTABLE dir `<senpi-state>/strategies/<strategy>/<hash8>/`
+  — written to a temp sibling, every file re-verified against the manifest (CMP203), then atomic-renamed
+  into place, and NEVER edited after (so the frozen inline-YAML in the registry can't drift from the
+  scan.py re-read off disk on a scaffold respawn). `hash8` = the first 8 hex of a sha256 over the manifest
+  `artifacts` map, so identical staged content always maps to the same dir and a re-install is an idempotent
+  no-op; (c) BINDS the real `--wallet` for the `${..._WALLET}` placeholder in the COPIED `runtime.yaml` only
+  (the staged source stays pristine), records the binding in `install.json`, and re-runs the placeholder
+  policy — any remaining bare `${VAR}` after binding is CMP115; (d) INVOKES the FROZEN consumer,
+  `openclaw senpi runtime create -p <hashdir>/main/runtime.yaml` (PATH mode — never `--content`), behind an
+  injectable seam; (e) maps the known installRuntime failure classes (duplicate id CMP210,
+  one-runtime-per-wallet CMP211, wallet not ACTIVE CMP212, invalid YAML CMP213, entrypoint missing CMP214)
+  to teaching errors that name the exact next command. The runtime id is `<strategy>-<hash8>` (content-keyed,
+  so a duplicate is meaningful). Every step's completion is derivable from disk (staged tree / hash dir +
+  `install.json` / the box registry entry) — the verb is resumable-by-artifact, with no hidden session state.
+  The wallet is supplied by `--wallet`, or auto-bound from the `composer fund` `wallet.json` when `--wallet`
+  is omitted (see `fund`, below); the update/reinstall (delete+create) flow is OUT of scope (the sanctioned
+  teardown path is `composer close`, below).
+- **`fund` creates + funds the wallet — inside the flow, with an EXPLICIT budget.** `composer fund
+  <staged-dir> --budget <usd>` is the funding step the composer used to hand off conversationally. `--budget`
+  is REQUIRED and EXPLICIT (≥ $100): agree it with the user and pass the exact amount. It is NEVER derived
+  from a `funding_share` nor split across wallets — that legacy ops derivation misfired on a real box
+  (it bridged in pieces and told a user with sufficient balance to top up), so this verb funds ONE wallet
+  with the ONE number you pass. Steps, resumable-by-artifact: (a) if `<senpi-state>/strategies/<strategy>/wallet.json`
+  exists (STRATEGY-level, ABOVE the `<hash8>` dirs — the wallet is the strategy's instance identity across
+  content versions), verify it via MCP `strategy_list` — ACTIVE → `FUNDED` no-op, still initializing →
+  `PENDING`, closed/gone → CMP231 (stale); (b) otherwise PREFLIGHT the visible balance via
+  `account_get_portfolio` (free Hyperliquid + free EVM USDC, summed as the backend funds a create) — short
+  of budget → CMP232 stating the current visible total, the exact shortfall, the bridged-funds VISIBILITY
+  LAG (funds moved HL→EVM can lag ~a minute; wait + re-run), and the top-up options (the composer NEVER
+  bridges); (c) sufficient → call MCP `strategy_create_custom_strategy` (`skillName` = the strategy name,
+  matching what `composer close`'s legacy discovery reads), record `wallet.json` BEFORE polling, then poll
+  briefly to ACTIVE. `strategy_create_custom_strategy` is a MONEY MUTATION: there is no `--yes` (the CLI is
+  agent-driven — the user's confirmation is conversational per the skill), but the verb prints an
+  unmistakable pre-action line (creating wallet, budget, funding source) in its result. Missing MCP creds
+  is a loud CMP223. Then `composer install` (omit `--wallet`) auto-binds the funded wallet.
+- **`close` is the ONLY sanctioned teardown — never a raw `strategy_close`.** The invariant is
+  non-negotiable: STOP the runtime first (`openclaw senpi runtime delete <id>`), CONFIRM it is gone,
+  and ONLY THEN submit MCP `strategy_close(<strategyId>)` (which flattens ALL positions and returns
+  funds). A raw `strategy_close` with a live runtime STRANDS the runtime — it keeps trading a wallet the
+  server is tearing down. `composer close <target>` enforces this behind injectable seams: if the runtime
+  delete fails (CMP220) or the runtime is still present afterward (CMP221), `strategy_close` is WITHHELD
+  and the verb fails loud rather than strand or double-fire. It is IDEMPOTENT and SUBMIT-ONLY (no poll):
+  `strategy_close` is async, so the verb reports `CLOSING` and re-running it IS the poll — a re-run skips
+  the delete (runtime already gone) and skips the re-submit (strategy left the ACTIVE set), reporting
+  `CLOSED` once the strategy is terminal. It resolves the target from the composer's own on-box artifacts
+  first (a canonical hash dir's `install.json`, or a strategy name / runtime id under `--state-dir`), and
+  falls back to `strategy_list` attribution (skillName / strategyId + the wallet read from the strategy
+  record) so it also closes legacy ops-deployed strategies and orphan runtimes. Missing MCP creds
+  (`SENPI_API_KEY`) is a loud CMP223, not a silent skip.
+- **`status --state-dir` is the resumable-by-artifact install chain.** With a box named, `status` walks
+  the current staged content DOWN onto the box entirely from artifacts + one read-only `runtime list`:
+  landed (canonical hash dir + `install.json`) → registered (`installed_runtimes.json`) → running. Multiple
+  hash dirs for one strategy are distinguished — which hash is installed/running vs a merely-landed prior
+  version. Liveness is reported HONESTLY: `runtime list` proves only that the process is up, so a running
+  install is annotated that functional liveness (scan() `runCount>0`, a fresh `lastRunFinishedAt`,
+  `consecutiveErrorCount==0` — see `senpi-strategy-ops/references/liveness-verification.md`) is NOT checked
+  here; run `openclaw senpi state -r <id> --json` for that. "running" ≠ "operating".
+
+## 8. Debugging generation deterministically
+
+Generation (`new`/`check`/`deploy`) is fully offline-reproducible: no creds, no network, no
+wall-clock — the same answers always produce the same bytes. So any "the composer generated the
+wrong thing" report replays exactly. The procedure (proven on the first real dev-test incident):
+
+1. Reconstruct the user's answers file from the conversation (the graph's `metadata` block IS the
+   answers when you have the generated graph — spec-is-state).
+2. Drive the CLI into a scratch dir: `python -m composer.cli new --archetype <a> --answers <f> -o /tmp/repro`
+   (deps: pyyaml, pydantic, jinja2, jsonschema — a throwaway venv or `uvx` is enough).
+3. Diff the emitted graph against what the user agreed to — the delta names the lost intent.
+4. Read the archetype's `build()` in `composer/authoring/archetypes/` for where that intent was
+   dropped (a hardcoded literal, an unread answer field, a missing archetype route).
+
+Classify before fixing: COVERAGE (no archetype+params expresses it) · EXPRESSIVENESS (the answers
+surface can't say it) · ROUTING (wrong archetype chosen) · INSTRUCTION (the skill never told the
+agent to pass it). Each has a different smallest fix — and only genuinely-missing SOURCE
+capability (no data feed in the world) is a registry gap; everything else is composer-side.
+
+**Maintainer note (source coverage).** The source vocabulary is kept EXHAUSTIVE over the scanner-
+usable Senpi MCP read surface, and that claim is enforced continuously by the CI closure check
+(`composer/registry/mcp_closure.py`, offline by default). If a new server-side read tool appears,
+CI goes red until it is either mapped by a new source node (declaring `mcp_tool="..."`) or added to
+the allowlist with a reason. To pick up a catalog change, run
+`MCP_SNAPSHOT_REFRESH=1 pytest python-tests/composer/test_mcp_closure.py` (fetches the live
+unauthenticated `tools/list`, rewrites `mcp-tools-snapshot.json`, and surfaces input-schema drift),
+then commit the refreshed snapshot. Full design in `docs/composer/design-models.md` §9.

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,59 @@
+"""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,
+    Indicator,
+    Risk,
+    Scoring,
+    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",
+    "Indicator",
+    "Risk",
+    "Scoring",
+    "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",
+]