The public API's `transposition` field documentation states the wrong direction relative to what the code actually implements

By the code's own arithmetic (see the detection field below), `transposition` is the number of semitones the WRITTEN pitch sits ABOVE concert/sounding pitch (written = concert + transposition) — the standard way orchestration texts describe transposing instruments (a Bb clarinet's transposition value is positive because its written C sounds a concert Bb, a whole step BELOW the written note, i.e. written sits above sounding).

This is a code-correctness finding, not a disputed engraving convention — cited here because it directly affects whether an agent authoring a public-API score gets transposition right, which is squarely this chapter's brief ("specify every validity check on it").

This rule can be decided from pitches, durations and voices — no layout required. A validator can check it before anything is drawn.