# Step 5: Versioned profiles and articulation compiler ## Objective and accepted prerequisites Implement Step 5 of the approved plan using the reviewed contracts and MIDI writer. Steps 1-4 are accepted; the orchestrator independently reran 135 MIDI tests and reviewed the complete Step 4 report and writer. Important: Step 4 explicitly reports that production mapping evidence is not currently available. Implement and verify the reusable profile/compiler mechanics, attempt a bounded check of lawful public official evidence, and report the production acceptance gate as BLOCKED if it remains unresolved. Do not fill the gap with invented values or mark the whole step ready. Read the plan, reports 1-4, schemas/errors, and MIDI API. Do not delegate, commit, generate later prompts, implement text composition/native codecs, or replace the Step 3 unfinished generation handler. ## Owned files - Create `src/riff_groove_builder/profiles.py`. - Create `src/riff_groove_builder/articulations.py`. - Create `tests/unit/test_profiles.py`. - Create `tests/unit/test_articulations.py`. - Create `tests/integration/test_articulation_midi.py`. - Create clearly synthetic JSON fixtures under `tests/fixtures/profiles/`. - Create `docs/articulation-profiles.md`. - Update `docs/architecture.md` and `docs/compatibility.md` for actual outcomes. - Update `README.md` only for accurate current capability/validation status. - Create minimal resource-package initializers under `src/riff_groove_builder/data/` and `data/profiles/` only if needed to make an explicitly empty packaged registry reliable in wheels. - Create real production profile JSON only if supported by sufficient evidence. - Write `prompts/report_5.md`. Explain any tightly coupled schema/error/MIDI changes and add regressions. Preserve the reviewed public tool contract and prior reports. ## Evidence and production-registry requirements 1. Check existing evidence and publicly accessible official sources before assuming anything about Eclips, Ray, or SD3. Limit research to a focused attempt; do not spend the whole session guessing URLs. Record exact sources and findings, including failed/blocked documentation access. 2. Exact product/build, mapping/preset version, playable range, channels, drum voices, keyswitch MIDI numbers, latch/momentary semantics, CC/reset actions, timing, and velocity layers need evidence. Octave labels alone are not enough. 3. Use no credentials, bypass, user-file upload, licensed manual copying, guessed MIDI numbers, assumed GM-as-SD3 map, or synthetic production evidence. 4. Provenance must distinguish test-only data from verified mappings. Synthetic fixture values prove compiler mechanics only. The packaged production registry must never advertise or load test-only profiles as real targets. 5. If no real maps can be verified, ship an explicitly empty production registry and document the blocker. Do not claim that the production part of Step 5 passed. Missing profiles must remain actionable typed failures. 6. Native `.agp`/`.sdp` availability is independent: real MIDI mapping evidence cannot set native_available=true without the separate native evidence gate. ## Implementation details 1. Define strict, versioned declarative profile models, reusing shared MIDI ranges/parts/timing types. Keep them in profiles.py unless shared schema extraction is genuinely needed. Do not add a generic plugin framework. 2. Profiles describe target identity, part/channel, playable range or logical drum voice map, canonical articulations/aliases, velocity behavior, switch and CC actions, latch/momentary state/reset semantics, and provenance. 3. Support keyswitch notes, velocity-layer selection, and CC actions individually and in combination, using a small explicit action model rather than arbitrary code or an untyped settings bag. 4. Define timing units explicitly and convert with the reviewed exact tick helpers. Any profile lead time, switch gate, or release/reset offset must be representable at the selected PPQ; reject off-grid values. 5. Validate layer boundaries/ranges and intensity behavior; do not silently clamp, resolve overlapping layers arbitrarily, invent defaults, or accept aliases that collide after normalization. Test endpoints. 6. Load packaged JSON through importlib.resources so an installed wheel works outside the repository. An intentionally empty registry is valid; malformed JSON, inconsistent metadata, duplicate IDs/defaults, invalid maps, missing declared resources, and synthetic-production leakage must fail explicitly. Distinguish an empty registry from failed resource loading. 7. Provide deterministic profile selection: explicit IDs must match the part; missing/ambiguous verified defaults return named errors with safe actionable details. Public summaries reuse the reviewed ProfileSummary contract. 8. Compile a Score and explicit selected profiles into an EventPlan. The compiler accepts synthetic profiles in explicit tests, but production discovery/selection must exclude them. Resolve pitches/drum voices and articulation aliases against the selected map, never a global guess. 9. State is isolated per part/channel. Deduplicate latched selection actions while preserving required per-note momentary actions, switch releases, and CC resets. Restore a normal technique using its actual declared actions, not an assumed universal reset. 10. Account correctly for polyphony: same-articulation overlaps must not release controls still required by active notes. Incompatible overlapping state requirements must fail explicitly unless the profile has a supported mechanism. Reject unrepresentable overlapping physical switch triggers rather than merging away required retriggers or producing invalid notes. 11. Compute one common nonnegative pre-roll from control lead requirements and shift every part equally. Score.start is a logical origin, not additional pre-roll. Include all required release/reset tails in the shared end_tick. 12. Order same-tick releases, state changes, switches/CC, and musical onsets causally using EventPlan priority/sequence. Boundary retriggers must work with the reviewed writer's strict note-pair/overlap/channel checks. 13. Every musical/switch note gets a matching positive-duration release. Reject out-of-range notes, unsupported voices/techniques, colliding switch and musical pitches, shared channels across parts, and ambiguous state. 14. Enforce the 100,000-event budget and call the reviewed event-plan validator before returning. Surface named errors with public-safe fixed reasons. No silent dropped articulations, defaults for invalid profiles, or broad success-shaped fallback. 15. Keep service wiring and tool registry behavior unchanged for now. ## Required unit tests - JSON loading, version/identity/provenance, wrong/missing/duplicate resources, corrupt profiles, explicit empty registry, wheel-safe access. - Test-only exclusion; no real target claimed from synthetic fixture values. - Correct part/default/explicit profile selection and actionable missing/ambiguous profile failures. - Channels, playable ranges/drum voices, alias normalization/collisions, keyswitch/CC data, timing rules, layer gaps/overlaps/boundaries. - Keyswtich-only, CC-only, velocity-only and combined techniques. - Latched transitions/deduplication, momentary releases/resets, normal-technique restoration, same-articulation overlaps, incompatible overlaps, and retriggers. - Positive switch gates, no dangling/orphan notes, musical/switch collisions, part/channel isolation, nonzero logical origin, exact pre-roll/tails. - Off-grid timings, invalid/unsupported score content, deterministic output, and event-budget rejection. ## Required integration tests - Synthetic palm-muted lead, bass techniques, and articulated drums compile to exact independently expected events, then write/read back through Mido. - Assert exact keyswitch numbers, velocities/layers, CC values/timing/reset, common pre-roll, channel isolation, note pairing, and shared end. - Use a synthetic three-part score with overlapping compatible notes and boundary transitions; verify the compiler and MIDI writer agree. - Exercise packaged profile discovery in a built wheel outside the repository, proving an intentionally empty registry remains honest and resource loading is not current-directory dependent. - Run all relevant existing contract/MIDI/server/distribution regressions. These tests prove mechanics, not vendor compatibility. If real maps are verified, add separate evidence-based target cases and clearly distinguish their source. ## Verification and acceptance Run focused new tests, directly affected regressions, Ruff lint/format, strict mypy, and the complete current suite before reporting. Use the known working repository-venv pytest CLI fallback as needed. Clean up owned temporary files and child processes. Report two distinct conclusions: - Mechanics implemented/verified, with actual test evidence. - Full Step 5 production acceptance satisfied or BLOCKED by named missing mapping evidence. Do not declare readiness for Step 6 if that gate is open. ## Required report When complete, write your end-of-step report to ./prompts/report_5.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step The entire report must be inside exactly one plain triple-backtick fence. Include changed files, API/state/layer decisions, exact test/check commands and outcomes, production registry contents, public evidence attempts, separate mechanics/production/native status, and precise evidence needed to unblock. Stop after writing this report. Do not fabricate a passing gate or start Step 6.