livepilot 1.10.9 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,332 @@
 # Changelog
 
+## 1.13.0 — Branch-native architecture (April 20 2026)
+
+Twelve-PR migration from "match request → pick move → compile move" to
+"understand intent → generate branches → compile branches → compare".
+The planning layer opens up — Wonder, Preview Studio, Experiment, and
+the new synthesis_brain all share one BranchSeed + CompiledBranch
+contract. Move-first is still available as a targeted flow; branch-native
+is the canonical exploratory path.
+
+**No tool count change** (still 398). **Domain count 51 → 52**
+(added `synthesis_brain`). **+175 new tests** across 9 new files
+(2206 → 2387 passing, 1 skipped, 0 failures).
+
+### New substrate (additive, non-breaking)
+
+- **`mcp_server/branches/`** (PR1) — shared `BranchSeed` and
+  `CompiledBranch` types with `seed_from_move_id` / `freeform_seed` /
+  `analytical_seed` factories. `BranchSeed` sources:
+  `semantic_move` / `freeform` / `synthesis` / `composer` / `technique`.
+- **SessionKernel creative controls** (PR2) — `freshness`,
+  `creativity_profile`, `sacred_elements`, `synth_hints` added as
+  optional fields on `SessionKernel` and `get_session_kernel`. Legacy
+  callers see zero behavior change.
+- **ExperimentBranch compat shim** (PR3) — `move_id` now optional;
+  new `ExperimentBranch.from_seed()` classmethod and
+  `create_experiment_from_seeds(seeds=[...], compiled_plans=[...])`
+  entry point. Legacy `create_experiment(move_ids=...)` keeps working
+  and internally delegates via `seed_from_move_id`.
+- **Creative conductor fork** (PR4) — `classify_request_creative()`
+  alongside `classify_request()`. Adds producer selection
+  (`branch_sources`, `seed_hints`) based on request content + kernel state.
+- **`interesting_but_failed` branch status** (PR7) — new
+  `classify_branch_outcome()` in `evaluation/policy.py`. Exploration
+  mode downgrades score / measurable-delta failures to
+  `interesting_but_failed`; protection violations still force undo
+  (safety invariant).
+- **Per-goal-mode novelty bands** (PR8) — TasteGraph's single
+  `novelty_band` is now a view over `novelty_bands["improve"]`; the
+  `explore` band lets surprise-me branch generation disconnect from
+  conservative improve-mode history. `bypass_taste_in_generation` flag
+  makes `rank_moves` return uniform scores.
+
+### Branch-native producers
+
+- **Wonder branch assembler** (PR6) — `generate_branch_seeds()` emits
+  seeds from four sources: semantic_move, technique (session memory),
+  sacred-element inversion (freshness-gated), and corpus hints.
+  `enter_wonder_mode` now surfaces `branch_seeds` alongside variants.
+- **`synthesis_brain/` subsystem** (PR9, PR10) — native-synth-aware
+  branch production with adapters for Wavetable, Operator, Analog,
+  Drift, Meld. `analyze_synth_patch()` / `propose_synth_branches()`
+  callable from Python; `extract_timbre_fingerprint()` builds a
+  TimbralFingerprint from 8-band spectrum + optional FluCoMa
+  descriptors. No MCP tools yet — next release will wire dedicated
+  tools and do the tool-count metadata sweep in one pass.
+- **Composer branch producer** (PR11) — `propose_composer_branches()`
+  emits N distinct compositional hypotheses from one prompt via three
+  strategies (canonical / energy_shift / layer_contrast), gated on
+  freshness. Each branch ships a pre-compiled scaffolding plan.
+
+### Docs refactor
+
+- **Skills + command guides thinned** (PR5) — `livepilot-core/SKILL.md`
+  now presents two peer flows (Flow A targeted / Flow B exploratory)
+  instead of one recipe-first pipeline. `arrange` / `beat` / `mix` /
+  `sounddesign` commands each add a short Branch-Native section.
+- **Branch status vocabulary** documented including
+  `interesting_but_failed` retention semantics.
+
+### Migration notes for callers
+
+- All additions are optional-param / new-function shaped. Any code
+  reading `branch.move_id` keeps working because `ExperimentBranch`
+  mirrors `seed.move_id` there. Any code calling
+  `create_experiment(move_ids=...)` keeps its exact behavior.
+- If you have persistent state on disk (`~/.livepilot/taste.json`):
+  v1.13 migrates `novelty_band` (flat float) to `novelty_bands` (dict)
+  on first read. Old clients reading the file still see the flat field.
+- Tests added across 9 new files — no existing test needed editing
+  beyond `test_experiment_engine.py` (which gains PR3 coverage but
+  keeps every pre-PR3 test passing).
+
+## 1.12.2 — Post-release audit reliability fixes (April 18 2026)
+
+Six issues surfaced by an immediate post-v1.12.0 deep audit (parallel
+code-reviewer subagents + manual verification). All fixed TDD-style —
+every bug now has a named regression guard in the test suite.
+
+**No tool count change** (still 398). **+11 regression tests**
+(2195 → 2206 passing, 1 skipped, 0 failed).
+
+### Critical fixes (reliability in hot paths)
+
+- **`send_capture` no longer blocks `send_command`** (BUG-audit-C1).
+  The M4L bridge shared `_cmd_lock` between `send_capture` and
+  `send_command`, so any concurrent MCP tool invocation during a
+  recording was blocked for the full capture duration (up to 35s).
+  The two operations use independent receiver state
+  (`_capture_future` vs `_response_callback`) and now use
+  independent locks (`_capture_lock` + `_cmd_lock`).
+  [`mcp_server/m4l_bridge.py:780-790, 912-913`](mcp_server/m4l_bridge.py).
+- **`_parse_osc` no longer crashes on malformed packets**
+  (BUG-audit-C2). `data.index(b'\x00')` raised `ValueError` when a
+  packet had no null byte — on UDP port 9880 collision with
+  non-OSC traffic, every incoming packet logged a noisy stack
+  trace. Replaced with `data.find(...)` + bounds checks on every
+  offset; malformed packets drop silently.
+  [`mcp_server/m4l_bridge.py:513-565`](mcp_server/m4l_bridge.py).
+- **`classify_simpler_slices` returns structured error on bad WAV**
+  (BUG-audit-C3). `sf.read()` was unguarded — corrupt or missing
+  files raised `soundfile.LibsndfileError` through the MCP
+  framework as an internal server error. Every other tool in the
+  module returns `{"error": ...}` dicts. Now wrapped in
+  `try/except` for consistent error shape.
+  [`mcp_server/tools/analyzer.py:571-581`](mcp_server/tools/analyzer.py).
+
+### High-severity fixes (API consistency)
+
+- **`batch_set_parameters` rejects negative `parameter_index`**
+  (BUG-audit-H3). `set_device_parameter` validates this at the MCP
+  layer; `batch_set_parameters` didn't, leaking an unstructured
+  `IndexError` from the Remote Script. Now rejected with a clear
+  ValueError at normalisation time.
+  [`mcp_server/tools/devices.py:318-328`](mcp_server/tools/devices.py).
+
+### Medium-severity fixes
+
+- **`_enrich_slice_response` uses positional fallback for missing
+  `index` field** (BUG-audit-M2). Direct `s["index"]` access in a
+  list comprehension raised `KeyError` on bridge version skew.
+  Now uses `s.get("index", i)` with `enumerate` fallback.
+  [`mcp_server/tools/analyzer.py:57-62`](mcp_server/tools/analyzer.py).
+- **`test_identify_returns_none_for_free_port` is no longer flaky**
+  (BUG-audit-M4). The test hardcoded port 59999 as "almost
+  certainly free"; when another process on the machine held it
+  (hitting Claude Desktop during the audit), the test failed
+  without diagnosing a real code bug. Now uses
+  `socket.bind(("127.0.0.1", 0))` to get a kernel-assigned free
+  port, releases it, then verifies.
+  [`tests/test_startup_safety.py:50-70`](tests/test_startup_safety.py).
+
+### .amxd binary patched in place
+
+- `m4l_device/LivePilot_Analyzer.amxd` had the `ping` response
+  version string patched from `"1.12.0"` → `"1.12.2"` via direct
+  byte replacement (same-length delta, size preserved). No Max
+  re-export needed.
+- `m4l_device/livepilot_bridge.js` source version also updated for
+  the next full rebuild.
+
+---
+
+## 1.12.1 — Silent-failure fixes + slice classifier (April 18 2026)
+
+Reconciles the "separate git stash" called out under v1.12.0's Known
+limitations — the 2026-04-18 Villalobos-groove session surfaced four
+silent-failure bugs and the need for a drum-slice spectral classifier.
+
+**+1 tool (397 → 398): `classify_simpler_slices`.** +43 regression
+guards (pure-Python, run without a live Ableton).
+
+### Ship-stoppers fixed
+
+- **`get_master_rms.pitch.midi_note` clamped** (BUG-F1) — polyphonic
+  pitch detector emitted values up to 319.15 with amplitude 0. Now
+  drops readings with zero amplitude or out-of-range MIDI.
+  [`mcp_server/tools/analyzer.py:128-147`](mcp_server/tools/analyzer.py).
+- **`get_simpler_slices` discloses base MIDI pitch** (BUG-F2) — Simpler
+  Slice mode uses C1 (MIDI 36) as slice 0, NOT C3. Response now
+  includes `base_midi_pitch` at top level and `midi_pitch` per slice.
+  Prevents the class of silent-audio bugs where MIDI notes at pitch
+  60+ trigger nothing. Docstring updated to mandate using the
+  returned `midi_pitch`.
+  [`mcp_server/tools/analyzer.py:37-62, 462-487`](mcp_server/tools/analyzer.py).
+- **`delete_track` last-track error message** (BUG-F3) — Ableton's
+  default rejection message was unrelated to the real cause ("you
+  can't add notes to a clip that doesn't exist yet"). Now pre-checks
+  `track_count` and raises a clear ValueError.
+  [`mcp_server/tools/tracks.py:93-112`](mcp_server/tools/tracks.py).
+- **`batch_set_parameters` accepts aligned schema** (BUG-F4) — supports
+  `parameter_index` / `parameter_name` (matching `set_device_parameter`)
+  in addition to the legacy `name_or_index`. Rejects ambiguous entries
+  with clear errors.
+  [`mcp_server/tools/devices.py:292-328`](mcp_server/tools/devices.py).
+
+### New tool
+
+- **`classify_simpler_slices(track, device, file_path?)`** — runs
+  FFT-based spectral analysis on a Simpler's slice boundaries, returns
+  each slice labeled as KICK / SNARE / HAT / ghost plus feature
+  breakdown (peak, rms, band %). Validated thresholds from the
+  2026-04-18 Villalobos-groove session on "Break Ghosts 90 bpm":
+    - KICK: sub+low ≥ 45%, high < 40%
+    - HAT: high ≥ 70% AND mid < 25%
+    - SNARE: mid ≥ 25% AND high ≥ 40% AND peak ≥ 0.6
+    - ghost: peak < 0.35
+  Eliminates the "assume slice 0 = kick" class of bug.
+
+### New module
+
+- **`mcp_server/sample_engine/slice_classifier.py`** — pure-Python
+  band-energy + peak classifier. Testable without Ableton
+  (`tests/test_slice_classifier.py` uses synthesized drum hits).
+  Exported `classify_segment()` and `classify_slices()` for direct
+  use outside MCP as well.
+
+### Documented bug entries
+
+- `BUGS.md` gains a new **"F. 2026-04-18 Villalobos-groove creative
+  session"** section: F1-F4 fixed here, F5-F7 scoped to v1.13+, F8
+  wontfix (workaround documented).
+
+### Not included in this release
+
+- `package.json` / `server.json` / plugin manifests / skill tool-count
+  sync — release-discipline is a separate task per CLAUDE.md's
+  "Version Bump" section. Run `python3 scripts/sync_metadata.py --fix`
+  before the next release.
+- Registering `classify_simpler_slices` in
+  `tests/test_tools_contract.py::test_analyzer_tools_registered` — the
+  total-count assertion there already passes if regenerated; the
+  registration list is additive and can land with the metadata sync.
+
+---
+
+## 1.12.0 — Live 12 LOM completeness (April 18 2026)
+
+Thirteen chunks closing the gap between LivePilot and Ableton Live 12.3.6's
+Live Object Model. **325 → 397 tools (+72). 45 → 51 domains (+6).**  Every
+addition is hasattr-probed where the underlying API varies by Live version
+— Core (12.0+), Enhanced (12.1.10+), and Full Intelligence (12.3+) tiers
+keep their graceful degradation contract.
+
+### New tools by chunk
+
+- **Chunk 1 — Song scale awareness (4 tools):** `get_song_scale`,
+  `set_song_scale`, `set_song_scale_mode`, `list_available_scales` — exposes
+  Live 12.0's Scale Mode at the song level. Remote Script probes
+  `song.scale_name` / `song.root_note`; missing on pre-12 falls back to
+  "Scale awareness unavailable".
+- **Chunk 2 — Per-clip scale override (3 tools):** `get_clip_scale`,
+  `set_clip_scale`, `set_clip_scale_mode` — Live 12.0 MIDI clip-level override
+  for the song scale. Honors `clip.scale_name` and `clip.scale_mode`.
+- **Chunk 3 — Tuning System (4 tools):** `get_tuning_system`,
+  `set_tuning_reference_pitch`, `set_tuning_note`, `reset_tuning_system` —
+  Live 12.1 microtonal tuning. Writes to `song.tuning_system`,
+  `tuning.reference_pitch`, and individual tuning-note cents.
+- **Chunk 4 — Follow Actions (8 tools):** Clip-level Live 12.0 revamp
+  (multi-action enum, `follow_action_time`, `follow_action_enabled`) +
+  scene-level Live 12.2+ (`scene.follow_action`, `scene.follow_action_time`)
+  + preset wrapper for "A→B→C chain" common shapes.
+- **Chunk 5 — Groove Pool (7 tools):** Pool enumeration, per-clip assignment,
+  master groove dial. Exposes Live 11+ `song.groove_pool` and the swing /
+  timing / random / velocity amount on each groove.
+- **Chunk 6 — Take Lanes (6 tools):** Enumeration, creation, per-lane clip
+  creation. Live 12.0 read surface + 12.2 write surface — both paths handled
+  with `hasattr` probes so older hosts degrade cleanly.
+- **Chunk 7 — Rack Variations + Macro CRUD (8 tools):** Variation
+  store/recall/delete + macro add/remove/randomize on Instrument/Audio-Effect
+  Racks (Live 11+).
+- **Chunk 8 — Sample Slice CRUD (6 tools):** `insert_slice`, `move_slice`,
+  `remove_slice`, `clear_slices`, `reset_slices`, `import_slices_from_onsets`.
+  Writes to `SimplerDevice.sample.slices` (Live 11+).
+- **Chunk 9 — Wavetable Modulation Matrix (5 tools):** Targets,
+  routing, amounts — completes the Wavetable surface alongside the existing
+  parameter tools (Live 11+).
+- **Chunk 10 — Song/Track long-tail primitives (12 tools):** `tap_tempo`,
+  `nudge_tempo_down/up`, exclusive arm/solo, `capture_and_insert_scene`,
+  `count_in`, Ableton Link state, `jump_in_session_clip`, performance-impact
+  read, `appointed_device`.
+- **Chunk 11 — Device A/B Compare (3 tools):** State read, toggle, copy
+  direction. Uses Live 12.3+ `Device.is_ab_state_enabled` / `ab_state`
+  where available; all three tools hasattr-probe so they return a clear
+  "unsupported on this Live build" error on 12.2 and older.
+- **Chunk 12 — ControlSurface enumeration (2 tools):** `list_control_surfaces`,
+  `get_control_surface_info`. Always-available diagnostic for multi-surface
+  setups.
+- **Chunk 13 — MIDI Tool bridge (4 tools):** `install_miditool_device`,
+  `set_miditool_target`, `get_miditool_context`, `list_miditool_generators`.
+  Exposes Live 12 MIDI Tools (Generators + Transformations) backed by
+  LivePilot generators (euclidean_rhythm, humanize, tintinnabuli). Ships
+  with both `.amxd` files pre-built from Live's factory templates — install
+  via `install_miditool_device()` which copies to the correct User Library
+  subfolders. **Note**: end-to-end Max-side integration is a known
+  follow-up; Max's `[js]` object may not locate `miditool_bridge.js` on
+  every machine without the folder being added to Max's File Preferences →
+  File Search Path. Server-side tools and config dispatch work standalone;
+  full round-trip notes-in-clip requires that Max path setup. Hence:
+  server shipped, Max-side user-setup step documented.
+
+### New domains (45 → 51)
+
+Source of truth is module layout — six new files registered @mcp.tool()
+decorators:
+
+- `mcp_server/tools/scales.py` — serves both scales (Chunks 1–2) AND tuning
+  (Chunk 3) since both live on the Song object.
+- `mcp_server/tools/follow_actions.py` — Chunk 4.
+- `mcp_server/tools/grooves.py` — Chunk 5.
+- `mcp_server/tools/take_lanes.py` — Chunk 6.
+- `mcp_server/tools/diagnostics.py` — Chunk 12.
+- `mcp_server/tools/miditool.py` — Chunk 13.
+
+Chunks 7–11 extended existing domains (devices, clips) and did not introduce
+new modules.
+
+### Known limitations
+
+- **MIDI Tool bridge (Chunk 13) — Max-side file search**: the `.amxd` files
+  reference `js miditool_bridge.js` relatively. Max normally searches the
+  .amxd's folder first, but Live's MIDI Tool instantiation context can
+  bypass that. If `Max → Window → Max Console` shows "can't find file
+  miditool_bridge.js" when you fire the tool: open Max → Options → File
+  Preferences → add `~/Music/Ableton/User Library/MIDI Tools/Max Generators`
+  and `~/Music/Ableton/User Library/MIDI Tools/Max Transformations` to the
+  File Search Path, save, reload the device.
+- A separate git stash ("pre-existing drift before LOM completeness work"
+  with `classify_simpler_slices` in flight) was left intact; the user will
+  reconcile it in its own release.
+
+### Not a breaking change
+
+Every new tool is additive. No existing tool names, parameters, or return
+shapes changed. Remote Script still boots cleanly on Live 12.0 — the 12.1+
+and 12.3+ tools just return `STATE_ERROR` with a clear message when the host
+lacks the underlying LOM attribute.
+
 ## 1.10.9 — Second-pass audit + deferred-bugs shipped (April 18 2026)
 
 Completes every non-feature item on the v1.10.8 audit backlog. 2116 → 2132

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  325 tools. 45 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
+  398 tools. 52 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
 </p>
 
 <br>
@@ -79,8 +79,8 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   325 MCP Tools  │                                  │
-│                  │   45 domains     │                                  │
+│                  │   398 MCP Tools  │                                  │
+│                  │   52 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
 │           Remote Script ──┤── TCP 9878                                │
@@ -120,7 +120,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 325 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 398 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -172,7 +172,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-325 tools across 45 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+398 tools across 52 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -360,7 +360,7 @@ The V2 intelligence layer. These tools analyze, diagnose, plan, evaluate, and le
 | Creative Constraints | 5 | constraint activation, reference-inspired variants |
 | Preview Studio | 5 | variant creation, preview rendering, comparison, commit |
 
-> **[View all 325 tools →](docs/manual/tool-catalog.md)**
+> **[View all 398 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -587,7 +587,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 325 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 398 tools, workflows |
 | [Intelligence Layer](docs/manual/intelligence.md) | How the 12 engines connect — conductor, moves, preview, evaluation |
 | [Device Atlas](docs/manual/device-atlas.md) | 1305 devices indexed — search, suggest, chain building |
 | [Samples & Slicing](docs/manual/samples.md) | 3-source search, fitness critics, slice workflows |

package/m4l_device/livepilot_bridge.js

@@ -95,7 +95,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.10.9"});
+            send_response({"ok": true, "version": "1.13.0"});
             break;
         case "get_params":
             cmd_get_params(args);

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.10.9"
+__version__ = "1.13.0"

package/mcp_server/branches/__init__.py

@@ -0,0 +1,32 @@
+"""Branch-native types — the shared substrate for Wonder, Preview Studio,
+Experiment, and future producers (synthesis_brain, composer).
+
+A BranchSeed is a producer-emitted creative intent (pre-compilation).
+A CompiledBranch pairs a seed with a concrete plan ready for the execution
+router. compiled_plan=None ⇒ analytical-only (directional suggestion).
+
+This module is pure types + factory helpers. No I/O, no side effects, no
+imports from other mcp_server subsystems.
+"""
+
+from .types import (
+    BranchSeed,
+    CompiledBranch,
+    BranchSource,
+    RiskLabel,
+    NoveltyLabel,
+    seed_from_move_id,
+    freeform_seed,
+    analytical_seed,
+)
+
+__all__ = [
+    "BranchSeed",
+    "CompiledBranch",
+    "BranchSource",
+    "RiskLabel",
+    "NoveltyLabel",
+    "seed_from_move_id",
+    "freeform_seed",
+    "analytical_seed",
+]

package/mcp_server/branches/types.py

@@ -0,0 +1,230 @@
+"""Branch-native types.
+
+Design (see docs/specs/2026-03-17-livepilot-design.md and the branch-native
+migration plan):
+
+- Producers (Wonder, synthesis_brain, composer, technique memory) emit
+  BranchSeed objects expressing creative intent. A seed carries a hypothesis,
+  a source label, a distinctness reason, and novelty/risk labels — but no
+  executable plan yet.
+- A compiler turns a seed into a CompiledBranch by attaching a plan. For
+  source="semantic_move" seeds, the existing semantic_moves.compiler is used.
+  For freeform/synthesis/composer seeds, the producer supplies the plan.
+- CompiledBranch is the canonical post-compilation shape. PreviewVariant
+  and ExperimentBranch will migrate to thin wrappers over CompiledBranch
+  in later PRs; this PR only introduces the types.
+
+compiled_plan=None means analytical_only — the branch is a directional
+suggestion with no executable path. This case already exists in Wonder
+(build_analytical_variant); the branch-native schema promotes it to a
+first-class concept across the whole system.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import asdict, dataclass, field
+from typing import Literal, Optional
+
+
+BranchSource = Literal[
+    "semantic_move",  # compiled via semantic_moves.compiler
+    "freeform",       # producer supplies the compiled plan directly
+    "synthesis",      # from synthesis_brain (PR9+)
+    "composer",       # from composer branch-native path (PR11)
+    "technique",      # from technique memory replay
+]
+RiskLabel = Literal["low", "medium", "high"]
+NoveltyLabel = Literal["safe", "strong", "unexpected"]
+
+
+@dataclass
+class BranchSeed:
+    """Pre-compilation creative intent.
+
+    Distinctness between branches is checked at seed layer — two seeds with
+    the same (source, hypothesis_hash, affected_scope_hash) are not distinct.
+
+    Fields:
+      seed_id: stable identifier. For semantic_move seeds, derived from move_id.
+      source: producer category.
+      move_id: populated when source="semantic_move"; empty otherwise.
+      hypothesis: one-line human-readable prediction of what the branch does.
+      protected_qualities: dimension names the producer promises not to regress.
+      affected_scope: {track_indices, device_paths, section_ids, clip_slots}.
+      distinctness_reason: why this seed is different from siblings in a set.
+      risk_label: execution safety tier.
+      novelty_label: creative novelty tier — maps to the safe/strong/unexpected UX triptych.
+      analytical_only: true ⇒ no plan will be compiled; branch is directional only.
+    """
+
+    seed_id: str
+    source: BranchSource
+    move_id: str = ""
+    hypothesis: str = ""
+    protected_qualities: list[str] = field(default_factory=list)
+    affected_scope: dict = field(default_factory=dict)
+    distinctness_reason: str = ""
+    risk_label: RiskLabel = "low"
+    novelty_label: NoveltyLabel = "strong"
+    analytical_only: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class CompiledBranch:
+    """Post-compilation branch — supersedes the move_id-locked ExperimentBranch.
+
+    Fields:
+      branch_id: stable identifier scoped to a branch set.
+      seed: the originating BranchSeed (carries source, hypothesis, move_id).
+      compiled_plan: execution-router-ready plan dict, or None for analytical-only.
+      execution_log: per-step results after run/commit; [{tool, backend, ok, error, result}].
+      before_snapshot / after_snapshot: captured session state dicts.
+      evaluation: evaluator result dict; shape determined by the evaluator.
+      score: composite quality score (0-1).
+      status: pending | running | evaluated | committed | discarded
+              | interesting_but_failed   ← PR7 will gate on this
+      created_at_ms / executed_at_ms: timestamps.
+    """
+
+    branch_id: str
+    seed: BranchSeed
+    compiled_plan: Optional[dict] = None
+    execution_log: list = field(default_factory=list)
+    before_snapshot: Optional[dict] = None
+    after_snapshot: Optional[dict] = None
+    evaluation: Optional[dict] = None
+    score: float = 0.0
+    status: str = "pending"
+    created_at_ms: int = 0
+    executed_at_ms: int = 0
+
+    @property
+    def move_id(self) -> str:
+        """Back-compat convenience — delegates to seed.move_id.
+
+        Lets callers that currently read branch.move_id keep working once
+        ExperimentBranch migrates to wrap CompiledBranch.
+        """
+        return self.seed.move_id
+
+    @property
+    def analytical_only(self) -> bool:
+        """A branch is analytical when the seed says so OR when no plan exists."""
+        return self.seed.analytical_only or self.compiled_plan is None
+
+    def to_dict(self) -> dict:
+        d = {
+            "branch_id": self.branch_id,
+            "seed": self.seed.to_dict(),
+            "move_id": self.move_id,
+            "score": self.score,
+            "status": self.status,
+            "analytical_only": self.analytical_only,
+            "created_at_ms": self.created_at_ms,
+        }
+        if self.compiled_plan:
+            d["step_count"] = self.compiled_plan.get("step_count", 0)
+            d["summary"] = self.compiled_plan.get("summary", "")
+        if self.before_snapshot is not None:
+            d["before_snapshot"] = self.before_snapshot
+        if self.after_snapshot is not None:
+            d["after_snapshot"] = self.after_snapshot
+        if self.evaluation is not None:
+            d["evaluation"] = self.evaluation
+        if self.execution_log:
+            d["execution_log"] = self.execution_log
+            d["steps_ok"] = sum(1 for e in self.execution_log if e.get("ok"))
+            d["steps_failed"] = sum(1 for e in self.execution_log if not e.get("ok"))
+        return d
+
+
+# ── Factory helpers ──────────────────────────────────────────────────────
+
+def _stable_seed_id(prefix: str, *parts: str) -> str:
+    """Deterministic seed_id from parts — no timestamps, stable across runs."""
+    seed = "|".join(str(p) for p in parts)
+    return f"{prefix}_" + hashlib.sha256(seed.encode()).hexdigest()[:10]
+
+
+def seed_from_move_id(
+    move_id: str,
+    seed_id: str = "",
+    hypothesis: str = "",
+    novelty_label: NoveltyLabel = "strong",
+    risk_label: RiskLabel = "low",
+    protected_qualities: Optional[list[str]] = None,
+    distinctness_reason: str = "",
+) -> BranchSeed:
+    """Build a semantic_move seed — the baseline producer path.
+
+    Mirrors how wonder_mode.engine.discover_moves already hands moves to
+    build_variant. In later PRs, the Wonder distinctness selector will emit
+    BranchSeed directly instead of move dicts.
+    """
+    if not seed_id:
+        seed_id = _stable_seed_id("seed", "move", move_id, novelty_label)
+    return BranchSeed(
+        seed_id=seed_id,
+        source="semantic_move",
+        move_id=move_id,
+        hypothesis=hypothesis or f"Apply {move_id}",
+        novelty_label=novelty_label,
+        risk_label=risk_label,
+        protected_qualities=protected_qualities or [],
+        distinctness_reason=distinctness_reason,
+    )
+
+
+def freeform_seed(
+    seed_id: str,
+    hypothesis: str,
+    affected_scope: Optional[dict] = None,
+    protected_qualities: Optional[list[str]] = None,
+    distinctness_reason: str = "",
+    novelty_label: NoveltyLabel = "strong",
+    risk_label: RiskLabel = "medium",
+    source: BranchSource = "freeform",
+) -> BranchSeed:
+    """Build a freeform seed — producer has a concrete hypothesis without a move.
+
+    The compiled plan is attached downstream by the producer; this seed
+    carries intent only. Used by synthesis_brain, composer, and any
+    producer that doesn't go through semantic_moves.compiler.
+    """
+    return BranchSeed(
+        seed_id=seed_id,
+        source=source,
+        hypothesis=hypothesis,
+        affected_scope=affected_scope or {},
+        protected_qualities=protected_qualities or [],
+        distinctness_reason=distinctness_reason,
+        novelty_label=novelty_label,
+        risk_label=risk_label,
+    )
+
+
+def analytical_seed(
+    seed_id: str,
+    hypothesis: str,
+    source: BranchSource = "freeform",
+    protected_qualities: Optional[list[str]] = None,
+) -> BranchSeed:
+    """Build an analytical-only seed — no plan will be compiled.
+
+    Used when a producer has a directional suggestion but no executable path:
+    - Wonder fallback when no move matches (already present as
+      build_analytical_variant in wonder_mode.engine).
+    - Synthesis brain on opaque devices where parameter state can be read
+      but safe mutations cannot be proposed yet.
+    """
+    return BranchSeed(
+        seed_id=seed_id,
+        source=source,
+        hypothesis=hypothesis,
+        protected_qualities=protected_qualities or [],
+        analytical_only=True,
+    )

package/mcp_server/composer/__init__.py

@@ -1 +1,10 @@
-"""Composer Engine — auto-composition from text prompts via Splice + Sample Engine."""
+"""Composer Engine — auto-composition from text prompts via Splice + Sample Engine.
+
+PR11 adds branch_producer.propose_composer_branches() for emitting
+multiple section-hypothesis BranchSeeds alongside the existing
+single-plan compose() entry point.
+"""
+
+from .branch_producer import propose_composer_branches
+
+__all__ = ["propose_composer_branches"]