11 KiB
Step 3: Implement the composition model and deterministic text planner
Objective and prerequisites
Step 2 has been reviewed and accepted: the .NET 10 stdio MCP lifecycle works, the production tool registry is empty, and all 130 tests pass.
Read the approved plan, the Step 2 report, and existing code before editing. Implement only the instrument-neutral composition model, validation, documented bounded English grammar, and deterministic basic pattern planning. This step does not require proprietary mappings.
Do not implement production profiles, keyswitch/CC event generation, MIDI/native writers, public generation tools, publication, audio, network calls or an LLM. Do not alter orchestrator prompts/plan, create later prompts, commit or delegate.
Files to create or modify
src\GAJ3T.MusicGen.RiffGrooveBuilder.Core\
Composition\BeatFraction.cs
Composition\Composition.cs
Composition\TrackPlan.cs
Composition\MusicalNote.cs
Composition\DrumHit.cs
Composition\CompositionDiagnostic.cs
Composition\CompositionPlanningResult.cs
Composition\CompositionValidator.cs
Composition\DescriptionParser.cs
Composition\CompositionPlanner.cs
tests\GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests\
Composition\BeatFractionTests.cs
Composition\CompositionValidatorTests.cs
Composition\DescriptionParserTests.cs
Composition\CompositionPlannerTests.cs
tests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests\
GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests.csproj
Composition\CompositionPipelineTests.cs
docs\text-description-contract.md
README.md
prompts\report_3.md
Small directly related typed enums/value objects/helpers may have their own files if clearer. Avoid public interfaces or abstractions with no actual use. IntegrationTests may add a Core project reference for in-process full-pipeline tests; refresh generated locks when required. No new package is needed.
Design and implementation details
Model and timing
- Core remains independent of DryWetMIDI and vendor schemas.
- Model tempo, time signature, key/root/mode, bar count, selected role tracks
and notes/hits. Use typed roles (
lead,bass,drums), articulations and drum voices, not unchecked magic strings. - Pitched notes hold absolute MIDI pitch and musical velocity/duration. Drum hits hold logical voices (kick, snare, closed hi-hat), not guessed SD3 note numbers. Articulations remain intentions, not vendor switch values.
- Beat positions/durations are exact fractions of a quarter note. Implement normalized immutable rational arithmetic with checked integer operations, comparison, and exact conversion to 960 PPQ ticks. Reject nonpositive denominators, negative starts and nonpositive durations.
- A bar is
numerator * 4 / denominatorquarter notes. Validate time signature fields and exact tick representability. Human "beat 1" in a meter refers to the denominator-note beat; document and test this explicitly. - Keep track planning independent of production profile verification. Planned pitches/velocities are musical choices, not evidence of plugin playability. Vendor ranges, profiles, channels and switch-state validation belong to Step 4.
- Validate MIDI numeric ranges, positive finite/representable SMF tempo, bar bounds, selected roles, note/hit duration and complete musical extent. Validate arithmetic/resource bounds before allocating large note lists.
- Diagnostics identify a stable code, field/phrase when applicable, and an actionable message. Invalid input cannot return a successful empty composition. Failure results have no usable partial composition.
Document the grammar before implementing it
The initial vocabulary is deliberately bounded; do not claim arbitrary English understanding. Write the text contract first, then make parser/tests match it.
Required supported concepts:
- Bar count, integer BPM, meter, and key/root (major or minor).
- Role clauses for lead/guitar, bass, and drums.
- Repeated root-note quarter/eighth/sixteenth-note lead or bass patterns and sustained root notes (one full-bar note per bar).
- Canonical sustain and palm-mute articulation intentions, binding modifiers to the relevant role, not every track. Actual support remains profile-gated.
- Drum placement on explicit numbered beats and closed hi-hat subdivisions.
- Representative documented paraphrases such as
120 BPM/120 bpm,4 bars/four bars,palm-muted/palm mute, andlead guitar/lead. Support ordinary whitespace/case/punctuation variation without deleting or ignoring meaningful unknown text.
The exact acceptance description from the plan must work:
Generate 4 bars at 120 BPM in E minor, 4/4: palm-muted eighth-note lead guitar, sustained root-note bass, kick on beats 1 and 3, snare on beats 2 and 4, and closed hi-hat eighth notes.
For that example, with zero lead-in at this planning stage:
- Four bars of 4/4 span exactly 16 quarter notes / 15,360 ticks.
- Lead: 32 eighth notes; starts every 480 ticks; duration 480 ticks; root E and palm-mute intention. Bass: four sustained notes, each 3,840 ticks.
- Kick: eight hits at beats 1/3; snare: eight at beats 2/4; closed hi-hat: 32 eighth-note hits. All start positions repeat on exact bar boundaries.
- Do not infer drum MIDI pitches or keyswitch values.
Document deterministic defaults, used only when a setting is omitted: 120 BPM, 4 bars, 4/4, E minor; lead root in MIDI octave 4 (C4=60), bass root in octave 2 (C2=36), velocity 96, sustain articulation unless explicitly changed. Thus E is MIDI 64 for lead and 40 for bass; these are composition defaults, not product mappings. Permit root names/accidentals within the documented key grammar and test enharmonic normalization.
If no role is mentioned, default to all three. When a role/part is explicitly mentioned, generate only explicitly selected roles (drum part clauses select drums). For omitted role patterns, default to root eighth-note lead, full-bar sustained bass, and the documented 4/4 kick-1/3, snare-2/4, eighth-note closed-hi-hat pattern.
Do not silently apply a 4/4 drum default to another meter. For non-4/4 drum
requests, require explicit valid drum part placement/subdivision if no
documented meter-aware default exists. Any omitted defaulted parts/settings
must be visible in DefaultsApplied; explicitly selecting a drum subset must
not silently add omitted parts.
Record every applied default with its value. Reject contradictions, malformed numbers, duplicate conflicting settings, invalid beat positions, unsupported articulations/patterns and unconsumed meaningful instructions. Genre labels, chord progressions, tuning instructions, arbitrary melodies, dynamics outside the supported grammar, and unknown text are not excuses for guessed behavior.
For resource safety, choose and document a single internal generated-event limit, estimate counts using checked arithmetic before expanding patterns, and return a specific diagnostic when exceeded. Do not add public resource configuration or silently truncate. Keep this limit generous enough for ordinary multi-bar descriptions and test its precise boundary.
Planning behavior
- Parser output and the final model must preserve explicitly supplied settings. Explicit modifiers apply only to their intended clause/role.
- Keep parsing/planning failures explicit. Catch only expected parsing, representability and checked-arithmetic errors at an appropriate boundary; do not convert arbitrary exceptions into apparently successful defaults.
- Identical text and options produce structurally identical compositions.
- No randomization, humanization, audio analysis or external semantic service.
- Preserve currently working MCP behavior. The production tool registry stays empty until Step 8; do not wire a premature generation tool.
Required tests
Unit tests
- Rational normalization/arithmetic/comparison, exact tick conversion, zero/ invalid denominators, negative positions, fractional unrepresentability and checked overflow.
- Full acceptance example with exact values, counts, starts, durations, articulation intentions, defaults and musical extent.
- Paraphrases, case/whitespace/punctuation, key accidentals/enharmonics, explicit role selection and omitted-setting defaults.
- Pattern subdivisions and sustained notes without drift across many bars.
- Time-signature quarter-note math and denominator-beat placement in at least one non-4/4 meter; invalid/nonrepresentable meters and beats rejected.
- Contradictory settings/clauses, malformed numeric text, unsupported/leftover meaningful words, unknown articulations and invalid requests.
- Numeric pitch/velocity/duration bounds and tempo/SMF representability.
- Exact resource limit and just-over-limit rejection before expensive expansion.
- Deterministic repeated calls and no shared mutable collection state between independent composition results.
Integration tests
Call the real Core parser -> planner -> validator pipeline in-process using the documented full description. Inspect all three tracks and exact musical timing. Also cover selected-role output, a documented non-4/4 description, and failures that yield actionable diagnostics with no partial successful composition. Retain the real-process MCP/scaffold integration tests; do not mistake the in-process composition check for the final public MCP generation integration.
Validation and exit criteria
Use targeted composition tests during development, then:
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 any project-manifest change before validating. Installed SDK:
C:\Program Files\dotnet\dotnet.exe; editor test discovery was unavailable,
so CLI execution is the known fallback.
Exit: supported descriptions deterministically produce validated multi-role compositions with exact timing, rejected text is not silently ignored, tests all pass, docs match behavior, and production mappings/writers/tools remain unimplemented rather than fabricated.
Mandatory worker report
When complete, write your end-of-step report to ./prompts/report_3.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
Entire report: exactly one plain triple-backtick fence, with no outside prose. Include changed files, grammar/default decisions and limits, exact commands and exit codes, test counts, unrun checks and reasons, issues and readiness. Explicitly note that accepting Step 3 does not satisfy Step 4's real production mapping evidence gate. Stop after the report.