188 lines
9.8 KiB
Markdown
188 lines
9.8 KiB
Markdown
# 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](plan.md), [the Step 3 report](report_3.md), 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
|
|
|
|
```text
|
|
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
|
|
|
|
1. Profile validation: versions/provenance/status, roles, pitch/channel/velocity/
|
|
CC ranges, layer boundaries, invalid advances/durations, duplicates and
|
|
musical/control collisions.
|
|
2. Each mechanism separately and combined, using clearly synthetic profiles.
|
|
3. Exact resulting note/CC numbers, values, channels, starts, ends and ordering;
|
|
note-off pairing, unchanged source data, deterministic immutable results.
|
|
4. Latching, repeated same articulation, momentary retrigger/release, transition
|
|
to sustain, CC initial/reset state and explicit velocity-layer behavior.
|
|
5. Unsupported articulation, unverified/missing profile, unmapped drum voice,
|
|
conflicting simultaneous articulation/state and channel collisions.
|
|
6. Three-track shared lead-in with different advances, tick-zero boundaries,
|
|
same-tick transition ordering, final releases and checked overflow.
|
|
7. 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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
1. Infrastructure implementation/test status: pass/fail with exact evidence.
|
|
2. 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.
|