livepilot 1.12.2 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,224 @@
 # Changelog
 
+## 1.14.0 — Branch-native v2: producer context, synth intelligence, render verify (April 20 2026)
+
+Five-PR follow-up to v1.13.0 that closes the loops the first pass left
+open. Producer context flows through the branch lifecycle via a versioned
+`producer_payload`; synthesis adapters decode algorithm topology instead
+of always targeting the same operator; composer winners commit the full
+resolved plan instead of the audition scaffold; render-verify captures
+audio before/after each branch and feeds spectral movement into the
+hard-rule classifier; and four dedicated MCP tools expose the new
+producers to the LLM.
+
+**Tool count**: 398 → **402** (added `analyze_synth_patch`,
+`propose_synth_branches`, `extract_timbre_fingerprint`,
+`propose_composer_branches`). **Domain count**: unchanged at 52.
+**Tests**: 2409 → **2467 passing** (+58 new), 0 regressions.
+
+### New substrate
+
+- **`producer_payload: dict` on `BranchSeed`** (PR1) — versioned
+  opaque dict producers populate with regeneration / provenance /
+  winner-escalation context. Always carries `schema_version` (default 1)
+  so older payloads don't break newer readers. Lives on the seed, not
+  `compiled_plan`, so analytical-only branches can carry context too.
+  Canonical shapes documented per producer (synthesis / composer /
+  semantic_move / freeform / technique).
+
+- **`BranchSnapshot` gains render-based fields** (PR4) —
+  `capture_path`, `loudness`, `spectral_shape`, `fingerprint`. Populated
+  only when `run_experiment(render_verify=True)` opts in. Pre-v2
+  consumers see no shape change when render-verify is off.
+
+### Synthesis adapters get topology awareness (PR2)
+
+- **Wavetable**: position→region classification (sub / mid / bright /
+  complex) drives shift direction. Target brightness biases the chosen
+  target region — not just freshness scaling.
+
+- **Operator**: static `_ALGO_TOPOLOGY` table maps all 11 algorithms
+  to their carrier/modulator roles. Targeting picks the modulator with
+  the highest Level for the ratio shift; additive algorithms (5, 9)
+  fall back to the dominant carrier. No more "always Osc B".
+
+- **Analog / Drift / Meld**: single fixed proposers become strategy
+  registries. Gates honor `role_hint` ("bass" skips `detune_warmth`,
+  "pad" skips `filter_pluck`, silent engines skip `engine_mix_shift`)
+  and target fingerprint dimensions (`target.brightness` picks
+  `filter_sweep_open` vs `filter_sweep_close`).
+
+### Composer winner escalation (PR3)
+
+- Composer seeds now carry their `CompositionIntent` in
+  `producer_payload` at emit time. On `commit_experiment`,
+  `escalate_composer_branch` rehydrates the intent and runs the full
+  `ComposerEngine.compose()` pipeline — Splice / filesystem / browser
+  sample resolution — then swaps the scaffold plan for the resolved one
+  BEFORE `commit_branch_async` runs it through the async router. The
+  scaffold is preserved on `branch.evaluation` for audit.
+
+- Graceful fallback when compose yields zero executable layers:
+  commit runs the scaffold instead of erroring. User gets tracks +
+  scenes they can populate manually, with `composer_escalation.error`
+  explaining why escalation couldn't complete.
+
+- **Latency note**: composer winner commit now takes 10-30s (Splice +
+  filesystem resolution) vs ~0.5s pre-v2. Documented; a progress
+  callback version is future work.
+
+### Render-verify + classifier wiring (PR4)
+
+- `run_experiment(render_verify=False, render_duration_seconds=2.0)` —
+  opt-in per-branch audio capture → offline loudness + spectrum
+  analysis → `TimbralFingerprint` extraction. ~2 * duration seconds +
+  ~1-2s analysis overhead per branch; default off preserves speed.
+
+- New `derive_goal_progress_from_fingerprint(diff, target?)` turns
+  TimbralFingerprint diffs into `(goal_progress, measurable_count)`.
+  Dimensions below 0.02 epsilon are dropped as noise. With a target:
+  sign(target) * diff gives signed progress. Without: magnitude-only
+  contribution (branch moved = measurable).
+
+- `classify_branch_outcome` accepts `fingerprint_diff` + `timbral_target`
+  kwargs. When set and caller didn't supply their own measurable inputs,
+  the classifier derives them from the diff. Caller-supplied values
+  still take precedence (back-compat). Protection violations still
+  trump fingerprint evidence — safety invariant preserved.
+
+- `compare_experiments` automatically surfaces `fingerprint_diff` +
+  `fingerprint_before` + `fingerprint_after` on each branch's
+  `evaluation` dict via the existing pass-through.
+
+### Four new MCP tools (PR5, 398 → 402)
+
+- **`analyze_synth_patch(track_index, device_index, role_hint="")`** —
+  SynthProfile for any supported native synth. Fetches parameter state
+  + display values, hands to the adapter. Opaque fallback for
+  non-supported devices.
+
+- **`propose_synth_branches(track_index, device_index, target?,
+  freshness?, role_hint?)`** — algorithm/topology-aware branch seeds
+  with pre-compiled plans. Feeds directly to
+  `create_experiment(seeds=..., compiled_plans=...)`.
+
+- **`extract_timbre_fingerprint(spectrum?, loudness?, spectral_shape?)`**
+  — pure transform from analysis dicts to 9-dimensional
+  `TimbralFingerprint`. For callers that already have analysis data.
+
+- **`propose_composer_branches(request_text, count=2, freshness=0.65)`**
+  — N compositional hypotheses (canonical / energy_shift /
+  layer_contrast) with producer_payload-captured intents for
+  winner-commit escalation.
+
+### Migration notes for callers
+
+- All additions are optional-param / new-function shaped. Pre-v2
+  callers see no behavior change unless they opt in.
+- Pre-v2 serialized branches deserialize fine: `producer_payload`
+  defaults to `{"schema_version": 1}` when absent.
+- `create_experiment(move_ids=...)` identical behavior.
+- `enter_wonder_mode` response shape stable; `branch_seeds` /
+  `compiled_plans_by_seed_id` still additive.
+- `run_experiment(render_verify=False)` default matches v1.13.0
+  behavior exactly.
+
+### Known limitations
+
+See [`docs/manual/branch-native-migration.md`](docs/manual/branch-native-migration.md#known-limitations)
+for the full list. Headlines:
+
+- Wavetable region classification is a coarse heuristic on raw
+  `Osc 1 Pos`. Future work: render-based per-wavetable mapping.
+- Composer commit latency (10-30s) with no progress callback yet.
+- Render-verify requires the M4L analyzer bridge + LivePilot_Analyzer
+  on master; silently degrades to fast-path when either is missing.
+- End-to-end render-verify path (capture_audio + bridge) is hardware-
+  dependent and not unit-tested; wiring is covered via classifier +
+  fingerprint derivation tests.
+
+## 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

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  398 tools. 51 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
+  402 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
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   398 MCP Tools  │                                  │
-│                  │   51 domains     │                                  │
+│                  │   402 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 398 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 402 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
 
-398 tools across 51 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+402 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 398 tools →](docs/manual/tool-catalog.md)**
+> **[View all 402 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 398 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 402 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.12.2"});
+            send_response({"ok": true, "version": "1.14.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.12.2"
+__version__ = "1.14.0"

package/mcp_server/branches/__init__.py

@@ -0,0 +1,34 @@
+"""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,
+    PRODUCER_PAYLOAD_SCHEMA_VERSION,
+    seed_from_move_id,
+    freeform_seed,
+    analytical_seed,
+)
+
+__all__ = [
+    "BranchSeed",
+    "CompiledBranch",
+    "BranchSource",
+    "RiskLabel",
+    "NoveltyLabel",
+    "PRODUCER_PAYLOAD_SCHEMA_VERSION",
+    "seed_from_move_id",
+    "freeform_seed",
+    "analytical_seed",
+]

package/mcp_server/branches/types.py

@@ -0,0 +1,286 @@
+"""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"]
+
+
+PRODUCER_PAYLOAD_SCHEMA_VERSION = 1
+
+
+@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}.
+        Session-scope information: which tracks/devices/sections the branch
+        affects. Distinct from ``producer_payload`` which carries regeneration
+        context.
+      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.
+      producer_payload: free-form dict the emitting producer populates with
+        whatever it needs for regeneration / provenance / winner escalation.
+        Consumers must check ``schema_version`` (defaults to 1) before reading
+        specific keys so older serialized branches don't break newer readers.
+
+        Canonical shapes per producer:
+          semantic_move: {schema_version: 1}  (empty — move_id is the key)
+          freeform / technique: {schema_version: 1}  (optional)
+          synthesis:
+            {schema_version: 1,
+             device_name: "Wavetable",
+             track_index: int, device_index: int,
+             strategy: "osc_position_shift" | "voice_width_variant" | ...,
+             topology_hint: {...}}  (used by PR4 render-verify to re-target)
+          composer:
+            {schema_version: 1,
+             strategy: "canonical" | "energy_shift" | "layer_contrast",
+             intent: {<CompositionIntent.to_dict()>}}  (used by PR3 to
+             rehydrate for winner-commit escalation)
+    """
+
+    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
+    producer_payload: dict = field(
+        default_factory=lambda: {"schema_version": PRODUCER_PAYLOAD_SCHEMA_VERSION}
+    )
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        # Guarantee schema_version in the payload even if the dict was
+        # mutated to empty by a caller.
+        payload = d.get("producer_payload") or {}
+        if "schema_version" not in payload:
+            payload = dict(payload)
+            payload["schema_version"] = PRODUCER_PAYLOAD_SCHEMA_VERSION
+            d["producer_payload"] = payload
+        return d
+
+
+@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 = "",
+    producer_payload: Optional[dict] = None,
+) -> 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,
+        producer_payload=_normalize_payload(producer_payload),
+    )
+
+
+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",
+    producer_payload: Optional[dict] = None,
+) -> 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,
+        producer_payload=_normalize_payload(producer_payload),
+    )
+
+
+def analytical_seed(
+    seed_id: str,
+    hypothesis: str,
+    source: BranchSource = "freeform",
+    protected_qualities: Optional[list[str]] = None,
+    producer_payload: Optional[dict] = 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,
+        producer_payload=_normalize_payload(producer_payload),
+    )
+
+
+def _normalize_payload(payload: Optional[dict]) -> dict:
+    """Ensure a producer_payload always has schema_version set.
+
+    Producers that don't care about versioning pass None / empty dict and
+    get the default schema_version=PRODUCER_PAYLOAD_SCHEMA_VERSION back.
+    Producers that carry their own version number have it preserved.
+    """
+    if not payload:
+        return {"schema_version": PRODUCER_PAYLOAD_SCHEMA_VERSION}
+    out = dict(payload)
+    out.setdefault("schema_version", PRODUCER_PAYLOAD_SCHEMA_VERSION)
+    return out

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, escalate_composer_branch
+
+__all__ = ["propose_composer_branches", "escalate_composer_branch"]