224 lines
11 KiB
Markdown
224 lines
11 KiB
Markdown
```
|
||
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.
|
||
```
|