7.3 KiB
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.pyand__main__.pyonly 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
- Provide one small concrete service API using the configured output root and real packaged ProfileRegistry. Revalidate incoming models and mutable graphs.
- Wire resolve_description -> profile selection -> compose_score -> compile_score -> write_midi/read-back -> publication -> GenerationResult.
- Recheck parts/formats/profile associations after text resolution; request fields omitted before parsing must not bypass applicability checks.
- Missing formats mean MIDI plus applicable native targets for selected parts. Explicit mid means MIDI only; AGP applies to lead/bass, SDP to drums.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- Tool input cannot choose arbitrary paths. Validate local output-root directory and safe basename with existing helpers plus necessary confinement checks.
- 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.
- Stage files under one unique owned directory inside the output root. Write
<basename>.mid, validate the actual saved file and compute real size. - 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. - 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.
- 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.