93 lines
5.3 KiB
Markdown
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.
|