# Bounded text-to-composition contract (Step 3) This is a deterministic English subset, not arbitrary English understanding. The Core API is in-process; Step 8's MCP `generate_project` reuses it unchanged. This text contract alone implies no production profile, plugin playability, drum mapping, audio or native-format compatibility. Generic profile/event planning and a Standard MIDI writer consume successful models. MCP generation requires explicit admitted profile IDs: AGLP/AGM/AGT/AME Documented Lead profiles and ABJ Sustain-only Bass exist. ABJ PalmMute explicitly fails `unsupported_articulation`; AMR and all Drums mappings remain unavailable. Selecting unavailable roles or omitting a selected role's explicit profile fails the complete request rather than changing the grammar/defaults or dropping those roles. ## Grammar Input is nonempty text of at most 16,384 UTF-16 characters. Keywords are case-insensitive; ordinary whitespace (including newlines), commas, colons, semicolons and full stops separate clauses. `and` can join clauses or numbered beats. One optional `generate` may prefix the description. Settings and role clauses can appear in any order. Punctuation separates tokens; it does not erase unsupported words or turn decimal numbers into integers. ```text description = ["generate"] clause { separator clause } setting = [ "at" ] integer "bpm" | bar-count ("bar" | "bars") | [ "in" ] root ("major" | "minor") | numerator "/" denominator role = pitched | "drums" | drum-part pitched = [articulation] [pattern] ("lead guitar" | "lead" | "guitar" | "bass") | ("lead guitar" | "lead" | "guitar" | "bass") [articulation] [pattern] pattern = subdivision ["root-note" | "root notes"] | "sustained" ["root-note" | "root notes"] subdivision = ("quarter" | "eighth" | "sixteenth") ("note" | "notes") articulation = "sustain" | "palm-muted" | "palm mute" drum-part = ("kick" | "snare") "on" ("beat" | "beats") integer { "and" integer } | "closed hi-hat" subdivision root = A..G [ "#" | "b" | "♯" | "♭" ] bar-count = integer | "one" | "two" | "three" | "four" | "five" | "six" | "seven" | "eight" | "nine" | "ten" | "eleven" | "twelve" | "thirteen" | "fourteen" | "fifteen" | "sixteen" ``` Hyphens in `eighth-note`, `root-note`, `palm-muted` and `hi-hat` are interchangeable with spaces. `sustained` specifies the full-bar pattern, not a vendor articulation. Explicit `palm mute sustained bass` is therefore meaningful. Role-local modifiers never leak to another role. Patterns cannot straddle a different clause or be specified both before and after a role. Integers are unsigned ASCII decimal tokens (no signs, decimals, exponent notation, mixed digit/word numbers or thousands separators). Only bar counts also accept the words one through sixteen. Beat lists use `and`, not commas. Repeated identical settings/role clauses/parts are accepted once, without duplicating events; conflicting repetitions and duplicate beats are rejected. Only one articulation and one pattern are allowed per pitched clause. No synonyms other than those listed here are promised. Examples: > 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. > generate four bars at 120 bpm in F♯ minor: lead guitar palm mute sixteenth notes > 3/8, 2 bars: kick on beats 1 and 3, snare on beat 2, closed hi-hat eighth notes Unsupported meaningful text is an error, including genres, chord progressions, tuning, melodies, swing, dynamics/velocity instructions, unknown articulations, open hi-hat and additional drums. `heavy metal lead`, `120.5 bpm`, `lead legato`, `bass quarter notes and eighth notes` and `kick on beats 1, 3` do not become guessed defaults. Failures have stable codes, fields and offending phrases where applicable, with actionable messages; they expose no partial plan/model. ## Defaults and role selection Every applied default is returned as a field/value pair in `DefaultsApplied`, on both the parsed description and successful composition: | Field | Value when omitted | | --- | --- | | `tempoBpm` | 120 | | `bars` | 4 | | `meter` | 4/4 | | `key` | E minor | | `roles` | lead,bass,drums, **only if no role or drum part is mentioned** | | `lead.pattern` | eighth notes | | `bass.pattern` | sustained (one full-bar root note per bar) | | `lead.articulation`, `bass.articulation` | sustain | | `lead.rootOctave`, `bass.rootOctave` | 4, 2 (only for selected pitched roles) | | `lead.velocity`, `bass.velocity`, `drums.velocity` | 96 (only for selected roles) | | `drums.kick`, `drums.snare`, `drums.closedHiHat` | beats 1 and 3; beats 2 and 4; eighth notes | Any explicit role selects **only** the mentioned roles. `bass` produces no lead or drums; `kick on beat 1` selects drums but adds neither snare nor hi-hat. `drums` alone (also `lead and drums`) selects the full default drum pattern only in 4/4. If any drum part is explicit, only explicit parts are generated, even if `drums` also appears. A non-4/4 request selecting drums must provide one or more explicit drum parts; no 4/4 pattern is silently applied. Defaults for unselected roles/omitted explicit-subset drum parts are not applied. C4=60, C2=36; add the normalized root pitch class, so E gives lead 64/bass 40. Enharmonics normalize to pitch classes 0..11 and canonical sharp names (Db -> C#, B# -> C, Cb -> B). Octaves are chosen *after* normalization; B# lead is C4=60. Key mode is preserved but does not change repeated root patterns. These are musical defaults, not production instrument ranges or mappings. ## Exact timing, validation and resource bounds All positions/durations are normalized signed Int64 rational quarter notes; denominators must be positive. Default rational zero is 0/1. Arithmetic uses checked integer intermediates and rejects results outside Int64 representation. Tick conversion at **960 PPQ** must be exact and fit signed Int64. A bar is `numerator * 4 / denominator` quarter notes. Human beat 1 is the start of the bar; beat N is `(N-1) * 4 / denominator`, **not** N-1 quarter notes except in /4 meters. Meter numerator is 1..255; denominator must be a power of two with an exactly tick-representable denominator beat (1..256). Quarter/eighth/sixteenth patterns step by 1, 1/2, 1/4 quarter notes. The subdivision must divide a bar exactly; no partial final note is truncated. Sustained pitched notes span a full bar. Kick/snare durations are one denominator beat; hi-hat durations equal its subdivision. Each event starts at/after zero, has a positive duration and fits within the declared arrangement. Gaps/rests are allowed: `kick on beat 1` does not need a last-bar-end hit. The model's declared musical extent is always all bars, independently of the last event's end. No planning lead-in is added. Bars must be a positive Int32; pitch is 0..127 and sounding velocity 1..127. Tempo must be positive and finite with `60,000,000 / BPM` in the SMF range 1..16,777,215 microseconds per quarter note. That value is rounded to the nearest integer, midpoint away from zero, as SMF tempo resolution requires; the requested BPM remains in the model. The parser accepts integer BPM only. Undefined enum values, empty/duplicate roles, empty selected tracks and pitched/drum event-kind mismatches are errors. One fixed internal generated-event limit is **100,000** notes plus hits combined (not MIDI note-ons/offs or switches). Exactly 100,000 is accepted; 100,001 is rejected with `event_limit_exceeded`, without expanding patterns. Counts, arrangement extent and representability are preflighted with checked arithmetic before allocating event lists. No public limit override, truncation, randomization or shared mutable result collection exists. The validator also checks manually constructed models, independent of parsing. Parsing/planning return explicit failure results; only expected numeric, representability and checked-overflow errors are translated to diagnostics. Profile ranges, articulation support and switch/channel validation remain Step 4 and require real evidence, currently absent. ## Standard MIDI output boundary (Step 5) The text parser/planner remains unchanged. After successful composition and explicit profile/event planning, Generation's in-process `MidiFileWriter.WriteFile(absolutePath, composition, eventPlan, token)` writes SMF type 1 at 960 PPQ; `Write(stream, composition, eventPlan, token)` borrows a writable stream. See [the MIDI API guide](../README.md#in-process-standard-midi-generation) for exceptions, no-overwrite staging, cleanup and synchronous cancellation limits. The conductor's tempo/meter stay at zero; every role uses the same planned lead-in and global end marker, including rests and later control tails. The four-bar example's **15,360 unshifted ticks** become **15,600** with the integration tests' invented 240-tick lead-in. Its 32/4/48 musical counts exclude keyswitch control notes; those test-only numbers are not vendor mappings. Requested BPM remains in the model; output metadata rounds the valid quotient nearest-integer, midpoint away from zero. DryWetMIDI 8.0.3 accepts the actual meter denominator through **128**; Core continues accepting **256**, but the writer rejects /256 with a clear library-limitation exception. Each SMF delta must be at most **0x0FFFFFFF**; the conductor's unsplit end gap also bounds global `EndTick`. Long gaps fail, never wrap or acquire filler events. These output constraints do not silently alter parser/Core validation or musical semantics.