livepilot 1.20.2 → 1.21.0

package/CHANGELOG.md

@@ -1,5 +1,227 @@
 # Changelog
 
+## 1.21.0 — Consolidation: experiment ledger + preset library + record-readiness + reader audit (April 24 2026)
+
+Consolidation release closing five items from the v1.20 plan §12 non-goals
+that were tractable in a 2-session scope. Adds 1 new semantic move + 1
+major-tool auto-ledger-write + minimal preset-library infrastructure +
+a store-purpose audit that turns the v1.20 director-SKILL fix into a
+codebase-wide invariant, all gated behind a test-first wire-format
+parity extension that caught 1 pre-v1.20 drift bug and closed the
+audit window.
+
+Registry: 43 → 44 moves. Test suite: 3043 → 3118 pass (+75 across all
+chunks). Wire-format parity suite: 10 → 44 scenarios. Zero regressions.
+
+### New semantic moves (1)
+
+- **`configure_record_readiness`** (performance family, low risk, protects
+  `signal_integrity=0.7`)
+  - seed_args: `{track_index, armed, exclusive?}`
+  - Non-exclusive: single step `set_track_arm(track_index, arm=armed)` — note
+    the wire-format key is `arm`, not `armed` (the MCP tool accepts `armed`
+    as an ergonomic kwarg but renames to `arm` before send_command; the
+    remote_command backend bypasses that rename).
+  - Exclusive (`exclusive=True` + `armed=True`): N+1 step plan —
+    `set_track_arm(arm=False)` for every other regular track, then
+    `set_track_arm(target, arm=True)` for the target. Emulates Ableton's
+    exclusive-arm mode manually because `song.exclusive_arm` has no
+    Python setter in Live 12.4 (pre-existing v1.20.3 Remote Script bug
+    surfaced during v1.21 live-test pre-flight — see plan correction #6).
+    Requires `session_info.tracks` (automatically built by
+    `apply_semantic_move`).
+  - Rejects `exclusive=True + armed=False` (contradictory), missing `armed`
+    seed_arg, and negative `track_index` (return tracks can't be armed
+    per Ableton's handler at `remote_script/LivePilot/tracks.py:261`).
+  - Closes the one tech_debt entry seeded during v1.20 live test 6.
+
+### Experiment-engine ledger writer
+
+- **`commit_experiment`** now writes to `SessionLedger` after a successful
+  commit, mirroring v1.20's `apply_semantic_move` pattern (commit `0b3489b`).
+  Anti-repetition filters downstream now see experiment commits the same
+  way they see direct semantic-move applies.
+  - `engine` tag reflects branch SOURCE (not escalation success): `"composer"`
+    when `target.seed.source == "composer"`, else `"experiment"`. A composer-
+    sourced branch that fell back to scaffold execution is still
+    `engine=composer` — the escalation-success detail lives in
+    `target.evaluation["composer_escalation"]`.
+  - `move_class` via `_infer_move_family(target)`: `seed.family` when set,
+    else inspect first compiled_plan step's tool via `_TOOL_TO_FAMILY`
+    lookup, else default `"mix"`.
+  - `actions` = one entry per ok row in `commit_result["execution_log"]`
+    (the router's actual execution record — captures the post-escalation
+    plan when composer escalation fired).
+  - Response gains `ledger_entry_id` field (same pattern as
+    `apply_semantic_move`). Best-effort — a ledger-write exception is logged
+    and swallowed so the commit never fails on a bookkeeping path.
+
+### Minimal affordance preset library
+
+- New path `mcp_server/affordances/` with loader (`presets.py`), schema
+  validator (`_schema.py`), and 3 seed YAML files:
+  - `reverb.yaml` — preset `dub-cathedral` (Basic Channel-adjacent huge
+    space; Decay 0.85, Room 0.95, Dry/Wet 0.40, Predelay 0.45, Diffusion 0.80)
+  - `delay.yaml` — preset `ping-pong-dub` (dotted 8th, feedback 0.45,
+    HP+LP filtered)
+  - `auto-filter.yaml` — preset `slow-sweep` (LP type, bar-long LFO,
+    moderate resonance)
+- `configure_device` compiler gained optional `preset` + `device_slug`
+  seed_args (additive — v1.20 callers unaffected). Merge: preset resolves
+  first, explicit `param_overrides` win on per-key conflict (last-write-wins).
+  v1.21 requires explicit `device_slug` when `preset` is used; v1.22
+  adds class_name → slug auto-inference.
+- `livepilot-creative-director/references/phase-6-execution.md` §Affordance-
+  preset resolution rewritten to document the live import path and the
+  three dispatch patterns (preset reference, preset + explicit override,
+  fallback to Python resolve).
+
+### Wire-format parity retroactive gate
+
+- `tests/test_compiler_wire_format_parity.py` extended from 10 to 44
+  scenarios (10 v1.20 + 33 pre-v1.20 + 1 new `configure_record_readiness`).
+  Gate surfaced **1 pre-v1.20 drift pattern** affecting 7 moves:
+  `create_chaos_modulator`, `create_feedback_resonator`,
+  `create_wavefolder_effect`, `create_bitcrusher_effect`,
+  `create_karplus_string`, `create_stochastic_texture`, `create_fdn_reverb`
+  all shipped with a `find_and_load_device` plan_template emitting
+  `{"query": "Wonder X"}` but no `track_index`. The `remote_command`
+  backend bypasses MCP normalization, so Ableton's handler threw
+  `KeyError` on `params["track_index"]` — broken at runtime since
+  pre-v1.20, caught now.
+- Fix: `device_creation_compilers.py::_compile_device_creation` threads
+  `track_index` from `seed_args` into `find_and_load_device` steps.
+  Plan templates updated from `{"query": ...}` to `{"device_name": ...}`
+  across all 7 Device Forge moves.
+- Variant-B' consideration (>3 drift bugs → pause v1.21, ship patch):
+  all 7 failures were one pattern in one file, fixable in one commit.
+  Path B (inline fix as part of Task 1.1.5a) taken — single-pattern
+  single-file fixes are exactly what Task 1.1.5a was written for.
+  See `docs/plans/v1.21-impl-status.md` §3 for the decision log.
+
+### Store-purpose reader audit
+
+- Every file in `mcp_server/` that imports `SessionLedger` or calls
+  `memory_list` / `get_session_memory` now carries a
+  `# store_purpose: <purpose>` comment naming its intent.
+- Allowed purposes (closed set): `writer`, `anti_repetition`,
+  `audit_readonly`, `technique_library`, `session_observations`,
+  `escape_hatch_log`, `mcp_tool_definition`.
+- **`tests/test_ledger_readers.py`** new (5 test cases): enforces the
+  annotation contract at CI, AND guards against any file annotated
+  `anti_repetition` also calling `memory_list` — which would be the
+  latent v1.20 store-confusion bug (director SKILL originally pointed
+  at `memory_list` for recency; `memory_list` reads the persistent
+  technique library, not the action ledger).
+- Audit was clean across the entire `mcp_server` tree — no anti-repetition
+  caller was found reading the wrong store. The audit is purely
+  documentation contracts enforced at CI.
+
+### Plan corrections applied during execution (6, logged in impl-status doc)
+
+Documented for future release planners in `docs/plans/v1.21-impl-status.md`:
+
+1. **Baseline drift** — v1.20.2 and v1.20.3 shipped between plan-write and
+   execution; all version-string literals in the plan needed `1.20.1 →
+   1.20.3` remapping.
+2. **Wire-format drift in device_creation** — plan_templates emitted
+   `{"query": ...}`; handler requires `{"track_index", "device_name"}`.
+3. **`set_track_arm` wire format** — plan §3.1 used `{"armed": ...}`;
+   handler reads `params["arm"]`. MCP tool renames `armed → arm` before
+   send_command; remote_command backend bypasses the rename.
+4. **`set_exclusive_arm` shape** — plan §3.1 assumed a per-track signature
+   `(track_index=...)`; handler is a global mode toggle taking
+   `{"enabled": bool}`.
+5. **Return-track arm rejection** — plan's test expected negative
+   `track_index` to succeed; handler raises `ValueError: "Cannot arm a
+   return track"`. Corrected test pins compile-time rejection.
+6. **`set_exclusive_arm` is broken in Live 12.4 LOM** — live-test pre-flight
+   (2026-04-24) surfaced that `song.exclusive_arm` is a property WITHOUT a
+   Python setter in Live 12.4's Remote Script API. The v1.20.3 handler's
+   direct assignment `song.exclusive_arm = bool(...)` errors with
+   "property of 'Song' object has no setter". v1.21's
+   `configure_record_readiness` exclusive-mode now emulates the behavior
+   manually (disarm-all-others + arm-target loop) — correctness is
+   identical, works in any Live version. The broken v1.20.3
+   `set_exclusive_arm` handler is LEFT AS-IS for potential future fix
+   (when/if Ableton re-exposes the setter, or someone finds a LOM method
+   alternative); it's tracked as an independent bug in the Remote Script.
+
+### Non-goals (deferred)
+
+- **Hard cutover of the escape hatch.** v1.22+ target, conditional on
+  zero `tech_debt` log entries accumulating in one month of production.
+- **Standard / Deep preset catalog.** v1.22+. Minimal library from v1.21
+  proves the loader; catalog fills in after real-usage signal.
+- **class_name → slug auto-inference** for the preset library. v1.22+.
+- **Pre-v1.20 move compiler refactors** beyond the 1 drift fix. v1.22+.
+- **New move families beyond the canonical 7.** The performance family
+  already exists; `configure_record_readiness` joins it.
+- **Taste-graph integration for preset ranking.** v1.22+ once the catalog
+  exists.
+
+### Scope stats
+
+- 7 atomic commits on `v1.21.0-dev` (fix + gate + 4 feature + refactor + release)
+- 28 files changed, +1933 / -63 lines
+- 3 new test files (commit_experiment_ledger, performance_moves,
+  affordance_presets, ledger_readers) + 1 doc (impl-status)
+- 1 new package (`mcp_server/affordances/`) + 3 YAML seed files
+- 15 version-string sites bumped + `.amxd` binary patch (2 bytes)
+- 10 files annotated with `# store_purpose:`
+
+---
+
+## 1.20.3 — Automated analyzer pre-flight (April 24 2026)
+
+Micro-release closing one class of operator error that broke the v1.20.1
+five-project live-test campaign: the LLM operator had a clear memory
+instruction to load `LivePilot_Analyzer` on master at the start of a
+fresh Ableton session but missed it in 5 of 5 projects — producing
+basic mixes instead of the intended mix-polish outcomes because every
+analyzer-gated move (`tighten_low_end`, `sculpt_midrange`,
+`balance_stereo_image`, etc.) silently degraded. Fixed forward with a
+new idempotent pre-flight tool + Director skill wiring.
+
+### Added
+
+**New tool: `ensure_analyzer_on_master`** (`mcp_server/tools/analyzer.py`).
+Idempotent pre-flight that loads `LivePilot_Analyzer.amxd` on master
+when missing, no-ops when already loaded. Returns one of:
+- `already_loaded` (with `is_last_on_master`, `duplicate_count`)
+- `loaded` (first-time load from Ableton browser)
+- `install_required` (device not in browser — actionable hint points at
+  `install_m4l_device`)
+- `failed` (any other error)
+
+Post-load report surfaces the CLAUDE.md invariant "LivePilot_Analyzer
+must be LAST on master" via `is_last_on_master: bool` and warns when
+violated. Duplicate-count warning covers the edge case of multiple
+analyzers on the master chain.
+
+Safe to call every turn — subsequent calls short-circuit via one
+`get_master_track` read. Tool count: 429 → 430. 6 new contract tests
+covering already-loaded, missing-loads, install-required,
+duplicate-handling, is-last warning, and two-call idempotence.
+
+### Changed
+
+**Director Phase 1** (`livepilot-creative-director/SKILL.md`). Added
+`ensure_analyzer_on_master` at the top of the "Ground" reads as a
+REQUIRED call, ahead of `get_session_info`. Wording explicitly connects
+the step to the failure it prevents so future agents don't rationalize
+skipping it: "Skipping it is how the v1.20.1 live-test campaign
+produced basic mixes — the analyzer-gated moves degrade silently when
+there's no master spectrum to read."
+
+### Notes
+
+No breaking changes. Calling code that assumed the analyzer was loaded
+continues to work; the new tool adds an explicit pre-flight path.
+`install_m4l_device` contract unchanged.
+
+---
+
 ## 1.20.2 — 5 bugs + 1 race condition from the live-test campaign (April 24 2026)
 
 Patch release fixing every issue surfaced during the v1.20.1 five-project

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  429 tools. 53 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
+  430 tools. 53 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
 </p>
 
 <br>
@@ -38,12 +38,12 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 | Layer | What it provides |
 |-------|-----------------|
 | **Deterministic Tools** | Direct control: transport, tracks, clips, notes, devices, scenes, mixing, arrangement, browser, automation |
-| **Device Atlas** | Knowledge of every device in Ableton's library — 1305 devices indexed by name, URI, category, tag, genre, and pack (641 pack-indexed). 120 enriched with sonic intelligence (47 with aesthetic-tagged `signature_techniques`). 683 drum kits mapped. **Free-text `atlas_describe_chain`** ("a granular pad like Tim Hecker") and **reverse-lookup `atlas_techniques_for_device`** (what techniques reference this device?) added in v1.17 |
-| **Concept Surface** | **New in v1.17.** Two reference files let the LLM's training translate into LivePilot: `artist-vocabularies.md` maps ~25 producers (Villalobos, Hawtin, Basic Channel, Gas, Basinski, Hecker, Aphex, Autechre, Dilla, Burial, Henke, Daft Punk, …) to `reach_for` / `avoid` / `key_techniques`; `genre-vocabularies.md` maps 15 genres to tempo / kick / bass / percussion / harmonic / texture / devices. 146 cross-references between devices and techniques. The LLM reads "sound like Gas" and gets a concrete device chain, not guesswork |
-| **Sample Engine** | Three-source sample intelligence — Ableton's browser, your filesystem, and Splice's catalog (plan-aware: Ableton Live plan uses daily quota, Sounds+/Creator uses credits, free samples bypass both). 6 fitness critics. 29 processing techniques. Collections, presets, preview-URL audition, **LIVE Describe-a-Sound + Variations via Splice GraphQL (v1.17)** |
-| **Spectral Perception** | Real-time ears via M4L — **9-band FFT (v1.17+, sub_low split at 20-60 Hz)**, RMS/peak metering, Krumhansl-Schmuckler key detection, pitch tracking, FluCoMa mel/chroma/onset. Closes the feedback loop so the AI hears its own changes |
+| **Device Atlas** | Knowledge of every device in Ableton's library — 1305 devices indexed 7 ways (by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack — 641 pack-indexed). 120 enriched with sonic intelligence (47 with aesthetic-tagged `signature_techniques`). 683 drum kits mapped. Free-text `atlas_describe_chain` ("a granular pad like Tim Hecker") and reverse-lookup `atlas_techniques_for_device` cross-reference 146 techniques across 58 devices |
+| **Concept Surface** | Two reference files let the LLM's training translate into LivePilot: `artist-vocabularies.md` maps ~25 producers (Villalobos, Hawtin, Basic Channel, Gas, Basinski, Hecker, Aphex, Autechre, Dilla, Burial, Henke, Daft Punk, …) to `reach_for` / `avoid` / `key_techniques`; `genre-vocabularies.md` maps 15 genres to tempo / kick / bass / percussion / harmonic / texture / devices. The LLM reads "sound like Gas" and gets a concrete device chain, not guesswork |
+| **Sample Engine** | Three-source sample intelligence — Ableton's browser, your filesystem, and Splice's catalog (plan-aware: Ableton Live plan uses daily quota, Sounds+/Creator uses credits, free samples bypass both). 6 fitness critics. 29 processing techniques. Collections, presets, preview-URL audition, LIVE Describe-a-Sound + Variations via Splice GraphQL |
+| **Spectral Perception** | Real-time ears via M4L — 9-band FFT (with sub_low split at 20-60 Hz for kick fundamentals), RMS/peak metering, Krumhansl-Schmuckler key detection, pitch tracking, FluCoMa mel/chroma/onset. Auto-loaded via `ensure_analyzer_on_master` (v1.20.3) — no more silently-degraded mix moves from forgotten analyzer |
 | **Technique Memory** | Persistent library of production decisions. Save a beat pattern, device chain, or mix template. Recall by mood, genre, or texture across sessions |
-| **Creative Intelligence** | A dozen engines that understand song identity, learn your taste, diagnose stuck sessions, generate creative options, and evaluate results before claiming success |
+| **Creative Intelligence** | 12 engines on top of the tools: SongBrain, Taste Graph, Wonder Mode, Mix/Sound-Design/Transition/Reference/Translation engines, Hook Hunter, Stuckness Detector, Session Continuity, Preview Studio. **43 semantic moves** (v1.20) — musical intents like "tighten the low end" or "make kick and bass lock" that compile into tool sequences with risk levels and target dimensions |
 
 <br>
 
@@ -80,7 +80,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   429 MCP Tools  │                                  │
+│                  │   430 MCP Tools  │                                  │
 │                  │   53 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
@@ -103,7 +103,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 **M4L Bridge** (`m4l_device/`) — Optional Max for Live Audio Effect on the master track. Provides deep LOM access through Max's LiveAPI that the ControlSurface API can't reach. UDP 9880 (M4L to server) carries spectral data and LiveAPI responses. OSC 9881 (server to M4L) sends commands. The 32 spectral/analyzer tools strictly require the bridge; device and sample tools that call the bridge also have graceful fallbacks, so core functionality works without it. Backed by 31 bridge commands for hidden parameters, Simpler internals, warp markers, display values, and Simpler warp / Compressor sidechain writes that live on child objects Python can't reach.
 
-**Device Atlas** (`mcp_server/atlas/`) — In-memory indexed JSON database. 1305 devices with browser URIs, 120 enriched with YAML sonic intelligence profiles (mood, genre, texture, recommended chains). 6 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre. The AI never hallucinates a device name or preset — it always resolves against the atlas first.
+**Device Atlas** (`mcp_server/atlas/`) — In-memory indexed JSON database. 1305 devices with browser URIs, 120 enriched with YAML sonic intelligence profiles (mood, genre, texture, recommended chains). 7 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack (641 devices mapped to their source pack). Reverse-index `device_techniques_index.json` powers `atlas_techniques_for_device` (146 cross-references across 58 devices). The AI never hallucinates a device name or preset — it always resolves against the atlas first.
 
 **Sample Engine** (`mcp_server/sample_engine/`) — Searches three sources simultaneously: BrowserSource (Ableton's library), SpliceSource (local Splice catalog via SQLite), FilesystemSource (user directories). Every result passes through a 6-critic fitness battery (key, tempo, spectral, genre, mood, technical). 29 processing techniques (Surgeon precision vs. Alchemist experimentation). Builds complete sample processing plans with warp, slice, and effect recommendations.
 
@@ -121,7 +121,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 429 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 430 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -133,7 +133,7 @@ Learns your production preferences across sessions. Tracks which move families y
 
 ### Semantic Moves — Musical Actions, Not Parameters
 
-26+ high-level intents ("add contrast," "tighten the low end," "build tension") that compile into tool sequences. Each move carries a risk level, target dimensions, and protection thresholds. The AI knows what it's risking with every action.
+**43 high-level intents** across 7 families (mix, arrangement, transition, sound_design, performance, device_creation, sample) — "add contrast," "tighten the low end," "make kick and bass lock," "sample vocal ghost," "destroy then rebuild." Each move compiles into a concrete tool sequence with risk level, target dimensions, and protection thresholds. Analyzer-gated moves (`tighten_low_end`, `make_kick_bass_lock`) mark their spectrum pre-reads as optional so the plan continues even when the analyzer isn't available. The AI knows what it's risking with every action.
 
 ### Wonder Mode — Stuck-Rescue Workflow
 
@@ -173,11 +173,11 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-429 tools across 53 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+430 tools across 53 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
-### Core (210 tools)
+### Core Ableton Control — highlights
 
 | Domain | # | What it covers |
 |--------|:-:|----------------|
@@ -200,12 +200,12 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 <br>
 
-### M4L Bridge — 30 tools `[optional]`
+### M4L Bridge — 38 analyzer tools `[optional]`, 31 bridge commands
 
-The M4L Analyzer sits on the master track. UDP 9880 carries spectral data to the server. OSC 9881 sends commands back.
+The M4L Analyzer sits on the master track. UDP 9880 carries spectral data to the server. OSC 9881 sends commands back. The `ensure_analyzer_on_master` pre-flight (v1.20.3) loads the analyzer idempotently on first use — call it once at session start and forget about it.
 
 > [!TIP]
-> Most tools work without the analyzer — it adds 32 spectral/analyzer tools (frequency, loudness, perception) and closes the feedback loop.
+> Most tools work without the analyzer — it adds 38 spectral/analyzer tools (frequency, loudness, perception, Simpler, warp) and closes the feedback loop.
 
 ```
 SPECTRAL ─────── 9-band frequency decomposition (sub_low → air)
@@ -228,36 +228,43 @@ WARP ─────────── get / add / move / remove markers
 
 <br>
 
-### Device Atlas — 6 tools
+### Device Atlas — 10 tools
 
 The atlas is an in-memory indexed database of Ableton's entire device library.
 
 ```
 1305 devices total
   120 enriched with sonic intelligence (mood, genre, texture, chains)
- 683 drum kits mapped with note assignments
-   6 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre
+   47 with aesthetic-tagged signature_techniques
+  683 drum kits mapped with note assignments
+    7 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack
+  146 technique cross-references across 58 devices (reverse-index)
 ```
 
 ```
-atlas_search           Search devices by name, category, or tag
-atlas_suggest          Suggest devices for a musical intent (e.g., "warm pad")
-atlas_chain            Build a device chain from a genre or purpose
-atlas_compare          Compare two devices side-by-side
-atlas_detail           Get full enriched profile for a device
-atlas_library_scan     Scan what's actually installed on this machine
+atlas_search                   Search devices by name, category, or tag
+atlas_device_info              Full enriched profile for a single device
+atlas_suggest                  Suggest devices for a musical intent (e.g., "warm pad")
+atlas_chain_suggest            Build a device chain from a genre, artist, or purpose
+atlas_compare                  Compare two devices side-by-side
+atlas_describe_chain           Free-text describe-a-chain ("granular pad like Tim Hecker")
+atlas_techniques_for_device    Reverse-lookup: what techniques reference this device?
+atlas_pack_info                Inspect a single Ableton pack — devices + enrichment coverage
+scan_full_library              Scan what's actually installed on this machine
+reload_atlas                   Hot-reload the atlas after adding enrichments
 ```
 
 <br>
 
-### Sample Engine — 6 tools
+### Sample Engine — 23 tools
 
-Three-source sample intelligence with critic-driven fitness scoring.
+Three-source sample intelligence with critic-driven fitness scoring, plus deep Splice integration (catalog search, preview, collections, preset downloads).
 
 ```
 SOURCES ─────────── BrowserSource  (Ableton's built-in library)
                     SpliceSource   (local Splice catalog via SQLite)
                     FilesystemSource (user-specified directories)
+                    Splice LIVE    (gRPC + GraphQL for the full catalog)
 
 CRITICS ─────────── key fitness · tempo fitness · spectral match
                     genre alignment · mood alignment · technical quality
@@ -265,15 +272,35 @@ CRITICS ─────────── key fitness · tempo fitness · spectr
 TECHNIQUES ─────── 29 processing recipes:
                     Surgeon (precise, transparent) vs.
                     Alchemist (experimental, transformative)
+
+PLAN-AWARE ─────── Ableton Live plan   100 samples/day (no credit drain)
+                    Sounds+/Creator     CREDIT_HARD_FLOOR=5 safety gate
+                    Free samples        bypass both gates
 ```
 
 ```
-analyze_sample         Build a complete SampleProfile (material, key, BPM, spectral)
-search_samples         Multi-source search with critic scoring
-suggest_sample_move    Recommend processing technique for a sample
-build_sample_plan      Full processing pipeline: warp + slice + effects
-list_sample_techniques Browse the 29-technique library
-get_sample_technique   Get detailed recipe for a specific technique
+Sample analysis & planning
+  analyze_sample            Build complete SampleProfile (material, key, BPM, spectral)
+  search_samples            Multi-source search with critic scoring
+  evaluate_sample_fit       Score a candidate sample against session context
+  suggest_sample_technique  Recommend processing technique for a sample
+  plan_sample_workflow      Full processing pipeline: warp + slice + effects
+  plan_slice_workflow       Slice-specific workflow for breaks / drum loops
+  get_sample_opportunities  Surface sample-friendly spots in the session
+
+Splice LIVE (catalog, collections, presets)
+  get_splice_credits        Plan + remaining credits + daily quota state
+  splice_catalog_hunt       Query the full Splice catalog (gRPC)
+  splice_download_sample    Plan-aware download (credit floor + quota check)
+  splice_preview_sample     Zero-cost audition via PreviewURL
+  splice_describe_sound     Natural-language search via Splice GraphQL
+  splice_generate_variation Find catalog samples similar to a given UUID
+  splice_list_collections   Enumerate user's Likes / bass / keys folders
+  splice_search_in_collection / add_to_collection / remove_from_collection / create_collection
+  splice_list_presets       Purchased instrument presets
+  splice_preset_info · splice_download_preset
+  splice_pack_info          Per-pack metadata
+  splice_http_diagnose      Debug the Splice HTTPS bridge
 ```
 
 <br>
@@ -362,7 +389,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 429 tools →](docs/manual/tool-catalog.md)**
+> **[View all 430 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -461,12 +488,12 @@ livepilot --install
 </details>
 
 <details>
-<summary><strong>3. M4L Analyzer (optional — adds 27 tools)</strong></summary>
+<summary><strong>3. M4L Analyzer (optional — adds 38 tools)</strong></summary>
 
 Drag `LivePilot_Analyzer.amxd` onto the master track for real-time spectral analysis.
-The `--setup` wizard and Desktop Extension do this automatically.
+The `--setup` wizard and Desktop Extension do this automatically. From v1.20.3, your AI client can also call `ensure_analyzer_on_master` — an idempotent pre-flight that loads the device if missing and no-ops otherwise. The Creative Director skill does this on every session's Phase 1 ground read so you can't forget.
 
-> **Important:** The Analyzer must be the LAST device on the master track — after all effects (EQ, Compressor, Utility) so it reads the final output signal.
+> **Important:** The Analyzer must be the LAST device on the master track — after all effects (EQ, Compressor, Utility) so it reads the final output signal. The pre-flight tool reports `is_last_on_master: bool` and warns if the invariant is broken.
 
 </details>
 
@@ -589,7 +616,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 429 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 430 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

@@ -34,7 +34,7 @@ outlets = 2; // 0: to udpsend (responses), 1: to buffer~/status
 // Single source of truth for the bridge version — bumped alongside the
 // rest of the release manifest. Surfaced in the UI via messnamed("livepilot_version", ...)
 // so the frozen .amxd visibly reports which build it was last exported from.
-var VERSION = "1.20.2";
+var VERSION = "1.21.0";
 
 // ── State ──────────────────────────────────────────────────────────────────
 

package/mcp_server/__init__.py

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

package/mcp_server/affordances/__init__.py

@@ -0,0 +1,31 @@
+"""Affordance-preset library — named presets per Ableton device class.
+
+v1.21 (minimal): infrastructure + 3 seed presets proving the resolver
+pattern:
+  - reverb.yaml       → preset: dub-cathedral
+  - delay.yaml        → preset: ping-pong-dub
+  - auto-filter.yaml  → preset: slow-sweep
+
+v1.22 (planned): full catalog coverage, class_name → slug inference,
+taste-graph integration for preset ranking.
+
+Public API (re-exported for ``from mcp_server.affordances import ...``):
+  resolve_preset(device_slug, preset_name) -> dict[str, number|bool] | None
+  list_devices() -> list[str]
+  list_presets(device_slug) -> list[str]
+  get_preset_metadata(device_slug, preset_name) -> dict | None
+"""
+
+from .presets import (
+    resolve_preset,
+    list_devices,
+    list_presets,
+    get_preset_metadata,
+)
+
+__all__ = [
+    "resolve_preset",
+    "list_devices",
+    "list_presets",
+    "get_preset_metadata",
+]

package/mcp_server/affordances/_schema.py

@@ -0,0 +1,143 @@
+"""Schema validator for affordance-device preset YAML files.
+
+Enforces at test-time that every seed preset file is well-formed. The
+runtime loader (``presets.py``) is tolerant of missing optional fields
+so the product never crashes on a bad preset; this validator is the
+pre-ship gate run by ``tests/test_affordance_presets.py``.
+
+Schema:
+    device_slug: str                    # REQUIRED — must match filename stem
+    device_class_name: str              # REQUIRED — Ableton's class_name
+    presets:                            # REQUIRED — dict[name → PresetRecord]
+      <name>:
+        description: str                # REQUIRED — human-readable
+        param_overrides: dict           # REQUIRED — {name: number|bool|int}, ≥1 entry
+        risk_notes: str                 # optional
+        suggested_pairings: list[str]   # optional
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+_REQUIRED_TOPLEVEL = {"device_slug", "device_class_name", "presets"}
+_REQUIRED_PER_PRESET = {"description", "param_overrides"}
+_OPTIONAL_PER_PRESET = {"risk_notes", "suggested_pairings"}
+
+
+def validate_preset_file(path: Path) -> list[str]:
+    """Return a list of validation errors. Empty list = valid.
+
+    Errors are human-readable one-liners suitable for test failure output.
+    """
+    errors: list[str] = []
+
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        return [f"{path.name}: YAML parse error — {exc}"]
+
+    if not isinstance(data, dict):
+        return [
+            f"{path.name}: top-level must be a mapping, "
+            f"got {type(data).__name__}"
+        ]
+
+    missing = _REQUIRED_TOPLEVEL - set(data.keys())
+    if missing:
+        errors.append(
+            f"{path.name}: missing required top-level fields {sorted(missing)}"
+        )
+
+    slug = data.get("device_slug")
+    if slug is not None and not isinstance(slug, str):
+        errors.append(f"{path.name}: device_slug must be a string")
+    elif slug and slug != path.stem:
+        errors.append(
+            f"{path.name}: device_slug {slug!r} must match "
+            f"filename stem {path.stem!r}"
+        )
+
+    class_name = data.get("device_class_name")
+    if class_name is not None and not isinstance(class_name, str):
+        errors.append(f"{path.name}: device_class_name must be a string")
+
+    presets = data.get("presets")
+    if presets is not None:
+        if not isinstance(presets, dict):
+            errors.append(f"{path.name}: presets must be a mapping")
+        elif not presets:
+            errors.append(f"{path.name}: presets dict is empty")
+        else:
+            for preset_name, preset in presets.items():
+                errors.extend(_validate_preset(path.name, preset_name, preset))
+
+    return errors
+
+
+def _validate_preset(filename: str, name: str, preset: Any) -> list[str]:
+    errors: list[str] = []
+    if not isinstance(preset, dict):
+        return [f"{filename}: preset {name!r} must be a mapping"]
+
+    missing = _REQUIRED_PER_PRESET - set(preset.keys())
+    if missing:
+        errors.append(
+            f"{filename}: preset {name!r} missing required fields {sorted(missing)}"
+        )
+
+    description = preset.get("description")
+    if description is not None and not isinstance(description, str):
+        errors.append(f"{filename}: preset {name!r} description must be a string")
+
+    overrides = preset.get("param_overrides")
+    if overrides is not None:
+        if not isinstance(overrides, dict):
+            errors.append(
+                f"{filename}: preset {name!r} param_overrides must be a dict"
+            )
+        elif not overrides:
+            errors.append(
+                f"{filename}: preset {name!r} param_overrides is empty"
+            )
+        else:
+            for k, v in overrides.items():
+                if not isinstance(k, str):
+                    errors.append(
+                        f"{filename}: preset {name!r} param_overrides key "
+                        f"{k!r} must be a string"
+                    )
+                if not isinstance(v, (int, float, bool)):
+                    errors.append(
+                        f"{filename}: preset {name!r} param_overrides value for "
+                        f"{k!r} must be number|bool, got {type(v).__name__}"
+                    )
+
+    pairings = preset.get("suggested_pairings")
+    if pairings is not None:
+        if not isinstance(pairings, list):
+            errors.append(
+                f"{filename}: preset {name!r} suggested_pairings must be a list"
+            )
+        elif not all(isinstance(p, str) for p in pairings):
+            errors.append(
+                f"{filename}: preset {name!r} suggested_pairings entries "
+                f"must be strings"
+            )
+
+    risk_notes = preset.get("risk_notes")
+    if risk_notes is not None and not isinstance(risk_notes, str):
+        errors.append(f"{filename}: preset {name!r} risk_notes must be a string")
+
+    extras = set(preset.keys()) - _REQUIRED_PER_PRESET - _OPTIONAL_PER_PRESET
+    if extras:
+        errors.append(
+            f"{filename}: preset {name!r} has unknown fields {sorted(extras)} "
+            f"(allowed: {sorted(_REQUIRED_PER_PRESET | _OPTIONAL_PER_PRESET)})"
+        )
+
+    return errors