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

224 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

```
Step 2 report — typed domain models and MCP tool contracts
Date: 2026-10-19
Result: PASS. Step 2 is verified and ready for Step 3 review/authorization.
SCOPE AND CHANGED FILES
Created:
- src\riff_groove_builder\schemas.py
- src\riff_groove_builder\errors.py
- tests\unit\test_schemas.py
- tests\unit\test_errors.py
- tests\integration\test_contracts.py
- prompts\report_2.md
Updated:
- docs\architecture.md — implemented contracts, units, serialization, reuse,
validation limits, and later-step responsibilities.
- README.md — accurate Step 1–2 scope, direct contract-test dependencies,
focused validation command, and editor-discovery fallback.
- pyproject.toml — directly declared jsonschema>=4.26,<5 and
types-jsonschema>=4.26,<5 development dependencies.
No additional support files were necessary. Existing foundation tests,
initializer, approved plan, Step 1 report, prompts, and unrelated work were
preserved. No commits or delegation. No later prompts, server, scheduler,
writer, parser/composer, production profiles, or native codecs were created.
IMPLEMENTED CONTRACT
Pydantic v2 is authoritative. Contract objects reject unknown fields, numeric
booleans/strings, nonfinite numbers, invalid bounds/enums, duplicate selection
members, and required empty arrays. Integer-only fields reject floats even
when mathematically integral; integer and fractional BPM are accepted.
The meter denominator has an additional strict type guard for Literal values.
Exactly two tool contracts are exposed:
- list_instrument_profiles: empty-object request; profile-list/error output.
- generate_music: the approved parameters; generation-result/error output.
tool_input_schema(name) and tool_output_schema(name) return fresh dictionaries.
Both output schemas have an object root and explicit oneOf success/error
branches. GENERATION_OUTPUT and PROFILE_LIST_OUTPUT are reusable typed union
adapters. Step 3 can reuse these contracts without re-declaring fields.
Omitted parts, formats, musical overrides, and profiles remain None. Explicit
null on those optional fields also means unresolved; model_fields_set and
model_dump_json(exclude_unset=True) preserve the omission/null distinction.
Seed defaults to 0 and allow_midi_fallback to true. No musical defaults, text
inference, default instrument selection, or profile lookup are implemented.
Explicit parts constrain native formats and per-part profile selections now.
Unresolved parts require those checks again after later intent resolution.
Profile summaries enforce Eclips/lead/agp, Ray/bass/agp, SD3/drums/sdp and
explicit limitations for unavailable capabilities. An empty registry is valid.
Synthetic metadata appears only in tests and is not a registry or real mapping.
Basenames enforce the approved ASCII grammar, 1–64 characters, case-insensitive
Windows device-name rejection, and no separators/traversal/trailing whitespace
or dots. A discovered trailing-newline regex edge case was fixed and tested in
both typed-model and published-schema validation.
Key grammar: A–G letter (case-insensitive), optionally one ASCII # or lowercase
b, ASCII spaces, then major/minor (case-insensitive); outer spaces are allowed.
Keys normalize to twelve sharp-spelled pitch classes and lowercase mode:
Bb major -> A# major; Cb minor -> B minor. Contradictory/multiple keys, other
modes, malformed/double accidentals, Unicode accidentals, tabs, and newlines
are rejected. This parses only a structured key, not a musical description.
INTERNAL REPRESENTATION
MusicalIntent requires resolved fields; bars/meter yield exact Fraction duration.
RationalBeat uses reduced integer numerator/denominator JSON objects in
quarter-note beats. Positions are nonnegative; PositiveBeat durations are
strictly positive. No floating timing is accumulated or silently quantized.
LogicalNote is a discriminated pitched/drum union. Lead/bass carry a numeric
pitch; drums carry a logical voice. Both carry exact timing, finite 0–1 intensity
without clamping, and an articulation name. Score enforces shared positive
duration, one ordered track per selected part, matching note parts, and bounds.
ScheduledEvent is a discriminated note-on/note-off/CC union with no irrelevant
optional payload fields. Channels are 0–15; note/CC data are 0–127; note-on
velocity is 1–127; note-off velocity is 0–127. Note roles distinguish musical
notes from keyswitches; CCs carry an articulation-control role.
Nonnegative tick/priority/sequence metadata defines a unique per-track ordering
key but does not implement sorting or scheduling. EventPlan retains the score,
selected event tracks, exact musical tick span, shared pre-roll/end/tail
boundaries, and positive resolution (default 960 ticks/quarter). Musical and
overall event bounds and the 100,000-event budget are validated.
RESULTS AND ERRORS
GenerationResult validates complete/midi_fallback status, resolved profile
coverage, end >= start, positive artifact sizes, absolute-path syntax,
format/part applicability, resolved artifact profile IDs, duplicate outputs,
one combined MIDI covering all selected parts, and selected warning parts.
Fallback requires explicit substituted parts and per-part native-unavailability
warnings, with no simultaneous native output for a substituted part.
GenerationError has stable code/message/details fields. Named exceptions cover
invalid requests, unsupported descriptions/articulations, required/missing
profiles, unavailable native formats, collisions, output IO, and serialization.
ProfileNotFoundError uses PROFILE_REQUIRED with a specific missing-ID message.
Messages give fixed public actions. Finite JSON details are explicitly supplied;
conversion never copies exception causes, tracebacks, or private file content.
VALIDATION ENVIRONMENT AND DEPENDENCIES
Windows AMD64; repository .venv; CPython 3.13.13.
The existing >=3.11 policy is unchanged; no other runtime/OS was executed.
New directly used development dependencies installed/tested:
- jsonschema 4.26.0
- types-jsonschema 4.26.0.20261006
Dependencies were installed only after the manifest edit:
& '.\.venv\Scripts\python.exe' -m pip install --disable-pip-version-check --no-cache-dir -e '.[dev]'
PASS: editable installation/dependency resolution completed. Only the repository
venv was targeted. Final pip check passed.
All validation below ran from the repository root. Scratch setup:
$scratch = New-Item -ItemType Directory -Force '.test-artifacts\scratch'
$env:TEMP = $scratch.FullName
$env:TMP = $scratch.FullName
$env:TMPDIR = $scratch.FullName
The editor runTests tool was attempted for the three absolute new test paths.
It returned "No tests found in the files." This was not counted as a pass or
automated skip; the known working pytest fallback was used.
FINAL EXACT COMMANDS AND OUTCOMES
$env:PIP_NO_INDEX = '1'
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_schemas.py tests\unit\test_errors.py tests\integration\test_contracts.py -q
PASS: 321 passed in 1.40s; 0 failed, 0 skipped.
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_package.py tests\integration\test_distribution.py -q -s
PASS: all 6 unchanged foundation/distribution tests passed in 6.33s;
0 failed, 0 skipped. Includes four unit tests and two distribution tests.
& '.\.venv\Scripts\python.exe' -m pytest -q -s
PASS: final combined suite, 327 passed in 7.46s; 0 failed, 0 skipped.
No test warnings were reported.
& '.\.venv\Scripts\python.exe' -m ruff check .
PASS: All checks passed!
& '.\.venv\Scripts\python.exe' -m ruff format --check .
PASS: 17 files already formatted.
& '.\.venv\Scripts\python.exe' -m mypy
PASS: Success: no issues found in 8 source files.
& '.\.venv\Scripts\python.exe' -m pip check
PASS: No broken requirements found.
git --no-pager diff --check
PASS: no tracked-diff whitespace errors. Existing untracked work remains
untracked; authored Python is additionally covered by Ruff lint/format.
Editor problems tool: no errors in the five new Python files.
Formatting was applied only to the five owned new Python files:
& '.\.venv\Scripts\python.exe' -m ruff format src\riff_groove_builder\schemas.py src\riff_groove_builder\errors.py tests\unit\test_schemas.py tests\unit\test_errors.py tests\integration\test_contracts.py
Distribution tests rebuilt both sdist and wheel offline with --no-isolation,
installed the wheel with --no-index --no-deps in a unique repository-local
venv, and imported the initializer with -I -B from outside the checkout.
Final installed-wheel evidence:
- version and distribution metadata: 0.1.0
- cwd: D:\_Repos\Code\GAJ3T\MCPs\MusicGen
- isolated mode: 1
- module: repository-local .test-artifacts\distribution-bbb54d7455604f1db2132f58a0c8d749\wheel-venv\Lib\site-packages\riff_groove_builder\__init__.py
This proves distribution layout/import safety, not all dependency/runtime
combinations or instrument support. Unique build/wheel-venv workspaces were
cleaned; only the existing ignored scratch directory remains.
DEVELOPMENT FAILURES AND CORRECTIONS
The first focused pytest run had 318 passed, 1 failed: basename "a\n" incorrectly
matched a regex ending in $. An absolute-end assertion fixed it, and matching
schema regressions were added for basename/key newlines. An intermediate
focused run passed 319 tests; the final focused run passes all 321.
Initial strict mypy checks found generic dictionary/literal inference and
heterogeneous test-fixture typing issues (two source diagnostics, then six test
diagnostics). These were corrected with explicit typed data structures and a
schema callback. No broad ignores or Any casts were added.
Initial Ruff checks identified overlong literals (four source diagnostics,
then seven combined diagnostics). Formatting and split literals corrected
them; a remaining import-smoke string was caught and split before the final
successful full lint/format/type rerun. No known step-caused failures remain.
LIMITS AND READINESS
JSON Schema 2020-12 expresses static shapes, bounds, uniqueness, and conditional
associations/branches. Standard JSON Schema cannot compare arbitrary field
values, perform rational arithmetic, or fully express projected ID uniqueness,
profile correspondence, fallback-warning coverage, and timeline invariants.
Portable path checks and these relational checks remain model validators.
JSON Schema also considers 4.0 an integer; strict typed integer fields do not.
Downstream boundaries must use the authoritative models, not schema-only
validation. Revalidate changed payloads rather than mutating validated objects
or using unchecked model_copy updates.
Later work must resolve text/default intent and profile identity, validate
verified instrument ranges/voices/techniques/channels, implement scheduling,
quantization and note pairing, and verify actual files, root/link confinement,
requested-output coverage, fallback permission, and atomic publication.
None of these later behaviors is claimed here.
No target instrument maps, AGP/SDP layouts, lawful native fixtures, or actual
Cubase/plugin load/save compatibility have been verified. The prior evidence
gates remain open. Synthetic tests prove contracts only and do not create
generated music, real native output, or compatible files.
No genuine Step 2 blocker remains. Required contracts, owned tests/docs,
offline foundation/distribution regression checks, lint, formatting, and strict
types pass. Ready for Step 3 to reuse the reviewed schemas and errors; Step 3
was not implemented, and this is not full-project or application readiness.
```