5.3 KiB
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.pyfor a typed optional request property.- A small exact scheduled-control helper in
articulations.pyorservice.py, reusing existing event models rather than duplicating the scheduler. service.pyfor 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.