167 lines
9.7 KiB
Markdown
167 lines
9.7 KiB
Markdown
# 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.
|