Cubase-MCP-GAJ3T.MusicGen.R.../prompts/step_9_fix_controls.md

93 lines
5.3 KiB
Markdown

# 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.