``` 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. ```