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

122 lines
7.3 KiB
Markdown

# Step 9: Operational MCP generation service and explicit MIDI fallback
## Objective and accepted prerequisites
Implement the amended plan's independent end-to-end Standard MIDI path.
Read reports 5_fix, 6, 7 and 8 and the continuation decision. The parser,
composer, profile registry, compiler, MIDI writer and native capability checks
are reviewed/tested. Real native serialization is still blocked with persistent
step_7_fix/step_8_fix prompts; do not call those native gates passed.
Replace the Step 3 unfinished handlers with useful real behavior. No fake native
success, invented maps, extra output formats, audio, model service, commit,
delegation or later prompts.
## Owned files
- Create `src/riff_groove_builder/service.py`.
- Modify `server.py` and `__main__.py` only as required for actual service wiring.
- Create `tests/unit/test_service.py`.
- Create `tests/integration/test_generation_service.py`.
- Update server/stdio tests that intentionally expected empty/unimplemented tools.
- Update `README.md`, `docs/architecture.md`, compatibility/profile status docs
as necessary for accurate operational usage.
- Write `prompts/report_9.md`.
Reuse strict existing contracts/errors/APIs; explain and test any necessary
shared corrections. Do not weaken lint/types or duplicate the composition logic.
## Generation and result requirements
1. Provide one small concrete service API using the configured output root and
real packaged ProfileRegistry. Revalidate incoming models and mutable graphs.
2. Wire resolve_description -> profile selection -> compose_score ->
compile_score -> write_midi/read-back -> publication -> GenerationResult.
3. Recheck parts/formats/profile associations after text resolution; request
fields omitted before parsing must not bypass applicability checks.
4. Missing formats mean MIDI plus applicable native targets for selected parts.
Explicit mid means MIDI only; AGP applies to lead/bass, SDP to drums.
5. Preflight native capabilities using the real check APIs before touching output.
Currently no native codec is available. With allowed fallback, emit one
combined MIDI for all selected parts even if mid was not listed. With
fallback=false and requested unavailable native output, fail before files.
6. Only known native-capability unavailability permits fallback. Invalid requests,
unsupported techniques, corrupt maps, serialization/read-back failure,
permissions/disk failures and unexpected bugs must remain explicit failures.
7. Return actual published absolute paths/sizes/part/profile IDs, resolved musical
metadata, assumptions/overrides and exact fallback_for coverage. Never include
nonexistent native artifacts, raw private inputs or file bytes.
8. Standard-only mappings need explicit per-part STANDARD_MIDI_MAPPING warnings
and honest profile summaries. Native substitutions additionally need per-part
NATIVE_FORMAT_UNAVAILABLE warnings, status=midi_fallback and matching
fallback_for. Explicit MIDI-only output can be complete but still includes
standard-mapping warnings; it never claims vendor compatibility.
9. List profiles from the actual registry (three standard profiles today),
keeping mapping_kind/product limitations. Remove development-only descriptions
and unfinished errors from registered tools.
10. Successful output includes declared structuredContent plus useful concise
text. Known failures use declared typed isError output; protocol behavior,
strict schemas, sanitization, stderr diagnostics and EOF must remain intact.
11. Build/validate the anticipated result before publication where possible so
a result-model bug cannot publish files and then report generation failure.
## Filesystem/publication requirements
1. Tool input cannot choose arbitrary paths. Validate local output-root directory
and safe basename with existing helpers plus necessary confinement checks.
2. Pin/recheck root identity and reject relevant symlink/junction/reparse-point
escapes or root changes. Do not claim comprehensive adversarial race safety
if the portable APIs cannot provide it; document exact behavior/limitations.
3. Stage files under one unique owned directory inside the output root. Write
`<basename>.mid`, validate the actual saved file and compute real size.
4. Publish the complete set as `<output-root>/<basename>` by same-volume directory
rename. No partial final directories, silent overwrite/merge, or replacement
of existing empty directories. Concurrent same-name requests have one winner
and explicit collision failure. If relying on Windows no-replace semantics,
enforce/document that accurately rather than silently weakening other OSes.
5. No unrelated output-root files are deleted. Cleanup only a specific owned
stage directory with verified identity; surface cleanup failures explicitly.
Preserve sentinels and existing outputs on every failure path.
6. Keep this simple: no persistent job database, generic exporter framework,
remote server, on-disk sidecar manifests or broad silent catches.
## Required unit tests
- Default/explicit formats, text-resolved part applicability and profile mismatch.
- Exact success/fallback artifact/warning/status coverage.
- Fallback false/no files; unsupported palm mute/no dropped articulation.
- Mutated/corrupt inputs, map or serialization/read-back/IO failures stay errors.
- Safe names/root validation, root identity changes, reparse/confinement checks,
collisions, cleanup ownership/failures and no silent overwrite.
- Accurate real profile listing and MCP result/error conversion.
## Required integration tests
- Real description -> selected standard maps -> actual MIDI -> read-back ->
published directory -> schema-valid metadata for individual/all parts.
- Default native requests yield only actual MIDI with explicit fallback warnings.
- Native-only request with allowed fallback yields one combined MIDI; disabled
fallback publishes nothing. Invalid format associations fail after inference.
- Inject write/read-back/publication/cleanup failure and verify no corrupt/partial
final directory or overwritten sentinel. Test competing same-basename requests.
- Test genuine Windows junction/reparse handling where available; report any
environment skip honestly, not as passed confinement.
- Real stdio initialize/list/call generation: inspect returned actual disk MIDI,
warnings/profiles/output schema, strict invalid arguments, IDs, stdout and EOF.
- Different working directory and existing distribution/resource regressions.
## Validation and acceptance
Run focused service/server tests, complete current suite, Ruff lint/format,
strict mypy and pip check. Clean up owned test workspaces and child processes.
Acceptance is a working standard-MIDI MCP generator with explicit native fallback
and safe publication, not full native/vendor/application completion. Do not
leave generation as a placeholder merely because native layouts are unknown.
When complete, write your end-of-step report to ./prompts/report_9.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 real stdio
generation evidence, exact checks/results, filesystem guarantees/limitations,
artifact/warning examples, cleanup and separate software/native/app readiness.