122 lines
7.3 KiB
Markdown
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.
|