docs: explain the direction/voice/staff round-trip drop cluster - #325
Merged
Conversation
Investigated why round-trip discovery reports drop:voice / drop:staff / drop:direction / drop:direction-type together on ~60 corpus files. DirectionReader already dispatches every direction-type choice, but eleven of them (harp-pedals, damp, damp-all, eyeglasses, string-mute, scordatura, image, principal-voice, accordion-registration, percussion, other-direction) are no-op stubs. When a <direction> contains only one of these, the resulting DirectionData carries no content and is correctly left unwritten -- MusicXML requires at least one direction-type child, so there is no schema-valid way to keep the <direction> (and its <voice>/<staff>) without modeling what it actually says. This is one gap (unmodeled content), not four; data/api.features.xml already correctly audits each of these subtypes as support="none" (only the parent direction/direction-type container, which does work, is full). The remaining <voice>/<staff> drops trace to <forward>/<backup>'s own optional voice/staff children, which mx::api does not read: forward/backup are pure wire cursor mechanics with no api representation (the writer regenerates whatever the tick math requires), so there is nothing to carry a source's forward/backup voice/staff value from. Also documented the same shape of gap in DirectionReader::parsePedal: sostenuto/change/continue/discontinue/resume are unmodeled, only start/stop. Filed #324 to track implementing the unmodeled direction-type subtypes and pedal states; no code behavior changes here, just comments pointing at the finding so it isn't re-investigated from scratch. Closes #278 Closes #280
Coverage reportCore-dev coverage
|
| Metric | Coverage | Covered / Total |
|---|---|---|
| Lines | 77.8% | 28513 / 36640 |
| Functions | 74.3% | 6352 / 8551 |
| Branches | 50.7% | 22678 / 44751 |
API coverage src/private/mx/{api,impl,utility}/
| Metric | Coverage | Covered / Total |
|---|---|---|
| Lines | 80.8% | 6391 / 7913 |
| Functions | 67.7% | 2217 / 3275 |
| Branches | 49.5% | 5476 / 11052 |
Core HTML report | API HTML report
Commit c27714bde8571269365216540fa9a435b9cb517a.
gen-quality
|
This was referenced Jul 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Human Summary
Hmmm, ok, well this adds a couple of stateful comments around directions that are currently unsupported. Seems harmless and perhaps it will help the LLM understand what's going on in the future. Seems like a bit of a cop out from the agent instead of supporting the missing features, but oh well. It opened an issue that likely words what is needed in a way it can understand more clearly.
Summary
#278 and #280 asked whether the round-trip classifier's
drop:voice/drop:staff/drop:direction/drop:direction-typesignatures (co-occurring on ~60 corpus files) are a genuineimpl bug or an audit-correction. Investigated with
make dump-api-roundtrip+make classify-api-roundtripand by diffing individual dumped files; this is neither -- it's onealready-understood, already-correctly-audited gap wearing four signatures:
DirectionReaderdispatches everydirection-typechoice, but eleven of them (harp-pedals,damp,damp-all,eyeglasses,string-mute,scordatura,image,principal-voice,accordion-registration,percussion,other-direction) are no-op stubs. A<direction>containing only one of these produces an empty
DirectionData, which is correctly leftunwritten -- MusicXML requires at least one
direction-typechild, so there is no schema-validway to keep the
<direction>(and its<voice>/<staff>) without modeling what it actuallysays.
data/api.features.xmlalready correctly audits each of these subtypes assupport="none"(only the parentdirection/direction-typecontainer, which does work, isfull) -- so there's no audit to correct either.<voice>/<staff>drops are<forward>/<backup>'s own optional children, whichmx::api does not read: forward/backup are pure wire cursor mechanics with no api representation
(the writer regenerates whatever the tick math requires), so there's nothing to carry a source's
forward/backup voice/staff value from.
DirectionReader::parsePedal:sostenuto/change/continue/discontinue/resumeare unmodeled, onlystart/stop(lysuite/ly33a_Spanners.xml).No code behavior changes -- this adds comments at each stub/gap pointing at the finding (and #324,
opened to track actually implementing this worklist) so it doesn't get re-investigated from
scratch.
Testing
make test: all pass (4724 assertions in 378 test cases, plus the three examples) --comments only, no behavior change
make fmt/make check: cleanReferences