71 KiB
Architecture overview
The amended approved implementation plan defines the
authoritative contracts and sequencing. The native/MIDI MCP service is operational
on Windows with real installed-wheel stdio acceptance. Target defaults are the
AME 4.0.1 / AMR 4.1.0 Riffer normal/palm-mute subsets and SD3 3.4.4 SL-DFH
core three-voice subset. SD3 native writing needs an operator-local template.
Every actual saved native/MIDI file is validated before one atomic publication.
Application open/play/save/reload and Cubase acceptance remain unrun.
agp/sdp are request aliases; actual metadata uses griff/briff/sd3p.
Step-numbered sections retain the original layer acceptance history; the
current native service report,
Riffer codec and profiles
supersede historical default/capability statements in earlier step sections.
See the
Step 10 evidence for separate outcomes.
Current release 0.2.0 includes the accepted Step14 pitch/voicing and
corrected Step15 public hybrid layers below. __version__ is the sole package
version source; setuptools metadata and MCP initialization derive from it.
The final persisted wheel/sdist, exact original E2 prompt, source/installed
numeric acceptance and new user-output publication are recorded in
report16. Earlier reports/artifacts remain historical.
Restart the MCP after updating, then open a fresh chat for current schemas;
the existing configured venv needs no config edit or config reinstall.
Bounded local deterministic prose is not arbitrary language understanding.
Events / and backslash are reserved slides, not implemented: origin/target/
timing codec evidence is still required. Chord slash/Over bass is implemented,
not a slide. Exact explicit pitches are never secretly retuned/revoiced to
the key or to rescue an impossible native fingering. Live playback is unrun.
Implemented in Step 1
- A
src-layout Python package, standard setuptools build backend, one literal public version, and metadata derived from that version. - An import-only initializer with no service startup, logging, dependency imports, filesystem writes, or transport initialization.
- pytest unit tests and offline sdist/wheel integration tests, Ruff, and strict mypy. AnyIO's pytest plugin provides SDK-aligned asynchronous test support.
- Package-data inclusion for six versioned profile JSON resources (three target defaults and three explicit standard fallbacks).
- An evidence inventory; no target instrument is certified.
Implemented in Step 2
riff_groove_builder.schemas is the authoritative Pydantic v2 contract;
riff_groove_builder.errors supplies explicit domain exceptions and stable
public codes. Neither imports MCP, starts a server, inspects files, or loads a
profile registry. The initializer remains unchanged and dependency-free.
Tool boundary and reuse
ListInstrumentProfilesRequestaccepts exactly{}.ProfileListResultcontains three target defaults and three explicit standard fallbacks; the contract also permits an honestly empty registry in isolated tests.ProfileSummaryfixes Eclipse/griff to lead, Ray5/briff to bass, and SD3/sd3p to drums. Unavailable MIDI or native capabilities require explicit limitations. IDs are opaque, nonblank strings, not evidence that a mapping exists.GenerateMusicRequestimplements Section 7's parameter names and limits: nonblank 1–4000-character descriptions; 1–64-character safe basenames; unique, nonempty selected parts/formats; finite numeric tempo 20–300 BPM (including integer/fractional BPM); 1–256 integer bars; bounded meter; key grammar below; per-part profile IDs; seed 0–2147483647 (default 0); and a strict fallback boolean (default true).- Optional
cc_eventsdefaults empty. EachScheduledControlcontains exactly selectedpart, exactRationalBeatrelative to musical start, strict MIDIcontrollerandvalueintegers 0–127. Normalized duplicate points, sub-tick beats, out-of-duration points and unselected parts are invalid; part association is rechecked after description inference. The post-compilationapply_scheduled_controlshelper preserves original note/switch events and timing, appends unique sequence keys on the profile channel, sorts controls before note-ons, and shares the existing 100,000-event budget. Articulation CC collisions fail with actionableINVALID_REQUEST; no implicit resets or vendor-effect inference. See the concrete CC example. Empty controls return the original compiled plan unchanged. Native preflight distinguishes supported Riffer CC1 stairs from unsupported controllers and SD3's precisesd3_native_controller_not_supportedlimitation. Note/channel/ role/release corruption is checked first and is never controller fallback. - Unspecified
parts,formats, tempo, bars, meter, key, and profiles stayNone; explicit null on those optional fields also means unresolved.model_fields_setdistinguishes omission from explicit null. Serialize requests withmodel_dump_json(exclude_unset=True)to preserve this distinction.ProfileSelection.selected()excludes unresolved entries. Empty profile selections are valid; profile-ID values, when present, are nonblank. No defaults, text interpretation, or production profiles are chosen. - Explicit parts constrain profile selection and applicable formats immediately: agp needs lead/bass, sdp needs drums; actual griff/briff/sd3p suffix requests require lead/bass/drums respectively. If parts are unresolved, these checks must run again after text/default resolution. Registry lookup, profile-ID/part identity, supported vocabulary, text contradictions, and verified articulation availability necessarily belong to later services.
tool_input_schema(name)andtool_output_schema(name)return fresh schema dictionaries for exactlylist_instrument_profilesandgenerate_music. Step 3 reuses these and the models rather than duplicating their fields. Both output schemas have an object root and explicit mutually exclusiveoneOfsuccess/error branches.GENERATION_OUTPUTandPROFILE_LIST_OUTPUTare reusable typed union adapters for validation and JSON round trips.
All contract objects reject unknown fields. Numeric inputs reject booleans, numeric strings, nonfinite numbers, and fractional/floating representations of integer-only fields; meter's integer literals also receive an explicit strict type check. Lists of enums and declared unique strings reject duplicates. Empty arrays are rejected where selection/content is required; empty registry, warnings, assumptions, overrides, supported-articulation lists, and note/event tracks remain meaningful (including rests or unavailable capabilities).
Basenames use [A-Za-z0-9][A-Za-z0-9_-]{0,63} and reject case-insensitive
CON, PRN, AUX, NUL, COM1–COM9, and LPT1–LPT9. Separators, traversal, drive
prefixes, extensions, trailing dots/spaces/newlines, and non-ASCII characters
cannot pass. This is lexical validation, not output-root or link confinement.
Key grammar is one A–G pitch-class letter (case-insensitive), optionally one
ASCII # or lowercase b, one or more ASCII spaces, then major or minor
(case-insensitive). Structured key inputs also accept an attached lowercase m
minor suffix: Em, F#m, Bbm. Optional outer ASCII spaces are accepted. Examples:
Bb major -> A# major, db MINOR -> C# minor, Cb minor -> B minor.
Normalization uses the twelve sharp-spelled pitch classes and lowercase mode;
it retains pitch-class meaning, not original enharmonic spelling. Tabs,
newlines, Unicode accidentals, double accidentals, bare letters/other modes, and
multiple or contradictory keys are rejected. This is key-string parsing only,
not description interpretation.
Internal structures and units
MusicalIntent requires resolved description, parts, tempo, bars, meter, key,
and seed; rhythm terms/techniques are unique nonblank names, not an implemented
text vocabulary. It computes exact duration as
bars * numerator * 4 / denominator quarter-note beats using Fraction.
RationalBeat serializes as {"numerator": 1, "denominator": 3} with strict
nonnegative integer numerator and positive integer denominator. Ratios reduce
exactly (2/6 -> 1/3, 0/n -> 0/1); .value returns fractions.Fraction.
PositiveBeat additionally rejects zero. Floats, decimal approximations, and
string fractions are not timing inputs. Sub-tick logical durations survive
serialization exactly; later quantization must explicitly accept/reject them.
LogicalNote is a discriminated union: PitchedNote(kind="pitched") has lead
or bass plus numeric pitch, while DrumNote(kind="drum") has drums plus a
logical voice name. Both have exact start/duration, normalized finite intensity
0–1 (inclusive, never clamped), and a nonblank articulation name. Numeric
pitches 0–127 only establish MIDI's logical envelope, not an instrument's
playable range. Voice/articulation names are not verified maps.
Score retains intent, rational shared start/end, and exactly one track per
selected part in selected-part order. Positive duration equals bars/meter;
every note belongs to its track and fits the shared interval. Empty note lists
allow rests. These contracts do not compose notes or modify random state;
Step 6 supplies the separate composer.
ScheduledEvent is a discriminated union of NoteOnEvent, NoteOffEvent,
and ControlChangeEvent, not a bag of optional payloads:
| Quantity | Representation/range |
|---|---|
| Absolute event tick, priority, sequence | strict nonnegative integers |
| MIDI channel | 0–15, not 1–16 |
| Note number, controller number/value | 0–127 |
| Note-on velocity (including keyswitches) | 1–127 |
| Note-off velocity | 0–127; default 0 |
| Note role | musical_note or keyswitch |
| CC role | articulation_control |
The stable ordering key is (tick, priority, sequence); keys must be unique
within each part track. Priority is supplied metadata, not a scheduler or
a claim that arbitrary numeric priorities satisfy profile-specific causality.
EventPlan retains the logical score and one event track per selected part,
positive ticks-per-quarter (default 960), common nonnegative musical start/end,
and a shared overall end allowing control-release tails. Musical tick duration
must exactly match the score; all events fit the overall end, musical events
fit the musical interval, and musical note-ons precede its end. Keyswitches and
controls may occupy pre-roll/tails. Plans reject more than 100,000 events.
Step 4 now implements exact grid checks, sorting, pair/retrigger validation,
channel independence, and event writing. Compiling profile-specific controls,
verified lead times, and articulation state transitions remain Step 5.
Results, errors, and validation limits
GenerationResult contains the planned status, resolved metadata, nonempty
artifacts, and warnings. ResolvedGeneration requires exact selected-part
profile coverage, unique profile IDs, and end tick >= start tick. Artifact
size is a positive integer; parts/profile IDs are nonempty and unique. Paths
must be lexically absolute Windows or POSIX local-file paths (without nulls or
line breaks); they are not resolved or checked on disk. Native artifacts
contain exactly one applicable part. Only one combined MIDI can be reported,
and it must cover all selected parts. Artifact profile IDs must match resolved
parts. Duplicate format/part outputs and unselected warning parts are rejected.
complete cannot contain substituted parts or native-unavailability warnings.
midi_fallback requires a combined MIDI artifact naming substituted parts,
an explicit NATIVE_FORMAT_UNAVAILABLE warning for each such part, and no
native artifact for a substituted part. Unavailability warnings must identify
substituted parts. Other public warnings can be part-specific or global.
These validate internally feasible claims, not successful generation: actual
existence/size, requested-format coverage, fallback permission, verified maps,
resolved root/link confinement, atomic publication, and read-back are Step 9's
responsibility. Synthetic in-memory tests do not create or certify artifacts.
GenerationError {code, message, details} supports these named exceptions:
InvalidRequestError, UnsupportedDescriptionError, ProfileRequiredError,
ProfileNotFoundError (same PROFILE_REQUIRED code, with a missing-ID message),
UnsupportedArticulationError, NativeFormatUnavailableError,
OutputExistsError, OutputIOError, and SerializationError.
Messages are fixed actionable public guidance. GenerationError.from_domain
copies only the declared code/message and explicitly provided finite JSON
details; it never reads exception causes, traceback text, or private files.
Callers must supply public-safe details, not raw exception strings/paths.
Step 3 sets MCP isError for domain failures; protocol failures remain SDK
errors. These contracts themselves implement no transport behavior.
Published schemas use JSON Schema 2020-12 vocabulary, including uniqueItems,
static conditional part/format/profile associations, native artifact shape,
and complete/fallback branch conditions. Standard JSON Schema cannot compare
two arbitrary field values (end >= start, rational arithmetic, profile-ID
correspondence, fallback warning coverage, or cross-track ordering). Those
remain enforced by the authoritative Pydantic validators; schema validation
alone is not sufficient at a service boundary. JSON Schema also treats 4.0
as an integer mathematically; the typed models intentionally reject it in
integer-only fields. Nonfinite floats are not JSON numbers at all. Downstream
code must always validate with these models, not rely solely on client-side
JSON Schema checks. Do not mutate validated model fields/containers in place;
revalidate changed payloads rather than using unchecked model_copy(update=...).
Implemented in Step 3
server.py uses the installed official MCP 1.30.0 low-level Server,
@server.list_tools(), @server.call_tool(validate_input=False), and
mcp.server.stdio.stdio_server. The SDK owns framing, JSON-RPC parsing and
dispatch, IDs, notifications, initialization/negotiation, and EOF cancellation.
There is no second protocol layer or custom shutdown method. FastMCP inference
is unnecessary: tool definitions copy the exact reviewed tool_input_schema
and tool_output_schema, with no wrapper or weakened union.
The SDK's JSON-Schema-only input checker is disabled deliberately. Its error
messages can echo input values, and JSON Schema accepts 4.0 as an integer.
Both handlers instead validate arguments using the authoritative Pydantic
request models, including strict types and cross-field validators. Validation
details contain only model-known field names, numeric list positions,
<unknown> placeholders for unknown properties, Pydantic/authored reason codes,
and fixed, authored field corrections (grammar, bounds, shapes and recovery actions).
They never copy input, raw descriptions, validation messages/contexts, exception
representations, or causes. An issue at the whole-request boundary uses
$request only when no precise field is available. Part/format/profile and CC
cross-field validators use typed custom reasons; their public issues identify
formats, profiles or cc_events, not a generic root value_error.
The service repeats these same safe checks after omitted parts resolve.
Results are constructed as authoritative output models, serialized into explicit
SDK CallToolResult objects with structured content and the complete identical
public JSON object in a single text block. Returning
CallToolResult bypasses the SDK decorator's automatic output-schema check;
the typed constructors and tests against the published schemas provide that
validation without losing isError on the success/error union. Narrow type
ignores are confined to the SDK's untyped decorators; strict project mypy
remains enabled. Schema constraints, isError, strict models and SDK lifecycle
are preserved; text/description guidance and structured-key shorthand are Step 11 updates.
Exactly two tools are registered:
list_instrument_profilesreturns the real six-profileProfileListResult.generate_musiccalls the concrete service described in Step 9, returning real published Standard MIDI or an explicit typed error. The old development skeleton is historical in report_3.md and is no longer the server's behavior.
Known DomainErrors preserve only their declared public code/message/details.
Unexpected handler failures are not silently relabeled as invalid requests:
they log the failure class (without values, traceback, or exception text) on
stderr and return the SDK's ordinary error result with a fixed internal-error
message. Internal output-model failures follow this diagnostic path as well.
Unexpected failures never become success-shaped fallback.
__main__.py requires --output-dir, validates/resolves an existing directory,
configures stderr logging only on CLI execution, and runs the SDK on asyncio.
The root is retained in the SDK lifespan context and pinned by the service.
Importing the package, server, or entry module starts nothing and prints nothing.
Startup rejects URI/network/device/drive-relative syntax, controls, missing
roots, and regular files. It does not create roots or test writeability.
Step 9 additionally implements root/ancestor reparse checks, volume
classification, identity checks, collisions and atomic publication; trusted ACL
and race/crash limits remain explicit below.
Observed SDK protocol behavior
Real subprocess tests exercise the installed SDK, not an invented dispatcher:
- Normal initialization sends/accepts the initialized notification. Requested supported versions are retained; unsupported requested versions negotiate to an SDK-supported version. Only the tools capability is registered.
- String and integer request IDs are preserved. Valid notifications and unknown notifications produce no response. Ping continues working after bad input.
- Invalid tool arguments are typed
INVALID_REQUESTtool results. Unknown tools are SDKisErrortext results, not declared domain errors. - An unknown method outside the SDK request union or invalid method parameters
yields
INVALID_PARAMS(-32602). A recognized but unregistered method (resources/list) reaches SDK dispatch and yieldsMETHOD_NOT_FOUND(-32601). - Invalid JSON, array messages, and messages without a required method are
handled by the SDK as stream-validation exceptions: a generic
notifications/message(Internal Server Error) is sent, with no invented parse-error response or ID. The connection remains usable. - The SDK parses a request-like object with
id: nullas a notification. An unknown such method is logged/rejected without a response. Tests preserve this observed behavior rather than asserting a nonexistent parse error. - The SDK's validation logs can contain raw values. A CLI-only logging filter replaces its known stream/request/notification-validation and unlisted-tool diagnostics with fixed safe messages. Parsing, dispatch, and protocol responses are untouched. Operational diagnostics are not suppressed. Debug logging is not enabled by this application.
- stdout is exclusively valid UTF-8 newline-delimited JSON-RPC, including the SDK's generic logging notifications. Human-readable startup errors/diagnostics remain on stderr. Closing stdin exits zero, including before initialization; there is no protocol shutdown request.
The tests run the installed editable package with -I -B and no PYTHONPATH
or PYTHONHOME, from a different repository-local working directory. The normal
flow uses the official client, including its bounded stdin-close/termination
cleanup. A small raw subprocess test client validates every stdout line and
enforces bounded waits and exact-process kill fallback before workspace cleanup.
Valid supported requests generate real MIDI; unsupported/native-disabled
requests create no output directory. Built-wheel execution outside the checkout
is additionally covered below. Manual MCP-client/Cubase/plugin checks are UNRUN.
See startup and Windows client configuration.
Implemented in Step 4
riff_groove_builder.midi consumes the authoritative EventPlan; it neither
composes music nor compiles a Score into controls. The reviewed models, tool
schemas and errors are reused by the operational service.
Exact timing and ordering API
beats_to_ticks(Fraction | RationalBeat | int, ppq=960) -> intrequires exact nonnegative quarter-note beats and a legal positive, non-SMPTE PPQ (1–32767). Floats, numeric booleans/strings, and sub-tick fractions are rejected.bar_ticks(TimeSignature, bars=1, ppq=960) -> intusesbars * numerator * 4 / denominatorwithout intermediate floats.quarter_tempo(tempo_bpm) -> inttreats BPM as quarter notes/minute, regardless of meter denominator. It rounds the exact decimal-rational reciprocal60_000_000 / Fraction(str(bpm))to the nearest integer microseconds/quarter, ties to even, requiring 1–0xFFFFFF. It never calls a meter-adjusted BPM helper. TheEventPlanretains the stricter intent tempo range of 20–300 BPM.validate_event_plan(EventPlan) -> Nonerevalidates the whole mutable model graph before checking MIDI-specific invariants. Unsupported payloads, strict type errors, timeline violations, duplicate ordering keys, and the existing 100,000 scheduled-event limit therefore cannot bypass the writer through unchecked model copies or list/field mutations. That budget counts scheduled events, not the bounded conductor/name/EOT metadata.
Logical note offsets relative to Score.start and durations must fit the grid.
A nonzero logical score origin is not extra pre-roll: the compiler's intended
conversion is musical_start_tick + ticks(note.start - score.start). The writer
preserves the supplied compiled ticks and does not reconstruct notes from the
score or claim to validate profile-specific compilation.
Absolute events are stable-sorted only by their authoritative
(tick, priority, sequence) key, never by pitch or a replacement generic control
priority. Delta times are computed once when constructing Mido tracks.
All deltas are strict integers in 0–0x0FFFFFFF (the four-byte SMF VLQ range).
With no artificial conductor filler events, its final EOT delta spans the
entire plan, so this writer also limits the shared end_tick to 0x0FFFFFFF.
It rejects larger plans rather than emitting invalid deltas or inventing timing
events. PPQ 960 represents straight and triplet subdivisions exactly; other
resolutions and fractions are accepted only when exact.
Notes, channels, and shared tracks
Active notes are keyed by (channel, note) within each part. Every musical
note and keyswitch needs a positive-duration matching-role release. Orphan
releases, dangling notes, wrong-role releases, and same-channel/same-pitch
overlapping onsets are errors, including collisions between keyswitch and
musical roles. This conservative policy does not guess voice allocation.
At a same-pitch boundary the supplied ordering must release the old note before
the new onset. Roles may reuse a pitch only after release. Different pitches
on a part's channel are valid polyphony; the same pitch on separate channels
is independent.
Each used channel is reserved to its owning part for the whole plan, including keyswitch-only and CC-only usage. Different parts cannot share a channel even at disjoint times. A part may use several otherwise disjoint channels. Empty parts reserve none. No channel 10/zero-based 9 assumption or program change is added. Role labels guide validation/diagnostics; they are not extra MIDI metadata.
SMF type 1 has Conductor followed by Lead, Bass, and/or Drums in the
resolved selection order, not a fixed instrument order. Conductor name, tempo,
and meter are at zero (standard clocks-per-click 24, notated 32nds/quarter 8).
Part names are at zero. Controls and keyswitches stay in their affected part
track. Exactly one EOT per track is at the common end_tick, preserving common
pre-roll, exact musical span, and any control-release tail. Musical onsets
cannot occur before the musical start or at/after the musical end; musical
releases cannot exceed it. Keyswitches/CCs may occupy pre-roll and tails.
Disk validation and failure boundaries
write_midi(path: Path, plan: EventPlan) -> Path constructs and validates Mido
SMF bytes in memory, exclusively opens only the supplied path (xb), closes
the saved file, and reads its actual bytes back. validate_midi_file(path, plan) -> None exposes that disk expected-content check without writing or cleanup.
Both enforce header signature/length/type/track count/PPQ and compare every
absolute-tick message payload, track name/order, tempo/meter, channel,
note/CC/velocity, event sequence, and shared EOT. Opening with Mido alone is
not success; readable but changed content, missing/extra events, corruption,
truncation, and trailing data fail. Exact comparison with the already-pair-checked
plan also validates pairing of the saved events.
Failures use existing named SerializationError, OutputExistsError, and
OutputIOError with fixed safe reason codes, never raw exception values or
paths. Expected Mido/encoding and OS failures are caught narrowly; unexpected
programming failures propagate rather than becoming a successful fallback.
Failed writes/read-back remove only the newly exclusively created file,
checking its device/inode identity before unlinking. Pre-existing data and
replacements are not removed. Cleanup failures or ownership changes themselves
raise explicit IO failures; no success is returned if cleanup is denied.
The standalone validator never deletes an input, even if corrupt.
No parent directories are created. Relative and absolute Path destinations
are accepted, with no claim of output-root confinement, all-format publication,
fsync/crash durability, or adversarial race-proof filesystem operations.
The Step 9 service supplies staging/root/link checks and publishes the complete
artifact set only after actual saved-file validation.
Independent evidence and limitations
Tests construct a synthetic three-part Score/EventPlan with a nonzero score
origin, 240-tick common pre-roll, triplets, retriggers, keyswitches, CCs,
120-tick tail, and non-GM drum channel/pitch. Mido reloads real saved production
files; independent MIDIUtil addNote/duration and controller APIs build equivalent
reference files in 4/4, 3/4, 6/8, and 7/8, including fractional BPM.
Comparison preserves exact note/control ticks, channels, pitches, onset and
release velocities, and control payloads. Fixtures explicitly match MIDIUtil
1.2.1's release-velocity convention (copies the onset velocity); production
preserves any valid supplied release velocity rather than imposing that rule.
MIDIUtil type 1 inserts a conductor before its three user tracks; meter uses a denominator exponent in its API. Its tempo truncates instead of rounding (137.5 BPM: 436363 versus the correctly rounded production 436364). Tempo is tested independently rather than treated as an equivalent payload. Reference EOTs occur at each track's local last event; production EOTs share the full tail. These explicit metadata conventions are excluded from normalized note/control equality, with separate assertions for conductor/meter/tempo/end semantics. Duplicate removal, deinterleaving, and origin adjustment are disabled in the reference to avoid silently changing the fixture's intended events. Repeated production inputs, including permuted event-list input order, yield identical bytes with the tested Mido version.
Test workspaces live under .test-artifacts and are removed in fixture cleanup.
No licensed or checked-in binary fixtures, production mappings, native codecs,
or Cubase/plugin acceptance are introduced. Focused verification:
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_midi.py tests\integration\test_midi_files.py -q
Implemented in Step 5: mechanics and Standard MIDI fallback
profiles.py defines strict schema-version-1 declarative identity/provenance,
MIDI range/voice/alias/layer/action models, typed registry failures, and
deterministic production selection. importlib.resources loads an explicit
manifest from packaged resource initializers; three resources provide standard
pitched lead/bass and GM Level 1 percussion. Inaccessible/malformed/undeclared resources are errors,
not empty-registry success. Test-only data cannot enter production discovery.
articulations.compile_score revalidates explicit score/profile graphs and
produces a reviewed EventPlan. It uses exact quarter-note timing, per-part
channel ownership, latched deduplication, per-note momentary pulses/CCs,
reference-counted held controls, declared normal setup/restoration, and
conservative incompatible-state/physical-trigger rejection. One common pre-roll
and shared release/reset/restoration tail retain alignment and logical origin.
Deterministic release/reset/selection/onset priority and sequence preserve
writer causality; the 100,000-event budget and reviewed MIDI validator are
enforced before return.
See articulation profiles for schema/action details,
supported overlap boundaries, interpolation, named errors, API examples, exact
public standard sources and policy, and the remaining vendor evidence gate. Synthetic three-part
tests verify independently expected compiler events and real Mido disk read-back.
Built-wheel installed and ZIP-resource probes run outside the repository and
confirm exactly the three standard-only profiles and normal default selection.
Standard three-part tests also assert independent expected events and real MIDI
read-back. Public summaries add mapping_kind: instrument | standard_midi
(default instrument for existing contracts). Standard profiles have matching
standard_midi provenance, public fact references and separate generator policy;
neither can certify vendor evidence. Channels 0/1/9, normal/sustain without
controls, full legal pitched range, GM percussion numbers and linear positive
velocity policy are explicit. instrument identifies routing intent, not
compatibility; public product names and limitations disclose unverified vendors.
Only the explicit summary discriminator/provenance additions changed contracts; the exact MIDI APIs and generic compiler remain unchanged. Step 9's operational server lists the three profiles and reuses this compiler. Step 6 uses standard fallback, under the amended plan. Vendor maps remain unverified; native formats and application acceptance are separately unverified. Standard fallback does not close those evidence gates.
Implemented in Step 6: deterministic text and composition
description.resolve_description(GenerateMusicRequest) -> DescriptionResolution
revalidates the authoritative request and returns intent: MusicalIntent,
assumptions: list[str], overrides: list[str] (unique, nonblank records).
The records feed the service's ResolvedGeneration metadata, not a
fabricated successful GenerationResult. No files, registries, network/model
providers or service transports are used by resolution.
compose.compose_score(intent, selected_profiles, *, ppq=960) -> Score
revalidates intent/profile graphs, then composes on one rational timeline.
The registry remains authoritative: callers select using
registry.select(resolution.intent.parts, request.profiles or ProfileSelection()).
The composer does not guess instruments from vendor words. Compile that score
with articulations.compile_score, then use the existing midi.write_midi.
If overriding PPQ for direct use, pass the same PPQ to the compiler.
Format/capability/fallback decisions and post-resolution request-format checks
are service responsibilities; the resolver does not serialize native
formats or infer output filenames/profiles.
Exact description grammar
Case is folded and all whitespace collapsed before matching whole words. Clauses may appear in any order. This is a closed grammar, not free-form prose:
| Input | Interpretation |
|---|---|
120 BPM, 137.5 bpm, +.25 bpm |
Signed decimal numeric quarter-note BPM; final value must be 20–300. No exponent, fraction, textual number or unit conversion. |
4 bars, 1 bar |
Numeric integer-valued count, 1–256. Decimal spelling 4.0 bars also has integer value; fractional values fail. |
in 7/8, meter 3/4, 6 / 8 |
Numerator 1–16; denominator 1, 2, 4, 8 or 16. No mixed/changing meter. |
E minor, Bb major, key F# minor, Em, F#m |
A–G, optional single ASCII #/b, major or natural minor, including attached minor m; canonical sharp-spelled key. Case-insensitive text, including accidentals. |
lead, lead guitar, guitar, riff |
Lead part. |
bass, bass guitar, bass riff, bass groove, bass guitar riff/groove |
Bass part; slash here means either word, not literal /. |
drum, drums, drum groove, drums groove |
Drum part; groove is optional filler. |
lead and bass, bass, drums, lead + drums, bass & drums |
Part list. Separate positive part mentions also combine. Text order resolves to lead, bass, drums order. |
only bass and drums, lead and bass only |
Only-selection over that entire contiguous list. An additional positive part outside it is contradictory. |
no drums, without lead and bass, exclude bass, drums |
Exclude the entire contiguous list, never include negated words. With only exclusions, subtract from all three and record that baseline assumption. |
quarter, eighth, sixteenth |
Straight slots of 1, 1/2, 1/4 quarter-note beats, respectively. Optional note, notes, -note, -notes; straight is filler. |
rests, rest, no rests, no rest |
Omit the final slot of every bar, or omit none. No arbitrary rest schedule. |
rock, metal |
The two bounded original template policies below; riff/groove do not invoke a larger genre engine. |
slow, fast |
Fixed tempo candidates 80/160 BPM. Conflicting numeric/qualitative tempos are errors unless structured tempo overrides them. |
normal, sustain |
Same global normal technique. Sustain is an alias, not a pedal, CC64 or a different gate. |
palm mute, palm-mute, palm muted, palm-muted, palm muting |
Canonical palm_mute, applied only to selected lead/bass. Mixed-request drums stay normal and assumptions disclose applicability; drum-only palm mute errors. Standard pitched profiles cannot realize it. |
Simple subdivision, template and rest instructions apply globally. Palm mute has
the pitched-only applicability above; no arbitrary per-part technique schedule is
inferred. There are no per-part rhythms, sections, note
spellings, chords, arbitrary durations, accents or dynamics syntax.
Use the structured parts list to retain noncanonical part order.
Excluded and included occurrences of the same part are contradictory; an empty
selection is an error. no drums only is rejected as ambiguous rather than guessed.
Negation is supported only by the listed part exclusions and no rest(s);
other negated instructions are errors, not silently ignored.
Only these exact filler words are ignored:
please create produce generate make write a an the some simple music pattern groove for with and at in of on notes note key tempo meter straight.
Comma, period, semicolon, colon, exclamation/question marks, & and + are
separators; other punctuation/unrecognized tokens fail. At least one recognized
instruction or music/pattern/groove is required (please alone fails).
Whole-word matching never interprets bassoon as bass or leadership as lead.
Filler is not evidence that arbitrary prose was understood.
Tempo, bars, meter and key default to 120 BPM, 4 bars, 4/4, E minor.
No explicit part language defaults to lead, bass, drums, with a record.
Pattern defaults are eighth, rock, no_rests, normal, also with records.
Seed is the authoritative request's seed (default 0), never read from text.
Structured tempo/bars/meter/key/parts take precedence, even over distinct
contradictory or out-of-range scalar text for the same field. Every non-null
structured value records its value and observed text candidates (even if none);
it is not mislabeled as an assumption. Repeated equivalent values, including
enharmonic keys, are not contradictions. Null means unresolved.
Structured overrides never authorize unknown material or changing instructions.
then, to, from, changes/changing, ramp, accelerando, ritardando, rallentando,
speed up and slow down fail explicitly, including with a structured tempo.
Only complete supported beat-range clauses (below) consume from/to before this guard.
Unresolved conflicts raise DescriptionConflictError, an
UnsupportedDescriptionError subtype with public UNSUPPORTED_DESCRIPTION
and the field to correct. Unknown words, unsupported material and out-of-bound
text raise named UnsupportedDescriptionError; invalid/mutated requests retain
InvalidRequestError. Unknown instruments (piano, violin, etc.), unsupported
modes/techniques, vendor names, audio, swing/arbitrary triplets, tempo changes,
polyrhythm and song sections are never discarded into a default loop.
Typed rational phrase schedules (Step 12)
TimedNote contains reduced rational start/positive duration, a closed
normal/palm_mute/pinch_harmonic technique and optional finite intensity.
PhrasePlan contains a sole pitched part, low-tonic register policy, exact
duration and an ordered, nonoverlapping, event-budget-bounded note list.
MusicalIntent.phrase_plan is optional; a phrase must fit its selected part and
score duration and cannot coexist with global template terms/techniques.
Defensive revalidation rejects mutated invalid plans. No public score tool is added.
The bounded description parser composes two clauses, never a whole-prompt match:
[chugging] palm mute/muted/muting eighth/8th [notes] from X to Y and
triplets on B&A with the A as a pinch harmonic that carries over a whole note in the second/2nd measure. Palm/pinch hyphens and spacing around & are accepted.
X/Y are inclusive 1–4 labels with optional &; B is a beat 1–4. Straight notes
advance by 1/2 quarter beat; triplets by exactly 1/3. The last triplet ends at
quarter beat 8, tying through all of measure 2. Reversed ranges, overlaps,
out-of-bar labels, insufficient length, non-4/4 meter, extra global rhythm or
techniques and other prose fail without dropping instructions. This text grammar
requires lead only and both clauses, not arbitrary melodies/sections/ties.
Longer explicit scores contain the phrase once and then silence.
The original 1-to-3& / beat-4 request yields six PM eighths, two PM triplets and
one PH of duration 13/3, at quarter beats 0,1/2,1,3/2,2,5/2,3,10/3,11/3.
The hold infers two bars when omitted; 120 BPM remains the disclosed default.
A is a count, not a pitch. The composer generically applies per-note timing,
technique and intensity, resolving each profile articulation without fallback.
All notes use the tonic nearest MIDI40 within actual range and native tuning;
default AME Em is E2/MIDI40. Seeded intensity uses the unchanged local RNG policy
unless a typed note intensity is present. All PPQ conversion remains exact;
event budgets, compiler ordering, CC handling and atomic file transactions remain
unchanged. Simple patterns do not use the phrase path or change their notes.
Deterministic composition and exact musical policy
- One common interval starts at 0 and ends at
bars * numerator * 4 / denominatorquarter-note beats. Every part shares it, and the existing writer emits a common end-of-track tick even after rests. BPM is always quarter-note BPM, including 6/8. - Slots restart at every bar. If the chosen subdivision does not divide the bar (e.g. quarter in 7/8 or 1/16), only the last slot is shortened to that bar boundary. This is an explicit policy, not duration drift or rounding.
- Rests omit the last slot, including its drum hits, of every bar. A single-slot bar with rests is entirely silent but retains its exact duration. No requested technique is dropped even for silence: profile validation still runs.
- Major intervals are 0,2,4,5,7,9,11; natural minor 0,2,3,5,7,8,10. Lead requires a full ascending seven-degree scale fitting the actual inclusive profile range. Bass requires a root/fifth pair (0,7) fitting the range. Choose a root nearest MIDI 64 for lead and 40 for bass (lower root breaks a distance tie), among candidates that fit the entire palette. C4 = 60, E4 = 64, E2 = 40; profile note numbers, not vendor octave labels, remain authoritative. No pitch clamping, chromatic notes, dropped degrees or guessed alternate octave mapping.
- Lead rock degree cycle is (0,2,4,6), metal (0,0,4,1), zero-based; each bar starts at degree 0. Other slots add a seeded 0/1 degree variation modulo seven. Bass rock alternates root/fifth; metal uses root,root,fifth,root. These are original simple policy patterns, not factory/demo content or genre fidelity.
- Drum hats use selected profile alias
closed_haton every active slot. Metrical pulse ismax(slot_length, 4/denominator); on pulse-aligned slots, alternatekickandsnarestarting with kick each bar. Metal additionally adds kick on off-pulse slots. This is the explicit odd/compound-meter rule, not a claim of idiomatic 6/8 or automatic accent grouping. It avoids losing snares when a coarse subdivision skips denominator units. - Resolve all three required drum aliases before allocation. All physical notes are deferred to the compiler's selected profile lookup; no GM/vendor number is embedded in composition. Missing aliases fail rather than substituting.
- Pitched gates fill the slot; drum gates are
min(slot_length, 1/4 beat). Adjacent same-pitch notes only touch at boundaries (compiler releases first). Each slot has seeded intensity from {0.5, 0.625, 0.75}, shared by simultaneous drum hits. Profiles perform real supported velocity conversion, never clamping. - Local
Random(seed + part_offset)uses lead/bass/drums offsets 0/1/2, so adding/reordering other parts does not perturb a part's notes. Calls never change global random state. Same intent/seed yields the same score/events/bytes in the tested Python environment; no cross-runtime RNG certification is claimed. - Revalidate exact profile coverage, part identity and distinct channels.
Resolve each requested articulation to a canonical profile name, with only
one global canonical technique allowed.
UnsupportedArticulationErroridentifies part/profile/technique, including honest palm-mute failure for standard maps. No softer-note or guessed-switch approximation exists. - Before constructing notes, count exact active slots/hits over all bars and
reserve at least two events per note against the existing 100,000-event budget.
The compiler remains authoritative for additional control events/pre-roll/tails.
Grid-check slot offsets, lengths, drum gates and total duration using existing
beats_to_ticks; off-grid PPQ fails without rounding.CompositionError(SERIALIZATION_ERROR) identifies range, missing-voice, coverage/channel, unsupported direct-intent terms or budget problems. Existing exact timing/profile/compiler errors are not hidden by fallback.
The unchanged production registry supplies only Standard MIDI normal/sustain, channels 0/1/9, legal pitched ranges and declared GM aliases. It supplies no vendor techniques. One synthetic switch-profile unit test proves real compiler coupling only; it does not advertise vendor compatibility. No authoritative shared model/profile/compiler/writer changes were necessary in Step 6.
Focused validation:
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_description.py tests\unit\test_compose.py tests\integration\test_text_to_midi.py -q
& '.\.venv\Scripts\python.exe' -m pytest -q
& '.\.venv\Scripts\python.exe' -m ruff check .
& '.\.venv\Scripts\python.exe' -m ruff format --check .
& '.\.venv\Scripts\python.exe' -m mypy --strict src tests
Actual-disk tests cover lead/bass/drums/all-parts, 3/4, 6/8, 7/8, nondefault
tempo/key/length, independent event/pitch/channel/duration/pairing assertions,
precise expected bass/drum sequences, seed byte determinism and text-driven
rhythm changes. Tests use self-cleaning UUID directories under .test-artifacts.
The unchanged Step 3 tool handlers are not a text-generation service.
Implemented in Step 7 fix: real native Riffer codec
formats.NativeCapability is a small frozen/slotted internal result with part,
format, available and a fixed safe reason. It is not an exporter framework,
artifact, or caller-supplied authorization. The concrete AGP APIs are:
check_agp_capability(part: Part, profile: InstrumentProfile) -> NativeCapabilityrequire_agp_capability(part: Part, profile: InstrumentProfile) -> NativeCapability
Both reject non-lead/bass requests and defensively revalidate the full profile
through checked_profile, preserving the existing target/part/format and
native-metadata constraints. Valid wrong-part profiles raise the existing
ProfilePartMismatchError; malformed/mutated profiles raise
InvalidProfileError, not native-unavailable.
Checks are still pure/no-IO and keep format=agp as a legacy request alias.
The evidenced native subset returns available=True, reason=riffer_xml_2_1;
standard/synthetic maps return false with riffer_profile_not_supported.
Matching metadata alone is insufficient: strict native settings, provenance
and supported target/version are required.
write_riffer(path, plan, part, profile) exclusively creates an actual .griff
or .briff staged file. It validates/recompiles the score/event plan, assigns
physical strings with bounded backtracking, serializes real XML note/CC fields,
and invokes validate_riffer_file on actual saved bytes. The separate reader
checks structure, physical validity and requested musical content, not a second
serialization. Native PPQ 480 conversion is exact; unsupported pre-roll/tails,
off-grid events, other CCs/techniques or impossible strings fail explicitly.
Legacy write/validate AGP names alias these APIs, never emit .agp files.
At completion of Step 7 the two target profiles were nondefault. The service available-codec
guard remains: native service registration is deliberately not part of this
fix. Standard default MIDI/fallback behavior remains operational. Public
artifacts/summary metadata expose actual suffixes, while requests also accept
agp/sdp. The subsequent Step 8 fix adds SD3; no application automation is added.
See native schema/evidence/acceptance. Plugin/Cubase acceptance
remains unrun, independently of actual XML generation/read-back success.
Implemented in Step 8 fix: native SD3 template song codec
formats.sdp supplies a bounded balanced-text 3.4.4 parser, read-only
inspect_sdp_template, template-aware check/require APIs, exclusive staged
write_sdp and independent validate_sdp_file. The explicit typed optional
template: Path | None is an operator-local input, never a bundled private
project. Missing optional template is sdp_template_required; supplied bad,
unreadable, versioned or map-mismatched templates are errors, not fallback.
Standard profiles still report sdp_profile_not_supported with no IO.
The nondefault toontrack.sd3.3.4.4.core.v1 profile covers only locally verified
SL-DFH kickR/36, snareR/38 and hatsTP/42. The codec validates actual pad aliases
and input channel before use. Channel 9, intensity interpolation and neutral
song controls are generator policy, not vendor defaults.
All source active song tracks/clips/references are replaced with one original note-only track/clip. Packed status/pitch/velocity triples and exact finite decimal beat times are independently decoded from saved bytes and compared with a recompiled score/event plan. Unsupported event semantics, pre-roll, tails, release velocity, precision and corrupt input fail explicitly. Every non-song byte (kit/mixer/tracker and other operator state) is preserved. Only the staged output is exclusively written and read back; no publication.
Native tests use newly authored original fixtures and an opt-in read-only local template integration. SD3 application/Cubase acceptance is UNRUN, not inferred. At completion of Step 8, service wiring, CLI template configuration and defaults were untouched; Step 9 fix below now implements all three. See SD3 API, limitations and evidence and current verification.
Implemented in Step 9 (updated by native integration fix)
service.GenerationService(output_root: Path, *, registry: ProfileRegistry | None = None, sd3_template: Path | None = None) loads the packaged registry and pins
the existing local root. CLI --sd3-template threads a typed operator Path through
run_stdio/create_server; no tool argument can select a template.
Its two public operations are list_instrument_profiles() -> ProfileListResult
and generate_music(request: GenerateMusicRequest) -> GenerationResult.
The SDK handlers use this same concrete service, with no alternate composition
or exporter framework. The optional registry supports isolated tests; production
loads exactly six declared resources: three target defaults and three explicitly
selected standard fallbacks. Strict target validation still enforces evidence,
versions, tunings/voices, switches, velocity bands and timing policy.
The service revalidates mutable request graphs, resolves text, rechecks
parts/formats/profile associations after inference, selects/revalidates maps,
composes/compiles once, and preflights actual native capabilities/content before
any output staging. Omitted/null formats request MIDI and relevant native suffixes.
agp expands to selected lead .griff and bass .briff; sdp to drums .sd3p.
Aliases and actual names deduplicate. Explicit MIDI-only skips native capability
preflight and works with target maps even without a template.
Only known unavailable capability/representation limits permit fallback. Preflight
uses codec content/grid/routing checks without writing. Narrow fixed reason codes
cover common pre-roll/tails, exact native grid/decimal precision, unsupported Riffer
CC and impossible physical-string assignment. Invalid plans/maps, search exhaustion,
template errors, serializer/read-back/IO faults are errors, never fallback.
An explicitly supplied template is validated at construction and checked by source
identity/size/mtime/SHA-256 during listing/generation and before publication.
Even a MIDI-only request never hides an explicitly invalid configured template.
Composition and compilation reuse existing exact-timing APIs and event budget.
Registered writers create <basename>.mid, <basename>_lead.griff,
<basename>_bass.briff, <basename>_drums.sd3p as requested. Each exclusively
opens its path and invokes an optional on_created(fstat) hook before writing:
the service records that actual new file's identity, including on partial failure.
The hook is the only shared writer change; standalone APIs retain their behavior.
The service independently invokes each saved-file validator after the writer's
own read-back, bounds files to positive <=16 MiB, rejects reparse/nonregular/
hardlinked files, and checks identity/size/mtime/SHA-256 stability. It constructs and
revalidates the anticipated result including JSON serialization, then publishes.
A result-model error is SERIALIZATION_ERROR / invalid_generation_result before
publication, not a post-publication false failure.
MIDI is emitted only when requested or needed for fallback; it includes all selected
parts. Successful native-only requests have no MIDI. fallback_for contains selected native-requested
parts whose capability was unavailable. Each gets NATIVE_FORMAT_UNAVAILABLE;
status is midi_fallback. Explicit MIDI-only success is complete. Every selected
standard-only map gets STANDARD_MIDI_MAPPING, never vendor compatibility.
Target subsets get per-part VERIFIED_SUBSET_LIMITS warnings.
Missing drum template with allowed fallback preserves lead/bass natives and adds
one combined MIDI with fallback only for drums. Disabled fallback errors before
stage creation. Runtime profile summaries combine real preflight readiness with
version/library/subset/default and application-limit disclosures.
Results contain only actual published absolute paths, actual sizes, part/profile
IDs, resolved musical metadata, assumptions/overrides and public warnings.
Known failures use typed GenerationError with MCP isError; unexpected bugs
retain the sanitized diagnostic/SDK error path. Profile listing is now real.
Filesystem guarantees and limitations
- Tool inputs contain only the strict safe basename, not arbitrary paths.
Startup rejects URI/UNC/device/drive-relative/network-drive syntax,
.., files, nonexistent roots and all existing root/ancestor symlinks or Windows reparse points (including junctions). Windows drive type must be fixed/removable/RAM. The root and every ancestor's device/inode identity are pinned and rechecked. - One exclusive UUID stage under the root is owned per request (at most three name attempts). No global scratch or persistent job database is used. Directory checks verify stage identity, non-reparse status and parent confinement. Enumerations examine at most requested file count + 1 entries (at most five); only the exact planned names and claimed file identities are allowed. No sidecar manifests, renamed MIDI substitutes or extra formats are generated. All snapshots/hashes are rechecked immediately before commit, including earlier files after the last writer. Unknown injected content causes an error.
- A same-volume
Path.renameof the whole completed stage publishes<root>\<basename>. Windows only:os.renamerefuses existing destinations, including empty directories. Precheck improves diagnostics; the rename itself supplies no-replace semantics for concurrent same-name requests. Noreplace, merge, POSIX replacing rename, or delete-destination workaround is used. Non-Windows generation failsOUTPUT_IO_ERROR / no_replace_publication_requires_windowsbefore staging. - Existing output/sentinel data are never overwritten.
OUTPUT_EXISTS / destination_existsis explicit. Only a verified owned stage is cleaned: first verify all present entries have recorded exclusive-create identities and are regular, non-reparse and singly linked; unlink only those owned files, then remove that specific empty stage. Unexpected content or lost identity refuses cleanup; nothing follows links or recursively deletes output-root contents. - Cleanup failure is explicit
OUTPUT_IO_ERROR / stage_cleanup_failed, carrying only the original domain code (orinternal), and can leave the owned stage for operator inspection. Root/stage replacement similarly refuses unsafe cleanup. Permissions, disk failures, missing roots and publication failures remain visible; fallback cannot hide them. - These portable path/lstat/recheck APIs do not provide comprehensive hostile race safety. A local actor able to replace directories/files between checks and opens/unlinks/rename can race them. Use an operator-controlled root and ancestors/volume with trusted ACLs; no handle-relative Windows NT namespace confinement, cross-process malicious-lock protocol, mount-change defense, or power-loss/fsync durability is claimed. Directory mode 0700 is advisory on Windows, not an ACL guarantee. Root identity checks are not indefinite handle pins and cannot prove against filesystem file-ID reuse.
- Publication success is the commit point; a client disconnect or process crash afterward can leave a valid published output without a received response. No post-publication rollback or acknowledgement database is implemented.
The new unit/integration tests exercise these concrete guarantees, including
failure injection, concurrent same-basename publication, actual Windows
junctions, real stdio generation from another working directory and disk MIDI
inspection. Exact executed evidence and persistent example artifacts are in
prompts/report_9_fix.md. Native software integration is verified; application
acceptance remains separately unrun.
Installed software acceptance in Step 10
tests/integration/test_distribution.py extends the existing offline build
fixture and reuses the raw stdio client from test_stdio.py, without a second
production transport or duplicate build harness. The default build creates an
sdist then builds its wheel. The earlier dependency-free separate-venv import
test remains; the new server test installs that wheel with pip --no-index --no-deps --no-cache-dir --target into an owned test directory.
The -I -B bootstrap explicitly prepends this install target and asserts the
actual package, server, service, schemas, profiles, compiler, MIDI, native
boundaries, resource packages and __main__ entry resolve there (16 locations),
not editable src. Distribution metadata must also resolve to the target.
It reuses development-venv runtime dependencies: this is isolated application
installation/execution, not a fresh full dependency-environment certification.
The process working directory is the pre-existing parent outside the
checkout; the test does not create files there.
Six packaged JSON files are compared byte-for-byte to wheel archive members,
then discovered/read as installed resources and listed over real stdio.
Initialize, exactly two tools, exactly six profiles, public
input/output schemas, explicit MIDI, default fallback and native-only fallback
are exercised with explicit standard IDs. Independent Mido inspection checks type 1 / PPQ 960,
436364 microseconds/quarter at 137.5 BPM, 7/8, Conductor/Lead/Bass/Drums, common
end 6720, exact onsets/gates, legal positive onsets, complete note pairs and
channels 0/1/9. Returned paths/sizes/profile IDs/status/warnings must agree.
All three request-format policies produce the same 324-byte musical content,
not different native encodings. Additional real installed-server calls use an
original minimal SD3 template and target defaults to generate actual full
default/native-alias/actual-name/MIDI-only outputs, exact CC1 stairs/resets and
per-part controller fallback. Missing-template target fallback, disabled fallback
and native collisions are also checked. All saved .griff/.briff/.sd3p and
MIDI files are independently checked against the same requested score.
Native-disabled, unsupported palm mute, Unicode unsupported text and collision errors are schema-checked and cannot leave new output directories. The client validates every UTF-8 newline stdout message as MCP JSON-RPC; deliberate malformed input produces only a generic protocol notification on stdout and sanitized diagnostics on stderr, with successful ping recovery. Both initialized and pre-initialize EOF exit zero. Reads/writes/termination are bounded; cleanup kills only the owned child if EOF times out, reaps it, and removes the owned distribution/install/output workspace even on failure.
The full suite, Ruff lint/format, strict mypy, pip check and final real
sdist/wheel build are separate checks. See current tested configuration and
outcomes and
report_10.md. These are native/MIDI software checks,
not receiver, Eclipse/Ray5/SD3 application or Cubase acceptance.
Operational service and remaining native boundaries
MCP client
-> SDK stdio lifecycle and two operational tools
-> strict Pydantic request/domain/result models (implemented contracts)
-> deterministic closed-grammar description and coordinated score (implemented)
-> versioned target subset defaults or explicitly selected standard fallback profiles
-> native check/require (Riffer subsets; SD3 subset requires local-template preflight)
-> explicit service fallback policy for known unavailable native capabilities only
-> Mido SMF writer / actual Riffer XML and SD3 template-song codecs
-> read-back validation -> staged, atomic local publication -> typed result
The registered tools are list_instrument_profiles and generate_music.
The SDK owns JSON-RPC lifecycle/negotiation. stdout is reserved for stdio
protocol traffic; diagnostics go to stderr. No HTTP application, GUI, database,
plugin host, audio engine, DAW automation, or model provider is introduced.
Keep intent, logical notes, scheduled MIDI events, and native representation separate. The planned shared timeline uses rational beat arithmetic before tick quantization, aligned lead/bass/drum tracks, deterministic local random state, and profile-specified control timing. Mido is the production MIDI library; MIDIUtil is an independent test-fixture library, not a second production writer.
Instrument-specific production profiles must identify exact instruments, versions, source provenance, playable ranges, drum maps, keyswitch/CC semantics and layers. Standard-only profiles instead identify their standard and explicit generator policy; they cannot use verified vendor provenance or imply native availability. Synthetic fixtures test mechanics but cannot become production maps. Guitar/bass native adapters may share code only if evidence proves shared layout.
The service publishes complete validated native/MIDI artifact sets under an operator-configured local output root, rejecting unsafe names and collisions. Unavailable native capabilities may permit explicitly reported MIDI fallback; unverified vendor mappings and unexpected serialization/IO errors cannot be hidden by a fallback success. A selected standard profile must remain explicitly standard-only in metadata/warnings, never represented as a working vendor map. A preset-only native format may contradict the requested song-content requirement and needs a decision, not a fabricated implementation.
Sequencing and evidence
Step 11 fixes a verified text-only feedback failure: the prior profile result
exposed only a count in text, and lead + sd3p with valid E minor exposed only
generic guidance while the useful error object lived in structured content.
Both result representations now contain the same complete safe JSON object.
Unit, official-client, raw-stdio and installed-wheel tests decode text and
assert equality with structured content. The text-only recovery scenario lists
real IDs, receives a formats correction, receives a separate missing-profile
recovery action, and generates/read-backs actual guitar .griff and .mid
using a returned ID and structured Em. Unrequested CC91 is removed by the
test consumer, not silently stripped by the server. Step 12 adds the bounded
beat-range/triplet/cross-bar-PH phrase above; arbitrary triplet melodies still error.
MCP schema constraints and protocol handling have not been simplified or replaced.
An existing LM Studio setup needs an operator MCP restart and a fresh chat to
refresh cached tool definitions; no live client/configuration is changed here.
Steps 2–4 define typed contracts, an honest stdio skeleton, and a controlled MIDI writer without inventing instrument data. Step 5 generic profile/compiler mechanics and standard-fallback production profiles are implemented; vendor mapping acceptance remains gated and does not block standard-only Step 6. Standard-only composition, native Riffer writers/validators and the native SD3 template-song codec and native/MIDI service wiring are implemented. Step 9 fix verifies actual native integration, not a bypass of application acceptance. Mapping evidence gates production instrument claims; separate native structure and actual application acceptance gates each native writer. The compatibility inventory records those gaps. The existing AGP native fix and SDP native fix distinguish completed codecs from remaining application work. Independent Step 10 software acceptance does not satisfy the original full native definition of done.
Step 14: internal explicit pitch and polyphonic attack foundation
Step14 introduced internal atoms/plans, not a public score tool. Step15 below
now exposes those atoms through bounded public hybrid description lanes.
The legacy low-tonic PhrasePlan and ordinary pattern paths are unchanged.
pitch.py exposes immutable PitchToken, ChordSymbol, ExplicitVoicing,
NotationToken, and ResolvedVoicing values and these reusable functions:
parse_pitch(text)parses exactly one uppercase A–G, optional single ASCII#/b, optional signed octave. C4=60; C-1=0; G9=127. Accidentals cross octave boundaries correctly (Cb4=59, B#3=60). Unsupported spellings or explicit pitches outside MIDI 0–127 fail..midion an octave-free token fails until register resolution;.pitch_classremains available.parse_chord(text)parses a bare major root,m/minminor, optional root octave after the quality, optional(add4), and optional/orOverbass. Thus Em4 is E4–G4–B4, not a fourth/add4 quality. Intervals are major[0,4,7], minor[0,3,7], major-add4[0,4,5,7], and minor-add4[0,3,5,7]. Digits always mean root octave, never seventh/extensions. Other qualities, extension syntax, or guessed slides fail.[C3 E3 G3]is an explicit whitespace-separated octave-qualified pitch set; duplicate numeric pitches (including enharmonic duplicates) are invalid.tokenize_notation(text, kind="note" | "chord")lexes compact runs up to 4000 characters: F#F#, DD, BbBb, CEG, C4E4G4, and concatenated chord atoms.text,start,end, and exactleading_spacepreserve token boundaries and spacing width without assigning rhythmic meaning. Note and chord modes are deliberately separate: C4 is one note in note mode, a major chord root in chord mode. Unknown/ambiguous tails are errors, not ignored text.resolve_voicing(value, profile)returns sorted independent MIDI pitches and disclosedassumptions. An absent note/root octave selects the playable root nearest MIDI40 (lower wins ties) under the chosen profile range/tuning, before constructing the chord. It does not search for another octave if the complete chord then fails to fit. Explicit pitches are never changed to match a key. Slash bass is strictly lower than every upper chord tone: Em4/B2 and Em4OverB2 ->[47,64,67,71]; Em4/B and Em4OverB ->[59,64,67,71], with the nearest-below default reported. Contradictory explicit bass octaves fail. Identical computed pitches are deduplicated.validate_voicing(pitches, profile)checks every tone against MIDI bounds, profile range, and evidenced individual-string tuning without dropping, spreading, transposing, or arbitrarily revoicing.
schemas.ExplicitAttack extends exact TimedNote timing/technique/intensity
with a nonempty unique set of MIDI pitches. ExplicitAttackPlan contains
one pitched part, positive rational duration, ordered attacks, and
optional register assumptions supplied by the notation resolver. It bounds
the timeline to the existing maximal score length, validates half-open
intervals, forbids independent same-pitch overlaps, permits disjoint compatible
polyphony, and rejects overlapping different profile-wide techniques.
Attack duration means one continuous sustain; gaps mean silence. There are no
rest, continuation, slide, lane-spacing, or prose-interpretation guesses.
Later parsing can represent rests with gaps and continuation by extending the
original duration rather than retriggering. It must propagate assumptions.
MusicalIntent.explicit_plan is internal and mutually exclusive with
phrase_plan; it requires its sole part, sufficient bars/meter, and no global
rhythm/technique overrides. compose_score expands all tones as independent
simultaneous PitchedNotes at exact starts/durations. One seed draw per attack
provides shared chord intensity unless explicitly supplied, with the existing
bass seed offset. Techniques resolve through the actual selected profile.
The plan counts expanded note-on/off pairs; explicit composition also invokes
the authoritative compiler to enforce the 100,000-event ceiling including
articulation controls and to validate grid/control timing. Subsequent explicit
CC points remain subject to the existing combined compiler/control budget.
The unchanged Riffer codec assigns independent tones using bounded physical
string allocation and validates saved pitch/fret/timing/technique data. A
full voicing with no physical string assignment can use only the existing
explicit no_physical_string_assignment MIDI-fallback policy; all pitches
survive in MIDI. Out-of-map pitches are composition errors, not fallback.
No profiles, tunings, vendor claims, dependencies, versions, or public request
fields were changed. Integration tests inject an internal resolution solely
to exercise actual service publication; they do not claim public chord prose
or lane parsing. Saved Mido/XML checks independently assert 11 musical tones,
4 MIDI selectors, 30 scheduled events, exact thirds, PM/PH, a non-key F# major
chord, both slash-bass octaves/aliases, and legal occupied physical strings.
Step 15: public hybrid prose and precise lanes
hybrid.py separates lane/hold clauses before the legacy prose sequence guard.
description.resolve_description reuses the closed prose resolver for context,
then attaches a strict, profile-independent HybridPlan of rational
HybridSlots. Count labels are denominator beats; widths/spaces are lexical only.
count_grid is reusable exact Fraction math for complete eighth/sixteenth and
explicit eighth-triplet beats, including 3/4 and non-quarter denominators.
1&a is rejected without a disambiguating grid; under sixteenths its e is
omitted (positions 0, 1/2, 3/4), while under eighth-triplets it is 0, 1/3, 2/3.
Bare labels remain one denominator beat even with a Grid directive.
After profile selection, service and composer both reuse hybrid.materialize.
It calls Step14 tokenization/voicing resolution, never a second voicing engine,
and creates the existing ExplicitAttackPlan. ~ extends the previous
adjacent attack duration; rests create real gaps; prose ties extend a final
attack to an exact bar end only if no specified rest/new attack conflicts.
Exact source/installed E2 prose-tie, all-tilde-bar and continuation-clause outputs
are byte-identical. Structured meter changes cannot reinterpret explicit
labels; bars cannot truncate notation or holds.
o/x/^/-/~, Notes/Chords empty lanes, compact tokens, explicit chord voicings,
slash/Over bass and ordered Bar blocks or matching | spans are public.
Events/Notes brackets group consecutive positions; Chords brackets specify
simultaneous notes. A slide direction in Events returns specific unsupported
origin/destination/timing guidance; slash chord spelling is unrelated.
Unknown prose is rejected, including tempo changes; style does not modify
precise pitches/times. Global techniques and explicit prose pitch claims must
agree with affected events. No implicit CC, transpose, revoice or dropped tone.
The additive default-empty resolved.interpretation lists InterpretedAttack
records: exact pitches, rational start/duration, part, technique, optional
intensity and held status. Register/bass/default/velocity policy is in
resolved.assumptions. Text-only JSON and structuredContent are identical;
errors expose static authored reasons/guidance, never raw user text or paths.
The corrected native fixture uses F#2 major, D3 major [50,54,57], Bb2 major, then C4/E4/G4: 21 musical tones with legal independent string assignments. The old explicit D2 major [38,42,45] is deliberately a negative-native / positive-exact-MIDI test, not a reason to disable the generic parser. Native validation/tuning/fallback/publication/CC/event budgets are unchanged. See README's hybrid section for tested public syntax and limits.