9.8 KiB
Step 4: Articulation infrastructure and verified-profile evidence gate
Objective and current gate
Step 3 has been reviewed and accepted. All 318 tests pass; supported text yields instrument-neutral compositions with exact timing and articulation intentions.
Read the approved plan, the Step 3 report, the current Core composition model, and the compatibility inventory before editing.
Implement the generic profile validation and articulation event-planning infrastructure with synthetic test-only profiles. Production Eclips, Ray and SD3 mapping evidence is currently absent. Implement production profiles only if actual authorized evidence has appeared in the repository; never invent it. The infrastructure is actionable now, but synthetic passing tests CANNOT satisfy Step 4's production exit gate. If evidence remains absent, write a truthful BLOCKED report with readiness false and stop. Do not proceed to Step 5.
No later prompts, orchestration-document edits, commits or delegation.
Files to create or modify
src\GAJ3T.MusicGen.RiffGrooveBuilder.Core\
Articulations\InstrumentProfile.cs
Articulations\ArticulationRule.cs
Articulations\InstrumentProfileValidator.cs
Articulations\ArticulationPlanner.cs
Articulations\ArticulationPlanningResult.cs
Articulations\PlannedMidiEvent.cs
src\GAJ3T.MusicGen.RiffGrooveBuilder.Generation\
Profiles\InstrumentProfileCatalog.cs
Profiles\instrument-profiles.json
GAJ3T.MusicGen.RiffGrooveBuilder.Generation.csproj
tests\GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests\
Articulations\InstrumentProfileValidatorTests.cs
Articulations\ArticulationPlannerTests.cs
Articulations\InstrumentProfileCatalogTests.cs
tests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests\
GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests.csproj
Articulations\ArticulationPipelineTests.cs
docs\articulation-mappings.md
docs\format-compatibility.md
README.md
prompts\report_4.md
Small directly necessary typed value objects/test helpers may have separate files. Add a Generation test reference only if needed. No new packages. Use BCL JSON serialization for profile data, not a second MIDI library.
Implementation requirements
Profiles and catalog
- Reuse existing typed roles/articulation/drum voice enums and exact timing. Keep Core independent of DryWetMIDI and vendor file serialization.
- A profile identifies role, exact product/version, mapping version, evidence provenance/verification status, pitch range, channel, initial state and supported articulation/control rules. Store absolute MIDI numbers; octave label conventions must not determine switch values.
- Express only the required mechanisms: keyswitch notes with velocity and advance/duration semantics, velocity-layer constraints or verified articulation-dependent output, CC number/value actions, and verified combinations. State/reset semantics must be explicit rather than implicit defaults guessed from product names.
- Support drum voice-to-note mapping and verified CC state as data. Do not assume GM or choose real SD3 pitches.
- Validate IDs/roles/versions/evidence, all MIDI ranges, layer boundaries, nonnegative advances, positive switch durations, duplicate/conflicting rules, channel/state constraints and switches colliding with playable notes.
- Unsupported articulations or unmapped drum voices are explicit diagnostics. Invalid/unverified production profiles must not be selectable as usable.
- Embed the profile catalog in Generation and load it independently of cwd. With no real evidence, its content is an honest empty list, not fake Eclips, Ray or SD3 entries. Unknown profile/default selection returns actionable diagnostics; no synthetic production fallback.
- The embedded catalog is the only production data source for now. No filesystem plugin search, runtime profile editor, user plugin system, vendor installation scanning, network access or arbitrary configuration discovery.
- Synthetic profiles live only in tests, have obviously synthetic identities, and are not embedded, returned, or registered as production targets.
- Malformed catalog resources fail explicitly; do not catch them and return an empty "successful" catalog. The intentionally empty resource is distinct.
Event planning
- Accept a validated composition and explicit matching profiles. Preserve the source composition; produce a new immutable typed event plan and diagnostics.
- These are MIDI event intentions (pitch/velocity/channel/tick/priority), not handwritten MIDI encoding or DryWetMIDI event objects. Actual MIDI construction remains Step 5 and must use DryWetMIDI 8.0.3.
- Include musical note-on/off intentions, mapped drum note-on/off intentions, keyswitch note-on/off, required CC/state changes and releases/resets.
- Cover keyswitch-only, velocity-only, CC-only and combined rules. Document the smallest clear velocity-layer semantics and verify boundaries; reject unsupported/conflicting requested velocities rather than silently clamping. Any profile-specified articulation transformation must be explicit and distinguishable from an accidental mutation of musical dynamics.
- Respect configured latched versus momentary behavior. Suppress redundant latched state changes, not required per-note momentary switches. Never leave keyswitch notes stuck or issue reset events not specified by the profile.
- Compute the largest required switch advance across selected tracks and use
one shared nonnegative lead-in offset for the entire arrangement. All musical
starts/ends shift consistently; report
LeadInTicks. Do not clamp controls to tick zero or shift only one role. - Preserve deterministic same-tick ordering: previous note-offs/releases, state-changing controls/keyswitches, then musical note-ons. Ensure transitions have the intended state when a prior note-off and new note-on share a tick.
- Track-global keyswitch/CC state cannot express conflicting simultaneous articulations. Reject conflicts unless the actual profile provides a verified representable route; no channel-per-note workaround or guessed behavior.
- Preflight channel collisions between independently controlled tracks and profile musical/switch collisions. Validate arithmetic/timing and event ranges, including lead-in and final releases.
- Return a complete valid plan or explicit failure with no usable partial plan. Report exact total musical extent plus any final required release event. No broad catch/silent fallback or success-shaped invalid-input handling.
Documentation
- Explain mapping fields, synthetic-only examples, velocity semantics, state transition/ordering, channels, shared lead-in, unsupported behavior and evidence.
- Update compatibility inventory with generic infrastructure completed but real product/version/mapping/native acceptance evidence still missing.
- README must not claim playable Eclips/Ray/SD3 mappings, MIDI files or native generation exist. The production MCP registry remains empty.
Required tests
Unit
- Profile validation: versions/provenance/status, roles, pitch/channel/velocity/ CC ranges, layer boundaries, invalid advances/durations, duplicates and musical/control collisions.
- Each mechanism separately and combined, using clearly synthetic profiles.
- Exact resulting note/CC numbers, values, channels, starts, ends and ordering; note-off pairing, unchanged source data, deterministic immutable results.
- Latching, repeated same articulation, momentary retrigger/release, transition to sustain, CC initial/reset state and explicit velocity-layer behavior.
- Unsupported articulation, unverified/missing profile, unmapped drum voice, conflicting simultaneous articulation/state and channel collisions.
- Three-track shared lead-in with different advances, tick-zero boundaries, same-tick transition ordering, final releases and checked overflow.
- Embedded catalog loads from unrelated cwd; honest empty production state; unknown profile resolution errors; malformed data never becomes silent empty.
Integration
Run description -> composition -> profile validation -> event planner with synthetic profiles. Inspect all three role plans, exact shared timing, switches, velocity and CC events. Also cover missing production profiles and explicit failures with no partial plan. Do not write MIDI/native files or expose tools. Retain all prior tests.
Validation and exit gate
Run targeted articulation tests during development, then Release solution build, all xUnit tests, and locked restore. Use:
dotnet build .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-restore
dotnet test .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-build
dotnet restore .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx --locked-mode
Restore after a manifest edit first. SDK executable:
C:\Program Files\dotnet\dotnet.exe. CLI is the known test-discovery fallback.
Two separate conclusions are mandatory:
- Infrastructure implementation/test status: pass/fail with exact evidence.
- Full Step 4 readiness: false/blocked unless actual production mappings for all three targets satisfy the approved evidence gate.
If evidence remains missing, do not search personal directories or fabricate product profiles merely to claim readiness. List exactly what is needed and stop without Step 5, even if every infrastructure test passes.
Mandatory worker report
When complete, write your end-of-step report to ./prompts/report_4.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
Put the entire report in exactly one plain triple-backtick fence, with no outside content. Include changed files, exact commands/exit codes/counts, mechanism/velocity/state decisions, skipped checks, missing evidence and the two distinct readiness conclusions above. Stop after writing the report.