mx-api-doctrine

mx::api doctrine

mx::api is not "MusicXML minus rare features." It re-shapes MusicXML into a model where invalid or ambiguous documents are hard or impossible to express. MusicXML's recurring defects -- stateful encodings, flat streams with label fields, one fact stated in two places, id-linked declarations, order-dependent meaning -- each have a countering principle below. Never mirror an element's raw shape. The price of every simplification is paid in mx::impl: the writer regenerates the spec-compliant encoding, the reader accepts every spec-legal variant.

The audience is a musician, not the round-trip harness

Corpus round-tripping is how we develop mx::api; it is not what the api is for. The api exists for people who create music and who build, modify, and interpret MusicXML files. Public-header comments must explain the notation semantics, how MusicXML encodes them, and how to author or read them through the api.

• Never write from the harness's viewpoint. "The source", "preserved on round-trip", "populated by the reader" are wrong unless the field truly records non-semantic source fidelity (a principle-7 knob) -- then say so plainly (i.e. "Do not populate this when authoring").
• Do not document what is not modeled; listing what isn't there is noise.
• No separator/banner comments.

Bad: // staffIndex is zero-based; a source with an explicit number attribute always populates Good: // Which staff of the part this layout applies to, zero-based from the top staff.

Failure model: misuse must be boring

Responses to wrong api usage, in order of preference:

1. Unrepresentable: shape the type so the wrong state cannot be expressed (choice types below; merged fields, principle 3).
2. Defined fallback: document a harmless result and return it. A wrong-kind choice accessor returns a default-constructed copy; the writer drops the half of an encoding that is meaningless for the note it is on (a tie on a silent cue note is written as <tied> notation only, never as a sound-level <tie>). No signal to the caller.
3. Result<T> (Result.h): the error channel of last resort. It exists for the DocumentManager I/O boundary, where failure is real (unreadable file, unparseable XML). Do not spread it into the data model.