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

124 lines
7.3 KiB
Markdown

# Step 2: Typed domain models and MCP tool contracts
## Objective and prerequisites
Step 1 has been reviewed and accepted: its persistent report was read and all
six foundation/distribution tests independently passed. Implement Step 2 of the
approved plan, not server behavior, generation, mapping data, or native writers.
Read `prompts/plan.md`, `prompts/report_1.md`, and the current package/tooling.
Keep the reviewed public MCP contract consistent with Section 7 of the plan.
Do not delegate, commit, generate later prompts, or fabricate compatibility data.
## Owned files
- Create `src/riff_groove_builder/schemas.py`.
- Create `src/riff_groove_builder/errors.py`.
- Create `tests/unit/test_schemas.py` and `tests/unit/test_errors.py`.
- Create `tests/integration/test_contracts.py`.
- Update `docs/architecture.md` with the implemented contracts.
- Update `README.md` only where needed for accurate validation instructions.
- Update `pyproject.toml` only if a directly used test/type dependency is needed;
install only after its manifest change.
- Write `prompts/report_2.md`.
Keep existing foundation tests intact. Explain any additional directly necessary
file. Do not change Step 1's report or the approved plan.
## Implementation details
1. Use Pydantic v2 typed models and a small explicit domain-error hierarchy.
Reject unknown fields and invalid input with actionable messages.
2. Implement request and response models for exactly `list_instrument_profiles`
and `generate_music` as specified by the approved plan, including the explicit
success/error output-schema branches. Empty list-profile input accepts only
an empty object. Expose reusable JSON Schema helpers/constants as appropriate;
Step 3 must not duplicate the contract.
3. Preserve absent override fields as absent/None. Text inference, default
musical intent resolution, and choosing a production profile are later work.
Enforce cross-field constraints when sufficient fields are explicitly known,
and clearly define which checks require resolved intent later.
4. Strictly validate numeric inputs: reject booleans as integers/numbers,
non-finite values, out-of-range values, duplicate enum-list members, empty
arrays, unsupported fields, and invalid part/format/profile combinations.
Accept valid integer or fractional BPM values within the proposed limits.
5. Validate safe basenames, including Windows reserved device names, path
separators/traversal, trailing dots/spaces, length, and the approved ASCII
grammar. Filesystem root/link resolution is future service work.
6. Parse/normalize the documented key grammar for pitch classes (including
conventional sharps/flats) plus major/minor. Reject unsupported modes,
malformed accidentals, or contradictory key strings; test normalization.
7. Define the internal intent, score, logical-note, instrument-profile summary,
and scheduled-event structures needed by the plan. Avoid speculative native
fields. Define exact rational beat positions/durations using Fraction or an
equally explicit rational representation; do not accumulate float timing.
8. Document the representation and units. MIDI channel numbers are 0-15; notes
and CC payloads are 0-127; musical note-on velocity is 1-127; event ticks are
nonnegative integers. Separate keyswitch events from musical-note roles.
Intensity, if normalized to 0-1, is finite and validated rather than clamped.
9. Keep event payloads type-safe: prefer small discriminated event models or
explicit valid combinations over a bag of optional/Any fields. Model stable
event ordering metadata without implementing the scheduler in this step.
10. Make shared timeline/part invariants enforceable: nonempty selected parts,
valid meter, unique part tracks, positive duration, valid note/event ranges.
Distinguish logical musical range checks from future verified profile checks.
11. Define GenerationResult and GenerationError types matching the plan. Validate
feasible result invariants (status/warnings, artifact parts/formats, positive
sizes, and end >= start) without inventing fake files or inspecting disk.
Runtime existence, publication, and full output coverage belong to Step 9.
12. Provide specific named domain exceptions/codes, including invalid requests,
unsupported descriptions/articulations, missing profiles, unavailable native
formats, output collision/IO, and serialization errors. Keep public messages
actionable without exposing stack traces/private file content.
13. Keep package imports side-effect-free and dependency direction simple.
No placeholders pretending to generate files, real production profiles,
parser/composer, filesystem publication, or proprietary codecs.
## Required unit tests
- Every generate_music parameter at valid and invalid boundaries.
- Strict numeric types, NaN/infinity, duplicate/empty lists, invalid enums,
unknown fields, bad profile-part associations, incompatible explicit formats.
- Optional parts/formats/overrides remain unresolved when omitted.
- Safe basenames including case-insensitive Windows reserved names and traversal.
- Keys, meter, seed, exact rational timing, duration/intensity, event payloads,
note/channel/controller ranges, and malformed combinations.
- Empty list-profile input/output and valid/unavailable profile summaries.
- Valid success/fallback/error results and invalid claimed result combinations.
- Domain error codes and stable, useful public details.
## Required integration tests
- Representative requests for each part and combined parts validate and
JSON-round-trip without losing optional-field semantics.
- Published input/output schemas are valid JSON Schemas and agree with the
typed models for representative accepted/rejected payloads.
- Valid success and error branches round-trip through their published schema.
- Logical score/event structures preserve rational timing exactly in documented
serialization, without depending on a production instrument map.
- The existing foundation/distribution tests still pass.
If importing jsonschema directly in tests, declare it directly as a development
dependency rather than depending implicitly on the MCP SDK's transitive package.
Use repository-standard typing without broad ignores or Any casts.
## Verification and acceptance
Run focused new tests, existing relevant tests, Ruff lint/format checks, and
strict mypy. Do not claim an unavailable editor test runner passed; use the
known working `.venv\Scripts\python.exe -m pytest` fallback when necessary.
Run the distribution test if package/dependency configuration changes.
Acceptance requires one authoritative, strict, serializable contract ready for
the Step 3 server and Step 4 MIDI writer. No real mapping/native evidence is
required for purely synthetic model tests, and none may be invented.
## Required report
When complete, write your end-of-step report to ./prompts/report_2.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
The report must be entirely inside exactly one plain triple-backtick fence.
Include changed files, model/schema design decisions, exact validation commands
and pass/fail/skip counts, unresolved limits, and whether Step 3 is ready.
Do not claim any server, generated music, or target application compatibility.