# Step 9 controls fix: Expose scoped CC messages through the MCP request ## Objective The real native/MIDI integration is accepted after report/source review and independent tests. Read CURRENT `report_9_fix.md`, schemas/compiler/service and native codecs. Complete the scoped CC-message surface: CC generation already works internally, but callers need a strict way to request it through the MCP tool. Do not invent a vendor vibrato mapping or add audio/host/model features. No commits, delegation, later prompts or unrelated refactoring. ## Owned surfaces - `schemas.py` for a typed optional request property. - A small exact scheduled-control helper in `articulations.py` or `service.py`, reusing existing event models rather than duplicating the scheduler. - `service.py` for applying controls and honest native preflight. - A precise SD3 unsupported-controller reason if needed to distinguish known format limits from corrupt note/channel/release semantics. - Related request/schema/service/stdio/installed/native tests and docs. - `prompts/report_9_fix_controls.md`. ## Contract and behavior 1. Add optional `cc_events`, default empty list, to GenerateMusicRequest. Each strict item contains: - part: lead | bass | drums - beat: existing RationalBeat quarter-note position relative to musical start - controller: strict MIDI data integer 0..127 - value: strict MIDI data integer 0..127 No filenames, raw code, arbitrary properties, silent clamping or float drift. 2. Reuse the existing 100,000-event resource budget; count controls together with all note/switch events. Bounds/strict booleans/types and unknown fields remain enforced. No new unrelated dependency. 3. Validate part association before/after text inference as appropriate, exact tick representability and beat <= resolved musical duration. End-boundary explicit resets are valid. Reject duplicate normalized (part, beat, controller) points rather than choosing an arbitrary winner. 4. Apply explicit controls after ordinary score compilation, using common musical-start offset and stable event ordering (controls before note-ons). Preserve unique ordering keys and all original note/switch events. 5. Do not silently override an articulation-generated controller at the same instant/controller. Detect conflicting controls and return an actionable INVALID_REQUEST, unless an existing explicit repository policy proves otherwise. No implicit reset is invented; callers can request value=0 at musical end. 6. MIDI exports must retain every requested valid controller/channel/tick/value. Native Riffer preserves supported CC1 stair events already implemented. An unsupported native controller is known capability unavailability, so only the affected native target may fall back when allowed; combined MIDI still preserves ALL controls. No silent dropped native CC. 7. SD3's observed native subset does not establish CC triples. Give legitimate explicit drum CC requests a precise unsupported-controller preflight reason, distinct from corrupted channel/note/role/release data. Only that known controller limitation permits native fallback. fallback=false errors before staging. Explicit MIDI-only drum CC remains supported. 8. Default empty cc_events preserves existing outputs exactly. No unsupported vendor technique is inferred from a controller number or vice versa. ## Required unit tests - Strict CC object schema/types/ranges, rational normalization, projected duplicates, part associations, beat bounds/grid and event-budget rejection. - Exact controller ordering/channel/tick/value and unchanged musical/switch events; multiple controllers and end resets. - Explicit-control/articulation conflict failure. - Precise native controller fallback versus corruption errors; disabled fallback produces no artifacts. ## Required integration tests - Actual real stdio lead/bass CC1 request + explicit end reset: MIDI and Riffer native read-back both contain independently expected exact control points. - All-part request with drum CC: valid guitar/bass natives survive; only drum native is substituted, combined MIDI preserves requested CC, correct warnings. - Unsupported Riffer CC and fallback disabled/enabled cases; no mislabeled native output, dropped messages or partial publication. - MIDI-only controls retain exact bytes/positions independently parsed by Mido. - Installed-wheel input/output schema and actual control generation outside the checkout; portable original template only, no private state in source. - All existing native/default/alias/transaction/profile/MIDI tests remain. Run focused new tests, full current suite, Ruff lint/format, strict mypy, pip check and affected installed-package tests. Use no blanket expected-failure markers or weaker assertions. Update MCP contract/usage documentation with a concrete optional cc_events example and exact native limitations. When complete, write your end-of-step report to ./prompts/report_9_fix_controls.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step Entire report inside exactly one plain triple-backtick fence. Include actual stdio/native/MIDI control evidence, exact checks/counts, no-control regression, explicit fallback results, cleanup and readiness for final native acceptance.